# 01. TỔNG QUAN KIẾN TRÚC & CƠ CHẾ MULTI-TENANT

Tài liệu này mô tả chi tiết kiến trúc tổng thể, công nghệ nền tảng và cơ chế đa chi nhánh (Multi-tenant Connection) của hệ thống EMS Testsite.

---

## 1. Tổng Quan Hệ Thống

**EMS Testsite** (Exam Management System) là nền tảng quản lý kỳ thi, tổ chức làm bài, bóc tách kết quả thi tự động, hỗ trợ giáo viên chấm các kỹ năng Speaking/Writing và quản lý quy trình hậu kiểm/phúc khảo (QA) cho học sinh.

### 🛠️ Công Nghệ Nền Tảng (Tech Stack)

| Thành phần | Công nghệ sử dụng | Mô tả & Vai trò |
|---|---|---|
| **Backend Framework** | Laravel 10 / PHP 8.1+ | Xử lý logic API, phân quyền, xử lý dữ liệu và tích hợp bên thứ 3. |
| **Database** | MySQL (Master & Tenant DBs) | Lưu trữ thông tin người dùng master, cấu hình tenant và dữ liệu bài thi học sinh. |
| **Frontend Rendering** | Laravel Blade Views + Tailwind CSS | Giao diện hiện đại, responsive, tối ưu trải nghiệm người dùng. |
| **Frontend Logic** | Vanilla JavaScript ES6+ | Xử lý render động, bóc tách JSON, modal tương tác nhanh. |
| **UI Components** | TomSelect, Lucide Icons, Alpine.js | Thư viện chọn dropdown AJAX, bộ icon SVG vector, reactive states. |

---

## 2. Kiến Trúc Kết Nối Đa Chi Nhánh (Multi-tenant Architecture)

Hệ thống hoạt động theo mô hình **Multi-Database Multi-tenant**:
- **Master Database** (`mysql`): Chứa bảng `users`, `hocmai_tenants`, `hocmai_tenant_domains`, `user_tenants` để quản lý danh sách tenant và phân quyền truy cập tenant cho user.
- **Tenant Database** (`tenant_db`): Mỗi chi nhánh/tenant sở hữu một cơ sở dữ liệu riêng chứa toàn bộ dữ liệu nghiệp vụ: `student_exam_histories`, `baikiemtra`, `questions`, `roles`, `permissions`, v.v.

```mermaid
graph TD
    UserRequest[Request từ User / Browser] --> ResolveTenant{Xác định Tenant}
    ResolveTenant -->|Theo Domain / User Config| TenantContext[Thiết lập Tenant Connection]
    TenantContext --> HelperTenant[HelperTenant::getCurrentTenantConnection]
    HelperTenant --> MasterDB[(Master DB: Users & Tenant Management)]
    HelperTenant --> TenantDB[(Tenant DB: Exams, Scores, Histories, Roles)]
```

### ⚙️ Cơ Chế Xử Lý Kết Nối trong Code

Để đảm bảo truy vấn đúng cơ sở dữ liệu của Tenant hiện tại, toàn bộ các Model và Query Builder phải chỉ định connection động:

```php
// 1. Lấy tên connection tenant hiện tại
$tenantConnection = HelperTenant::getCurrentTenantConnection();

// 2. Thực hiện truy vấn trên tenant connection
$histories = StudentExamHistory::on($tenantConnection)
    ->where('idHistoryContest', $idHistoryContest)
    ->first();

// 3. Với quan hệ / bảng phân quyền:
$rolePermissions = RolePermission::on($tenantConnection)
    ->whereIn('permission_id', $permissionIds)
    ->get();
```

> [!WARNING]
> **Quy tắc bắt buộc khi viết Code**:
> Khi truy vấn các bảng nghiệp vụ (Exam, History, Question, Role, User trong tenant), **luôn luôn** sử dụng `.on($tenantConnection)` hoặc `DB::connection($tenantConnection)`. Không được truy vấn mặc định không có connection vì sẽ bị trỏ nhầm về Master DB.

---

## 3. Cấu Trúc Thư Mục Dự Án (Project Structure)

```
hocmai_testsite/
├── app/
│   ├── Helpers/
│   │   ├── Helper.php               # Danh mục quyền, format dữ liệu, hằng số
│   │   └── HelperTenant.php         # Quản lý kết nối Tenant DB & Session
│   ├── Http/
│   │   ├── Controllers/             # Toàn bộ Controllers xử lý nghiệp vụ
│   │   └── Middleware/              # Kiểm tra quyền, Tenant switcher
│   ├── Models/                      # Eloquent Models (User, Exam, History...)
│   ├── Providers/
│   │   └── AppServiceProvider.php   # Định nghĩa getMenus() và View Composer
│   └── Services/                    # Service layer (StudentExamDetailService...)
├── public/
│   ├── js/
│   │   ├── exam-history/            # exam-detail-modal-v3.js (Engine bóc tách bài thi)
│   │   ├── teacher-speaking/        # teacher-speaking.js (Phân công GV Speaking)
│   │   └── student-exam-history/    # JS danh sách làm bài & bài cần chấm
│   └── exam-json-tester.html        # Trang sandbox kiểm thử JSON trực quan
├── resources/views/                 # Giao diện Blade Templates
│   ├── student-exam-history/        # Views DS học sinh, bài cần chấm
│   ├── teacher-speaking/            # Views quản lý thi Speaking
│   ├── exam-mapping/                # Views Mapping Exam v2
│   └── layouts/                     # Sidebar navigation, master layout
├── routes/
│   ├── web.php                      # Endpoints giao diện & AJAX nội bộ
│   └── api.php                      # Endpoints API / Webhook bên thứ 3
└── docs/                            # Thư mục tài liệu hướng dẫn hệ thống
```