# Phân Hệ Quản Lý Bài Làm Của Học Viên & Chấm Bài Thi ## 01. Use Case & Luồng Hoạt Động (Use Cases & Activity Workflows) --- ### 1. Tổng Quan Phân Hệ (Overview) Phân hệ **Quản lý bài làm của học viên & Chấm bài thi** (kết hợp `web_exam_histories` và `web_student_exam_histories`) là trung tâm xử lý dữ liệu sau thi (Post-Exam Processing) trên hệ thống LMS. Phân hệ đảm nhiệm các chức năng cốt lõi: - **Quản lý bài làm học viên**: Theo dõi, tìm kiếm, lọc toàn bộ lịch sử thi, kết quả thi, trạng thái chấm và nghi vấn gian lận của học viên. - **Xem chi tiết bài làm (Detail View)**: Hiển thị đầy đủ bài làm trắc nghiệm, tự luận (Writing), ghi âm (Speaking), kèm câu trả lời của học viên và đáp án/giải thích. - **Chấm điểm & Đánh giá (Teacher Grading)**: Cung cấp giao diện chấm thi chuyên nghiệp cho Giáo viên (GV) theo thang điểm Rubric tiêu chí (Criteria), ghi nhận nhận xét chi tiết, audio nhận xét và file bằng chứng. - **Phân công chấm bài (Teacher Assignment)**: Gán giáo viên chấm Writing/Speaking theo từng Part/Kỹ năng hoặc gán hàng loạt theo Team/Skill. - **QA Phúc khảo (QA Regrading & Review)**: Quy trình kiểm định chất lượng chấm (QA), gán ngẫu nhiên QA để rà soát điểm số và phê duyệt kết quả phúc khảo. - **Báo cáo & Xuất dữ liệu**: Xuất báo cáo điểm thi quy mô lớn chạy ngầm qua Queue Batching (CSV/ZIP). - **Đồng bộ kết quả thi**: Tích hợp đồng bộ điểm sang hệ thống ICL / Zeus (`IclScoreService`). --- ### 2. Danh Sách Tác Nhân (Actors) | Tác nhân (Actor) | Vai trò & Trách nhiệm trong phân hệ | | :--- | :--- | | **Học viên (Student)** | Người thực hiện bài thi; xem kết quả điểm, nhận xét và đề xuất phúc khảo bài thi. | | **Cán bộ Vận hành Thi (Operator)** | Giám sát danh sách bài làm, điều phối gán giáo viên chấm, kích hoạt phúc khảo, đồng bộ điểm và xuất báo cáo. | | **Giáo viên chấm thi (Teacher / Grader)** | Nhận bài thi được phân công; trực tiếp nghe audio Speaking, đọc bài viết Writing, chấm điểm theo Rubric, ghi chú nhận xét và lưu kết quả. | | **Cán bộ Kiểm định Chất lượng (QA / Reviewer)** | Thực hiện chấm lại ngẫu nhiên hoặc theo yêu cầu phúc khảo, đối soát điểm của giáo viên chấm trước đó và duyệt điểm chính thức. | | **Hệ thống AI Hub / EMS Service (AI Grader)** | Dịch vụ AI chấm tự động bước đầu cho Writing/Speaking trước khi chuyển sang giáo viên rà soát. | | **Hệ thống ICL / Zeus (External Core)** | Hệ thống backend quản trị học tập đối tác; nhận kết quả điểm đồng bộ từ LMS sau khi hoàn tất chấm. | --- ### 3. Use Case Diagram (Sơ đồ Use Case Tổng Thể) ```mermaid usecaseDiagram actor "Cán bộ Vận hành" as Operator actor "Giáo viên Chấm thi" as Teacher actor "Cán bộ QA" as QA actor "Hệ thống AI Hub" as AIHub actor "Hệ thống ICL / Zeus" as Zeus package "Phân Hệ Quản Lý Bài Làm & Chấm Thi (web_exam_histories & web_student_exam_histories)" { usecase "UC01: Tra cứu & Lọc Danh Sách Bài Làm" as UC01 usecase "UC02: Xem Chi Tiết Bài Làm (Modal Detail)" as UC02 usecase "UC03: Gán Giáo Viên Chấm Bài (Assign Teacher)" as UC03 usecase "UC04: Chấm Bài Thi Writing & Speaking" as UC04 usecase "UC05: QA Phúc Khảo / Đánh Giá Lại (Regrading)" as UC05 usecase "UC06: Xử Lý Nghi Vấn Gian Lận (Cheating)" as UC06 usecase "UC07: Tính Điểm Tổng & Band Score Overall" as UC07 usecase "UC08: Xuất Báo Cáo Kết Quả Thi (Async Export)" as UC08 usecase "UC09: Đồng Bộ Điểm Sang ICL / Zeus" as UC09 usecase "UC10: Tạo Lượt Thi Lại (Retake Session)" as UC10 } Operator --> UC01 Operator --> UC02 Operator --> UC03 Operator --> UC05 Operator --> UC06 Operator --> UC08 Operator --> UC09 Operator --> UC10 Teacher --> UC02 Teacher --> UC04 QA --> UC05 AIHub --> UC04 : <> UC04 ..> UC07 : <> UC05 ..> UC07 : <> UC07 ..> UC09 : <> UC09 --> Zeus ``` --- ### 4. Chi Tiết Luồng Hoạt Động Cốt Lõi (Activity Workflows) #### 4.1. Luồng 1: Tra Cứu & Lọc Danh Sách Bài Làm (`exam-histories.getExamHistories`) - **Mã Use Case**: `UC_EH_01` - **Mô tả**: Hiển thị bảng danh sách lịch sử bài làm kèm điểm các kỹ năng (Listening, Reading, Writing, Speaking), điểm Overall, trạng thái chấm, cờ gian lận, và các nút thao tác mở modal chi tiết/chấm bài. - **Bộ lọc đa chiều**: - Thời gian nộp bài (`start_date`, `end_date`), Số điện thoại, Email, Mã học viên (`student_code[]`), Mã lớp (`class_code[]`), Sản phẩm (`product[]`), Khóa học (`course[]`), Bài thi (`exam[]`). - Trạng thái thi (`exam_status`: 0 - Chờ nộp, 1 - Đã nộp, 2 - Không nộp). - Trạng thái chấm (`point_status`: 0 - Đang xử lý, 1 - Hoàn tất, 2 - Giao chấm lại, 3 - Đã hủy). - Trạng thái gán giáo viên (`teacher_status`: 0 - Chưa gán, 1 - Đã gán, 2 - Gán 1 phần). - Loại học viên (`is_vip`: 1 - VIP, 0 - Thường), Nghi vấn gian lận (`cheating_status`: 1 - Có nghi vấn, 0 - Không). - **Sequence Diagram**: ```mermaid sequenceDiagram autonumber actor User as Cán bộ Vận hành participant FE as Frontend View (index-v2.blade.php / exam-history.js) participant Ctrl as ExamHistoryController participant DB as Database (Tenant Connection) User->>FE: Truy cập trang hoặc thay đổi bộ lọc FE->>Ctrl: GET /exam-histories/list (Kèm query params) Ctrl->>Ctrl: buildExamHistoryQueryV2: Query bảng student_score (ss) Ctrl->>DB: Paginate kết quả theo ss.id DESC Ctrl->>DB: Post-processing: Lấy timeEnd (MAX created_at từ student_exam_histories) Ctrl->>DB: Lấy Moodle Hierarchy từ api_moodle (Cache Map) Ctrl->>DB: Lấy thông tin điểm các kỹ năng & Teacher assigned status Ctrl-->>FE: Trả về JSON {data, pagination, permissions} FE->>User: Render DataTable, hiển thị Badges điểm số & Action Buttons ``` --- #### 4.2. Luồng 2: Xem Chi Tiết Bài Làm Của Học Viên (`student-exam-histories.detail`) - **Mã Use Case**: `UC_EH_02` - **Mô tả**: Mở modal hiển thị toàn bộ bài thi 4 kỹ năng của học viên dưới dạng Read-only. - **Sequence Diagram**: ```mermaid sequenceDiagram autonumber actor User as Người xem (Vận hành / GV) participant FE as Modal Detail (exam-detail-modal.js / detail.js) participant Ctrl as StudentExamHistoryController participant Svc as StudentExamHistoryService participant DB as Database User->>FE: Bấm "Xem chi tiết" (student_score_id) FE->>Ctrl: GET /student-exam-histories/{student_score_id}/detail Ctrl->>Svc: Lấy tổng quan bài thi (studentInfo, listParts, overallScore) Ctrl-->>FE: Trả về JSON Sidebar & Danh sách các Part FE->>FE: Render Sidebar học viên & Danh sách Part (L, R, W, S) User->>FE: Chọn Part Writing / Speaking FE->>Ctrl: GET /api/student-exam-histories/data-rescored?student_score_id=...&idHistory=... Ctrl->>DB: Query chi tiết nội dung đề bài, bài làm học viên, nhận xét & điểm tiêu chí Ctrl-->>FE: Trả về chi tiết bài làm FE->>User: Render giao diện xem chi tiết (displayWritingDetails / displaySpeakingDetails) ``` --- #### 4.3. Luồng 3: Gán Giáo Viên Chấm Bài (`student-exam-histories.assignTeacher`) - **Mã Use Case**: `UC_EH_03` - **Mô tả**: Cán bộ vận hành chọn giáo viên để giao chấm các phần Writing hoặc Speaking cho học viên. - **Sequence Diagram**: ```mermaid sequenceDiagram autonumber actor Operator as Cán bộ Vận hành participant FE as Modal Gán Giáo Viên participant Ctrl as StudentExamHistoryController participant DB as Database (Tenant) Operator->>FE: Chọn Giáo viên cho Part Writing / Speaking -> Bấm "Lưu phân công" FE->>Ctrl: POST /student-exam-histories/assign-teacher Ctrl->>Ctrl: Validate dữ liệu: student_score_id, teacher_id, part_number, skill Ctrl->>DB: Bắt đầu Transaction Ctrl->>DB: INSERT / UPDATE teacher_assigned_histories (Lưu vết phân công) Ctrl->>DB: INSERT / UPDATE student_exam_history_teachers (Gán quyền chấm cho GV) Ctrl->>DB: Cập nhật trạng thái chấm trong student_score (score_processing_status = 0) Ctrl->>DB: Commit Transaction Ctrl-->>FE: HTTP 200 {success: true, message: 'Gán giáo viên chấm thành công'} FE->>Operator: Hiển thị thông báo & cập nhật Badge giáo viên trên danh sách ``` --- #### 4.4. Luồng 4: Quy Trình Giáo Viên Chấm Bài Thi (`student-exam-histories.edit`) - **Mã Use Case**: `UC_EH_04` - **Mô tả**: Giáo viên được phân công mở giao diện Chấm bài thi (`edit`), nhập điểm chi tiết theo tiêu chí Rubric, ghi nhận xét từng tiêu chí, đính kèm nhận xét chung (Text/Audio) và bấm hoàn tất chấm. - **Sequence Diagram**: ```mermaid sequenceDiagram autonumber actor Teacher as Giáo viên Chấm thi participant FE as Giao diện Chấm thi (exam-detail-modal.edit.js) participant Ctrl as StudentExamHistoryController participant ScoreSvc as RoundMixOverallService / ScoringScale participant IclSvc as IclScoreService participant DB as Database Teacher->>FE: Mở modal Chấm bài (student_score_id) FE->>Ctrl: GET /student-exam-histories/{student_score_id}/teacher-assigned-overview Ctrl->>DB: Kiểm tra quyền chấm của GV (can_grade, assigned_parts) Ctrl-->>FE: Trả về dữ liệu bài thi được phép chấm Teacher->>FE: Nhập điểm tiêu chí (TR, CC, LR, GRA), Nhận xét & Upload Audio Teacher->>FE: Bấm "Lưu kết quả chấm" FE->>Ctrl: POST /api/student-exam-histories/update-data-rescored Ctrl->>DB: Bắt đầu DB Transaction Ctrl->>DB: UPDATE student_exam_histories (Lưu điểm kỹ năng & externalGradingDetail) Ctrl->>DB: INSERT student_score_grading_histories (Lưu lịch sử chấm) Ctrl->>DB: INSERT teacher_grading_logs (Ghi log thao tác chấm của GV) Ctrl->>ScoreSvc: Tính toán lại điểm Overall 4 kỹ năng (Overall Band Score) Ctrl->>DB: UPDATE student_score (Cập nhật điểm tổng & score_processing_status = 1) Ctrl->>DB: Commit Transaction opt Điểm hoàn tất & Đủ điều kiện đồng bộ Ctrl->>IclSvc: Đồng bộ kết quả chấm sang Zeus / ICL IclSvc->>DB: Ghi log student_score_icl_logs end Ctrl-->>FE: HTTP 200 {success: true, overall_score} FE->>Teacher: Thông báo lưu thành công & cập nhật trạng thái "Đã hoàn thành chấm" ``` --- #### 4.5. Luồng 5: Quy Trình QA Phúc Khảo / Đánh Giá Lại (`student-exam-histories.assignRandomQa`) - **Mã Use Case**: `UC_EH_05` - **Mô tả**: Quy trình kiểm định chất lượng khi có học viên yêu cầu phúc khảo hoặc ban chuyên môn kích hoạt rà soát định kỳ. - **Activity Flowchart**: ```mermaid flowchart TD Start([Bắt đầu Phúc khảo bài thi]) --> CheckNeed{Bài thi cần phúc khảo?} CheckNeed -->|Thủ công| SetNeed[Cán bộ bấm: Xác nhận bài thi cần chấm lại] CheckNeed -->|Tự động| AutoFlag[Hệ thống kích hoạt theo ngưỡng chênh lệch điểm] SetNeed --> AssignQA[Gán tài khoản QA ngẫu nhiên hoặc chỉ định] AutoFlag --> AssignQA AssignQA --> QAReview[QA mở giao diện chấm phúc khảo] QAReview --> CompareScore{QA giữ nguyên điểm hay điều chỉnh?} CompareScore -->|Giữ nguyên| ConfirmScore[Xác nhận điểm gốc của GV1] CompareScore -->|Điều chỉnh| UpdateScore[Nhập điểm mới & ghi chú lý do phúc khảo] ConfirmScore --> SaveQA[Lưu lịch sử phúc khảo vào student_score_grading_histories] UpdateScore --> SaveQA SaveQA --> Recalculate[Tính lại điểm Overall toàn bài] Recalculate --> UpdateStatus[Cập nhật student_score: score_processing_status = 1] UpdateStatus --> SyncICL[Đồng bộ điểm chính thức sau phúc khảo sang Zeus] SyncICL --> End([Kết thúc quy trình]) ``` --- #### 4.6. Luồng 6: Xuất Báo Cáo Kết Quả Thi (`exam-histories.export`) - **Mã Use Case**: `UC_EH_06` - **Mô tả**: Xuất toàn bộ dữ liệu lịch sử thi (kèm điểm chi tiết 4 kỹ năng, điểm Overall, trạng thái gán giáo viên, thời gian làm bài) ra file CSV/ZIP thông qua Queue Job (`ExportExamHistoryJob`), hỗ trợ hàng chục nghìn bản ghi không gây nghẽn hệ thống.