Chuyển tới nội dung chính

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). Hook commit-msg chạy commitlint với @commitlint/config-conventional (commitlint.config.js).
  • Hook pre-commit chạy lint-staged: eslint --fix trê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 ướcNguồn
Định dạngPrettier: nháy đơn, dấu chấm phẩy, trailingComma: all, rộng 100, thụt 2, arrowParens: avoid.prettierrc
LintESLint flat config với typescript-eslint và Prettiereslint.config.mjs
Cấu trúcController mỏng, logic ở service; cấu trúc module chuẩnproject-structure
Phản hồiGiữ envelope { statusCode, message, data }; dùng @ResponseMessageapi-overview
Xác thựcDùng @Public(), @OptionalAuth(), @Roles(); mọi route mặc định cần JWTuser-roles
ValidationDTO với class-validator; field không có decorator bị loạiapi-overview
XóaTheo mẫu xóa mềm trừ khi có lý do khácdatabase-overview
AIMô 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 địnhADR-0004

Những bẫy đã biết khi viết code mới (đừng lặp lại):

  • Dùng Schema.Types.ObjectId chứ không dùng Types.ObjectId trong @Prop (database-overview).
  • findOne, aggregate, update* không tự lọc xóa mềm; thêm isDeleted tường minh.
  • Đừng khai báo index hai lần cho cùng key (index: true và Schema.index).
  • TTL của CACHE_MANAGER tính bằng mili giây.
  • Hàng đợi mới: đặt jobId khi cần loại trùng, đặt removeOnFail có 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 đổiCập nhật
Schema, index04-database/collections/
Route, DTO, quyền05-api/endpoints/
Biến môi trường.env.example và environment-variables
Hàng đợi, cronqueues, data-flow
Quy tắc nghiệp vụbusiness-rules và tài liệu module
Quyết định kiến trúc mớiThê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.