# Bộ Tài Liệu Kỹ Thuật: Phân Hệ Quản Lý Chấm Thủ Công > **Module Identifier**: `web_exam_grading` | **Menu Path**: Quản lý lịch sử làm bài ➔ Quản lý chấm thủ công | **Route**: `exam-grading.index` --- ## 📌 Giới Thiệu Tổng Quan Phân hệ **Quản lý chấm thủ công** (`web_exam_grading`) là trung tâm quản lý và theo dõi tiến độ chấm bài thi tự luận (Writing, Speaking) dành cho Giáo viên và Cán bộ Quản trị: - **Kiểm soát phân công chấm lần 1 (`assign_type = 1`)**: Theo dõi bài thi đã gán, hạn chót hoàn thành (`deadline`) và trạng thái chấm của giáo viên. - **Phân quyền hiển thị theo Role**: Giáo viên chỉ thấy bài của mình; Quản trị viên (`exam-grading.viewAllGrading`) xem và lọc toàn bộ hệ thống. - **Đối soát điểm 2 lớp**: So sánh điểm trước review (`score_before_review` - AI chấm) và điểm sau review (`score_after_review` - GV chấm). - **Cảnh báo bài thi bất thường (`abnormal`)**: Nhận diện bài thi có chênh lệch điểm, thời gian bất thường hoặc vi phạm quy chế. - **Xuất báo cáo chi tiết**: Xuất báo cáo kết quả chấm 25 cột dữ liệu qua Background Queue Job. --- ## 📂 Cấu Trúc Bộ Tài Liệu Bộ tài liệu kỹ thuật được phân chia thành 6 file chuyên sâu: | STT | Tài liệu | Nội dung chính | Liên kết | | :---: | :--- | :--- | :--- | | **01** | **Use Case & Luồng Hoạt Động** | • Danh sách tác nhân (Giáo viên, Admin, Queue Job)
• Sơ đồ Use Case tổng thể
• Chi tiết 4 Use Case cốt lõi (Tra cứu phân công, Đối soát điểm Trước/Sau, Mở modal chấm, Xuất báo cáo Async) | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/01_use_case_va_luong_hoat_dong.md) | | **02** | **Quy Tắc Nghiệp Vụ (Business Logic)** | • Phân định lượt chấm lần 1 (`tah.assign_type = 1`)
• Quản lý trạng thái phân công (`tah.status`: Chờ chấm, Đã hoàn thành, Đã thu hồi)
• Logic phân quyền bảo mật (`viewAllGrading` vs `tah.user_id = me`)
• Logic tính toán điểm Trước/Sau Review
• Nhận diện bài thi bất thường (`abnormal_reasons`)
• Quản lý hạn chót chấm (`expires_at`) | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/02_business_logic.md) | | **03** | **Sơ Đồ Chức Năng & Thiết Kế API** | • Kiến trúc thành phần hệ thống
• Flowchart chi tiết cho `getExamGrading` và `ExportExamGradingJob`
• Quy trình xuất báo cáo 5000 records/batch kèm Polling progress
• Đặc tả chi tiết các API Endpoints | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/03_function_diagram_va_function_design.md) | | **04** | **Cơ Sở Dữ Liệu & Schema** | • Sơ đồ thực thể liên kết (ERD Diagram)
• Data Dictionary chi tiết kèm comment tiếng Việt từng cột cho các bảng: `teacher_assigned_histories`, `student_exam_histories_teachers`, `student_score_grading_histories`, `student_score` | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/04_database_va_database_schema.md) | | **05** | **Kịch Bản Kiểm Thử (Test Cases)** | • Ma trận kiểm thử chức năng giao diện (Quyền xem theo Role, Filter, Đối soát Trước/Sau, Modal chấm Rubric, Abnormal flag, Export)
• Kịch bản kiểm thử chi tiết P0-P2 (Tiền điều kiện, Các bước thao tác UI, Kết quả mong đợi)
• Kiểm thử biên quá hạn deadline và thu hồi bài thi | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/05_test_cases_va_kiem_thu.md) | | **06** | **Hướng Dẫn Vận Hành & Sự Cố** | • Quy trình thao tác chuẩn (SOP) dành cho Giáo viên chấm thi và Quản trị viên
• Quy chuẩn chấm Rubric 4 tiêu chí Writing & Speaking, quy chuẩn viết nhận xét Feedback
• Xử lý sự cố thực tế (Bài quá hạn, Nghi vấn đạo văn AI, Lỗi nộp bài) | [Xem chi tiết](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/06_huong_dan_van_hanh_va_troubleshooting.md) | --- ## 🛠️ Ma Trận File & Thành Phần Kỹ Thuật (Source Code Mapping) | Khối Chức Năng | File Mã Nguồn Liên Quan | | :--- | :--- | | **Cấu hình Quyền & Menu** | • [config/tenant_groups.php](file:///var/www/html/lms_hocmai/config/tenant_groups.php#L797-L825) | | **Định tuyến (Routes)** | • [routes/web.php](file:///var/www/html/lms_hocmai/routes/web.php#L630-L636) (`prefix: exam-grading`) | | **Controller** | • [app/Http/Controllers/ExamGradingController.php](file:///var/www/html/lms_hocmai/app/Http/Controllers/ExamGradingController.php) | | **Background Queue Job** | • [app/Jobs/ExportExamGradingJob.php](file:///var/www/html/lms_hocmai/app/Jobs/ExportExamGradingJob.php) | | **Models (Eloquent)** | • `app/Models/TeacherAssignedHistory.php`
• `app/Models/StudentExamHistoryTeacher.php`
• `app/Models/StudentScoreGradingHistory.php`
• `app/Models/StudentScore.php`
• `app/Models/StudentExamHistory.php` | | **Services & Engines** | • `app/Services/IclScoreService.php`
• `app/Services/ApiMoodleService.php` | | **Giao diện (Blade Views)** | • `resources/views/exam-grading/index-v2.blade.php`
• `resources/views/exam-grading/components/...` | | **Frontend Logic (JS)** | • `public/js/exam-grading/exam-grading-v2.js`
• `public/js/exam-schedule-result/exam-history/exam-detail-modal.edit.js` |