Điểm danh & Báo cáo chuyên cần

1Bối cảnh & mục tiêu

Trung tâm / trường (B2B) đang điểm danh trên giấy hoặc Excel rời rạc — chủ trường không có bức tranh chuyên cần theo lớp / chi nhánh, và không phát hiện sớm học sinh sắp bỏ học (chuyên cần thấp là tín hiệu churn mạnh nhất).

• Giáo viên: điểm danh 1 lớp trong < 30 giây, ngay nơi họ đang thao tác (màn chi tiết lớp).
• Chủ trường / quản lý chi nhánh: xem tỉ lệ chuyên cần theo lớp, danh sách học sinh cần chú ý, xuất Excel gửi phụ huynh / báo cáo nội bộ.
• FLYER: thêm lý do dùng hằng ngày (daily habit) cho FLYER Teacher; nền tảng cho tính năng thông báo phụ huynh qua ZNS/Zalo (Sprint 107+).

2Người dùng & user stories

3Phạm vi & phase

4Luồng sản phẩm

4a · Giáo viên điểm danh (tab trong chi tiết lớp)

1. Vào lớp → Quản Lý Lớp → chọn lớp → tab “Điểm danh” (tab cuối, value 8).
2. Chọn ngày (mặc định hôm nay; không chọn được ngày tương lai).
3. Đánh dấu: mỗi học sinh có 4 pill trạng thái; nhấn chọn — nhấn lại lần nữa để bỏ chọn. Nút “Tất cả có mặt” đánh cả lớp một phát. Ô ghi chú tự do cho từng học sinh (vd lý do vắng).
4. Theo dõi: 4 chip đếm (Có mặt / Đi muộn / Nghỉ phép / Vắng) cập nhật realtime + dòng “Đã điểm danh x/y học sinh”.
5. Lưu điểm danh → toast “Đã lưu điểm danh”. Lưu một ngày mà không đánh dấu gì = xoá buổi đó (cách xoá buổi lưu nhầm).
6. Lịch sử (toggle góc phải): bảng tổng hợp mỗi học sinh (số buổi từng trạng thái + % chuyên cần, tô màu theo ngưỡng) + danh sách các buổi đã điểm danh — nhấn 1 buổi để mở lại và sửa.

4b · Chủ trường xem báo cáo (menu Báo Cáo → Báo cáo điểm danh)

1. Mở sidebar Báo Cáo → “Báo cáo điểm danh” (route /report/attendance). Phạm vi = chi nhánh đang chọn (đúng mô hình mỗi chi nhánh là 1 school).
2. Tổng quan: 4 stat — số lớp đã điểm danh · tổng buổi · % chuyên cần chung (tô màu ngưỡng) · tổng lượt vắng.
3. Chuyên cần theo lớp: bảng từng lớp (số buổi, đếm 4 trạng thái, % chuyên cần) — sort lớp thấp nhất lên đầu.
4. Học sinh cần chú ý: mọi học sinh có chuyên cần < 80% (tên, lớp, số buổi vắng, %).
5. Lọc khoảng ngày (mặc định 30 ngày; xoá = toàn thời gian) + Xuất Excel.

5Spec UI — cho Designer

Trạng thái điểm danh (4 mức)

Thành phần & hành vi

• Hàng học sinh: STT · avatar 36px tròn (fallback avatar mặc định) · tên (đậm, truncate) · 4 pill · input ghi chú 180px. Hàng chẵn nền #FBFBFC.
• Pill: bo tròn full, cao 30px, đổi trạng thái tức thì (optimistic), nhấn lại = bỏ chọn.
• Ngưỡng màu % (dùng thống nhất mọi nơi): ≥ 80% xanh #16A34A · 50–79% cam #D97706 · < 50% đỏ #DC2626.
• Chống mất dữ liệu: đổi ngày / mở buổi khác khi đang có thay đổi chưa lưu → modal xác nhận “Chưa lưu điểm danh — Bỏ thay đổi / Ở lại” (nút Bỏ = danger).
• Empty states: lớp 0 học sinh → Empty “Lớp chưa có học sinh”. Báo cáo phân biệt 2 case: chưa có dữ liệu vs có dữ liệu nhưng ngoài khoảng ngày đã lọc (copy khác nhau).
• Hệ thống: antd (Segmented, DatePicker, Modal, Empty) + Tailwind; font Public Sans; song ngữ VI/EN (namespace attendance.*, đã có đủ key).
• Cần designer: soát lại spacing/màu theo design system, thiết kế trạng thái mobile (hàng học sinh wrap), icon cho tab + menu báo cáo, và cân nhắc biểu đồ xu hướng chuyên cần theo tuần (chưa làm).

6Business rules

7Data & API — cho Developer

Hiện tại (Phase 1 — localStorage)

flyer_attendance_<classId> = {
  "2026-08-12": {                       // date key, giờ địa phương
    "<learnerProfileId>": { "status": "present|late|excused|absent",
                             "note": "…", "name": "Nguyễn Văn A" }
  }, …
}
flyer_attendance_index = {              // để báo cáo gom theo chi nhánh
  "<classId>": { "name": "KET 1", "schoolId": "…", "schoolName": "…", "demo": true? }
}

Toàn bộ đọc/ghi đi qua src/utils/attendance.ts (single source of truth) — Phase 2 chỉ cần thay ruột các hàm này bằng API call, UI giữ nguyên.

Đề xuất Phase 2 — DB

attendance_sessions   id · class_id · date (unique class_id+date) · created_by · timestamps
attendance_records    id · session_id · learner_profile_id
                      · status ENUM(present, late, excused, absent)
                      · note TEXT NULL · marked_by · timestamps

Đề xuất API (REST v3, cùng pattern openapi hiện có)

• Quyền: GV chỉ điểm danh lớp mình dạy; report cấp chi nhánh cho role ADMIN/Owner (Phase 1 đang chưa gate — cần thêm khi có backend).
• Frontend đã có sẵn: component ClassAttendance (tab, value 8 trong [classId]/dashboard.tsx), view AttendanceReportView, route + sidebar + routeConfig + i18n VI/EN. Query danh sách học sinh dùng partnerViewerRollupStudents (limit 200 — Phase 2 cần phân trang nếu lớp lớn hơn).

8Edge cases đã xử lý (từ audit 26-agent)

Còn mở (chưa làm, cần quyết ở Phase 2): gate theo role & feature flag; nhấn dòng lớp trong báo cáo để nhảy vào lớp; phân trang lớp > 200 học sinh; đồng bộ đa thiết bị (đến khi có backend).

9Acceptance criteria (Phase 2)

1. GV mở tab Điểm danh của lớp có N học sinh → thấy đủ N hàng, mặc định ngày hôm nay, chưa đánh dấu gì.
2. Nhấn “Tất cả có mặt” → N pill Có mặt bật; sửa 1 học sinh thành Vắng + ghi chú; Lưu → reload trang → dữ liệu đúng như đã lưu (từ server, thấy được trên thiết bị khác).
3. Nhấn lại pill đang chọn → bỏ đánh dấu; lưu buổi không còn đánh dấu nào → buổi biến mất khỏi Lịch sử và báo cáo.
4. Đổi ngày khi có thay đổi chưa lưu → hiện modal xác nhận; “Ở lại” giữ nguyên, “Bỏ thay đổi” chuyển ngày.
5. Học sinh rời lớp sau khi đã được điểm danh → sửa và lưu lại buổi cũ → record của em đó vẫn còn trong báo cáo.
6. Báo cáo chi nhánh: % chuyên cần lớp = công thức mục 6 (viết unit test); lớp thấp nhất đứng đầu bảng; học sinh < 80% xuất hiện trong “Cần chú ý”.
7. Lọc khoảng ngày không trùng dữ liệu → hiện thông báo “ngoài khoảng ngày”; xoá lọc → dữ liệu hiện lại.
8. Xuất Excel ở cả 2 màn ra đúng cột, đúng ngôn ngữ đang chọn.
9. GV không phải admin không thấy “Báo cáo điểm danh” trong menu (role gate).
10. Toàn bộ text hiển thị đúng ở cả VI và EN.

10Ngoài phạm vi / tương lai

• Thông báo phụ huynh khi con vắng (ZNS / Zalo OA — nối với hạ tầng Sprint 107). Đây là “killer feature” bán cho B2B — đề xuất ưu tiên ngay sau Phase 2.
• Chuyên cần trong weekly / monthly report gửi chủ trường (template có sẵn).
• Biểu đồ xu hướng chuyên cần theo tuần; so sánh giữa các chi nhánh (view gộp toàn hệ thống).
• Điểm danh trên mobile ứng dụng giáo viên; điểm danh bằng QR cho lớp đông.
• Liên kết với Thu học phí (buổi vắng có phép ảnh hưởng tính buổi học phí hay không — cần quyết với vận hành).

Prototype chạy tại môi trường dev nội bộ (branch dev, tab Điểm danh trong chi tiết lớp + menu Báo Cáo → Báo cáo điểm danh). Liên hệ Tùng để xem demo trực tiếp.