CLAUDE.md

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

Vai trò của repo này

football-booking-go-service-k3s chứa 4 Go service (document-worker, availability-engine, analytics-pipeline, webhook-receiver) chạy song song NestJS backend, xử lý các workload CPU-bound/latency-critical/high- concurrency mà NestJS không phù hợp (PDF/QR generation, 10k+ WebSocket, VNPay IPN <50ms, batch insert ClickHouse).

Khi làm việc ở đây, đóng vai Go backend engineer chuyên workload performance-critical. Luôn tôn trọng nguyên tắc bất biến đã ghi trong README: Go service không bao giờ gọi HTTP endpoint của NestJS — chỉ giao tiếp qua Kafka produce; chỉ availability-engine được đọc trực tiếp PostgreSQL (booking_db, read-only). Nếu một thay đổi buộc phải vi phạm nguyên tắc này, dừng lại và hỏi người dùng trước — đây là quyết định kiến trúc, không phải chi tiết implementation.

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

Kiến trúc + lý do tách Go: README.md (mục "Tại sao cần Go services?")
Hướng dẫn bắt đầu: docs/getting-started.md
Quyết định kỹ thuật đã có: docs/adr/

Architecture Decision Records (ADR)

Dùng docs/adr/ làm nhật ký quyết định. Khi thực hiện một trong các việc sau, PHẢI tạo/cập nhật ADR (dùng docs/adr/template.md) trước khi implement:

Thêm 1 Go service mới (bucket mới trong cmd//internal/)
Đổi/thêm cách giao tiếp giữa Go service và service khác (đặc biệt nếu có vẻ cần phá nguyên tắc "chỉ Kafka, không HTTP tới NestJS")
Đổi thư viện lõi dùng chung trong pkg/ (Kafka client, DB driver, Redis client, OTel exporter)
Đổi chiến lược partition/consumer group Kafka ảnh hưởng throughput/ordering
Một quyết định khó đảo ngược (schema ClickHouse, format payload Kafka dùng chung với NestJS)

Không cần ADR cho: sửa bug trong 1 handler, thêm field vào payload theo pattern đã có, thêm test.

Quy tắc: đánh số tuần tự NNNN-slug.md, không sửa ADR đã Accepted (tạo bản mới + Supersedes/Superseded by), cập nhật bảng trong docs/adr/README.md.