Trường Số PRD/04 Điểm danh
VIEN
Trường Số · Yêu cầu sản phẩm · 09/2026

PRD 04 · Điểm danh

Điểm danh theo buổi học với bốn trạng thái (có mặt, muộn, vắng, có phép), quy trình dành cho giáo viên ưu tiên điện thoại, chỉnh sửa của quản trị có ghi nhật ký, thông báo phụ huynh qua Zalo, và liên kết từ điểm danh đến số dư gói buổi và lương giáo viên. Hiện tại, chưa có thực thể điểm danh nào tồn tại trong backend.

Xuất xứ / Prompt / Giới hạn
Trạng thái
Dự thảo v1
Mô-đun phụ trách
Điểm danh
Backend
NEW
Giai đoạn
P1
Phụ thuộc vào
03 Lớp học, 02 Học viên, 07 Phụ huynh

Tài liệu do trợ lý AI soạn trong một phiên làm việc ngày 10/09/2026, theo yêu cầu gốc được trích nguyên văn ở trang mục lục; mục Thiết kế đề xuất được bổ sung ngày 16/09/2026. Đây là bản đề xuất để đội thảo luận, chưa phải quyết định của đội sản phẩm.

Nguồn

  • Nghiên cứu công khai về đối thủ cạnh tranh (PSE ONE, pse4.one), mã nguồn center-crm-frontend và đặc tả OpenAPI /v3 trên staging (182 endpoint), tính đến ngày 10/09/2026.
  • Nhãn existing / extend / new trong trang được xác định bằng cách đối chiếu với đặc tả /v3 trên staging tại thời điểm trên.

Giới hạn

  • Cần xác minh khi khảo sát trực tiếp trong ứng dụng, vì đăng nhập tự động vào sản phẩm tham chiếu chưa được cấp phép trong phiên soạn:
    • Các trạng thái điểm danh của đối thủ và liệu có tồn tại trạng thái "muộn" hay không.
    • Liệu vắng học có trừ vào gói buổi theo mặc định hay không, và liệu cấu hình này có áp dụng riêng theo từng trung tâm hay không.
    • Giáo viên điểm danh trên di động như thế nào (ứng dụng hay web), và liệu có khung thời gian cho phép chỉnh sửa hay không.
    • Phụ huynh nhận được gì (thông báo đẩy trong ứng dụng, Zalo, SMS) và nội dung mẫu tin là gì.
    • Liệu "đánh dấu ghi chú học sinh nghỉ học" là văn bản tự do hay các lý do có sẵn.

Thiết kế đề xuất

Ba màn hình di động cho giáo viên (buổi học hôm nay, phiếu điểm danh, phiếu đã lưu) và năm màn hình desktop cho quản trị. Điều quan trọng nhất là thanh chọn bốn trạng thái Có mặt · Muộn · Vắng · Phép trên từng dòng học viên, mặc định Có mặt, vùng chạm 44 px: giáo viên chỉ chạm vào các ngoại lệ rồi nhấn Lưu.

1–2 · Giáo viên: buổi học hôm nay và phiếu điểm danh

/teach/today · /teach/sessions/:id/attendance · mobile

Giáo viên: buổi học hôm nay
Phiếu điểm danh trên điện thoại
Màn 1: danh sách buổi trong ngày với giờ, lớp, phòng, sĩ số và chip trạng thái (Đã lưu / Đang điểm danh 9/10 / Chưa điểm danh); buổi hôm trước chưa điểm danh được ghim lên đầu với màu vàng cam (ATT-05); thanh tab Hôm nay · Lịch tuần · Lớp của tôi · Tài khoản. Màn 2: phiếu Movers 2B với bộ đếm ở đầu, banner "Chưa đồng bộ" khi mất mạng (ATT-01), cờ đánh dấu (Cần lưu ý, số dư thấp, sinh nhật), dòng Muộn mở ô số phút với mốc 5/10/15/30 (quy tắc 3), dòng Có phép được chọn sẵn từ đơn xin phép (ATT-02), phần Khách gồm Học thử và Học bù chỉ có hai trạng thái và ô nhận xét cho tư vấn viên (ATT-07); nút Lưu và công tắc gửi thông báo cố định ở đáy.

3 · Phiếu đã lưu: trạng thái gửi thông báo

/teach/sessions/:id/attendance · mobile

Phiếu điểm danh đã lưu
Sau khi lưu, phiếu tổng hợp hiển thị kết quả gửi cho từng phụ huynh: đã gửi Zalo, Zalo thất bại rồi chuyển sang email, bỏ qua vì chưa có kênh liên lạc, không gửi vì đã có phép (ATT-03 và trường hợp biên). Học viên học thử có ba lựa chọn nhận xét nhanh gửi cho tư vấn viên; lượt học bù được cập nhật và trừ một buổi (ATT-07). Thông báo về cửa sổ 24 giờ được sửa không cần lý do (quy tắc 4).

4 · Phiếu điểm danh trên desktop (quản trị)

/attendance/sessions/:id · desktop

Phiếu điểm danh trên desktop
Cùng phiếu Movers 2B nhìn từ phía giáo vụ hai ngày sau: dải thông tin buổi học, tỷ lệ chuyên cần của buổi (7/9, không tính có phép, quy tắc 7) và nhật ký phiếu; bảng có đủ cột học viên kèm loại và cờ đánh dấu, thanh bốn trạng thái, số phút muộn, số dư gói (đã trừ / không trừ theo quy tắc 5), ghi chú và trạng thái thông báo phụ huynh. Chip "Ngoài cửa sổ 24 giờ" ở đầu trang cho biết mọi thay đổi cần lý do và quyền attendance.edit_any (quy tắc 4).

5 · Tổng quan điểm danh

/attendance · desktop

Tổng quan điểm danh
Tab Hôm nay · Chưa điểm danh · Theo lớp · Theo học viên · Báo cáo; bốn chỉ số ở đầu và bộ lọc ngày, chi nhánh, giáo viên, lớp. Bảng buổi học trong ngày có giờ, lớp, phòng, giáo viên, sĩ số, trạng thái điểm danh, số có mặt/muộn/vắng/có phép, thông báo đã gửi và thao tác Mở phiếu; buổi Flyers 1C kết thúc quá 2 giờ chưa điểm danh được tô đỏ với nút Nhắc GV (ATT-05). Hai thẻ bên dưới liệt kê buổi chưa điểm danh theo giáo viên với hai thao tác Nhắc GV và Điểm danh thay, và tỷ lệ chuyên cần 30 ngày theo lớp (ATT-08).

6 · Tab điểm danh của học viên

/students/:id#attendance · desktop

Tab điểm danh của học viên
Lịch tháng 9/2026 với một chip cho mỗi buổi (Có mặt, Muộn 15', Vắng, Có phép, Sắp tới), tỷ lệ chuyên cần 30 và 90 ngày, bảng lượt vắng và muộn gồm ngày, lớp, trạng thái, lý do và tình trạng đặt học bù. Thẻ cảnh báo cho biết học viên đã vắng 2 lượt trong 30 ngày, còn 1 lượt nữa là hệ thống tạo việc theo dõi (ATT-06); nút + Thêm phép là hành động chính của trang.

7 · Biểu mẫu xin phép

/students/:id/excuses/new · modal

Biểu mẫu xin phép
Hộp thoại có đủ các trường của mục 4: áp dụng cho một buổi hoặc khoảng ngày, lý do (Ốm / Việc gia đình / Đi học trường / Khác), người báo, kênh tiếp nhận và công tắc đề xuất học bù. Trạng thái đang hiển thị là lỗi kiểm tra: chọn "Khác" nhưng chưa nhập mô tả. Dòng trợ giúp nhắc kết quả sau khi lưu: buổi 21/09 hiển thị sẵn Có phép trên phiếu của giáo viên và phụ huynh nhận xác nhận (ATT-02).

8 · Sửa điểm danh với lý do và nhật ký

/attendance/sessions/:id · modal

Sửa điểm danh với lý do
Giáo vụ đổi một bản ghi từ Vắng sang Có phép sau 42 giờ: hộp thoại cảnh báo ngoài cửa sổ 24 giờ, bắt buộc nhập lý do, cho thấy hệ quả trên số dư gói (hoàn 1 buổi, 6 → 7) và tuỳ chọn gửi tin điều chỉnh cho phụ huynh; phần nhật ký bản ghi liệt kê trạng thái trước và sau cùng người thao tác (ATT-04, quy tắc 4 và 5).

1Mục đích

Điểm danh là nghiệp vụ kết nối thời khoá biểu với tiền và với phụ huynh. Mỗi buổi học diễn ra tạo ra một bản ghi cho từng học viên trong danh sách lớp; các bản ghi này trừ vào gói buổi, làm chứng cứ tính giờ dạy để trả lương giáo viên, và kích hoạt tin nhắn mà phụ huynh mong đợi nhận được trong vài phút sau khi buổi học bắt đầu. Quy trình phải giúp giáo viên hoàn tất điểm danh trong chưa đầy một phút trên điện thoại, ngay cả trong lớp học có kết nối mạng kém.

Trong phạm vi

Ngoài phạm vi

2Các trạng thái

MãNhãn giao diệnChipTrừ vào gói buổiThông báo phụ huynhTính vào tỷ lệ chuyên cần
presentCó mặtCó mặtcótuỳ chọn (theo cấu hình tenant, mặc định tắt)có mặt
lateMuộnMuộncócó, kèm số phútcó mặt
absentVắngVắngcó (theo cấu hình tenant "vắng không phép vẫn trừ buổi", mặc định bật)có, ngay lập tứcvắng
excusedCó phépCó phépkhông (mặc định); có đề xuất học bùkhông (phụ huynh đã được thông báo trước)không tính
unmarkedChưa điểm danhxámkhôngkhôngkhông tính đến khi điểm danh

Màu sắc theo các token trạng thái của Cloud: ok #16A34A trên #DCFCE7, late #D97706 trên #FEF3C7, abs #DC2626 trên #FEE2E2, exc #2563EB trên #DBEAFE. Mỗi chip luôn kèm chữ; màu sắc không bao giờ là dấu hiệu duy nhất.

3User story và tiêu chí chấp nhận

ATT-01Giáo viên điểm danh trên điện thoại
Giáo viên điểm danh toàn bộ lớp trong chưa đầy một phút.
  • Given Mở Điểm danh trên điện thoại vào lúc buổi học bắt đầu hoặc sau đó (hoặc trước đó tối đa 30 phút)
  • When Phiếu điểm danh của buổi học tải lên với toàn bộ học viên trong danh sách được đặt mặc định là Có mặt
  • Then Chỉ cần chọn các trường hợp ngoại lệ (Muộn yêu cầu nhập số phút với các mốc có sẵn 5/10/15/30; Vắng; Có phép được chọn sẵn khi đã có đơn xin phép), có thể thêm ghi chú buổi học, rồi nhấn Lưu; phiếu được lưu bằng một yêu cầu duy nhất; nếu đang offline, phiếu được lưu tạm trên máy và đồng bộ khi có mạng trở lại, kèm banner "Chưa đồng bộ" hiển thị rõ.
ATT-02Xin phép nghỉ trước
Quản trị ghi nhận thông báo của phụ huynh trước buổi học.
  • Given Phụ huynh thông báo cho bộ phận lễ tân (gọi điện, Zalo, yêu cầu qua cổng phụ huynh)
  • When Thêm đơn xin phép cho học viên áp dụng cho một buổi học hoặc một khoảng ngày, kèm lý do
  • Then Các buổi học đó hiển thị sẵn trạng thái Có phép trên phiếu điểm danh của giáo viên; phụ huynh nhận được xác nhận; đề xuất học bù xuất hiện nếu chính sách cho phép.
ATT-03Thông báo cho phụ huynh
Phụ huynh được biết ngay khi con vắng học.
  • Given Điểm danh đã lưu với một học viên được đánh dấu vắng và phụ huynh đã đồng ý nhận thông báo qua Zalo
  • When Việc lưu hoàn tất
  • Then Trong vòng 2 phút, tin nhắn ZNS "Học viên [tên] vắng buổi [lớp] ngày [dd/MM] lúc [HH:mm]. Vui lòng liên hệ [chi nhánh] [SĐT]." được gửi đi; nếu Zalo gửi thất bại, hệ thống chuyển sang thông báo trong ứng dụng rồi email; trạng thái gửi được hiển thị trên phiếu điểm danh của buổi học.
ATT-04Quản trị chỉnh sửa một bản ghi
Giáo vụ sửa lại một lượt điểm danh sai.
  • Given Phiếu điểm danh đã được lưu
  • When Thay đổi trạng thái của một học viên sau ngày diễn ra buổi học, kèm lý do
  • Then Bản ghi được cập nhật, một mục nhật ký lưu lại trạng thái trước và sau, số dư gói buổi được tính lại; nếu thay đổi làm vắng chuyển thành có mặt, một tin nhắn "điều chỉnh" có thể được gửi thêm (tuỳ chọn).
ATT-05Theo dõi các buổi học chưa điểm danh
Quản trị xem được những buổi học nào chưa có điểm danh.
  • Given Các buổi học đã kết thúc hơn 2 giờ nhưng chưa có phiếu điểm danh được lưu
  • When Mở Điểm danh → Chưa điểm danh
  • Then Các buổi học được liệt kê theo giáo viên, kèm nút "Nhắc GV" (đẩy thông báo trong ứng dụng) và "Điểm danh thay"; vào 21:00 hằng ngày, giáo viên nhận nhắc nhở cho mọi buổi học trong ngày chưa điểm danh; quản lý chi nhánh nhận bản tổng hợp các buổi học chưa điểm danh quá 24 giờ.
ATT-06Theo dõi vắng học
Tư vấn tuyển sinh hoặc nhân sự chăm sóc học viên theo dõi các trường hợp vắng học lặp lại.
  • Given Học viên vắng 2 buổi liên tiếp hoặc 3 buổi trong 30 ngày (theo ngưỡng cấu hình của tenant)
  • When Lượt vắng thứ hai/thứ ba được lưu
  • Then Một công việc "Liên hệ phụ huynh: [tên] vắng N buổi" được tạo cho người phụ trách chăm sóc học viên (mặc định theo chi nhánh), hiển thị trong việc hôm nay; tab "Cần quan tâm" trong danh sách học viên cũng bao gồm học viên này.
ATT-07Học viên học thử và học bù trên phiếu điểm danh
Giáo viên biết được những học viên khách nào đang có mặt trong buổi học.
  • Given Buổi học có một lượt đặt học thử và một lượt đặt học bù
  • When Mở phiếu điểm danh
  • Then Các học viên này xuất hiện ở phần cuối phiếu với chip Học thử / Học bù và một ô ghi chú; đánh dấu có mặt sẽ cập nhật lượt đặt (PRD 01, PRD 03), và với học thử, hệ thống gợi ý một ghi chú nhanh gồm 3 lựa chọn (Phù hợp / Cần lớp thấp hơn / Cần lớp cao hơn) gửi cho tư vấn viên.
ATT-08Báo cáo
Quản lý xem lại chất lượng điểm danh.
  • Given Có khoảng ngày và chi nhánh
  • When Mở báo cáo điểm danh
  • Then Xem được tỷ lệ theo lớp (có mặt cộng muộn trên tổng số đã điểm danh), phân bố số phút đi muộn, số lượt vắng theo lý do, số buổi học chưa điểm danh theo giáo viên, và danh sách học viên có thể sắp xếp theo số lượt vắng; có thể xuất sang xlsx.

4Màn hình

Giáo viên: buổi học hôm nay (di động) /teach/today

Danh sách các buổi học trong ngày kèm giờ học, lớp, phòng, số học viên trong danh sách và một chip trạng thái (Chưa điểm danh / Đã điểm danh 11/12 / Đã lưu). Chọn để mở phiếu điểm danh. Các buổi học hôm trước chưa điểm danh được ghim lên đầu với màu vàng cam. Thanh tab dưới cùng: Hôm nay · Lịch tuần · Lớp của tôi · Tài khoản.

Phiếu điểm danh (di động và desktop) /teach/sessions/:id/attendance · /attendance/sessions/:id
┌─────────────────────────────────────────────┐ │ ← Movers 2A · T3 10/09 · 18:00–19:30 · P.201 │ │ Có mặt 10 · Muộn 1 · Vắng 1 · Có phép 0 │ ├─────────────────────────────────────────────┤ │ ○ Nguyễn An [Có mặt][Muộn][Vắng][Phép] │ │ Cần lưu ý: dị ứng đậu phộng │ │ ○ Trần Bình Muộn 10' [Có mặt][Muộn][Vắng][Phép] │ │ ○ Lê Chi Số dư: 2 buổi ... │ │ ── Khách ──────────────────────────────────── │ │ ○ Phạm Dũng Học thử [Có mặt][Vắng] ghi chú │ ├─────────────────────────────────────────────┤ │ Ghi chú buổi học (tuỳ chọn) │ │ [ Lưu điểm danh ] Gửi thông báo PH [x] │ └─────────────────────────────────────────────┘

Mỗi dòng gồm: ảnh đại diện, tên, các cờ đánh dấu (Cần lưu ý, số dư buổi thấp, sinh nhật hôm nay), thanh chọn phân đoạn gồm bốn trạng thái (vùng chạm cao 44 px), biểu tượng ghi chú theo từng học viên. Bộ đếm ở đầu trang cập nhật theo thời gian thực. Nút lưu luôn cố định. Sau khi lưu: phiếu tổng hợp hiển thị trạng thái gửi của các thông báo và nút "Sửa" trong 24 giờ không cần lý do (đối với giáo viên), sau đó cần lý do (đối với quản trị).

Các trạng thái hiển thị: khung chờ tải (loading skeleton); danh sách rỗng "Lớp chưa có học viên"; banner offline; xung đột "Buổi này đã được [tên] điểm danh lúc HH:mm" kèm tuỳ chọn xem lại.

Tổng quan điểm danh (desktop) /attendance

Các tab: Hôm nay · Chưa điểm danh · Theo lớp · Theo học viên · Báo cáo. Tab Hôm nay: bảng các buổi học trong ngày (giờ học, lớp, phòng, giáo viên, số học viên, đã điểm danh, số lượng có mặt/muộn/vắng/có phép, đã gửi thông báo) với thao tác Mở phiếu. Bộ lọc: chi nhánh, giáo viên, lớp.

Tab điểm danh của học viên /students/:id#attendance

Lịch theo tháng với một chip cho mỗi buổi học, tỷ lệ chuyên cần trong 30/90 ngày, bảng các lượt vắng (ngày, lớp, trạng thái, lý do, đã đặt học bù), nút + Thêm phép.

Biểu mẫu xin phép (modal) /students/:id/excuses/new

Các trường: buổi học (chọn từ các buổi học sắp tới hoặc theo khoảng ngày), lý do (Ốm / Việc gia đình / Đi học trường / Khác + văn bản), người báo (tên phụ huynh), kênh (Zalo, gọi điện, trực tiếp, cổng PH), công tắc đề xuất học bù.

5Quy tắc nghiệp vụ

  1. Mỗi buổi học có một phiếu điểm danh; bản ghi chỉ tồn tại cho học viên có trong danh sách lớp (đang học tại ngày đó, học thử, học bù). Học viên nhập học sau ngày đó không được thêm ngược lại.
  2. Trạng thái mặc định khi mở phiếu là có mặt; lưu với toàn bộ đều có mặt là hợp lệ và phổ biến.
  3. Muộn yêu cầu nhập số phút (1–120); muộn vượt ngưỡng cấu hình của tenant (mặc định 45 phút) vẫn tính là muộn, không tính là vắng.
  4. Giáo viên (chính hoặc dạy thay của buổi học) có thể điểm danh và chỉnh sửa trong vòng 24 giờ mà không cần lý do; sau thời hạn đó, việc chỉnh sửa cần quyền attendance.edit_any và một lý do.
  5. Trừ gói buổi: có mặt và muộn luôn bị trừ; vắng bị trừ theo cấu hình của tenant; có phép không bao giờ bị trừ; học bù bị trừ theo cờ của lượt đặt.
  6. Quy tắc thông báo theo từng trạng thái là cấu hình của tenant, với giá trị mặc định nêu ở mục 2; trong giờ im lặng 21:30–07:00, tin nhắn được giữ lại đến sáng, trừ trường hợp vắng học ở lớp học buổi tối thì gửi ngay (phụ huynh mong được biết ngay).
  7. Tỷ lệ chuyên cần = (có mặt + muộn) / (có mặt + muộn + vắng) trên các buổi học đã điểm danh.
  8. Buổi học bị hủy không có phiếu điểm danh; hủy một buổi học đã có phiếu điểm danh được lưu yêu cầu xóa phiếu trước (chỉ quản trị, có ghi nhật ký).

6Mô hình dữ liệu

Thực thểTrườngGhi chú
attendance_sheetid uuid; session_id (unique); school_id; class_id; marked_by_staff_id; marked_at; note; notify_guardians bool; present_count; late_count; absent_count; excused_count; version intnew
attendance_recordid uuid; sheet_id; session_id; student_id; roster_type enum(enrolled, trial, makeup); status enum(present, late, absent, excused); late_minutes int null; note; excuse_id null; consumed_session bool; notified_at null; notify_status enum(sent, failed, skipped) null; updated_by; updated_atunique (session_id, student_id)
attendance_record_historyid; record_id; from_status; to_status; reason; actor_id; created_atchi tiết nhật ký
excuseid; student_id; session_id null; date_from; date_to; reason_code enum(sick, family, school, other); reason_text; reported_by; channel; offer_makeup bool; created_by; created_atnew
attendance_policy (cấu hình tenant)absent_consumes bool; late_threshold_min; edit_window_hours; consecutive_absent_threshold; monthly_absent_threshold; notify: {present, late, absent, excused, correction}; quiet_hourslưu trong cấu hình trường

7Hợp đồng API

MethodPathRequest / responseStatus
GET/v3/school/sessions/{id}/attendance→ {session, sheet | null, roster: [{student, roster_type, flags, balance, prefilled_status, excuse}]}new
PUT/v3/school/sessions/{id}/attendance{records: [{student_id, status, late_minutes?, note?}], note?, notify_guardians, version?, client_saved_at?} → sheet with records and notify statuses; 409 STALE_VERSION; idempotent by (session_id, client_saved_at)new
PATCH/v3/school/attendance/records/{id}{status, late_minutes?, note?, reason} (reason required after edit window)new
DELETE/v3/school/sessions/{id}/attendanceadmin, auditednew
GET/v3/school/attendance/sessionsschool_id, date_from, date_to, class_id, staff_id, marked=false → sessions with countsnew
POST/v3/school/attendance/sessions/{id}/remind-teacherin-app pushnew
GET/POST/DELETE/v3/school/students/{id}/excuses{session_id | date_from, date_to, reason_code, reason_text, reported_by, channel, offer_makeup}new
GET/v3/school/students/{id}/attendancefrom, to → records + ratenew
GET/v3/school/attendance/reportschool_id, from, to, group_by=class|student|teacher → aggregates; format=xlsx for exportnew
GET/v3/school/me/sessions?date=teacher's sessions with sheet statusnew
GET/PUT/v3/teacher/school-configattendance_policy block addedextend
GET/v3/parent/learner/{id}/attendanceguardian viewnew

8Phân quyền

Mã quyềnownerbranch_manageracademic_adminteacheraccountantparent
attendance.viewtất cảchi nhánhchi nhánhbuổi của mìnhchi nhánh (chỉ xem)con của mình
attendance.markcócócóbuổi của mìnhkhôngkhông
attendance.edit_anycócócókhôngkhôngkhông
attendance.delete_sheetcócókhôngkhôngkhôngkhông
excuses.managecócócókhôngkhôngchỉ được yêu cầu
attendance.report, attendance.exportcóchi nhánhchi nhánhlớp của mìnhbáo cáokhông
attendance.policycókhôngkhôngkhôngkhôngkhông

9Sự kiện phân tích

Sự kiệnThuộc tính
attendance_sheet_openeddevice (mobile|desktop), minutes_from_start, roster_size
attendance_savedseconds_to_save, counts, offline_queued, notify
attendance_record_editedhours_after_session, by_role, from, to
attendance_notification_sentstatus, channel, outcome
excuse_createdreason_code, channel, offer_makeup
absence_followup_task_createdtrigger (consecutive|monthly)
unmarked_reminder_senthours_late

10Trường hợp biên

11Câu hỏi còn mở

← 03 Lớp học05 Tài chính →

Trường Số (truongso.net) · Nội bộ FLYER