#07 – Kiến trúc hệ thống & Quyết định kiến trúc (ADR)

Giai đoạn: Thiết kế hệ thống · Phiên bản 0.1 – 29/10/2026

Kiến trúc dưới đây là đề xuất, phụ thuộc kết quả đánh giá onthi.hoclieu.vn (ADR-001). Các phần độc lập với quyết định đó (mô-đun nghiệp vụ, luồng dữ liệu, bảo mật) giữ nguyên trong mọi phương án.

#1. Động lực kiến trúc (Architecture drivers)

#2. Các phương án nền tảng

#ADR-001 – Lựa chọn nền tảng

Trạng thái: ⏳ Chờ quyết định (hạn 05/11/2026) · Người quyết định: HEID + SK

Danh mục đánh giá kỹ thuật onthi.hoclieu.vn (3 ngày)

1. Quyền truy cập mã nguồn, môi trường, CI/CD; công nghệ đang dùng; ai đang vận hành.
2. Có sẵn: ngân hàng câu hỏi (hỗ trợ đúng/sai 4 ý, trả lời ngắn, LaTeX?), làm bài, chấm, CMS?
3. API SSO (OIDC/OAuth2?), API lớp học/giao bài, tài liệu API.
4. Năng lực chịu tải hiện tại, số người dùng, lịch sử sự cố.
5. Chất lượng mã: kiểm thử tự động, cấu trúc mô-đun, khả năng thêm mô-đun mới không ảnh hưởng tính năng cũ.
6. Ràng buộc hạ tầng, hợp đồng, bảo mật.

Khuyến nghị sơ bộ của SK: nghiêng về C nếu Hoclieu có SSO; nếu không có API dùng được → B với tài khoản riêng và mã lớp, tích hợp LMS ở R1. Phần còn lại của tài liệu mô tả kiến trúc cho B/C (lớp hybrid do SK xây).

#3. Kiến trúc tổng thể (C4 – mức Container)

flowchart TB
    HS(["Học sinh<br/>(điện thoại, trình duyệt Zalo)"])
    GV(["Giáo viên"])
    BTV(["BTV / Admin"])

    subgraph EDGE["Biên"]
        CDN["CDN + WAF<br/>cache trang tĩnh, ảnh, chống DDoS"]
    end

    subgraph APP["Nền tảng hybrid"]
        WEB["Web học sinh & giáo viên<br/>Next.js (SSR, PWA)"]
        CMS["CMS & Quản trị<br/>SPA React"]
        API["Backend API<br/>Modular monolith (REST/OpenAPI)"]
        WORKER["Worker nền<br/>import, xuất file, đề xuất, báo cáo"]
        EVT["Thu sự kiện<br/>(endpoint nhẹ + hàng đợi)"]
    end

    subgraph DATA["Dữ liệu"]
        PG[("PostgreSQL<br/>dữ liệu giao dịch")]
        REDIS[("Redis<br/>cache, phiên, giới hạn tần suất, hàng đợi")]
        OBJ[("Object storage<br/>ảnh, file import/xuất, ảnh bài làm")]
        DWH[("Kho phân tích<br/>ClickHouse / PostgreSQL phân vùng")]
    end

    subgraph EXT["Hệ thống ngoài"]
        SSO[["Hoclieu SSO"]]
        LMS[["LMS Hoclieu"]]
        VIDEO[["Dịch vụ video<br/>chuyển mã + HLS + URL ký số"]]
        PAY[["Cổng thanh toán"]]
        MSG[["SMS / Email / Zalo ZNS"]]
    end

    HS --> CDN --> WEB
    GV --> CDN
    BTV --> CMS
    WEB --> API
    CMS --> API
    WEB --> EVT
    API --> PG & REDIS & OBJ
    API --> WORKER
    WORKER --> PG & OBJ & DWH
    EVT --> REDIS --> WORKER
    API <--> SSO
    API <--> LMS
    API --> VIDEO
    HS -. "phát video" .-> VIDEO
    API <--> PAY
    WORKER --> MSG

#4. Mô-đun trong Backend (modular monolith)

Mỗi mô-đun sở hữu bảng dữ liệu của mình, giao tiếp qua interface nội bộ và sự kiện miền; có thể tách thành dịch vụ riêng khi cần mở rộng.

#5. Luồng quan trọng

#5.1 Phân giải ID

sequenceDiagram
    actor HS as Học sinh
    participant WEB as Web
    participant API as API (code-resolver)
    participant C as Redis cache
    participant DB as PostgreSQL
    HS->>WEB: Nhập "tv 012" / quét QR /27/TV012
    WEB->>API: GET /codes/TV012?edition=27
    API->>API: Chuẩn hoá (BR-05)
    API->>C: Tìm (edition, code)
    alt Có trong cache
        C-->>API: resource_id, kind, book_id
    else Không có
        API->>DB: Tra CONTENT_CODE (+ sách đã kích hoạt của HS nếu thiếu edition)
        DB-->>API: Kết quả
        API->>C: Lưu cache 10 phút
    end
    API->>API: Kiểm tra entitlement (hoặc is_preview)
    API-->>WEB: { kind, resourceId, path } hoặc lỗi NOT_FOUND / NOT_ACTIVATED
    WEB->>HS: Chuyển tới trang tài nguyên
    WEB-)API: Sự kiện code_resolved

#5.2 Làm bài, nộp, chấm, đề xuất

sequenceDiagram
    actor HS as Học sinh
    participant WEB as Web (PWA)
    participant API as API (assessment)
    participant Q as Hàng đợi
    participant REC as recommendation
    HS->>WEB: Bắt đầu
    WEB->>API: POST /assessments/{id}/attempts
    API-->>WEB: attempt (deadline_at), đề KHÔNG kèm đáp án
    loop Mỗi thay đổi
        WEB->>WEB: Lưu IndexedDB
        WEB->>API: PATCH /attempts/{id}/answers (gộp, debounce 2s)
    end
    HS->>WEB: Nộp bài
    WEB->>API: POST /attempts/{id}/submit (đồng bộ phần còn thiếu)
    API->>API: Chấm theo scoring_scheme (09)
    API-->>WEB: Kết quả + điểm
    API-)Q: AttemptSubmitted
    Q-)REC: Tính đề xuất
    REC-->>API: Lưu RECOMMENDATION
    WEB->>API: GET /attempts/{id}/recommendations (poll/SSE ≤ 2s)

Đề xuất được tính đồng bộ cho bài nhỏ (≤ 40 câu, thường < 50 ms) để trả cùng kết quả; xử lý bất đồng bộ là phương án khi tải cao.

#5.3 Thanh toán gói đề (P3)

sequenceDiagram
    actor HS as Học sinh
    participant API as API (commerce)
    participant PAY as Cổng thanh toán
    participant ENT as entitlement
    HS->>API: POST /orders {packageId}
    API-->>HS: URL thanh toán
    HS->>PAY: Thanh toán
    PAY->>API: IPN (có chữ ký)
    API->>API: Kiểm chữ ký, số tiền, trạng thái, provider_txn_id duy nhất
    API->>ENT: Cấp quyền (idempotent)
    API-->>PAY: Xác nhận
    PAY-->>HS: Chuyển về trang kết quả
    HS->>API: GET /orders/{id} → PAID

#6. Công nghệ đề xuất (cho phương án B/C)

#7. Bảo mật

#8. Triển khai & môi trường

flowchart LR
    DEV["dev<br/>(mỗi PR có preview)"] --> STG["staging<br/>dữ liệu mẫu + nội dung thật đang biên tập"] --> PRD["production"]
    STG -. "UAT, kiểm thử tải" .- STG

Mùa thi (tháng 4–6): tăng số máy chủ ứng dụng theo lịch, bật cache trang tài nguyên đã xuất bản tại CDN, kiểm thử tải trước 4 tuần.

#9. Nhật ký quyết định kiến trúc (ADR)

Mẫu ADR chi tiết (dùng khi chốt từng quyết định):

# ADR-xxx: <Tiêu đề>
- Trạng thái: Đề xuất | Chấp nhận | Thay thế bởi ADR-yyy
- Ngày: dd/mm/yyyy · Người quyết định: ...
## Bối cảnh
## Các phương án đã cân nhắc
## Quyết định
## Hệ quả (tích cực / tiêu cực / việc phải làm)