# Cổng Tài Liệu Kỹ Thuật & Vận Hành: Phân Hệ Vận Hành Thi LMS HOCMAI

> **Khu vực**: Vận hành Đào tạo & Khảo thí LMS Hocmai  
> **Áp dụng cho**: Cán bộ Vận hành Thi, Quản trị viên (Admin), Giáo vụ, Giáo viên Chấm thi, Cán bộ Kiểm định Chất lượng (QA Phúc khảo)

---

## 📌 Giới Thiệu Tổng Quan

Phân hệ **Vận Hành Thi** là khối chức năng cốt lõi trên nền tảng LMS Hocmai, chịu trách nhiệm quản lý toàn bộ vòng đời của một kỳ thi / bài kiểm tra định kỳ / bài thi Mocktest chuẩn quốc tế (IELTS, TOEIC, ĐGNL,...), trải dài từ khâu chuẩn bị kế hoạch, giao lịch, giám sát làm bài, chấm thi tự luận đến đối soát phúc khảo và đồng bộ điểm số sang hệ thống Zeus / ICL.

Toàn bộ phân hệ được thiết kế xoay quanh 4 trục chức năng chính:

```mermaid
graph LR
    Step1["1. Quản lý DSHV đến lịch thi<br><code>dshv-den-lich-thi</code>"] 
    --> Step2["2. Học viên làm bài & Quản lý bài làm<br><code>quan-ly-bai-lam-hv</code>"]
    Step2 --> Step3["3. Phân công & Chấm thủ công<br><code>quan-ly-cham-thu-cong</code>"]
    Step3 --> Step4["4. Phúc khảo & Chốt điểm cuối<br><code>quan-ly-phuc-khao</code>"]
    Step4 --> Sync["5. Đồng bộ kết quả sang Zeus / ICL"]
```

---

## 📂 Danh Mục Phân Hệ & Cấu Trúc Thư Mục

Phân hệ Vận Hành Thi được chuẩn hóa thành 4 thư mục chuyên biệt. Mỗi thư mục con được cấu trúc toàn diện từ khâu nghiệp vụ, thiết kế hệ thống, lược đồ dữ liệu cho tới kịch bản kiểm thử (Test Cases) và quy trình vận hành chuẩn (SOP & Troubleshooting):

| Phân Hệ | Thư Mục | Mã Module Quyền | Mô Tả & Nhiệm Vụ Trọng Tâm | Liên Kết Chi Tiết |
| :--- | :--- | :--- | :--- | :--- |
| **1. Quản lý DSHV đến lịch thi** | `dshv-den-lich-thi/` | `web_exam_schedule` | Điều phối lịch thi, tạo lịch theo lộ trình/thi lại/thi sớm, gia hạn deadline, quản lý lượt thi và nhắc lịch thi tự động qua Zalo/Zeus. | [👉 Xem thư mục](file:///var/www/html/lms_hocmai/van-hanh-thi/dshv-den-lich-thi/README.md) |
| **2. Quản lý bài làm của học viên** | `quan-ly-bai-lam-hv/` | `web_exam_histories`<br>`web_student_exam_histories` | Trung tâm giám sát kết quả thi 4 kỹ năng, xem chi tiết bài làm (audio Speaking, bài viết Writing), gán giáo viên chấm, công thức tính Overall IELTS và xuất báo cáo. | [👉 Xem thư mục](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-bai-lam-hv/README.md) |
| **3. Quản lý chấm thủ công** | `quan-ly-cham-thu-cong/` | `web_exam_grading` | Cổng phân công và chấm bài thi tự luận lần 1 (`assign_type = 1`), theo dõi tiến độ chấm theo giáo viên, đối soát điểm AI chấm vs Giáo viên chấm, nhận diện bài thi bất thường. | [👉 Xem thư mục](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-cham-thu-cong/README.md) |
| **4. Quản lý phúc khảo** | `quan-ly-phuc-khao/` | `web_exam_regrading` | Cổng chấm phúc khảo độc lập lần 2 (`assign_type = 2`), cơ chế reset điểm gốc bảo đảm khách quan, đối soát điểm Trước PK vs Sau PK, phân tích gian lận và chốt điểm chính thức. | [👉 Xem thư mục](file:///var/www/html/lms_hocmai/van-hanh-thi/quan-ly-phuc-khao/README.md) |

---

## 🗺️ Ma Trận Tài Liệu Chuẩn Hóa Theo Từng Phân Hệ

Mỗi phân hệ con bao gồm trọn bộ 6 tài liệu tiêu chuẩn:

| Mã File | Tên Tài Liệu | Mục Đích & Nội Dung Chính | Đối Tượng Sử Dụng Chính |
| :---: | :--- | :--- | :--- |
| `README.md` | **Bản Đồ Kỹ Thuật** | Giới thiệu phân hệ, chỉ mục tài liệu, ma trận file mã nguồn (Routes, Controllers, Jobs, Models, Views, JS). | Tất cả các bên |
| `01_...` | **Use Case & Luồng Hoạt Động** | Danh sách tác nhân (Actor), sơ đồ Use Case, Flowchart và Sequence Diagram các luồng nghiệp vụ chính. | BA, PM, Developer, QA |
| `02_...` | **Quy Tắc Nghiệp Vụ (Business Logic)** | Các quy tắc logic, công thức tính điểm/làm tròn, điều kiện mở khóa bài thi, phân quyền và trạng thái. | BA, Dev, QA, Vận hành |
| `03_...` | **Sơ Đồ Chức Năng & Thiết Kế API** | Kiến trúc module, flow chi tiết từng hàm controller, luồng queue job ngầm và đặc tả API request/response. | Developer, Tech Lead, QA |
| `04_...` | **Cơ Sở Dữ Liệu & Database Schema** | Sơ đồ thực thể liên kết (ERD), từ điển dữ liệu (Data Dictionary) chi tiết kèm mô tả từng cột, index. | DBA, Data Analyst, Dev |
| `05_...` | **Kịch Bản Kiểm Thử (Test Cases)** | Ma trận kiểm thử chức năng, bộ Test Cases chi tiết (P0 - P3), Happy Path, Negative & Edge Cases UI/UX. | QA/QC Tester, Vận hành |
| `06_...` | **Hướng Dẫn Vận Hành & Troubleshooting** | Quy trình thao tác chuẩn (SOP) từng bước trên giao diện Web UI, danh mục mã lỗi, xử lý sự cố & FAQ. | Cán bộ Vận hành, Giáo viên, CSKH |

---

## 👥 Ma Trận Phân Quyền & Vai Trò (RACI Matrix)

| Vai Trò | Trách Nhiệm Chính Trong Phân Hệ Vận Hành Thi | Quyền Hạn Tương Ứng |
| :--- | :--- | :--- |
| **Quản Trị Viên (Admin)** | Toàn quyền kiểm soát hệ thống, cấu hình tham số, phân quyền tenant, truy cập tất cả dữ liệu bài thi và lịch thi. | `tenant_admin`, `web_exam_schedule.*`, `web_exam_histories.*`, `web_exam_grading.viewAllGrading`, `web_exam_regrading.*` |
| **Cán Bộ Vận Hành Thi (Operator)** | Tạo mới, đổi lịch, gia hạn lịch thi cho học viên; phân công giáo viên chấm bài; kích hoạt phúc khảo; xuất báo cáo tổng hợp. | `web_exam_schedule.*`, `web_exam_histories.*`, `web_exam_grading.index`, `web_exam_regrading.index` |
| **Giáo Viên Chấm Thi (Teacher / Grader)** | Xem danh sách bài thi được phân công chấm lần 1, mở giao diện chấm Rubric, nhập nhận xét chi tiết, nộp điểm. | `web_exam_grading.index` (chỉ xem bài của chính mình được gán), `exam-histories.detail` |
| **Cán Bộ QA Phúc Khảo (QA Examiner)** | Tiếp nhận bài thi phúc khảo, thực hiện chấm lại độc lập khách quan trên điểm Raw, rà soát nghi vấn gian lận, chốt điểm phúc khảo. | `web_exam_regrading.index`, `web_exam_regrading.getExamRegrading` |
| **Giáo Vụ / CSKH (Academic Officer)** | Tra cứu lịch thi, theo dõi kết quả thi của học sinh để tư vấn lộ trình và tiếp nhận đơn xin phúc khảo/thi lại. | Quyền xem danh sách lịch thi & bài thi (`getExamSchedule`, `getExamHistories`) |

---

## 🔄 Luồng Vận Hành Liên Hoàn (End-to-End Workflow)

```mermaid
sequenceDiagram
    autonumber
    actor HV as Học Viên
    actor VH as Cán Bộ Vận Hành
    actor GV as Giáo Viên Chấm
    actor QA as QA Phúc Khảo
    participant LMS as Hệ Thống LMS
    participant Zeus as Hệ Thống Zeus / ICL

    Note over VH,LMS: BƯỚC 1: LÊN KẾ HOẠCH & MỞ LỊCH THI
    VH->>LMS: Tạo lịch thi cho học viên (Theo lộ trình / Thi lại / Thi sớm)
    LMS-->>Zeus: Đồng bộ trạng thái lịch thi & kích hoạt nhắc thi (Zalo/SMS)
    
    Note over HV,LMS: BƯỚC 2: HỌC VIÊN LÀM BÀI & NỘP BÀI
    HV->>LMS: Vào thi theo lịch, nộp bài 4 kỹ năng (L/R/W/S)
    LMS->>LMS: AI tự động chấm Listening, Reading và chấm sơ bộ Writing/Speaking

    Note over VH,GV: BƯỚC 3: PHÂN CÔNG & CHẤM THỦ CÔNG LẦN 1
    VH->>LMS: Phân công giáo viên chấm Writing / Speaking (assign_type = 1)
    GV->>LMS: Mở giao diện chấm bài, xem bài viết / nghe audio, chấm theo Rubric
    GV->>LMS: Hoàn tất chấm và xác nhận điểm số

    Note over VH,QA: BƯỚC 4: RÀ SOÁT & PHÚC KHẢO (NẾU CÓ)
    alt Có yêu cầu phúc khảo từ học viên / phát hiện bất thường
        VH->>LMS: Kích hoạt phúc khảo bài thi (assign_type = 2)
        QA->>LMS: Mở giao diện phúc khảo, chấm lại độc lập trên bài thi gốc
        QA->>LMS: Chốt điểm phúc khảo chính thức
    end

    Note over LMS,Zeus: BƯỚC 5: CHỐT ĐIỂM & ĐỒNG BỘ KẾT QUẢ
    LMS->>LMS: Tổng hợp điểm Overall 4 kỹ năng theo công thức làm tròn chuẩn IELTS
    LMS->>Zeus: Bắn Webhook đồng bộ điểm chính thức sang sổ điểm Zeus / ICL
```

---

## 📞 Hỗ Trợ & Liên Hệ
- **Bộ phận Kỹ thuật LMS**: Đội ngũ phát triển phần mềm LMS Hocmai.
- **Bộ phận Vận hành Khảo thí**: Phòng Vận hành Đào tạo & Quản lý Học viên.