# OMO Center — Database Schema

> Sơ đồ quan hệ các bảng dùng trong chức năng OMO Center.  
> Tài liệu nghiệp vụ tổng quan: [omo-center-guide.md](omo-center-guide.md)

---

## 1. Danh sách bảng

| Bảng | Vai trò |
|------|---------|
| `api_moodle` | Cây course → section → quiz (PK nội bộ + `moodle_id` Moodle) |
| `students` | Học sinh (`id`, `user_id` dùng join điểm) |
| `zeus_session_completions` | Zeus giao bài / ghi nhận session hoàn thành |
| `relationship_models` | Liên kết course + rule section nguồn → đích |
| `student_section_availability` | Lưu trạng thái đã pass + đề EMS đã mở cho học sinh |
| `api_moodle_ems` | Cấu hình khoảng điểm (`score_above`, `score_below`) cho từng đề |
| `student_score` | Điểm bài làm của học sinh |
| `user_quiz_grade` | Điểm quiz bổ sung |
| `student_exam_schedules` | Lịch mở/đóng section theo thời gian Zeus |
| `student_exam_schedule_histories` | Audit log thay đổi lịch thi |

---

## 2. Quy ước tham chiếu ID

Hầu hết bảng OMO **không khai báo FK constraint** trong DB — quan hệ dưới đây là **logic** theo code.

Có hai kiểu tham chiếu tới `api_moodle`:

| Kiểu | Dùng ở |
|------|--------|
| **`api_moodle.id`** (PK nội bộ) | `relationship_models`, `student_section_availability`, `student_exam_schedules`, `user_quiz_grade.quiz_id`, `api_moodle_ems.api_moodle_id` |
| **`api_moodle.moodle_id`** (ID Moodle) | `zeus_session_completions`, `student_score.quiz_id` |

---

## 3. Sơ đồ quan hệ (ER) — PK & FK logic

Sơ đồ: [so-do-quan-he.png](so-do-quan-he.png)

```mermaid
erDiagram
    students {
        bigint id PK
        bigint user_id
    }

    api_moodle {
        bigint id PK
        bigint moodle_id
        bigint parent_id FK
        string moodle_type
    }

    relationship_models {
        bigint id PK
        bigint source_id FK
        bigint destination_id FK
        enum type
        decimal min_avg_score
    }

    zeus_session_completions {
        bigint id PK
        bigint student_id FK
        bigint course_id "ref moodle_id"
        bigint section_id "ref moodle_id"
    }

    student_section_availability {
        bigint id PK
        bigint student_id FK
        bigint destination_section_id FK
        bigint ems_id FK
        decimal avg_score
    }

    api_moodle_ems {
        bigint id PK
        bigint api_moodle_id FK
        decimal score_above
        decimal score_below
    }

    student_score {
        bigint id PK
        bigint student_id FK
        bigint quiz_id "ref moodle_id"
    }

    user_quiz_grade {
        bigint id PK
        bigint user_id FK
        bigint quiz_id FK
    }

    student_exam_schedules {
        bigint id PK
        bigint student_id FK
        bigint course_id FK
        bigint section_id FK
    }

    student_exam_schedule_histories {
        bigint id PK
        bigint schedule_id FK
    }

    %% ── Cây Moodle ──
    api_moodle ||--o{ api_moodle : "parent_id → id"

    %% ── Cấu hình rule OMO ──
    api_moodle ||--o{ relationship_models : "source_id → id"
    api_moodle ||--o{ relationship_models : "destination_id → id"
    api_moodle ||--o{ api_moodle_ems : "api_moodle_id → id (quiz)"

    %% ── Học sinh & giao bài Zeus ──
    students ||--o{ zeus_session_completions : "student_id → id"
    students ||--o{ student_section_availability : "student_id → id"
    students ||--o{ student_score : "student_id → id"
    students ||--o{ student_exam_schedules : "student_id → id"
    students ||--o{ user_quiz_grade : "user_id → user_id"

    %% ── Kết quả availability ──
    api_moodle ||--o{ student_section_availability : "destination_section_id → id"
    api_moodle_ems ||--o{ student_section_availability : "ems_id → id"

    %% ── Lịch thi Zeus ──
    api_moodle ||--o{ student_exam_schedules : "course_id / section_id → id"
    student_exam_schedules ||--o{ student_exam_schedule_histories : "schedule_id → id"
```

---

## 4. Nhóm bảng theo luồng nghiệp vụ

Sơ đồ: [nhom-bang-theo-luong-nghiep-vu.png](nhom-bang-theo-luong-nghiep-vu.png)

```mermaid
flowchart LR
    subgraph CONFIG["Cấu hình Admin"]
        AM["api_moodle"]
        RM["relationship_models"]
        EMS["api_moodle_ems"]
        AM --> RM
        AM --> EMS
    end

    subgraph ZEUS["Zeus → LMS"]
        STU["students"]
        ZSC["zeus_session_completions"]
        STU --> ZSC
    end

    subgraph SCORE["Tính điểm section nguồn"]
        SS["student_score"]
        UQG["user_quiz_grade"]
        STU --> SS
        STU --> UQG
        AM --> SS
        AM --> UQG
    end

    subgraph AVAIL["Mở section đích"]
        SSA["student_section_availability"]
        RM --> SSA
        EMS --> SSA
        STU --> SSA
        AM --> SSA
    end

    subgraph SCHEDULE["Lịch thi (độc lập availability)"]
        SES["student_exam_schedules"]
        SEH["student_exam_schedule_histories"]
        STU --> SES
        SES --> SEH
        AM --> SES
    end

    ZSC -.->|"đã giao bài?"| AVAIL
    SCORE -.->|"avg_score"| AVAIL
```

---

## 5. Bảng tra quan hệ

| Quan hệ | Ý nghĩa |
|---------|---------|
| `relationship_models.source_id` → `api_moodle.id` | Section/course **nguồn** (Khóa học A) |
| `relationship_models.destination_id` → `api_moodle.id` | Section/course **đích** (khóa kiểm tra) |
| `zeus_session_completions.section_id` → `api_moodle.moodle_id` | Zeus giao bài theo ID Moodle, không phải PK |
| `student_score.quiz_id` → `api_moodle.moodle_id` | Điểm quiz theo moodle_id |
| `user_quiz_grade.quiz_id` → `api_moodle.id` | Điểm quiz theo PK nội bộ |
| `api_moodle_ems.api_moodle_id` → `api_moodle.id` | EMS gắn quiz trong section đích |
| `student_section_availability.ems_id` → `api_moodle_ems.id` | Đề EMS đã mở sau khi pass |

---

## 6. Migration tham chiếu

| Bảng | Migration |
|------|-----------|
| `zeus_session_completions` | `2025_12_22_073034_create_zeus_session_completions_table.php` |
| `relationship_models` | `2026_06_09_000001_create_relationship_models_table.php` |
| `student_section_availability` | `2026_06_10_000001_create_student_section_availability_table.php` |
| `api_moodle_ems` (score range) | `2026_06_09_000002_add_score_range_to_api_moodle_ems_table.php` |
| `student_exam_schedules` | `2026_06_04_064857_create_student_exam_schedules_table.php` |
| `student_exam_schedule_histories` | `2026_06_04_072158_create_student_exam_schedule_histories_table.php` |