Quy trình phát triển
Quy ước làm việc rút từ cấu hình trong repository. Quy ước viết tài liệu: documentation-guide. Quy ước code chi tiết nằm ở thư mục agent_docs/ (tài liệu tham khảo, không thuộc nhóm tài liệu chính thức): code_conventions.md, NAMING_CONVENTIONS.md, SENIOR_BACKEND_PRACTICES.md, service_architecture.md.
Thiết lập
quick-start, local-development. Dùng Node 24 (nvm use).
Nhánh và commit
- Nhánh theo loại thay đổi, ví dụ
feat/external-job-lifecycle,chore/toolchain-and-safety-net,docs/production-documentation; nhánh chính làmain. - Commit theo Conventional Commits (
feat,fix,chore,refactor,docs,test,style,ci). Hookcommit-msgchạycommitlintvới@commitlint/config-conventional(commitlint.config.js). - Hook
pre-commitchạylint-staged:eslint --fixtrên file*.tsđã staged. - Pull Request vào
main; CI chạy tự động (ci-cd).
Trước khi mở Pull Request
npx tsc --noEmit # kiểm tra kiểu
npm run lint # ESLint, tự sửa (--fix)
npm test # unit test
npm run build
CI chạy cùng các bước này (dùng eslint không --fix), thêm npm audit --omit=dev --audit-level=critical và build image production. Nếu thay đổi chạm vào luồng đã có e2e, chạy npm run docker:dev && npm run test:e2e.
Quy ước code
| Chủ đề | Quy ước | Nguồn |
|---|---|---|
| Định dạng | Prettier: nháy đơn, dấu chấm phẩy, trailingComma: all, rộng 100, thụt 2, arrowParens: avoid | .prettierrc |
| Lint | ESLint flat config với typescript-eslint và Prettier | eslint.config.mjs |
| Cấu trúc | Controller mỏng, logic ở service; cấu trúc module chuẩn | project-structure |
| Phản hồi | Giữ envelope { statusCode, message, data }; dùng @ResponseMessage | api-overview |
| Xác thực | Dùng @Public(), @OptionalAuth(), @Roles(); mọi route mặc định cần JWT | user-roles |
| Validation | DTO với class-validator; field không có decorator bị loại | api-overview |
| Xóa | Theo mẫu xóa mềm trừ khi có lý do khác | database-overview |
| AI | Mô hình chỉ trích xuất hoặc sinh nội dung; quy tắc và hành vi cuối do service quyết định | ADR-0004 |
Những bẫy đã biết khi viết code mới (đừng lặp lại):
- Dùng
Schema.Types.ObjectIdchứ không dùngTypes.ObjectIdtrong@Prop(database-overview). findOne,aggregate,update*không tự lọc xóa mềm; thêmisDeletedtường minh.- Đừng khai báo index hai lần cho cùng key (
index: truevàSchema.index). - TTL của
CACHE_MANAGERtính bằng mili giây. - Hàng đợi mới: đặt
jobIdkhi cần loại trùng, đặtremoveOnFailcó giới hạn. - Route mới: kiểm tra quyền sở hữu trong service, không chỉ
@Roles; đừng dựa vào CASL. - Đừng ghi dữ liệu cá nhân vào log (data-protection).
Cập nhật tài liệu cùng Pull Request
| Bạn đổi | Cập nhật |
|---|---|
| Schema, index | 04-database/collections/ |
| Route, DTO, quyền | 05-api/endpoints/ |
| Biến môi trường | .env.example và environment-variables |
| Hàng đợi, cron | queues, data-flow |
| Quy tắc nghiệp vụ | business-rules và tài liệu module |
| Quyết định kiến trúc mới | Thêm ADR ở 12-decisions |
Kiểm tra tài liệu
Các script kiểm tra tài liệu dùng trong dự án (link, anchor, Mermaid, schema, route, bí mật, src/ không đổi) nằm ở docs/superpowers/doccheck/ và chỉ có ở local (thư mục bị ignore); chưa có trong CI. Chúng cần mermaid và jsdom cài ngoài repository. Các script sinh tài liệu collection và API (gen-db.cjs, gen-api.mjs) đọc schema và controller thật nên giữ bảng field, index và route khớp code; phần mô tả tiếng Việt do người viết.
Known Limitation
Tài liệu không tự cập nhật khi code đổi và CI không kiểm tra tài liệu; sai lệch phát hiện bằng cách chạy lại các script trên.