Imported from vunam1306/summary-grade (AGENTS.md). Install upstream with npx skills add vunam1306/summary-grade. Copyright stays with the author.

AGENTS.md

Ngữ cảnh dự án cho AI Agent

File này đặt ở gốc repo. Đọc file này TRƯỚC mọi task. Không thay thế SRS/SDD/Task breakdown — chỉ định hướng nhanh và chặn các lỗi hay lặp lại.

1. Dự án này là gì

Công cụ giúp giáo viên tự động ghép điểm bài tập về nhà (xuất từ ClassIn) và điểm quiz (xuất từ Quizizz) vào đúng học sinh trong 1 file Excel tổng hợp, thay vì dò tên thủ công. Phần khó nhất và quan trọng nhất là engine ghép danh tính học sinh, vì tên hiển thị trên Quizizz không đồng nhất với danh sách lớp.

2. Tài liệu phải đọc, theo đúng thứ tự này

3. Quyết định đã chốt — không tự ý đổi giữa chừng

• Stack: Python/FastAPI + SQLite + React/TypeScript (lý do: xem SDD Mục 1)
• Ngưỡng matching: MATCH_THRESHOLD_HIGH=90, MATCH_THRESHOLD_REVIEW=70, AMBIGUOUS_GAP=3 (SDD Mục 5)
• Công thức quy đổi điểm mặc định: ClassIn chia 10, Quizizz (Accuracy%) chia 10 (SDD Mục 7)
• Đọc/ghi Excel bằng openpyxl, không bao giờ dùng pandas.to_excel() để ghi vào file tổng hợp (sẽ mất định dạng gốc)
• Nếu một học sinh làm Quizizz nhiều lượt, chọn lượt có Score cao nhất; giữ lại mọi lượt để audit. Nếu điểm thiếu/không hợp lệ hoặc hòa điểm cao nhất, bắt buộc giáo viên duyệt.
• Mẫu viết tắt chữ cái đầu của một từ trong Họ và tên đệm + Tên (vd N duy) được sinh làm ứng viên nhưng lần đầu luôn là fuzzy_needs_review; nếu trùng nhiều học sinh thì ambiguous. Alias đã xác nhận mới được exact ở lần sau.
• Khi cột Lớp của học sinh khác sheet đang xử lý, sheet được chọn là roster/đích ghi chính; hệ thống phải cảnh báo trong preview, không tự chuyển sheet hoặc loại học sinh.
• Import cho phép chỉ ClassIn, chỉ Quizizz, hoặc cả hai; phải có ít nhất một file. Nguồn không upload có nghĩa là không cập nhật, không được suy diễn thành Vắng/Chưa nộp.
• Preview thực hiện trong ứng dụng trên current revision; chỉ sau khi xác nhận mới tạo revision .xlsx bất biến bằng openpyxl. App chỉ tải current revision, không tạo output rời theo session. Phase 1 không dùng Google Sheets API.
• Working workbook có đúng một project active. Upload workbook mới archive project cũ và tạo revision 1; mỗi apply/undo thành công tạo revision mới, không sửa hoặc xóa revision cũ.
• Apply bắt buộc gửi base_revision_id; base cũ trả 409. Undo import cũ chỉ được phép khi revision về sau không chạm cùng sheet + cell; undo hợp lệ tạo revision bù, không hỗ trợ redo.
• Nếu ClassIn có Submitted="Yes" nhưng Task Scores trống, không suy diễn điểm và không ghi 0/Chưa nộp; giữ nguyên ô đích, cảnh báo và bắt buộc giáo viên chủ động chọn Bỏ qua dòng này trước khi xác nhận.
• Nếu một task khiến bạn muốn đổi 1 trong các quyết định trên: dừng lại, ghi thành "known open issue" mới, không tự đổi ngầm rồi code tiếp.

4. Việc bắt buộc trước khi coi 1 task là "xong"

1. Có test tương ứng và test đó pass.
2. Không phá bất kỳ test nào đã pass trước đó — đặc biệt toàn bộ 30 test case trong golden dataset phải luôn pass 100%, đây là gate cứng, không có ngoại lệ.
3. Nếu thay đổi schema/API/thuật toán so với SDD → cập nhật lại đúng mục trong SDD trước khi đóng task.
4. Nếu phát sinh quyết định nghiệp vụ mới (case chưa từng gặp, chưa có quy tắc) → không tự quyết định âm thầm, ghi lại thành open issue.

5. Việc KHÔNG được làm

• Không đoán liều khi matching engine không chắc chắn. not_found và ambiguous là kết quả ĐÚNG khi độ tin cậy thấp — không phải lỗi cần "sửa" bằng cách hạ ngưỡng để ép ra 1 kết quả.
• Không hard-code vị trí cột/dòng trong file Excel tổng hợp. Luôn dò theo nội dung header ("Họ và tên đệm", tên buổi học...) — xem SDD Mục 6.3, vì cấu trúc file sẽ thay đổi khi giáo viên thêm buổi học mới.
• Không ghi đè ô nào trong file gốc mà không lưu previous_cell_value trước đó (bắt buộc cho tính năng hoàn tác — BR-09).
• Không hạ ngưỡng số của matching engine (90/70/gap=3) mà không thêm test case chứng minh vào golden_dataset_ghep_ten.json trước.

6. Quy ước code (backend Python)

• Có type hints cho toàn bộ function public.
• Format bằng black, không tự chọn style khác.
• Docstring ngắn cho mỗi hàm trong matching/, parsers/, scoring/ — nêu rõ đang hiện thực Business Rule nào (vd """BR-02...""").
• Test đặt cùng cấu trúc với SDD_Tech_Spec_He_thong_ghep_diem.md Mục 2 (backend/tests/).

7. Cách chạy test nhanh (cập nhật lại nếu setup thực tế khác)

cd backend
pip install -r requirements.txt
pytest tests/test_matching_engine.py -v   # bắt buộc pass trước khi làm gì khác
pytest -v                                  # toàn bộ test suite

8. Quyết định nghiệp vụ đã chốt

Các vấn đề trong known_open_issues đã được giáo viên chốt:

• ISSUE-01: lấy lượt Quizizz có Score cao nhất; trường hợp không xác định duy nhất lượt điểm cao nhất phải duyệt tay (quyết định cập nhật ngày 14/09/2026).
• ISSUE-02: tự sinh gợi ý initial + Tên, nhưng luôn duyệt tay lần đầu; alias đã xác nhận được tự ghép ở lần sau.
• ISSUE-03: ưu tiên roster của sheet đang xử lý và cảnh báo khi cột Lớp không khớp.
• ISSUE-04 (15/09/2026): dòng đã nộp nhưng trống điểm phải được cảnh báo và giáo viên chủ động bỏ qua; không tự ghi giá trị vào ô đích.

Khi gặp case mới ngoài các quyết định trên, không tự quyết định cách xử lý — ghi thành known open issue và hỏi giáo viên.

9. Trạng thái hiện tại

Cập nhật mục này mỗi khi hoàn thành 1 Epic trong Task_Breakdown_Implementation_Plan.md, để phiên làm việc sau (hoặc agent khác) biết đang ở đâu mà không phải đọc lại toàn bộ lịch sử chat.

• Epic đã hoàn thành: Epic A — Scaffolding; Epic B — Matching engine (30/30 golden cases pass); Epic C — Parser 3 nguồn dữ liệu; Epic D — UC-01 Cấu hình mapping lớp học; Epic E — UC-02 Tải lên và tự động ghép điểm; Epic F — UC-03 Duyệt, xác nhận và học alias; Epic G — UC-05 Cấu hình công thức quy đổi điểm; Epic H — UC-04 Preview và ghi bản sao Excel; Epic I — UC-06 Lịch sử và hoàn tác; Epic J — UC-07 Quản lý alias học sinh; Epic K — kiểm thử ISSUE-01→04 và E2E 3 file thật; Epic L — Working workbook tích lũy và quản lý revision
• Epic đang làm: (không có — toàn bộ Epic A→L trong kế hoạch đã hoàn thành)
• Ghi chú bàn giao: SRS chuẩn hiện là SRS_He_thong_ghep_diem_giao_vien_v1.3.docx; hướng dẫn manual test là MANUAL_TEST_GUIDE.md. Working workbook có project/revision bất biến, optimistic locking, global download và undo bù có kiểm tra xung đột. Quizizz hỗ trợ correct_direct nhưng vẫn chọn lượt theo Score cao nhất. Automated gate ngày 16/09/2026: backend 71 tests pass, golden dataset 30/30 pass, frontend 6 test UI, production build và Black check pass. Vite dev đã proxy API. Known defect ngoài Epic L còn lại: DEFECT-01 chưa sinh nhãn Vắng cho học sinh roster không xuất hiện trong file Quizizz đã upload, trái BR-08.