Quy trình nội bộ
Quy ước dự án, quy trình nghiệm thu và hệ thống tài liệu.
Nguyên tắc gốc
Nghiệm thu là xác nhận của người dùng, không suy từ test
Nghiệm thu là xác nhận của người dùng về một phạm vi cụ thể, không suy ra từ build xanh, test pass, nhãn APPROVED trong tài liệu nhập, hay câu "OK" ở một tác vụ khác.
Ba nguyên tắc chi phối mọi thay đổi:
- Xác nhận trực tiếp của người dùng có ưu tiên cao nhất.
- Code và test là bằng chứng triển khai, không tự xác nhận nghiệp vụ. Không suy code đang chạy là nghiệp vụ đã được chấp nhận.
- Không tự thêm chức năng hoặc chính sách từ dữ liệu mẫu, tài liệu nhập hay nhãn phê duyệt.
Sau mỗi lần code — ba bước
- Đọc spec và bàn giao của tính năng. Cập nhật hành vi đã làm, API và model thực có, trạng thái, và phần còn chưa rõ.
- Cập nhật test case theo workflow đã chốt, chạy kiểm tra phù hợp với thay đổi. Lưu kết quả thật kèm môi trường, build, ngày, giới hạn và bằng chứng. Phần chưa chạy ghi NOT RUN.
- Bàn giao để người dùng test. Chưa có nghiệm thu thì giữ trạng thái chờ.
PASS chỉ dành cho kiểm tra thực chạy
Không được ghi PASS cho phần chưa chạy, không được dựng log giả, và không được đổi case chưa chạy thành PASS.
Khi người dùng nói "nghiệm thu" — sáu bước
- Ghi lại phạm vi được chấp nhận và nguồn xác nhận. Phải phân biệt rõ: chỉ frontend, chỉ backend, một luồng, hay toàn bộ tính năng.
- Hoàn thiện
spec.mdtừ xác nhận thực tế: giao diện, vai trò, đầu vào, tiền điều kiện, luồng chính, nhánh lỗi, chuyển trạng thái, kiểm tra dữ liệu, quyền và phạm vi, nguồn đọc ghi. Giữ phần chưa rõ và giữ lịch sử của quyết định đã bị thay thế. - Cập nhật
frontend-handoff.md, vàdatabase-model.mdcùngimplementation-handoff.mdnếu thuộc phạm vi đã triển khai. - Đóng gói
test-cases.md: mỗi case có căn cứ, tiền điều kiện, dữ liệu, bước, kết quả mong đợi, tầng kiểm tra và liên kết kết quả. Xác nhận thủ công của người dùng ghi là xác nhận thủ công. - Tạo biên bản nghiệm thu theo mẫu, liên kết kết quả thực chạy và bằng chứng có sẵn.
- Cập nhật chỉ mục tính năng, trạng thái spec và checklist liên quan.
Nghiệm thu không mở khoá việc khác
Nghiệm thu không tự cho phép triển khai, chạy migration production, hay phát triển tính năng kế tiếp. Nghiệm thu frontend không nghiệm thu backend hay toàn app.
Thay đổi sau nghiệm thu
- Giữ nguyên biên bản và kết quả cũ; không ghi đè.
- Ghi rõ thay đổi mới, phiên bản, phạm vi cần test lại và các case hồi quy bị ảnh hưởng.
- Cập nhật đặc tả tại chỗ, có lịch sử.
- Chỉ tạo biên bản mới khi người dùng nghiệm thu phần thay đổi.
Hồ sơ theo tính năng
Mỗi tính năng có một thư mục riêng dưới docs/features/<nhóm>/<tính năng>/, gồm:
| Tệp | Nội dung |
|---|---|
spec.md | Đặc tả chính: nguồn giao diện, phạm vi, workflow, quyền, kiểm tra dữ liệu, câu hỏi và quyết định. |
frontend-handoff.md | Code và nguồn giao diện đã kế thừa, trạng thái màn hình, giới hạn. |
database-model.md | Model, schema và migration thực có hoặc đề xuất được ghi rõ. |
implementation-handoff.md | API đã triển khai, bảo toàn dữ liệu, kiểm chứng và giới hạn. |
test-cases.md | Case theo tính năng, liên kết case toàn app. |
test-results/<mã-lần-chạy>.md | Kết quả thực chạy của từng lần. |
acceptance/<ngày>-<phạm-vi>.md | Biên bản nghiệm thu từ người dùng. |
Tạo khi có, không tạo trước
test-results chỉ tạo khi có lần chạy thật. acceptance chỉ tạo khi được nghiệm
thu. Không tạo sẵn tệp PASS trống.
Bảo vệ bí mật và dữ liệu
- Không sửa bộ bàn giao nguồn.
- Không xoá cơ sở dữ liệu, thư mục tải lên hay bằng chứng.
- Không xuất thông tin đăng nhập vào tài liệu.
- Các tệp cấu hình riêng và thông tin xác thực phải được bảo vệ, không đưa nội dung vào tài liệu hay bằng chứng.
Kiểm thử
| Lệnh | Việc |
|---|---|
pnpm test:api | Test API trên cơ sở dữ liệu tạm. |
pnpm test:e2e | Test đầu cuối trên trình duyệt. |
pnpm test:shared-domain | Test domain dùng chung. |
pnpm typecheck | Kiểm tra kiểu toàn workspace. |
pnpm build | Build toàn bộ. |