#06 – Mô hình miền & dữ liệu

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

Mô hình logic, độc lập công nghệ. Tên thực thể dùng tiếng Anh để dùng thẳng trong mã nguồn; mô tả tiếng Việt.

#1. Các miền nghiệp vụ (Bounded contexts)

flowchart LR
    subgraph ID["Định danh & Quyền"]
        U["User / Role"]
        ENT["Entitlement"]
    end
    subgraph CAT["Nội dung (Catalog)"]
        BOOK["Book / ContentNode"]
        RES["LearningResource"]
        CODE["ContentCode (ID)"]
        VID["Video"]
        TAX["Taxonomy (ma trận)"]
    end
    subgraph ASM["Đánh giá (Assessment)"]
        Q["Question / Rubric"]
        A["Assessment / Section / Item"]
        AT["Attempt / Answer"]
        REC["Recommendation"]
    end
    subgraph ACT["Kích hoạt"]
        BATCH["ActivationBatch / Code"]
    end
    subgraph CLS["Lớp học"]
        C["Class / Assignment"]
    end
    subgraph COM["Thương mại"]
        P["Package / Order / Payment"]
    end
    subgraph ANA["Phân tích"]
        EV["Event"]
    end
    ACT -- "cấp" --> ENT
    COM -- "cấp" --> ENT
    CODE --> RES
    RES --> A
    A --> Q
    Q --> TAX
    AT --> REC
    REC --> TAX
    C --> A
    ID -.-> ANA

#2. Sơ đồ quan hệ thực thể (ERD)

erDiagram
    USER ||--o{ ENTITLEMENT : "có"
    USER ||--o{ ATTEMPT : "thực hiện"
    USER ||--o{ ORDER : "đặt"
    USER ||--o{ CLASS_MEMBER : "thuộc"
    BOOK ||--o{ CONTENT_NODE : "gồm"
    BOOK ||--o{ ACTIVATION_BATCH : "có"
    BOOK ||--o{ CONTENT_CODE : "in"
    ACTIVATION_BATCH ||--o{ ACTIVATION_CODE : "sinh"
    ACTIVATION_CODE |o--o| ENTITLEMENT : "tạo"
    CONTENT_NODE ||--o{ CONTENT_NODE : "con"
    CONTENT_NODE ||--o{ LEARNING_RESOURCE : "chứa"
    CONTENT_CODE }o--|| LEARNING_RESOURCE : "trỏ tới"
    LEARNING_RESOURCE |o--o| VIDEO : "dùng"
    LEARNING_RESOURCE |o--o| ASSESSMENT : "là"
    ASSESSMENT ||--o{ ASSESSMENT_SECTION : "chia"
    ASSESSMENT_SECTION ||--o{ ASSESSMENT_ITEM : "gồm"
    ASSESSMENT_ITEM }o--|| QUESTION : "dùng"
    QUESTION }o--o| PASSAGE : "thuộc ngữ liệu"
    QUESTION |o--o| RUBRIC : "chấm theo"
    QUESTION |o--o| VIDEO : "lời giải video"
    QUESTION ||--o{ QUESTION_TAG : "gắn"
    TAXONOMY_TAG ||--o{ QUESTION_TAG : "được gắn"
    TAXONOMY_TAG ||--o{ TAXONOMY_TAG : "con"
    TAXONOMY_TAG |o--o{ CONTENT_NODE : "ứng với chuyên đề"
    ATTEMPT }o--|| ASSESSMENT : "của"
    ATTEMPT }o--o| ASSIGNMENT : "theo bài giao"
    ATTEMPT ||--o{ ATTEMPT_ANSWER : "gồm"
    ATTEMPT_ANSWER }o--|| QUESTION : "trả lời"
    ATTEMPT ||--o{ RECOMMENDATION : "sinh"
    RECOMMENDATION }o--|| TAXONOMY_TAG : "về"
    CLASS ||--o{ CLASS_MEMBER : "có"
    CLASS ||--o{ ASSIGNMENT : "được giao"
    ASSIGNMENT }o--|| ASSESSMENT : "giao"
    PACKAGE ||--o{ PACKAGE_ITEM : "gồm"
    PACKAGE_ITEM }o--|| ASSESSMENT : "đề"
    ORDER }o--|| PACKAGE : "mua"
    ORDER ||--o{ PAYMENT : "thanh toán"
    ORDER |o--o| ENTITLEMENT : "tạo"
    USER ||--o{ EVENT : "phát sinh"

#3. Cơ chế ID nội dung và QR

#3.1 Yêu cầu đối với ID

• Ngắn, gõ được trên điện thoại trong < 5 giây; không có ký tự dễ nhầm.
• Học sinh và nhân viên hỗ trợ đọc được ý nghĩa (môn, loại).
• Không trùng trong phạm vi một phiên bản sách; không bao giờ thay đổi sau khi in.
• Không phụ thuộc vào cấu trúc kỹ thuật (đổi tài nguyên đích mà không đổi ID).

#3.2 Định dạng đề xuất (ADR-002)

 T  V  0 1 2
 │  │  └┴┴── Số thứ tự 3 chữ số trong (môn, loại): 001–999
 │  └─────── Loại tài nguyên (1 chữ)
 └────────── Môn (1 chữ)

Ví dụ: TL021 – lý thuyết Toán số 21; TV045 – ví dụ Toán số 45; TD003 – đề thi thử Toán số 3; AK002 – placement test Tiếng Anh số 2; VB007 – bài vận dụng Ngữ văn số 7.

Phạm vi phiên bản: khoá duy nhất của ID là (book_edition_id, code). Học sinh chỉ gõ TV045; hệ thống tra trong các sách học sinh đã kích hoạt (BR-06). QR chứa phiên bản để không mơ hồ: https://<tên miền>/27/TV045 (27 = phiên bản 2027).

Phương án thay thế (nếu HEID muốn ID không mang nghĩa): mã ngẫu nhiên 5 ký tự từ bảng 31 ký tự (≈ 28,6 triệu tổ hợp) – an toàn trước việc đoán ID nhưng khó hỗ trợ qua điện thoại. Vì nội dung đã được bảo vệ bằng quyền sử dụng (BR-03), việc đoán được ID không làm lộ nội dung → khuyến nghị dùng ID có nghĩa.

#3.3 Vòng đời ID

stateDiagram-v2
    [*] --> RESERVED: BTV sinh ID
    RESERVED --> ASSIGNED: Gán tài nguyên
    ASSIGNED --> RESERVED: Bỏ gán (chưa khoá)
    ASSIGNED --> LOCKED: Trưởng ban khoá khi chốt in
    LOCKED --> LOCKED: Đổi tài nguyên đích (lưu vết)
    LOCKED --> RETIRED: Ngừng dùng (chuyển hướng tới tài nguyên thay thế)
    RESERVED --> [*]: Xoá (chỉ khi chưa khoá)

#3.4 Mã kích hoạt

• 10 ký tự từ bảng 23456789ABCDEFGHJKMNPQRSTUVWXYZ (31 ký tự), in dạng XXXX-XXXX-XX và kèm QR https://<tên miền>/kich-hoat/<mã>.
• Lưu băm của mã để tra cứu (HMAC-SHA256 với khoá bí mật) và bản mã hoá để xuất lại cho nhà in khi cần; không lưu bản rõ trong log.
• Trạng thái: NEW → EXPORTED → REDEEMED / REVOKED.

#4. Từ điển dữ liệu (thực thể chính)

#4.1 Định danh & quyền

USER

ENTITLEMENT – quyền sử dụng

#4.2 Nội dung

BOOK (một phiên bản sách)

CONTENT_NODE – cây nội dung sách

LEARNING_RESOURCE

CONTENT_CODE – ID in trên sách

VIDEO

TAXONOMY_TAG – ma trận kiến thức

#4.3 Đánh giá

QUESTION

RUBRIC: id, criteria JSON [{code, name, max_points, levels:[{label, points, descriptor}]}], total_points.

ASSESSMENT

ASSESSMENT_SECTION: id, assessment_id, title ("Phần I"), order_no, question_type, points_rule JSON. ASSESSMENT_ITEM: section_id, question_id, question_version, order_no, points.

ATTEMPT

ATTEMPT_ANSWER

RECOMMENDATION: attempt_id, tag_id, items_total, items_wrong, items_slow, error_rate, rank, resource_ids (lý thuyết/ví dụ/bài tập gợi ý).

#4.4 Kích hoạt, lớp học, thương mại, phân tích

#5. Ràng buộc & chỉ mục quan trọng

#6. Phân loại dữ liệu & lưu trữ