# CLAUDE.md — Template cho dự án Node.js backend
# Cách dùng: copy vào gốc repo, chạy /init, merge, điền [ĐIỀN], xoá dòng không đúng.

## Lệnh thường dùng
- Cài deps: `npm ci`
- Dev: `npm run dev`; Test: `npm test` — chạy TRƯỚC mọi commit
- Lint/format: `npm run lint` — pass trước PR
- Build: `npm run build` [ĐIỀN: xoá nếu JS thuần]; DB migrate: [ĐIỀN: npx prisma migrate dev / npm run migrate]

## Kiến trúc
- Node [ĐIỀN: version LTS] + [ĐIỀN: Express/Fastify/NestJS] + [ĐIỀN: TypeScript?] + [ĐIỀN: PostgreSQL/MongoDB] + [ĐIỀN: Prisma/TypeORM/Mongoose]
- Luồng: Route → middleware (auth/validate) → Controller (mỏng) → Service (`src/services`) → Repository/ORM
- Validate input bằng [ĐIỀN: zod/joi] tại biên (route), KHÔNG validate rải rác trong service
- Config tập trung ở `src/config`, đọc env 1 chỗ duy nhất; logger dùng [ĐIỀN: pino/winston], KHÔNG console.log

## Quy ước code (bắt buộc)
- Async/await, KHÔNG callback/then-chain cho code mới; mọi promise phải được handle lỗi
- Lỗi đi qua error middleware trung tâm; error nghiệp vụ dùng class tự định nghĩa ở `src/errors`
- API trả về format thống nhất: [ĐIỀN: ví dụ `{ data, error, meta }`]
- Không import chéo giữa các module domain — đi qua service public của module đó

## Test
- [ĐIỀN: Vitest/Jest] + supertest cho endpoint; test đặt tại [ĐIỀN: `__tests__`/cạnh file]
- Mock I/O ngoài (DB, HTTP) — unit test không được gọi mạng thật
- Bugfix bắt buộc kèm test tái hiện

## Git & PR
- Nhánh `feature/<ticket>`, `fix/<ticket>`; Conventional Commits
- Trước PR: lint + test + build pass; không còn code debug, không lộ secret trong diff

## Definition of Done (feature chỉ được coi là xong khi)
1. Hành vi đúng theo spec ở mọi kịch bản mô tả, kể cả edge case đã nêu
2. `npm test` pass 100%; bugfix có test tái hiện kèm theo
3. `npm run lint` + build pass; không còn console.log/code debug
4. Input mới được validate tại biên; lỗi đi qua error middleware
5. Không lộ secret trong diff

## Cấm
- Không chạy lệnh xoá/ghi DB môi trường chung; seed chỉ local
- Không thêm dependency khi chưa được duyệt; không nâng major version tuỳ tiện
- Secrets qua env/secret manager, KHÔNG hardcode