# Phân Hệ Quản Lý Phúc Khảo (Web Exam Regrading)
## 04. Cơ Sở Dữ Liệu & Lược Đồ Chi Tiết (Database & Schema Design)

---

### 1. Sơ Đồ Quan Hệ Thực Thể (Entity Relationship Diagram - ERD)

```mermaid
erDiagram
    TEACHER_ASSIGNED_HISTORIES }o--|| STUDENT_SCORE : "student_score_id"
    TEACHER_ASSIGNED_HISTORIES }o--|| USERS : "user_id (Cán bộ QA)"
    
    STUDENT_SCORE ||--o{ STUDENT_SCORE_GRADING_HISTORIES : "student_score_id"
    STUDENT_SCORE ||--o{ STUDENT_EXAM_HISTORIES : "student_score_id"
    STUDENT_SCORE }o--|| STUDENTS : "student_id"
    STUDENT_SCORE }o--|| API_MOODLE : "quiz_id (moodle_id)"
    
    STUDENT_EXAM_HISTORIES ||--o{ STUDENT_EXAM_HISTORIES_TEACHERS : "student_exam_history_id"

    TEACHER_ASSIGNED_HISTORIES {
        bigint id PK "ID Khóa chính"
        bigint student_score_id FK "ID bài thi (student_score.id)"
        bigint user_id FK "ID Cán bộ QA được gán (users.id)"
        tinyint assign_type "2: Chấm phúc khảo (Regrading)"
        datetime assigned_at "Thời gian phân công QA"
        datetime expires_at "Hạn chót hoàn thành phúc khảo"
        tinyint status "0: Đang phúc khảo, 1: Hoàn tất"
        timestamp created_at "Thời điểm yêu cầu phúc khảo"
    }

    STUDENT_SCORE_GRADING_HISTORIES {
        bigint id PK "ID Khóa chính"
        bigint student_score_id FK "ID bài thi"
        tinyint assign_type "1: Snapshot Trước PK, 2: Snapshot Sau PK"
        longtext data_ems_snapshot "JSON Snapshot chi tiết điểm số"
        decimal overall_score "Điểm overall tương ứng lượt chấm"
        timestamp created_at "Thời điểm lưu điểm"
    }

    STUDENT_EXAM_HISTORIES_TEACHERS {
        bigint id PK "ID Khóa chính"
        bigint student_exam_history_id FK "ID Part bài thi"
        longtext data_rescored "JSON chứa điểm và cheating_reports"
        int skill "15: Writing, 16: Speaking"
    }

    STUDENT_SCORE {
        bigint id PK "ID Khóa chính"
        bigint student_id FK "ID Học viên"
        bigint quiz_id FK "ID Bài Quiz"
        tinyint manual_grading_status "Trạng thái phúc khảo (0: Chờ, 1: Xong)"
        tinyint cheating_status "1: Có nghi vấn gian lận, 0: Không"
        longtext cheating_reports "JSON lưu bằng chứng vi phạm"
        longtext abnormal_reasons "JSON lưu lý do bất thường"
    }
```

---

### 2. Chi Tiết Lược Đồ Bảng (Data Dictionary & Column Comments)

#### 2.1. Bảng `teacher_assigned_histories` (Lượt Phân Công Phúc Khảo)
- **Mô tả**: Ghi nhận lượt phân công cán bộ QA chấm lại bài thi với `assign_type = 2`.

| Tên Cột | Kiểu Dữ Liệu | Nullable | Mặc định | Chú Thích (Comment) Chi Tiết |
| :--- | :--- | :---: | :---: | :--- |
| `id` | `BIGINT UNSIGNED` | NO | Auto Increment | Khóa chính bản ghi phân công. |
| `student_score_id` | `BIGINT UNSIGNED` | NO | | ID bài thi gốc trong `student_score.id`. |
| `user_id` | `BIGINT UNSIGNED` | YES | `NULL` | ID tài khoản Cán bộ QA được gán chấm phúc khảo (`users.id`). |
| `assign_type` | `TINYINT` | NO | `2` | **`2`**: Định danh lượt chấm Phúc khảo. |
| `assigned_at` | `DATETIME` | YES | `NULL` | Thời điểm kích hoạt yêu cầu và phân công QA. |
| `expires_at` | `DATETIME` | YES | `NULL` | Hạn chót hoàn thành phúc khảo. |
| `status` | `TINYINT` | NO | `0` | Trạng thái: `0` (Đang phúc khảo), `1` (Đã hoàn thành phúc khảo). |
| `created_at` | `TIMESTAMP` | YES | `NULL` | Thời điểm tạo yêu cầu phúc khảo. |

---

#### 2.2. Bảng `student_score_grading_histories` (Snapshots Đối Soát Phúc Khảo)
- **Mô tả**: Lưu trữ 2 mốc snapshot quan trọng để đối chiếu điểm:
  - `assign_type = 1`: Điểm trước phúc khảo (Do GV1 chấm).
  - `assign_type = 2`: Điểm sau phúc khảo (Do QA chấm).

| Tên Cột | Kiểu Dữ Liệu | Nullable | Chú Thích (Comment) Chi Tiết |
| :--- | :--- | :---: | :--- |
| `id` | `BIGINT UNSIGNED` | NO | Khóa chính. |
| `student_score_id` | `BIGINT UNSIGNED` | NO | ID bài thi gốc. |
| `assign_type` | `TINYINT` | NO | `1`: Lần 1 (Trước PK), `2`: Lần 2 (Sau PK). |
| `data_ems_snapshot`| `LONGTEXT` | YES | Chuỗi JSON chứa toàn bộ điểm số các vòng thi và tiêu chí Rubric. |
| `overall_score` | `DECIMAL(4,2)` | YES | Điểm Overall Band Score của lượt chấm. |
| `created_at` | `TIMESTAMP` | YES | Thời điểm ghi nhận. |

---

#### 2.3. Bảng `student_exam_histories_teachers` (Bằng Chứng Gian Lận Trong `data_rescored`)
- **Mô tả**: Chứa cấu trúc JSON `data_rescored` nơi lưu trữ các báo cáo gian lận (`cheating_reports`) do giáo viên hoặc hệ thống AI ghi nhận.

| Tên Cột | Kiểu Dữ Liệu | Nullable | Chú Thích (Comment) Chi Tiết |
| :--- | :--- | :---: | :--- |
| `id` | `BIGINT UNSIGNED` | NO | Khóa chính. |
| `student_exam_history_id`| `BIGINT UNSIGNED`| YES | ID Part kỹ năng. |
| `data_rescored` | `LONGTEXT` | YES | Chuỗi JSON chứa điểm chấm và mảng `cheating_reports` (loại vi phạm, lý do vi phạm, task số mấy). |
| `skill` | `INT` | NO | `15`: Writing, `16`: Speaking. |