# Phân Hệ Quản Lý Phúc Khảo (Web Exam Regrading)
## 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ý phúc khảo** (`web_exam_regrading`) là phân hệ chuyên trách dành cho **Cán bộ Kiểm định chất lượng (QA / Examiner Reviewer)** và **Cán bộ Vận hành Thi** nhằm quản lý, rà soát và chấm lại các bài thi có yêu cầu phúc khảo hoặc các bài thi bị nghi ngờ có sai lệch điểm số (`assign_type = 2`).

Các tính năng trọng tâm:
- **Theo dõi danh sách bài thi cần phúc khảo**: Quản lý tập trung tất cả các yêu cầu phúc khảo phát sinh từ học viên hoặc do cán bộ vận hành kích hoạt.
- **Phân công & Gán QA**: Gán cán bộ QA chuyên môn để thực hiện chấm lại độc lập (tránh trùng với giáo viên đã chấm lần 1).
- **So sánh 2 lớp điểm (Trước PK vs Sau PK)**: Đối soát trực quan giữa điểm giáo viên chấm lần 1 (`scoreBeforePk` - snapshot `assign_type = 1`) và điểm QA chấm phúc khảo (`scoreAfterPk` - snapshot `assign_type = 2`).
- **Giám sát gian lận trong phúc khảo**: Hiển thị cảnh báo nghi vấn gian lận (`cheating_status`) và chi tiết báo cáo vi phạm (`cheating_reports`) phục vụ hội đồng phúc khảo ra quyết định.
- **Duyệt & Đồng bộ kết quả chính thức**: Sau khi QA hoàn tất, điểm phúc khảo trở thành điểm chính thức và được đồng bộ sang hệ thống ICL / Zeus.

---

### 2. Danh Sách Tác Nhân (Actors)

| Tác nhân (Actor) | Vai trò & Trách nhiệm |
| :--- | :--- |
| **Cán bộ QA / Reviewer** | Cán bộ kiểm định nhận bài thi phúc khảo; nghe lại audio Speaking, đọc lại bài viết Writing, đối soát với điểm GV1 và quyết định giữ nguyên hay điều chỉnh điểm. |
| **Cán bộ Vận hành / Admin** | Tiếp nhận yêu cầu phúc khảo từ học viên, phân công QA chấm lại, theo dõi tiến độ và phê duyệt kết quả cuối cùng. |
| **Học viên (Student)** | Đối tượng gửi yêu cầu phúc khảo khi không đồng ý với kết quả chấm ban đầu. |
| **Hệ thống ICL / Zeus** | Nhận điểm số chính thức sau khi quy trình phúc khảo hoàn tất. |

---

### 3. Use Case Diagram (Sơ đồ Use Case)

```mermaid
usecaseDiagram
    actor "Cán bộ QA / Reviewer" as QA
    actor "Cán bộ Vận hành / Admin" as Operator
    actor "Hệ thống ICL / Zeus" as Zeus

    package "Phân Hệ Quản Lý Phúc Khảo (web_exam_regrading)" {
        usecase "UC01: Tra cứu & Lọc Danh Sách Yêu Cầu Phúc Khảo" as UC01
        usecase "UC02: Phân Công / Gán QA Chấm Phúc Khảo" as UC02
        usecase "UC03: Đối Soát Điểm Trước & Sau Phúc Khảo" as UC03
        usecase "UC04: Thực Hiện Chấm Phúc Khảo (QA Regrading Modal)" as UC04
        usecase "UC05: Kiểm Tra Báo Cáo Vi Phạm & Gian Lận" as UC05
        usecase "UC06: Phê Duyệt & Đồng Bộ Điểm Sau Phúc Khảo" as UC06
    }

    Operator --> UC01
    Operator --> UC02
    Operator --> UC03
    Operator --> UC05
    Operator --> UC06

    QA --> UC01
    QA --> UC03
    QA --> UC04

    UC06 --> Zeus
```

---

### 4. Chi Tiết Luồng Hoạt Động Cốt Lõi (Activity Workflows)

#### 4.1. Luồng 1: Tra Cứu Danh Sách Phúc Khảo (`exam-regrading.getExamRegrading`)
- **Mã Use Case**: `UC_ER_01`
- **Mô tả**: Lấy danh sách bài thi đang có yêu cầu phúc khảo (`tah.assign_type = 2`), kèm snapshot so sánh điểm trước/sau PK và thông tin QA được phân công.
- **Sequence Diagram**:
  ```mermaid
  sequenceDiagram
      autonumber
      actor User as Cán bộ Vận hành / QA
      participant FE as Giao diện Phúc khảo (index.blade.php / exam-regrading.js)
      participant Ctrl as ExamRegradingController
      participant DB as Database (Tenant)
      participant Svc as IclScoreService

      User->>FE: Mở trang Quản lý phúc khảo hoặc lọc dữ liệu
      FE->>Ctrl: GET /exam-regrading/get-exam-regrading (Kèm query params)
      Ctrl->>DB: buildExamRegradingQuery: Lọc tah.assign_type = 2 và lấy bản ghi mới nhất cho mỗi student_score_id
      Ctrl->>DB: Thực thi Paginate
      
      Ctrl->>DB: Batch Query: Lấy toàn bộ StudentScoreGradingHistory của các student_score_id
      Ctrl->>DB: Query chi tiết cheating_reports từ data_rescored nếu có nghi vấn
      
      loop Với từng bài thi
          Ctrl->>Svc: Parse snapshot assign_type = 1 -> Gán scoreBeforePk (Điểm GV1 chấm)
          Ctrl->>Svc: Parse snapshot assign_type = 2 -> Gán scoreAfterPk (Điểm QA chấm)
          Ctrl->>Ctrl: Gán Root Category Product & Cờ has_cheating
      end
      
      Ctrl-->>FE: HTTP 200 JSON {success: true, data}
      FE->>User: Render DataTable hiển thị cột Điểm Trước PK, Điểm Sau PK, Cảnh báo gian lận & Action
  ```

---

#### 4.2. Luồng 2: Quy Trình Toàn Diện Từ Yêu Cầu Đến Hoàn Tất Phúc Khảo
- **Mã Use Case**: `UC_ER_02`
- **Mô tả**: Vòng đời từ khi phát sinh yêu cầu phúc khảo đến khi cập nhật điểm chính thức.
- **Activity Flowchart**:
  ```mermaid
  flowchart TD
      A([Tiếp nhận yêu cầu Phúc khảo]) --> B[Kích hoạt assign_type = 2 trong teacher_assigned_histories]
      B --> C[Gán tài khoản QA chuyên môn]
      C --> D[Bài thi xuất hiện trên trang Quản lý Phúc khảo]
      
      D --> E[QA mở modal Chấm phúc khảo]
      E --> F[Đọc bài viết / Nghe audio & Đối soát điểm GV1 scoreBeforePk]
      
      F --> G{QA quyết định thay đổi điểm hay giữ nguyên?}
      G -->|Giữ nguyên| H[Xác nhận điểm gốc của GV1]
      G -->|Điều chỉnh| I[Nhập điểm tiêu chí mới & Ghi chú lý do thay đổi]
      
      H --> J[Lưu Snapshot assign_type = 2 vào student_score_grading_histories]
      I --> J
      
      J --> K[Tính toán lại Overall Band Score bài thi]
      K --> L[Cập nhật student_score: manual_grading_status = 1 Hoàn tất]
      L --> M[Đồng bộ điểm chính thức sau phúc khảo sang Zeus / ICL]
      M --> N([Kết thúc quy trình phúc khảo])
  ```