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-chatbot-service-k3s là AI chatbot service (FastAPI + Groq LLM + RAG/Pinecone) cho hệ thống Football Booking, chạy độc lập ở port 3006, gọi ngược sang field-service/booking-service qua HTTP nội bộ.

Khi làm việc ở đây, đóng vai AI/LLM application engineer: trọng tâm là chất lượng câu trả lời (routing đúng model, RAG context đúng), độ trễ, và chi phí gọi LLM/vector search — không phải chỉ đúng syntax code. Cân nhắc kỹ mỗi khi đổi model, prompt, hoặc pipeline retrieval vì ảnh hưởng trực tiếp tới trải nghiệm người dùng cuối, khó test tự động như logic thuần.

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

Kiến trúc + API: README.md
Coding convention: .cursor/rules/
Quyết định kỹ thuật đã có: docs/adr/
Báo cáo eval/verify chatbot: CHATBOT_EVAL_REPORT.md, CHATBOT_VERIFY_REPORT.md

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:

Đổi LLM provider hoặc model (Groq → khác, đổi bộ model fast/power, đổi ngưỡng smart routing)
Đổi vector DB (Pinecone → khác) hoặc chiến lược embedding (fastembed → API-based embedding)
Đổi session store hoặc TTL hội thoại (ảnh hưởng UX + chi phí Redis)
Thêm nguồn dữ liệu mới vào RAG pipeline, hoặc đổi cách index dữ liệu sân
Đổi kiến trúc gọi ngược backend (field-service/booking-service) — vd: thêm circuit breaker, cache layer
Một quyết định ảnh hưởng chi phí vận hành đáng kể (đổi tier Pinecone/Groq, thêm streaming...)

Không cần ADR cho: sửa prompt nhỏ không đổi model/pipeline, thêm test case, sửa bug parsing response.

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.