Bảng điểm (Gradebook)

Gradebook là hệ thống chấm điểm tổng hợp cấp lớp — định nghĩa các cột điểm (GradeItem) với trọng số, sau đó nhập điểm từng học viên (manual) hoặc import từ kết quả thi (auto). Hệ thống tự tính điểm tổng kết theo trọng số.

Một dòng tóm tắt

Mỗi Batch có riêng các cột điểm (Giữa kỳ 30%, Cuối kỳ 50%, Bài tập 20% chẳng hạn). Bạn nhập điểm tay hoặc import từ ExamTest → hệ thống tự tính điểm tổng kết theo trọng số. Có cơ chế override để sửa điểm import + revert quay lại điểm gốc.

Khái niệm chính

Khái niệm	Mô tả
GradeItem	Cột điểm trong sổ điểm của Batch — vd: "Giữa kỳ", "Cuối kỳ"
Grade	Điểm cụ thể của 1 học viên × 1 cột (user × grade_item)
weight	Trọng số cột điểm (% trên tổng điểm — 0–100)
max_score	Điểm tối đa cột — vd: 10 hoặc 100
source_type	manual (Nhập tay), exam (Bài thi — lấy từ ExamTest) hoặc quiz (Bài quiz — lấy từ một quiz trong khoá)
source (Grade)	manual / auto (lấy tự động) / override (đã sửa)
final_grade	Điểm tổng kết = tổng các (score/max × weight)

Vào quản lý Gradebook

Mở trang chi tiết Batch → tab Bảng điểm (URL: /admin/batches/{id}/edit?activeRelationManager=...).

Tab Bảng điểm chỉ ở Edit page

Lifecycle actions (tạo cột, nhập điểm) chỉ hiện ở Edit page (/admin/batches/{id}/edit), không hiện ở View page. Browse batch không gây nhầm lẫn — mutations cô lập ở Edit.

Tạo cột điểm (GradeItem)

Tab Bảng điểm → header Tạo mới:

Trường	Mô tả
Tên cột	Vd: "Giữa kỳ", "Cuối kỳ", "Bài tập lớn"
Mô tả	Tuỳ chọn — text giải thích cho học viên (chưa surface)
Trọng số (weight)	% trên tổng điểm — 0–100. Tổng các cột nên = 100%
Điểm tối đa (max_score)	Vd: 10 cho thang 10, 100 cho thang 100
Nguồn điểm (source_type)	Nhập tay, Bài thi hoặc Bài quiz
Bài thi (exam_test_id)	Hiện khi nguồn là Bài thi — chọn ExamTest từ module Examination
Bài quiz	Hiện khi nguồn là Bài quiz — chỉ liệt kê quiz thuộc các khoá trong chương trình của lớp
Thứ tự (position)	Số nguyên — nhỏ trước. Dùng để sort cột trong sổ điểm

Pattern cột điểm phổ biến

• Trường truyền thống: Giữa kỳ 30% + Cuối kỳ 50% + Bài tập 20%
• Cohort dự án: Quizzes 20% + Bài tập 30% + Project 40% + Thuyết trình 10%
• Workshop ngắn: Pretest 10% + Bài tập thực hành 50% + Bài cuối khóa 40%

Tổng nên = 100% — UI cảnh báo nếu lệch.

Validation tổng trọng số

Footer của bảng GradeItems hiển thị: "Tổng trọng số: X% (Đạt / cần bằng 100%)". Cảnh báo trực quan khi tạo / sửa cột — tổng = 100% bạn được "Đạt".

Lệch 100% được không?

Hệ thống không bắt buộc tổng phải = 100%. Bạn có thể có 90% (10% không cộng vào tổng) hoặc 110% (rủi ro). Tuy nhiên báo cáo + final_grade dựa trên trọng số nguyên — final có thể vượt 100% nếu lệch dương.

Đề xuất: luôn = 100%. Nếu cohort thay đổi cấu trúc giữa kỳ, sửa weights cho tổng vẫn = 100%.

Nguồn điểm: Nhập tay, Bài thi, Bài quiz

Nguồn manual (Nhập tay)

Dùng khi:

• Bài tập do giảng viên chấm tay (vd: thuyết trình, project review).
• Điểm quy đổi từ nhiều quiz gộp lại (vd: 10 quiz tuần × 1 điểm) — một quiz đơn lẻ thì dùng nguồn Bài quiz bên dưới.
• Điểm đánh giá thái độ / chuyên cần.

Nguồn exam (Bài thi từ Examination module)

Dùng khi:

• Có ExamTest chính thức trong module Examination (do Course Manager / Tenant Admin tạo).
• Học viên thi → điểm tự cập nhật vào sổ.

Yêu cầu:

• Module Examination đang bật. Nếu tắt, dropdown chọn ExamTest disabled — phải đổi cột về manual hoặc bật module.

Phụ thuộc tuỳ chọn

Module TrainingManagement không bắt buộc Examination. Nếu Examination tắt, GradeItem exam_test_id vẫn lưu trong DB nhưng action Nhập từ bài thi báo lỗi. UI ẩn dropdown khi tạo mới.

Nguồn quiz (Bài quiz trong khoá)

Dùng khi một quiz trong khoá học của chương trình là một đầu điểm của lớp (vd: Kiểm tra giữa phần).

• Khi tạo cột, chọn nguồn Bài quiz rồi chọn quiz. Danh sách chỉ gồm quiz thuộc các khoá trong chương trình của lớp.
• Trên dòng cột điểm, bấm Nhập từ bài quiz để kéo điểm về. Điểm được quy đổi từ thang 0–100 về Điểm tối đa của cột.
• Lượt làm nào được lấy là do người soạn quiz cấu hình ở chính bài quiz (lượt tốt nhất hoặc lượt gần nhất) — sổ điểm không tự lấy lượt cao nhất, để con số trong sổ khớp với con số học viên thấy ở bài quiz.
• Học viên chưa nộp lượt nào thì ô để trống, không bị ghi 0.
• Quyền dùng chung với nguồn bài thi: ai nhập được từ bài thi thì nhập được từ bài quiz.
• Như nguồn bài thi, ô bạn đã sửa tay được giữ nguyên khi nhập lại.

Nhập điểm — trang Enter Grades

Mỗi GradeItem có action Nhập điểm:

1. Bảng GradeItems → row → Nhập điểm.
2. Mở trang /admin/batches/{id}/grade-items/{item_id}/enter-grades.
3. Bảng học viên × ô điểm:
   • Mỗi row: tên + email + ô input điểm + ô note.
   • Học viên ở trạng thái active, completed, suspended đều hiển thị (xem Batch Enrollment Status).
   • transferred_out, dropped không hiển thị (đã rời lớp).
4. Nhập điểm — validation: 0 ≤ score ≤ max_score.
5. Nhập note (tuỳ chọn — vd: "Bonus tham gia").
6. Click Lưu điểm.

Hành vi save

• Ô trống → grade null (chưa chấm).
• Ô có số → tạo/cập nhật Grade record.
• Validation fail → toast error, các điểm hợp lệ vẫn được lưu, ô lỗi không lưu.

Nguồn của điểm sau khi save (Grade.source)

Logic trong GradebookService::setManualScore:

Trạng thái cũ	Trạng thái mới
Chưa có Grade	manual
Đã có manual	giữ manual
Đã có auto (từ exam)	đổi thành override, giữ auto_score (snapshot điểm gốc)
Đã có override	giữ override, cập nhật score mới

→ Nhập tay đè lên điểm auto-import → trở thành override (có dấu vết).

Import điểm từ ExamTest

Cho cột source_type = exam:

1. Bảng GradeItems → row → Nhập từ bài thi.
2. Modal confirm.
3. Hệ thống chạy GradebookService::importFromExam:
   • Lấy danh sách học viên on-roster (active, completed, suspended).
   • Với mỗi học viên: tìm best ExamSession đã hoàn thành cho exam_test_id.
   • Quy đổi điểm từ thang 0–100 (Examination) sang max_score của cột.
   • Tạo/update Grade với source = auto, auto_score = điểm đã quy đổi.
   • Skip học viên đã có Grade override (không clobber).
   • Skip học viên không có ExamSession.
4. Toast result: "Đã nhập :imported điểm. :overrides ô đã chỉnh được giữ nguyên. :skipped học viên chưa có bài thi."

Quy đổi điểm thi → điểm cột

ExamSession trả score thang 0–100 (theo cấu hình passed_score trong Examination).

GradebookService quy đổi: final_score = (raw_score / 100) × max_score.

VD: học viên thi được 85% — cột có max 10 → ghi 8.5.

Re-import sau update đề thi

Tình huống: Tenant Admin sửa đáp án sai trong đề thi → học viên thi lại. Click Nhập từ bài thi lại:

• Ô auto được cập nhật theo điểm mới (best score).
• Ô override (trainer đã chỉnh) giữ nguyên — không clobber.
• Ô chưa import (skipped no_session) thử lại.

→ Re-import an toàn để refresh data.

Override + Revert

Override

Khi nhập tay đè lên điểm auto-import:

• source đổi auto → override.
• auto_score giữ snapshot điểm gốc (từ exam).
• UI hiển thị badge: "Đã sửa (gốc: 8.5)".

Override workflow

Tình huống: học viên A báo "câu thi 5 trong đề chấm sai, cần xem lại". Trainer xem + đồng ý:

1. Vào Nhập điểm cho cột tương ứng.
2. Nhập điểm mới cho A.
3. Save → điểm A chuyển override, auto_score giữ điểm cũ.

Lịch sử rõ — sau này admin audit thấy điểm đã được override + ai làm + khi nào.

Revert override

Khi muốn quay lại điểm gốc:

1. Bảng nhập điểm → row học viên đã override → action Khôi phục điểm gốc.
2. Confirm.
3. score ← auto_score, source về auto.

Lỗi nếu:

• Grade hiện không phải override → "Điểm này không phải bản chỉnh sửa."
• auto_score null → "Không có điểm gốc để khôi phục." (hiếm — chỉ khi data corruption)

Điểm tổng kết (Final Grade)

GradebookService::finalGradeFor($batch, $user) tính:

final_grade = Σ (score_i / max_score_i × weight_i)

Với mỗi i = một GradeItem có Grade.score ≠ null.

Cột chưa chấm = không tính

Nếu học viên thiếu một cột (chưa nhập), cột đó bị bỏ qua trong công thức — NOT renormalized.

Hệ quả: học viên có 80% giữa kỳ + 0% cuối kỳ (chưa thi) → final = 80% × 30% = 24%, không phải 80%.

→ Đây là chủ đích — phản ánh việc học viên thiếu thi cuối kỳ thật sự ảnh hưởng kết quả.

Hiển thị Final Grade

Tab Bảng điểm → nút Xem bảng điểm cả lớp (URL /admin/batches/{id}/gradebook, Trainer Panel có bản tương ứng) mở ma trận học viên × cột điểm: mỗi ô hiện điểm kèm nhãn nguồn, cột cuối là Điểm tổng kết, dòng cuối là Điểm trung bình theo cột. Trang chỉ đọc.

Điểm tổng kết cũng hiện trong hồ sơ xem nhanh của học viên ở tab Học viên của lớp, và trên trang Bảng điểm của học viên (xem câu hỏi bên dưới).

Quan hệ với các tính năng khác

Với Examination module

• GradeItem exam source phụ thuộc exam_test_id.
• Re-import lấy ExamSession.score theo Modules\Examination\Models\ExamSession.
• Module Examination tắt → import disabled.

Chốt sổ bảng điểm đợt thi

Bảng điểm của một đợt thi (khác với Gradebook của lớp) có thêm cơ chế chốt sổ: Lịch thi → Báo cáo đợt thi → khối Chốt sổ bảng điểm.

Chốt sổ chụp lại bảng điểm và ghi một vân tay. Sau đó, mọi thay đổi điểm — kể cả sửa hợp lệ sau phúc khảo — đều hiện ra thành từng dòng trên chính trang báo cáo đó: ai đổi từ điểm nào sang điểm nào, ai có thêm, ai biến mất, và ngưỡng đạt có bị đổi hay không.

Chốt sổ KHÔNG khoá điểm

Điểm vẫn sửa được. Thứ chốt sổ mang lại là tính hiển lộ, không phải sự ngăn chặn.

Thứ tự đúng: chốt sổ đợt thi TRƯỚC, import vào Gradebook SAU

Chốt sổ khi cửa sổ thi còn mở hoặc còn người đang làm bài sẽ bị hệ thống từ chối (và nói rõ lý do). Chốt xong rồi mới import sang cột điểm của lớp thì con số trong Gradebook có một chứng từ đứng sau nó.

Quyền seal_exam_schedule chỉ cấp cho admin — cố ý không cấp cho course_manager, vì người soạn đề và chấm bài không nên là người chốt sổ chính bảng điểm mình vừa tạo ra. Chi tiết: Liêm chính học thuật.

Với BatchEnrollment

• Bảng nhập điểm filter active + completed + suspended — học viên transferred_out / dropped ẩn.
• Khi học viên drop giữa kỳ, điểm cũ vẫn lưu (không xoá Grade); chỉ ẩn khỏi UI nhập tiếp.
• Khi học viên transfer sang lớp mới: điểm cột cũ vẫn lưu trong lớp cũ; lớp mới có cột điểm riêng (không kế thừa).

Với Trainer Panel

Trainer cũng thấy tab Bảng điểm trong Trainer Panel (nếu được Tenant Admin gán quyền). Trang nhập điểm có ở cả 2 panel — trải nghiệm tương đương.

Phân chia work

• Trainer: nhập điểm các bài tập / project / thuyết trình họ chấm.
• Training Manager: cấu hình cột điểm + trọng số + import từ exam (workflow định kỳ).
• Tenant Admin / Course Manager: cấu hình ExamTest (chỉ làm 1 lần).

Với Certificate

Certificate hiện tại không tự gắn với final_grade. Học viên hoàn thành 100% activities → cấp chứng chỉ, bất kể điểm cao thấp. Nếu muốn certificate "có điều kiện điểm" — đề xuất Tenant Admin custom.

Với Notifications

Hiện không có notification tự động "điểm đã có". Nếu muốn báo học viên, manually gửi qua Notifications module hoặc batch announcement.

Workflow điển hình

Cohort 12 tuần với 4 cột điểm

Tuần 1 — set up:

1. Tạo Batch "Cohort 2026-04".
2. Trong tab Bảng điểm, tạo 4 cột:
   • Quiz tuần (10 quizzes) — manual, 20%, max 10.
   • Giữa kỳ — exam (link ExamTest "Mid-term"), 25%, max 10.
   • Bài tập lớn — manual, 25%, max 10.
   • Cuối kỳ — exam (link ExamTest "Final"), 30%, max 10.
3. Tổng = 100% ✓.

Tuần 6 (giữa kỳ): 4. Học viên thi mid-term qua module Examination. 5. Vào tab Bảng điểm → cột Giữa kỳ → Nhập từ bài thi. 6. Toast: "Đã nhập 25/25 điểm." 7. Học viên A báo điểm sai → trainer xem + override điểm A.

Tuần 8 — chấm bài tập: 8. Trainer / Training Manager vào cột Bài tập lớn → Nhập điểm → nhập 25 ô điểm + note.

Tuần 12 (cuối kỳ): 9. Tương tự: nhập từ exam Cuối kỳ. 10. Quiz tuần — Trainer ghi tổng kết tay (vd: 10 quiz × 1 điểm).

Cuối kỳ: 11. Final grade tự tính qua service. 12. Bulk graduate học viên đã pass. 13. Chuyển Batch → Completed (auto-complete enrollments).

Câu hỏi thường gặp

Tổng weight của tôi 95% (1 cột chưa nhập trọng số) — final tính sao? Final dựa trên cột đã nhập điểm. Cột thiếu weight = 0 → không cộng vào tổng. UI cảnh báo lệch 100% nhưng vẫn tính.

Học viên thi lại exam — điểm có tự cập nhật không? Cần manually click "Nhập từ bài thi" lại — service lấy best score mới. Không tự realtime.

Tôi xoá cột điểm có mất Grade không? Có — cascade xoá tất cả Grade trên cột đó. Không thể revert. Trước khi xoá, export điểm ra Excel nếu cần backup.

Học viên transfer sang lớp khác — điểm cũ? Lớp cũ giữ nguyên điểm. Lớp mới: bắt đầu trắng (cột điểm khác hoặc cùng tên cũng là entity riêng). Nếu muốn carry-over, manually nhập tay điểm tương ứng vào lớp mới — không có tool tự sync.

Có thể bulk import điểm từ CSV không? Hiện chưa có UI. Workaround: dùng SQL/seeder hoặc đề xuất tính năng. (Import từ ExamTest đã đáp ứng phần lớn nhu cầu.)

Học viên xem điểm ở đâu trong Learnspace? {#hoc-vien-xem-diem} Ở mục Bảng điểm (/learnspace/grades, trang Bảng điểm của tôi). Trang liệt kê mỗi lớp học viên thuộc về và có ít nhất một cột điểm: từng cột kèm trọng số và điểm của chính họ, cộng Điểm tổng kết — cùng con số với màn hình giáo vụ.

• Ô chưa có điểm hiện Chưa chấm, không hiện 0. Chưa cột nào có điểm thì điểm tổng kết để trống.
• Khi mới chấm một phần, trang ghi rõ "Mới chấm X/100 trọng số — điểm này chưa phải điểm cuối cùng", để học viên không đọc nhầm điểm dở dang là kết quả kém.
• Tổng trọng số các cột khác 100% thì trang cảnh báo học viên rằng điểm tổng kết chưa phải điểm trên thang 100 — thêm lý do để giữ tổng = 100%.

Final grade tính ra số thập phân — có cách hiển thị thang chữ A/B/C? Không trực tiếp. Tenant Admin có thể cấu hình mapping ngoài hoặc tạo custom report. Tự maintain mapping (vd: ≥85 = A, 70–84 = B, ...).

Tôi nhập điểm cho cột exam (sourced) trước khi import — có overwrite khi import? Không. Import skip rows đã có override. Tuy vậy manual direct (chưa import) sẽ được cập nhật khi import → cẩn thận thứ tự thao tác.

Tôi có thể delegate quyền "Nhập từ bài thi" cho người khác không phải Training Manager? Có — Tenant Admin có thể cấp quyền chạy nút "Nhập từ bài thi" tách riêng với quyền sửa cột điểm. Yêu cầu Tenant Admin nếu nhu cầu.