Lớp đào tạo (Batches)

Batch là một đợt mở của Program — định nghĩa cohort cụ thể: thời gian, sĩ số, trainer, học viên. Đây là entity bạn thao tác nhiều nhất trong vai trò Training Manager.

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

Tạo Batch → chọn Program nguồn → đặt thời gian + sĩ số → attach trainer (Lead/Assistant/Mentor) → attach học viên → sinh buổi học → đặt lộ trình mặc định → cohort sẵn sàng vận hành.

Vào quản lý Batches

Sidebar → Đào tạo → Lớp học (URL: /admin/batches).

Bảng list hiển thị:

• Tên lớp + mã lớp (code)
• Chương trình liên kết
• Trạng thái (Nháp / Đang hoạt động / Tạm dừng / Đã kết thúc / Đã lưu trữ)
• Sĩ số tối đa
• Số học viên hiện tại
• Ngày bắt đầu / Ngày kết thúc

Filter: trạng thái, program, khoảng ngày.

Tạo Batch mới

1. Click Tạo mới.
2. Điền thông tin lớp:
   • Tên lớp (vd: "Web Full-stack Cohort 2026-04")
   • Mã lớp (code) — duy nhất trong tenant; auto-generate nếu để trống
   • Chương trình — chọn Program đã tạo (xem Programs)
   • Ngày bắt đầu / Ngày kết thúc — quan trọng cho Catch-up + báo cáo
   • Sĩ số tối đa (max_students) — giới hạn enrollment
   • Lộ trình mẫu mặc định — chọn template do course_manager đã tạo (xem Lộ trình mặc định bên dưới)
3. (Tuỳ chọn) Tick "Tạo buổi học từ template của chương trình" — nếu Program có template buổi học mẫu, hệ thống tự sinh BatchSession sau khi lưu.
4. Click Lưu → Batch vào trạng thái Nháp.

Một số trường không sửa được sau khi tạo

• program_id — chuyển program sẽ phá vỡ enrollments.
• Một số tenant cấu hình code immutable.

Cần đổi → tạo Batch mới + chuyển học viên thủ công.

Vòng đời (Status)

Batch có 5 trạng thái:

Status	Ý nghĩa	Cho phép
Nháp (draft)	Vừa tạo, chưa active	Cấu hình tự do, chưa enroll học viên
Đang hoạt động (active)	Cohort đang chạy	Enroll học viên, sinh buổi, attendance
Tạm dừng (paused)	Lớp tạm hoãn	Không enroll mới được; trainer vẫn truy cập
Đã kết thúc (completed)	Cohort đã xong	Read-only, không sửa
Đã lưu trữ (archived)	Đóng vĩnh viễn	Read-only, ẩn khỏi list mặc định

Chuyển trạng thái

Header trang Batch có nút Chuyển trạng thái:

• Modal hiện danh sách trạng thái kế tiếp hợp lệ (state machine).
• Chọn → confirm → status đổi.

Quy tắc transition:

Nháp ──► Đang hoạt động ──► Tạm dừng ↔ Đang hoạt động
                              │
                              └──► Đã kết thúc ──► Đã lưu trữ

TIP

Đang hoạt động → Đã kết thúc thường thực hiện vào ngày end_date. Nếu lớp kết thúc sớm, chuyển sớm — hệ thống không tự chuyển.

Đóng lớp không chỉ là dọn dẹp

Trạng thái lớp quyết định việc gửi email đốc thúc học tập: chừng nào lớp còn Đang hoạt động, học viên vẫn nhận nhắc ôn tập / nhắc quay lại học như lớp đang chạy; chuyển sang Đã kết thúc thì các email đó tự ngừng cho cả lớp. Lớp quá end_date 3 ngày mà chưa đóng sẽ sinh cảnh báo vận hành "Lớp quá hạn chưa đóng". Chi tiết: Chính sách email học viên.

Tab Thông tin (chi tiết Batch)

Vào trang một Batch → các tab:

1. Thông tin

Read-write metadata cơ bản (như form tạo). Có thể sửa:

• Tên lớp, mã, mô tả
• start_date, end_date, max_students
• Lộ trình mặc định

2. Khoá học

Read-only — danh sách khoá thuộc Program (không sửa được từ đây; phải vào Program để chỉnh).

Cột:

• Tên khoá
• Thứ tự
• Số module

Click khoá học → vào trang Tiến độ khoá học cho cặp (Batch × Course) (xem Theo dõi & báo cáo).

3. Buổi học

Quản lý các BatchSession của lớp — xem Buổi học của lớp.

4. Giảng viên

Attach/detach trainer với vai trò Lead/Assistant/Mentor — xem Đội ngũ giảng viên bên dưới.

5. Học viên

Quản lý học viên trong lớp — xem Học viên trong lớp bên dưới.

6. Bảng điểm (Gradebook)

Định nghĩa các cột điểm (GradeItem) cho lớp + nhập điểm. Hỗ trợ:

• Cột manual (nhập tay) hoặc exam (import từ ExamTest).
• Trọng số per cột (% trên 100).
• Override điểm + revert.
• Tính điểm tổng kết theo trọng số.

Chi tiết: Bảng điểm.

7. Nhật ký (read-only cho Training Manager)

Đọc nhật ký mà trainer đã ghi. Training Manager không tạo log từ đây (đó là kênh trainer-side). Có thể xem để theo dõi tình hình lớp.

8. Sổ điểm danh

Tab Sổ điểm danh (có ở cả trang quản trị và Trainer Panel) là ma trận học viên × buổi: mỗi ô là trạng thái điểm danh của học viên ở buổi đó, cột tỉ lệ chuyên cần ở bên phải. Chỉ đọc — bấm tiêu đề một buổi để mở trang điểm danh của buổi đó và sửa ở đó.

• Bộ lọc khoảng ngày ngay trên ma trận (Toàn bộ / tuần này / 4 tuần gần nhất / tháng này / 3 tháng gần nhất / tuỳ chọn).
• Nút xuất CSV / XLSX xuất đúng khoảng đang xem, mỗi buổi một cột.
• Buổi đã diễn ra mà học viên không có bản ghi điểm danh được tính là vắng.

9. Dashboard

Tab Dashboard hiển thị các widget thống kê batch:

• BatchAttendanceStatsOverview — tổng tỉ lệ điểm danh, số buổi đã diễn ra, lượt có mặt, số học viên cần chú ý.
• BatchAttendanceTrendChart — xu hướng điểm danh theo tuần.
• BatchStatusBreakdownChart — phân loại trạng thái (active/suspended/dropped/completed) của học viên trong lớp.
• BatchAtRiskStudents — danh sách học viên dưới 70% rate hoặc vắng liên tiếp ≥ 3.

Tab này có cả ở Tenant Admin Panel và Trainer Panel — cùng widgets.

Đội ngũ giảng viên

Attach trainer

Trong tab Giảng viên:

1. Click Thêm giảng viên.
2. Chọn User (autocomplete — chỉ hiện user trong tenant). Lưu ý: user phải có role trainer hoặc teaching_assistant để vào Trainer Panel sau khi attach.
3. Chọn Vai trò batch (xem Phối hợp đội ngũ giảng viên):
   • Giảng viên chính (Lead)
   • Trợ giảng (Assistant)
   • Mentor
4. (Tuỳ chọn) Thêm Ghi chú.
5. Click Lưu.

Constraint UNIQUE

Mỗi user chỉ có 1 vai trò trong 1 lớp tại một thời điểm. Lỗi "Giảng viên đã được phân công vai trò này trong lớp" nếu trùng.

Đổi vai trò

Click vào dòng trainer → Cập nhật → đổi role → Lưu.

Detach

Click Gỡ khỏi lớp → confirm. Trainer không thấy lớp này trong Trainer Panel nữa. Nhật ký họ đã viết + comment vẫn giữ.

Học viên trong lớp

Lifecycle actions chỉ ở Edit page

Tab Học viên ở Edit page (/admin/batches/{id}/edit) có đầy đủ lifecycle actions (Suspend, Resume, Drop, Complete, Transfer). View page (/admin/batches/{id}) chỉ read-only — browse không có nút mutate.

Attach học viên

Cách 1 — Tìm cá nhân

Tab Học viên → Đính kèm:

1. Search theo tên / email.
2. Tick các user → Đính kèm.

Cách 2 — Theo Group

Tick một Group → tất cả thành viên Group được attach (snapshot tại thời điểm).

Cách 3 — Nhập hàng loạt từ Excel/CSV

Tab Học viên → nút Nhập học viên ở đầu bảng → trang Nhập học viên từ Excel:

1. Bấm Tải file mẫu nếu cần. File nhận .xlsx hoặc .csv, dòng đầu là tiêu đề cột. Chỉ bắt buộc cột Email; nhận thêm Họ và tên và Số điện thoại (chỉ dùng khi tạo tài khoản mới).
2. Chọn có Gửi email đặt mật khẩu cho tài khoản mới hay không. Tắt đi nếu bạn muốn tự phát mật khẩu tạm.
3. Bấm Đọc file & đối chiếu → bảng xem trước cho từng dòng một kết quả: Tạo mới + ghi danh, Ghi danh, Đã trong lớp, hoặc Lỗi (kèm lý do).
4. Bấm Nhập N dòng hợp lệ. Dòng lỗi bị bỏ qua, các dòng đúng vẫn nhập.

• Email đã có tài khoản thì chỉ được ghi danh vào lớp, không tạo lại. Người đã ở trong lớp bị bỏ qua — chạy lại cùng một file không nhân đôi ai.
• Tài khoản mới nhận vai trò mặc định đặt ở Cài đặt → Chung → Tài khoản.
• Nếu tắt email đặt mật khẩu, bước cuối hiện Mật khẩu tạm của tài khoản vừa tạo (có Chép tất cả, Tải CSV). Danh sách này chỉ hiện một lần — rời trang là không xem lại được.

Trang Import học viên mô tả thêm về nhập học viên.

Tự động sinh enrollment + Student record

Khi học viên được attach vào Batch:

1. Tạo batch_user với status active, joined_at = now().
2. Listener EnsureStudentForBatchMember chạy: User chưa có Student record → tự tạo với student_code auto-generate. Xem Quản lý học viên.
3. BatchCourseEnrollmentSync tạo Enrollment cho mỗi cặp (học viên, khoá) trong program.courses.
4. Học viên thấy các khoá xuất hiện trong Khoá học của tôi.
5. Nếu có lộ trình mặc định, tự động clone template thành lộ trình cá nhân.

Đồng bộ chạy nền

Quá trình này bất đồng bộ — học viên có thể thấy khoá xuất hiện sau vài giây / phút (tuỳ tải queue). Refresh nếu cần.

Bảng học viên — cột & filter

Cột chính:

Cột	Nguồn
Tên	users.first_name + last_name (searchable)
Email	users.email
Trạng thái	batch_user.status (5-state badge — màu theo enum)
Tỉ lệ điểm danh	AttendanceReportService::userRate() — color-coded ≥85 xanh, ≥70 vàng, else đỏ
Tiến độ từng khoá	enrollments.progress — toggleable per khoá Program
Joined at	batch_user.joined_at

Phía trên bảng là 6 thẻ thống kê bấm được — bấm một thẻ để lọc danh sách: Tổng học viên, Đang học (kèm tiến độ trung bình), Tạm dừng, Hoàn tất, Đã rời lớp (tách số thôi học / chuyển lớp), Chuyên cần dưới 70% (trên số học viên đang học).

Bộ lọc: Trạng thái, Tỉ lệ điểm danh (dưới 70% / từ 70% đến dưới 85% / từ 85% trở lên), Tiến độ chương trình (Chưa bắt đầu / Đang học dở / Đã hoàn thành), Ghi danh từ ngày – đến ngày.

Bấm Xem hồ sơ học viên trên một dòng để mở nhanh hồ sơ (thông tin học vụ, trạng thái trong lớp này, điểm danh, tiến độ từng khoá, điểm tổng kết, nhật ký lớp có nhắc tới học viên) mà không rời trang lớp.

Status hiển thị là per-batch

Cột Trạng thái đọc batch_user.status (per-batch lifecycle: active/suspended/transferred_out/dropped/completed) — không phải student.status (school-level: active/graduated/withdrawn). Suspend/Drop/Transfer/Complete làm badge này thay đổi.

Lifecycle actions (Edit page only)

Mỗi row có action menu:

Action	Khi nào hiện	Tác dụng
Tạm dừng (Suspend)	status = active	status → suspended, giữ row
Khôi phục (Resume)	status = suspended	status → active
Cho thôi học (Drop)	active hoặc suspended	status → dropped, exited_at set, vĩnh viễn
Hoàn tất (Complete)	status = active	status → completed, exited_at set
Chuyển lớp (Transfer)	status = active	Atomic transfer sang batch khác — xem Chuyển lớp
Gỡ (Detach — Filament default)	bất kỳ	Xoá row — không audit. Dùng khi data correction

Quy tắc đề xuất: dùng Drop / Complete (audit trail), tránh Detach trừ khi sửa nhầm.

Chi tiết flow: xem Ghi danh & Vòng đời ghi danh.

Bulk lifecycle actions

Tick nhiều rows → BulkActionGroup:

• Suspend đã chọn (1 modal lý do dùng chung)
• Drop đã chọn
• Complete đã chọn

Transfer không có bulk action (mỗi transfer cần dest batch riêng).

Xuất danh sách học viên

Header tab Học viên → Xuất danh sách:

1. Modal: chọn định dạng CSV hoặc XLSX.
2. File chứa: tên, email, phone, ngày tham gia, tiến độ từng khoá trong Program.
3. Tải về.

Lộ trình mặc định

Trường Lộ trình mẫu mặc định trên Batch:

• Chọn một RoadmapTemplate (do course_manager tạo).
• Mỗi học viên mới attach sẽ được tự động clone template → lộ trình cá nhân.
• Học viên cũ không bị ảnh hưởng (không retroactive).

Workflow điển hình

1. course_manager tạo template "Lập trình Web 12 tuần" (lộ trình bài học theo thứ tự).
2. Bạn (Training Manager) đặt template này làm default cho Batch "Cohort 2026-04".
3. Học viên mới vào Batch → nhận thông báo trong chuông "Bạn có lộ trình mới cho lớp X", bấm vào là mở thẳng lộ trình. Trước đây lộ trình xuất hiện im lặng nên nhiều người không biết mình đã có.
4. Học viên có thể "Điều chỉnh với AI" để cá nhân hoá thêm.

Lộ trình được giao đến ở trạng thái NHÁP, và nháp vẫn được tính

Lộ trình clone tự động ở trạng thái nháp cho tới khi học viên hoàn thành bài đầu tiên. Nháp vẫn được các màn hình "một lộ trình duy nhất" (Kế hoạch hôm nay, widget, lời nhắc) chọn tới — đó chính là người chưa bắt đầu và cần được dẫn vào.

Nhưng nếu học viên đã có lộ trình tự tạo và đã đặt nó làm lộ trình chính, lựa chọn của họ thắng: lộ trình lớp bạn giao sẽ không phải là thứ hiện trên Kế hoạch hôm nay của họ. Đây cũng là lộ trình mà Kế hoạch bắt kịp của trainer áp lên — xem Cá nhân hoá (Trainer) → Kế hoạch bắt kịp.

WARNING

Yêu cầu module LearningRoadmap đã bật. Nếu không thấy field này, Tenant Admin chưa bật module.

Tạo lớp từ Program template

Nếu Program đã có buổi học mẫu (Program Session Template — xem Programs → Template buổi học):

Khi tạo Batch

Tick "Tạo buổi học từ template của chương trình" trong form:

1. Bạn vẫn nhập start_date.
2. Sau khi lưu, hệ thống tự sinh tất cả BatchSession dựa vào:
   • template.day_offset + start_date → batch_session.starts_at ngày
   • template.time → giờ bắt đầu
   • template.duration_minutes → ends_at
3. Tất cả buổi tạo ra ở status Đã lên lịch, copy mode, location, meeting_url từ template.

Sau khi đã tạo Batch

Header trang Batch → Tạo từ template chương trình (chỉ hiện khi Program có template):

1. Modal hiện preview các buổi sẽ tạo (số ngày lệch + tiêu đề).
2. Confirm → tạo hàng loạt.

WARNING

Yêu cầu Batch đã có start_date. Nếu chưa, lỗi "Lớp học cần có ngày bắt đầu trước khi tạo từ template."

Quan hệ với các module khác

Với UserManagement (Groups)

Bạn có thể attach Group vào Batch (snapshot — không sync tự động sau đó). Group là cách gom nhanh nhiều user khi attach.

Với LearningRoadmap

• Đặt template làm default → tự clone cho học viên mới.
• Trainer trong Trainer Panel có thể áp Catch-up hoặc Override cho từng học viên — không phá lộ trình bạn đã set.
• Học viên cũng tự đặt hạn và tự rút gọn lộ trình được ngay trên trang lộ trình của họ, không cần trainer. Cùng cơ chế, cùng chỗ lưu — nên con số tiến độ bạn nhìn thấy có thể đã là con số sau khi học viên tự rút gọn.

Với CompetencyFramework

• Bản đồ năng lực của lớp là một nút trên trang lớp — có ở cả Trainer Panel lẫn trang quản trị (/admin → Lớp học → mở lớp → Bản đồ năng lực; quản lý đào tạo có sẵn quyền xem). Nút hiện theo quyền xem bản đồ; bản đồ chỉ có dữ liệu khi các khoá học của lớp đã gắn khung năng lực — gắn khung vào chương trình thì không đủ. Bản đồ dùng dữ liệu lớp, và có hai con số: lưới ô là độ phủ (đã đi qua bao nhiêu nội dung), cột "Mức nắm của lớp" là khả năng trả lời đúng. Ô xanh kèm mức nắm thấp nghĩa là cả lớp đã học xong mà không ai hiểu — tín hiệu về nội dung, không phải về học viên.
• Học viên trong lớp còn thấy so sánh ẩn danh với lớp trên trang Năng lực của họ (theo khoảng 10 điểm, chỉ hiện khi lớp có ≥ 10 người đang học). Không có tên, không có email — nó không phải bảng xếp hạng.

Với SocialLearning (bảng tin lớp)

Khi tổ chức bật bảng tin, form lớp có ô Bật bảng tin. Bật lên sẽ hiện thêm ô Người phụ trách cộng đồng: những người này nhận cảnh báo khi có bài hoặc bình luận mới trong bảng tin của lớp. Cảnh báo chỉ được gửi khi quản trị đã bật luật cảnh báo tương ứng ở mục cảnh báo vận hành.

Với Notifications

Khi học viên được attach:

• Auto-send email "Bạn đã được thêm vào lớp X" (template tuỳ biến trong Notifications).
• Notification in-app + bell.

Với Ecommerce

Không trực tiếp. Học viên mua subscription không tự vào Batch — đó là 2 kênh enrollment khác nhau:

• Subscription/Group → quyền vào khoá.
• Batch attach → quyền vào khoá + lịch buổi học + trainer.

Một học viên có thể có cả hai: Subscription để học self-paced + Batch để học theo cohort.

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

Tạo Batch trùng tên có sao không? Tên không bắt buộc unique — nhưng code thì unique. Đặt tên rõ ràng (ngày + cohort) để dễ phân biệt trên list.

Tôi attach 200 học viên cùng lúc — system có chậm không? Sync chạy queue background. UI trả về ngay, nhưng học viên có thể thấy khoá xuất hiện sau 30 giây – vài phút. Theo dõi Horizon nếu queue ùn.

Học viên cần rút lớp giữa kỳ — phải làm sao? Detach họ khỏi tab Học viên. Họ mất quyền truy cập khoá thuộc Program (qua Batch). Tiến độ học giữ nguyên. Nếu cần hoàn tiền, xử lý qua Ecommerce/Finance role.

Có thể chuyển học viên giữa 2 Batch? Detach lớp cũ + attach lớp mới. Tiến độ học giữ. Nếu hai lớp dùng cùng Program → smooth; nếu khác Program → khoá có thể overlap hoặc gap.

Tôi muốn xem lại nhật ký của lớp đã kết thúc? Tab Nhật ký vẫn hiển thị (read-only) khi Batch ở trạng thái Completed/Archived.

Cần "đông y" 50 lớp một lúc — có batch import? Hiện không có "import Batches CSV" trong UI. Cách tạm: dùng API hoặc admin tools (Tenant Admin can thiệp DB). Đề xuất tính năng nếu nhu cầu thường xuyên.

Status "Tạm dừng" có gửi email cho học viên không? Không tự động. Nếu cần thông báo, dùng module Notifications gửi broadcast.

Khi xoá Batch, tiến độ học viên có mất không? Soft delete giữ FK. Hard delete: học viên mất enrollment (qua Batch) nhưng tiến độ học (user, course) riêng vẫn còn — học viên có thể được Tenant Admin can thiệp khôi phục enrollment thủ công.