Chuyển tới nội dung chính

🔄 Quy chuẩn State Machine & Domain Events

Tài liệu này định nghĩa các chuỗi chuyển đổi trạng thái bắt buộc (Canonical State Machines) và danh mục các sự kiện miền (Domain Events) áp dụng cho mọi module trong LMS.

1. Danh mục Máy Trạng thái Chuẩn (Canonical State Machines)​

Khi xây dựng logic nghiệp vụ, lập trình viên BẮT BUỘC tuân thủ đúng các chuỗi chuyển đổi trạng thái sau, không tự ý thêm các trạng thái ngoài luồng:

  • Lead (CRM): new → contacted → appointment → consulted → interested → registered (hoặc lost).
  • Lớp học (Class): draft → open_enrollment → scheduled → running → completed → archived.
  • Buổi học (Session): scheduled → in_progress → completed (hoặc cancelled / rescheduled).
  • Ghi danh (Enrollment): pending → active → completed (hoặc suspended / transferred / dropped).
  • Hợp đồng (Contract): draft → pending_signature → signed → active → completed (hoặc terminated).
  • Hóa đơn (Invoice): draft → sent → partially_paid → paid (hoặc overdue / cancelled).
  • Bài tập (Homework): draft → published → submitted → graded → closed.
  • Đề thi (Exam): draft → published → available → in_progress → submitted → graded → closed.
  • Chứng chỉ (Certificate): eligible → approved → generated → issued (hoặc revoked).

2. Event-Driven Architecture (Tự động hóa theo Sự kiện)​

Mọi hành động kích hoạt liên module PHẢI được triển khai dưới dạng Laravel Events & Listeners, tuyệt đối không viết mã lồng chéo (hardcode) trực tiếp trong Controller hoặc Service:

Mẫu Khai báo Event & Listener Chuẩn​

// Phát sự kiện trong Service khi thanh toán hóa đơn
event(new InvoicePaidEvent(invoice, payment));
// Listener lắng nghe để kích hoạt ghi danh
namespace Modules\Academic\App\Listeners;

use Modules\Finance\App\Events\InvoicePaidEvent;

class ActivateEnrollmentOnInvoicePaid
{
    public function handle(InvoicePaidEvent $event): void
    {
        invoice = event->invoice;
        if ($invoice->enrollment_id) {
            enrollment = invoice->enrollment;
            $enrollment->update(['status' => 'active']);
        }
    }
}

🔗 Xem thêm​