Bỏ qua

CLAUDE.md

Ghi chú cho Claude Code khi làm việc trong repo này.

Tài liệu tham khảo trước

  • Kiến trúc tổng quan: docs/ARCHITECTURE.md, docs/requirements/06-SYSTEM-DESIGN.md
  • Coding convention / pattern chi tiết (naming, service/controller pattern, Kafka, migration...): .cursor/skills/my-rule/SKILL.md
  • Quyết định kỹ thuật đã có ("tại sao lại làm thế này"): docs/adr/
  • Hướng dẫn dev/local đầy đủ: docs/DEVELOPMENT.md

Kiến trúc tổng quan (quick facts)

NX monorepo, yarn. 6 service NestJS + 1 service Python. Chi tiết đầy đủ xem docs/ARCHITECTURE.md.

App Port Stack
apps/api-gateway 3000 NestJS, REST proxy + GraphQL (Apollo, DataLoader), WebSocket (Socket.IO)
apps/user-service 3001 NestJS, TypeORM/Postgres
apps/field-service 3002 NestJS, TypeORM/Postgres
apps/booking-service 3003 NestJS, TypeORM/Postgres, Redis lock
apps/payment-service 3004 NestJS, TypeORM/Postgres, Stripe
apps/notification-service 3005 NestJS, Kafka consumer, email (nodemailer)
apps/openclaw — Python/FastAPI — ops/monitoring Telegram bot, stack riêng biệt, không theo convention NestJS bên dưới

Cross-cutting: libs/{shared,database,messaging,cache,observability,config,testing}. Giao tiếp: sync = api-gateway proxy HTTP; async = Kafka (topics tại libs/shared/src/constants/kafka-topics.ts) + BullMQ (job queue nội bộ, xem ADR-0006); auth = Keycloak/JWT (ADR-0005); observability = OpenTelemetry + SigNoz (ADR-0004).

Lưu ý: repo tên có "-k3s" nhưng không chứa k8s/helm manifest local — deploy production qua GitOps repo riêng (footballbookingteam100/football-booking-gitops), xem .github/workflows/cd.yml. Dev/local dùng docker-compose.

Lệnh thường dùng

yarn dev              # chạy tất cả service song song
yarn dev:gateway      # chạy 1 service (đổi tên theo app)
yarn test             # unit test (nx test)
yarn test:integration # integration test (testcontainers, cần Docker)
yarn test:e2e:booking # e2e theo flow (xem test/e2e/flows/)
yarn check:all        # format:check + lint + typecheck — chạy trước khi commit

Chi tiết đầy đủ (env setup, docker infra, migration...) xem docs/DEVELOPMENT.md.

Claude Code Subagents

Repo có sẵn các subagent chuyên biệt trong .claude/agents/ — ưu tiên delegate sang subagent phù hợp thay vì tự làm hết trong main session, để tránh lẫn context giữa các domain khác nhau:

Subagent Dùng khi
nestjs-service-dev Implement/sửa feature trong 6 service NestJS hoặc libs/ (endpoint, entity, DTO, Kafka producer/consumer, GraphQL resolver...)
openclaw-ops-bot-dev Sửa apps/openclaw (Python/FastAPI ops bot) — stack và convention khác hẳn NestJS
adr-writer Trước khi thêm dependency/tech mới, đổi kiến trúc giữa service, hoặc quyết định khó đảo ngược — xem policy ở mục ADR bên dưới
security-reviewer Review bảo mật read-only trước khi merge thay đổi nhạy cảm (auth, payment, webhook) — OWASP, secrets, đối chiếu Semgrep/Trivy
test-debugger Debug test fail (unit/integration/contract/e2e/k6) — reproduce, isolate root cause, fix tối thiểu
observability-engineer Sửa OpenTelemetry instrumentation, SigNoz dashboard/alert, hoặc cần tra cứu nhanh trong đống doc OBSERVABILITY-*/SIGNOZ-*

Architecture Decision Records (ADR)

Repo dùng docs/adr/ làm nhật ký các quyết định kỹ thuật — mục đích để sau này nhìn lại được hành trình và lý do đằng sau mỗi lựa chọn, không chỉ code diff. Khi thực hiện một trong các việc sau, PHẢI tạo hoặc cập nhật một ADR trong docs/adr/ (dùng docs/adr/template.md) trước khi implement — không chỉ tóm tắt trong PR description hay báo cáo cuối task:

  • Thêm một dependency/công nghệ mới ở tầng service hoặc infra (DB, message queue, observability tool, API style, identity provider...)
  • Đổi kiến trúc giữa các service (giao tiếp sync/async, thêm gateway pattern, đổi cách chia sẻ dữ liệu...)
  • Có từ 2 phương án kỹ thuật khả thi trở lên và phải chọn 1 (framework, thư viện, cách tổ chức module...)
  • Một quyết định khó đảo ngược (schema, giao thức, vendor lock-in, thay đổi ảnh hưởng nhiều service)

Không cần ADR cho: bug fix, refactor nội bộ 1 file/module, thay đổi UI/copy, thêm field/endpoint theo pattern đã có sẵn.

Quy tắc khi viết ADR:

  • Đánh số file tuần tự NNNN-slug-khong-dau.md, tiếp theo số lớn nhất đang có trong docs/adr/ (xem bảng trong docs/adr/README.md).
  • Không sửa lại ADR đã Accepted khi quyết định thay đổi sau này — tạo ADR mới, set Supersedes ở ADR mới và Superseded by ở ADR cũ, đổi status ADR cũ thành Superseded.
  • Nội dung ngắn gọn theo template: Bối cảnh → Quyết định → Lựa chọn khác đã cân nhắc → Hệ quả → Liên kết. Không viết dài dòng như blog post.
  • Sau khi tạo/sửa ADR, cập nhật bảng danh sách trong docs/adr/README.md (số, tiêu đề, status, ngày).
  • Nếu không chắc một thay đổi có "đáng" ADR hay không, hỏi lại người dùng thay vì tự quyết định bỏ qua.