Ghi danh & Vòng đời ghi danh (Enrollments)

Ghi danh (Enrollment) trong context Training Manager có 2 lớp:

1. batch_user — bản ghi (batch, user) với lifecycle 5 trạng thái: active / suspended / transferred_out / dropped / completed.
2. enrollments — bản ghi (course, user) cấp Course (tự sinh từ batch_user khi user thuộc Batch).

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

Khi attach học viên vào Batch → tạo batch_user status active + auto-sync enrollments cho mọi khoá thuộc Program. Lifecycle batch_user (Suspend / Drop / Transfer / Complete) chỉ ảnh hưởng status; bản ghi gốc giữ nguyên cho audit. Tiến độ học gắn (user, course) → không mất khi transfer / drop.

Phân biệt batch_user vs enrollments

	batch_user (BatchUser pivot)	enrollments (CourseManagement)
Cấp	Lớp đào tạo	Khoá học
Pivot	(batch, user) — UNIQUE	(course, user) — UNIQUE
Status	5-state lifecycle	active / paused / completed / cancelled
Sinh ra bởi	Bạn attach thủ công / import	Auto-sync khi tạo batch_user
Service	BatchEnrollmentService	(qua BatchCourseEnrollmentSync)
Audit	exited_at, exit_reason; transfers	Không có audit chi tiết

→ Trang này tập trung batch_user (là phần mới trong v2).

5 trạng thái lifecycle (BatchEnrollmentStatus)

Status	Ý nghĩa	Tính active?	exited_at?
active	Đang học bình thường	✅	null
suspended	Tạm dừng (giữ chỗ)	❌ ngắn hạn	null
transferred_out	Đã chuyển sang lớp khác	❌	có
dropped	Đã thôi học hẳn	❌	có
completed	Đã hoàn tất	❌	có

Helper scopes (trên BatchUser model)

Scope	Lọc
active	status = active
onRoster	status ∈
closed	status ∈

→ Bảng nhập điểm dùng active + suspended + completed. Bản ghi danh sách "đang học" dùng onRoster. Xem audit dùng closed.

Mã màu UI (badge)

Status	Màu
active	Success (xanh)
suspended	Warning (vàng)
transferred_out	Gray
dropped	Danger (đỏ)
completed	Info (xanh dương)

Nguồn enrollment (cấp Course)

enrollments.channel ghi nhận kênh đã tạo:

Kênh	Tự sinh	Người quản lý
Batch	Khi batch_user tạo (sync với program.courses)	Training Manager
Group	Khi User thêm vào Group có quyền vào Course	Tenant Admin
Method (code/free/paid)	Khi học viên tự đăng ký qua trang khoá	Course Manager / Sales
Manual	Admin gán trực tiếp (user, course)	Bạn / Tenant Admin
Roadmap	Khi học viên lưu lộ trình → enroll khoá	Hệ thống tự động

→ 1 user có thể có nhiều enrollment cho cùng course qua nhiều kênh? Không. UNIQUE(user_id, course_id) — chỉ 1 row. Channel ghi kênh tạo đầu tiên.

Vào quản lý ghi danh

Theo Student (chính)

Sidebar → Đào tạo → Học viên → mở Student → tab Ghi danh (BatchEnrollmentsRelationManager).

Bảng list batch_user của student:

Cột	Mô tả
Lớp	Tên Batch (link)
Mã lớp (toggleable)	code
Trạng thái	Badge 5-state
Ngày ghi danh (joined_at)	Date
Ngày kết thúc (exited_at, toggleable)	Date hoặc —
Lý do kết thúc (exit_reason, toggleable, wrap)	Text hoặc —

Filter: status (5 options).

Theo Batch

Sidebar → Đào tạo → Lớp học → mở Batch → Edit page → tab Học viên (UsersRelationManager).

Cùng action 5-state nhưng từ góc nhìn lớp.

Action chỉ ở Edit page

Lifecycle actions chỉ hiện ở Edit (/admin/batches/{id}/edit). View page giữ read-only — browse batch không gây nhầm lẫn. Click Edit ở góc trên để vào Edit page.

Tạo enrollment mới

Cách 1 — Từ Student profile

Tab Ghi danh → header Ghi danh vào lớp:

1. Modal — chọn Lớp (chỉ hiện Batch active không có user này).
2. Click Lưu → tạo batch_user status active, joined_at = now().

Cách 2 — Từ Batch Users tab

Đây là cách chính cho onboarding cohort:

1. Edit Batch → tab Học viên → Đính kèm.
2. Tìm User → tick → Đính kèm.
3. Hoặc bulk import CSV (xem Import học viên).

Auto-create Student record

Mỗi lần batch_user tạo:

• Listener EnsureStudentForBatchMember chạy.
• User chưa có Student record → tự tạo (xem Quản lý học viên).

→ Workflow B2B: import CSV → User mới + Student mới + Enrollment cho khoá → tất cả tự động.

Action lifecycle

Action: Tạm dừng (Suspend)

Visible khi: status = active.

1. Modal — nhập Lý do (text).
2. Confirm → status = suspended, không set exited_at.
3. Dispatch event BatchEnrollmentStatusChanged.

Khi nào dùng Suspend?

• Học viên xin nghỉ tạm 1–2 tuần (vd: bị bệnh).
• Kẹt công việc tạm thời, sẽ quay lại.
• Vi phạm cần đình chỉ tạm trước khi quyết định cuối.

Học viên không vào học được lớp (UI ẩn). Tiến độ cũ giữ nguyên. Sau resume thì quay lại được.

Action: Khôi phục (Resume)

Visible khi: status = suspended.

1. Modal confirm.
2. Service: status = active, clear exited_at + exit_reason.

Resume chỉ từ suspended

Service BatchEnrollmentService::resume() validate status === Suspended. Nếu cố resume từ status khác (vd: dropped) → lỗi "Chỉ có thể khôi phục các ghi danh đang tạm dừng."

Để "phục hồi" enrollment đã dropped, đề xuất tạo enrollment mới (qua action Ghi danh vào lớp).

Action: Cho thôi học (Drop)

Visible khi: status = active hoặc suspended.

1. Modal — nhập Lý do. Cảnh báo: "Không thể hoàn tác. Hãy dùng 'Chuyển lớp' nếu học viên chuyển sang lớp khác."
2. Confirm → status = dropped, exited_at = now(), exit_reason = lý do.

Drop = mất quyền truy cập

Học viên rời lớp vĩnh viễn:

• Mất quyền truy cập các khoá thuộc Program (nếu chỉ enroll qua Batch này).
• Tiến độ học enrollments.progress giữ nhưng UI không hiển thị (không thấy khoá).
• Xuất hiện trong audit (exit_reason).
• KHÔNG có nút undo — phải tạo enrollment mới nếu quay lại.

→ Chắc chắn trước khi drop. Nếu cần "tạm rời", dùng Suspend thay vì Drop.

Action: Hoàn tất (Complete)

Visible khi: status = active.

1. Modal confirm.
2. Service: status = completed, exited_at = now().

Khác Drop: completed là kết quả tích cực — học viên hoàn thành cohort.

Auto-complete khi Batch → Completed

Listener CompleteEnrollmentsOnBatchCompleted chạy khi Batch chuyển status = completed:

• Tất cả batch_user active → đổi thành completed với exited_at = batch.end_date.
• Bulk thao tác — không cần manually từng người.

Nếu một số học viên thiếu (chưa đạt 100%), bạn có thể manually drop họ trước khi chuyển Batch sang Completed.

Action: Chuyển lớp (Transfer)

Visible khi: status = active. (Suspended phải resume trước.)

Quy trình atomic — xem trang riêng: Chuyển lớp (Batch Transfer).

Tóm tắt:

• status = transferred_out cho enrollment cũ.
• Tạo batch_user mới ở dest batch status active.
• Ghi vào batch_transfers audit log.

Detach (gỡ học viên khỏi lớp)

Action Đính kèm truyền thống: ngược lại là Gỡ (DetachAction Filament default).

Detach KHÁC Drop

• Drop (lifecycle action) — đổi status active → dropped, giữ row trong DB. Audit trail.
• Detach (Filament default) — xoá row khỏi batch_user. Không audit trail.

→ Khuyến nghị: dùng Drop mọi khi có thể. Detach chỉ dùng cho data correction (vd: attach nhầm user → detach undo).

Hành vi detach:

1. Xoá batch_user row.
2. Trigger BatchUser::deleted callback → huỷ enrollments tương ứng (qua BatchCourseEnrollmentSync::detachUser).
3. Không tạo BatchTransfer audit.

Cảnh báo khi Batch không cho phép enrollment

Một số trạng thái Batch chặn enrollment mới:

• Cancelled — không enroll mới được.
• Completed — không enroll mới được.
• Active, Draft, Paused — cho phép.

Service BatchUser::booted::creating kiểm tra:

• Nếu batch.allowsEnrollment() === false → throw exception.
• UI hiển thị: "Không thể ghi danh học viên khi lớp ở trạng thái :status."

→ Muốn enroll vào Batch đã Completed? Phải đổi status batch về Active trước (xem Lớp đào tạo → Vòng đời Status).

Bulk lifecycle actions

Bảng Users trong Batch hỗ trợ bulk:

• Tick nhiều rows → BulkActionGroup → Suspend / Drop / Complete với 1 modal lý do dùng chung.

Khi nào dùng bulk?

• Bulk Drop — cohort phần lớn không qua kỳ thi cuối → bulk drop những người fail. Cẩn thận: drop là vĩnh viễn.
• Bulk Complete — cohort kết thúc + 30 học viên đạt → bulk complete (hoặc cứ chuyển Batch → Completed thì auto).
• Bulk Suspend — họp khẩn cohort, tạm hoãn 2 tuần → bulk suspend; sau đó bulk resume.

Transfer không có bulk action — phải từng người (do mỗi transfer cần dest batch riêng).

Sự kiện (events)

Mỗi action dispatch event:

Action	Event
Suspend / Resume / Drop / Complete	BatchEnrollmentStatusChanged($enrollment, $from, $to)
Transfer	BatchEnrollmentStatusChanged (cho source) + StudentTransferred($transfer)
Attach (tạo mới)	UserJoinedBatch($user, $batch)
Detach (xoá)	(không event riêng — chỉ trigger sync detach)

Events này có thể được wire vào:

• Notifications (gửi email cho học viên / trainer).
• Gamification (cộng điểm khi join batch).
• External webhooks (Mautic / GetResponse sync).

Quy trình điển hình

Onboard cohort B2B (50 học viên)

1. Tạo Batch "Cohort 2026-04" — status Draft, set start/end date.
2. Tab Học viên → Nhập học viên CSV.
3. Hệ thống tạo:
   • User mới (50)
   • Student records (50)
   • batch_user status active (50)
   • enrollments cho mọi khoá Program (50 × N)
   • Welcome email (50)
4. Chuyển Batch → Active.

Học viên xin nghỉ tạm

1. Vào Edit Batch → tab Học viên → row học viên A → Tạm dừng.
2. Lý do: "Bị ốm 2 tuần — sẽ quay lại 15/05".
3. Học viên A status suspended. Mất quyền truy cập tạm.
4. Sau 2 tuần: action Khôi phục → status active. Quay lại học bình thường.

Học viên xin chuyển lớp

Xem Chuyển lớp (Batch Transfer).

Học viên rời hẳn

1. Drop với lý do "Quyết định không tiếp tục — không còn phù hợp."
2. Status dropped. Mất quyền truy cập.
3. Trên hồ sơ Student: nếu đây là enrollment duy nhất + active = none → cân nhắc Withdraw (level trường) cho tổng nhất quán.

Cohort kết thúc

1. Cuối kỳ — kiểm tra ai đã đạt yêu cầu.
2. Bulk Complete học viên đạt (hoặc đợi auto khi batch → completed).
3. Drop học viên không đạt (nếu chính sách).
4. Chuyển Batch → Completed:
   • Listener auto complete remaining active → completed.
   • Trigger gamification + notification "Cohort completed".
5. Bulk Graduate Student (level trường) cho người pass.

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

Với Student lifecycle

• Student status (active/graduated/withdrawn) không tự sync với batch_user status.
• Tự sync logic ngược lại: attach batch_user → auto-create Student active.
• Cần manual: Drop student khỏi mọi batch khi Withdraw level trường (xem Quản lý học viên → Withdraw).

Với Gradebook

• Bảng nhập điểm chỉ hiển thị student active + completed + suspended (xem Gradebook → Nhập điểm).
• transferred_out / dropped ẩn — không xuất hiện trong điểm.
• Điểm cũ giữ — không xoá (audit).

Với Attendance

• Học viên active đếm vào sessions held × students (mẫu số).
• transferred_out / dropped không đếm cho buổi sau ngày exit.
• suspended đếm — vẫn nhân vào mẫu số (giống Excused — không cộng tử số).

Với Notifications

Status change → email tương ứng (cấu hình ở Notifications):

• "Bạn đã được chuyển vào lớp X." (active)
• "Lớp X tạm dừng — sẽ thông báo khi resume." (suspended)
• "Cảm ơn bạn đã hoàn tất lớp X — chúng tôi gửi chứng chỉ qua email." (completed)

Với Subscription

Subscription cấp Group → Group cấp Course access. Khác kênh hoàn toàn với Batch.

Học viên có cả 2 kênh — sub + batch — vẫn truy cập khoá. Khi sub hết hạn:

• Mất quyền qua Group.
• Vẫn truy cập qua Batch (nếu enrollment Batch active).

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

Tôi suspend nhầm — undo nhanh? Action Khôi phục → status active. Audit log ghi lại — không phá vỡ.

Bulk drop 30 người — có cảnh báo gì không? Modal yêu cầu lý do. Confirm → drop 30. Không có "preview" — bạn nên rà filter trước khi tick all.

Học viên đã drop xin quay lại?

• Tạo batch_user mới (qua action Ghi danh vào lớp) — sẽ là enrollment mới với joined_at hiện tại.
• Hoặc: Drop record cũ giữ trong DB, không tự reactivate.

Drop vs Detach — chọn cái nào?Drop trong gần như mọi trường hợp. Detach chỉ khi:

• Sửa nhầm attach (vừa attach 5 phút trước, chưa tạo Student / Enrollment thực sự — undo nhanh).
• Data correction admin level.

Transfer giữa 2 cohort khác Program — có vấn đề không? Service không chặn nhưng tiến độ khoá có thể "mất" UI (xem Chuyển lớp → Khác Program).

Tôi không thấy nút lifecycle?

• Đang ở View page → click Edit để vào Edit page (lifecycle gated to Edit).
• Action visibility theo status — vd: Resume chỉ hiện khi suspended.
• Không có quyền — kiểm tra role có *_enrollment không.

Học viên detach rồi attach lại — Student record có duplicate? Không. Student UNIQUE(user_id) — listener firstOrCreate. Attach lại không tạo trùng.

Tiến độ khoá học có theo qua transfer / re-enroll? Có. Tiến độ gắn (user, course), không gắn batch_user. Học viên drop rồi enroll lại hoặc transfer → khoá đã hoàn thành không phải làm lại.

Audit log của lifecycle?

• batch_user.status + exited_at + exit_reason là audit cơ bản.
• batch_transfers table cho transfers (audit chi tiết).
• Tenant Admin audit log capture mọi thay đổi (nếu module bật).

Bulk transfer (1-1 giữa 2 batch lớn)? Hiện không có UI. Phải từng người. Đề xuất Tenant Admin chạy script nếu thường xuyên (vd: cohort huỷ → move toàn bộ).