# TÀI LIỆU KIẾN TRÚC & NGHIỆP VỤ HỆ THỐNG EMS TESTSITE > **Dự án**: EMS Testsite (Galaxy Education / Hocmai) > **Phiên bản tài liệu**: 3.0 (Cập nhật 2026) > **Mục tiêu**: Hướng dẫn chi tiết kiến trúc kỹ thuật, luồng nghiệp vụ, cơ sở dữ liệu và phân quyền hệ thống phục vụ phát triển, vận hành và bàn giao. --- ## 🗺️ Bản Đồ Tài Liệu (Documentation Sitemap) Tài liệu được chia nhỏ thành các module chuyên biệt dưới đây để tiện tra cứu: | STT | File Tài liệu | Nội dung trọng tâm | |:---:|---|---| | **01** | [**01. Kiến trúc Tổng thể & Multi-tenant**](file:///var/www/html/hocmai_testsite/docs/01_OVERVIEW_AND_ARCHITECTURE.md) | Tổng quan hệ thống, Tech Stack, Cơ chế chuyển đổi kết nối Multi-tenant Database (`HelperTenant`). | | **02** | [**02. Quản lý Bài thi & Chấm thi**](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | Luồng DS học sinh làm bài, Modal bóc tách bài thi v3, Phân công GV Speaking, QA Phúc khảo, Bắn webhook & Mail (`notifyThirdParty`). | | **03** | [**03. Kỹ thuật Bóc tách JSON & Skills Engine**](file:///var/www/html/hocmai_testsite/docs/03_SKILLS_AND_JSON_ENGINE.md) | Danh mục kỹ năng (Reading, Listening, Vocab...), Cấu trúc cây JSON câu hỏi, Quy tắc parse theo `quiz_type` (1, 2, 4, 7, 14...). | | **04** | [**04. Mapping Exam & Ngân hàng Đề**](file:///var/www/html/hocmai_testsite/docs/04_EXAM_MAPPING_AND_QUESTIONS.md) | Cấu hình Mapping Exam v2, Tạo link làm bài hàng loạt qua Batch Tracking CSV, Quản lý đề và câu hỏi. | | **05** | [**05. Sản phẩm, Chiến dịch & UTM Tracking**](file:///var/www/html/hocmai_testsite/docs/05_CAMPAIGN_AND_UTM_TRACKING.md) | Quản lý Campaign, Cấu hình UTM Tracking nguồn học sinh làm bài và chuyển đổi Marketing. | | **06** | [**06. Quản trị Hệ thống & Phân quyền RBAC**](file:///var/www/html/hocmai_testsite/docs/06_SYSTEM_ADMIN_AND_RBAC.md) | Mô hình RBAC 4 bảng (`roles`, `permissions`, `role_permissions`, `user_roles`), Danh mục Permission Route, Phân bổ Tenant. | | **07** | [**07. Cơ sở Dữ liệu & Sơ đồ Vòng đời Dữ liệu**](file:///var/www/html/hocmai_testsite/docs/07_DATABASE_AND_DATA_FLOW.md) | Sơ đồ ERD các bảng cốt lõi (`student_exam_histories`, `student_scores`, `student_answers`...), State Diagram vòng đời bài thi. | | **08** | [**08. Bẫy Ngầm & Hướng dẫn Xử lý Sự cố**](file:///var/www/html/hocmai_testsite/docs/08_GOTCHAS_AND_TROUBLESHOOTING.md) | Danh sách lỗi tiềm ẩn (Multi-tenant context, mảng JSON phẳng vs lồng, trùng lặp gửi mail) & Checklist trước khi deploy. | --- ## 🧭 Bảng Ánh Xạ Tính Năng Chính từ Menu (`AppServiceProvider::getMenus`) Toàn bộ các tính năng chính hiển thị trên giao diện điều hướng (Sidebar Menu) được ánh xạ tương ứng như sau: ```mermaid graph TD AppService[AppServiceProvider::getMenus] --> G1[Quản lý bài thi & Chấm thi] AppService --> G2[Quản lý đề & câu hỏi] AppService --> G3[Sản phẩm & UTM] AppService --> G4[Quản trị hệ thống] G1 --> M1[DS học sinh làm bài] G1 --> M2[Bài thi cần chấm của tôi] G1 --> M3[Quản lý thi Speaking với GV] G1 --> M4[Quản lý phúc khảo] G1 --> M5[DS HS làm bài của tôi] G2 --> M6[Quản lý Exam] G2 --> M7[Mapping Exam v2] G2 --> M8[Quản lý câu hỏi & nhóm] G3 --> M9[Quản lý sản phẩm] G3 --> M10[Cấu hình UTM & Tracking] G4 --> M11[Vai trò & Phân quyền] G4 --> M12[Quản lý Người dùng & Tenant] ``` ### Chi tiết tra cứu nhanh Menu: | Nhóm Menu | Tên Menu Item | Route Name | Controller chính | Tài liệu chi tiết | |---|---|---|---|:---:| | **Quản lý bài thi & Chấm thi** | Danh sách học sinh làm bài | `student-exam-history.index` | `StudentExamHistoryController` | [Xem File 02](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | | | Bài thi cần chấm của tôi | `student-exam-history.myAssessment` | `StudentExamHistoryController` | [Xem File 02](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | | | Quản lý thi Speaking với GV | `teacher-speaking.index` | `TeacherSpeakingController` | [Xem File 02](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | | | Quản lý phúc khảo | `exam-regrading.index` | `StudentExamHistoryController` | [Xem File 02](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | | | DS HS làm bài của tôi | `student-exam-history.myStudentExamHistories` | `StudentExamHistoryController` | [Xem File 02](file:///var/www/html/hocmai_testsite/docs/02_EXAM_AND_GRADING_WORKFLOW.md) | | **Quản lý đề & câu hỏi** | Mapping Exam | `exam-mapping.indexV2` | `ExamMappingController` | [Xem File 04](file:///var/www/html/hocmai_testsite/docs/04_EXAM_MAPPING_AND_QUESTIONS.md) | | | Quản lý Exam | `exams.index` | `ExamController` | [Xem File 04](file:///var/www/html/hocmai_testsite/docs/04_EXAM_MAPPING_AND_QUESTIONS.md) | | | Quản lý câu hỏi & nhóm | `questions.index` | `QuestionController` | [Xem File 04](file:///var/www/html/hocmai_testsite/docs/04_EXAM_MAPPING_AND_QUESTIONS.md) | | **Sản phẩm & UTM** | Quản lý sản phẩm | `campaigns.index` | `CampaignController` | [Xem File 05](file:///var/www/html/hocmai_testsite/docs/05_CAMPAIGN_AND_UTM_TRACKING.md) | | | Cấu hình UTM & Tracking | `campaign-exam-tracking.index` | `CampaignExamTrackingController` | [Xem File 05](file:///var/www/html/hocmai_testsite/docs/05_CAMPAIGN_AND_UTM_TRACKING.md) | | **Quản trị hệ thống** | Danh sách vai trò | `role.index` | `RoleController` | [Xem File 06](file:///var/www/html/hocmai_testsite/docs/06_SYSTEM_ADMIN_AND_RBAC.md) | | | Quản lý người dùng | `user-management.index` | `UserManagementController` | [Xem File 06](file:///var/www/html/hocmai_testsite/docs/06_SYSTEM_ADMIN_AND_RBAC.md) | | | Quản lý Tenant & Domain | `tenant-management.index` | `TenantController` | [Xem File 01](file:///var/www/html/hocmai_testsite/docs/01_OVERVIEW_AND_ARCHITECTURE.md) | | | Phân tài khoản tenant | `tenant-assignment.index` | `TenantAssignmentController` | [Xem File 06](file:///var/www/html/hocmai_testsite/docs/06_SYSTEM_ADMIN_AND_RBAC.md) |