System Design Document (SDD): AI Content Production Loop

Octo101 AI Platform | Version 1.0

Trường (Field)	Giá trị (Value)
Mã tài liệu (Document ID)	EQ-SDD-003
Phiên bản (Version)	1.0
Ngày tạo (Date)	2026-07-18
Trạng thái (Status)	Draft
Tác giả (Author)	Octo101 System Architecture Team

1. Kiến trúc Hệ thống & Luồng Dữ liệu (System Architecture & Data Flows)

AI Content Production Loop được xây dựng dựa trên mô hình phi tập trung gồm 3 tác nhân AI tương tác qua cơ sở dữ liệu Cloudflare D1 và được điều khiển bởi Cloudflare Workflows.

mermaid

graph TD
    Competency[cf_skills Table] -->|Gắn kết mục tiêu| KPack[cur_knowledge_packages Table]
    KPack -->|Nguồn dữ liệu gốc| GenEngine[AI 1: Content Generation Engine]
    
    GenEngine -->|Sinh nháp| Activities[cf_learning_activities Table]
    Activities -->|Đầu vào đánh giá| ReviewEngine[AI 2: Quality Review Engine]
    
    ReviewEngine -->|Đạt/Không đạt| ReviewTable[ops_ai_quality_reviews Table]
    ReviewTable -->|Đạt & Đợi phê duyệt| HumanPanel[Human-in-the-loop Interface]
    HumanPanel -->|Duyệt & Sửa 8%| Publish[Xuất bản Activities]
    
    Publish -->|Học sinh học| TelemetryTable[evd_content_telemetry Table]
    TelemetryTable -->|Phân tích dữ liệu| AnalyticsEngine[Content Analytics Engine]
    
    AnalyticsEngine -->|Tính chỉ số hiệu quả| AnalyticsTable[evd_content_analytics Table]
    AnalyticsTable -->|Đề xuất nâng cấp| EvolutionEngine[AI 3: Knowledge Evolution Engine]
    
    EvolutionEngine -->|Tạo phiên bản v2| KPackVersion[cur_knowledge_package_versions Table]
    KPackVersion -->|Kích hoạt nâng cấp| KPack

2. Thiết kế Cơ sở dữ liệu (Database Schema Design)

Dưới đây là các bảng SQLite D1 mới phục vụ cho AI Content Production Loop. Các định nghĩa bảng tuân thủ chế độ STRICT và cơ chế khoá ngoại đồng bộ với hệ thống hiện tại.

2.1 Bảng Gói Tri thức (`cur_knowledge_packages`)

Lưu trữ thông tin cấu trúc nền tảng làm "Single Source of Truth" cho một khái niệm (Concept).

sql

CREATE TABLE cur_knowledge_packages (
  id              TEXT NOT NULL PRIMARY KEY,
  concept_id      TEXT NOT NULL REFERENCES cf_concepts(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id) ON DELETE RESTRICT,
  title           TEXT NOT NULL,
  definition      TEXT NOT NULL,
  core_principles TEXT NOT NULL,         -- JSON array of strings
  mental_model    TEXT NOT NULL,         -- Markdown/Text
  visual_analogy  TEXT NOT NULL,         -- JSON hoặc Markdown miêu tả ẩn dụ trực quan
  examples        TEXT NOT NULL,         -- JSON array of objects: [{title, content, explanation}]
  counter_examples TEXT NOT NULL,        -- JSON array of objects: [{title, content, explanation}]
  common_misconceptions TEXT NOT NULL,   -- JSON array of objects: [{misconception, explanation, correction}]
  status          TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'active', 'archived')),
  current_version INTEGER NOT NULL DEFAULT 1,
  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE UNIQUE INDEX idx_cur_kpack_concept ON cur_knowledge_packages(concept_id);

2.2 Bảng Phiên bản Gói Tri thức (`cur_knowledge_package_versions`)

Để đảm bảo tính bất biến (immutability) của lịch sử học tập, mỗi phiên bản nâng cấp từ Evolution Engine sẽ lưu vào đây.

sql

CREATE TABLE cur_knowledge_package_versions (
  id                  TEXT NOT NULL PRIMARY KEY,
  knowledge_package_id TEXT NOT NULL REFERENCES cur_knowledge_packages(id) ON DELETE CASCADE,
  version_number      INTEGER NOT NULL,
  definition          TEXT NOT NULL,
  core_principles     TEXT NOT NULL,     -- JSON array
  mental_model        TEXT NOT NULL,
  visual_analogy      TEXT NOT NULL,
  examples            TEXT NOT NULL,     -- JSON array
  counter_examples    TEXT NOT NULL,     -- JSON array
  common_misconceptions TEXT NOT NULL,   -- JSON array
  evolution_reason    TEXT,              -- Lý do nâng cấp từ AI 3
  created_at          TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE UNIQUE INDEX idx_cur_kpv_num ON cur_knowledge_package_versions(knowledge_package_id, version_number);

2.3 Bảng Kiểm duyệt Chất lượng AI (`ops_ai_quality_reviews`)

Lưu kết quả kiểm duyệt của Quality Review Engine (AI 2).

sql

CREATE TABLE ops_ai_quality_reviews (
  id              TEXT NOT NULL PRIMARY KEY,
  workflow_id     TEXT NOT NULL REFERENCES ops_workflows(id) ON DELETE CASCADE,
  activity_id     TEXT NOT NULL REFERENCES cf_learning_activities(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id) ON DELETE RESTRICT,
  reviewer_model  TEXT NOT NULL,         -- e.g. "gemini-1.5-pro"
  pedagogy_score  REAL NOT NULL,         -- Điểm sư phạm 0.0 - 1.0
  accuracy_score  REAL NOT NULL,         -- Điểm chính xác khoa học 0.0 - 1.0
  safety_score    REAL NOT NULL,         -- Điểm an toàn nội dung 0.0 - 1.0
  alignment_score REAL NOT NULL,         -- Điểm đồng bộ năng lực 0.0 - 1.0
  is_passed       INTEGER NOT NULL CHECK (is_passed IN (0, 1)),
  feedback_details TEXT NOT NULL,        -- JSON chứa chi tiết lỗi hoặc khuyến nghị sửa đổi
  created_at      TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE INDEX idx_ops_aqr_activity ON ops_ai_quality_reviews(activity_id);

2.4 Bảng Telemetry Tương tác của Học sinh (`evd_content_telemetry`)

Lưu trữ chi tiết các hành động tương tác thời gian thực của người học để phục vụ phân tích nội dung.

sql

CREATE TABLE evd_content_telemetry (
  id              TEXT NOT NULL PRIMARY KEY,
  student_id      TEXT NOT NULL REFERENCES iam_users(id) ON DELETE CASCADE,
  activity_id     TEXT NOT NULL REFERENCES cf_learning_activities(id) ON DELETE CASCADE,
  class_id        TEXT REFERENCES lrn_classes(id) ON DELETE SET NULL,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id) ON DELETE RESTRICT,
  event_type      TEXT NOT NULL CHECK (event_type IN ('start', 'progress', 'hint_usage', 'wrong_attempt', 'dropout', 'complete')),
  time_spent_secs INTEGER NOT NULL,
  completion_rate REAL NOT NULL,         -- Điểm phần trăm hoàn thành bài học (0.0 - 1.0)
  event_context   TEXT,                  -- JSON chi tiết sự kiện (ví dụ: hint_id, wrong_answer_details)
  created_at      TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE INDEX idx_evd_telemetry_student ON evd_content_telemetry(student_id);
CREATE INDEX idx_evd_telemetry_activity ON evd_content_telemetry(activity_id);

2.5 Bảng Phân tích Hiệu năng Nội dung (`evd_content_analytics`)

Lưu kết quả tổng hợp phân tích định kỳ hiệu quả của từng hoạt động học tập.

sql

CREATE TABLE evd_content_analytics (
  id              TEXT NOT NULL PRIMARY KEY,
  activity_id     TEXT NOT NULL REFERENCES cf_learning_activities(id) ON DELETE CASCADE,
  organization_id TEXT NOT NULL REFERENCES iam_organizations(id) ON DELETE RESTRICT,
  sample_size     INTEGER NOT NULL,      -- Số học sinh đã học bài này trong kỳ tính toán
  completion_rate REAL NOT NULL,         -- Tỷ lệ hoàn thành trung bình
  confusion_score REAL NOT NULL,         -- Điểm số gây bối rối (0.0 - 1.0)
  dropout_rate    REAL NOT NULL,         -- Tỷ lệ bỏ giữa chừng
  discrimination_index REAL,             -- Chỉ số phân loại câu hỏi (đối với quiz, -1.0 đến 1.0)
  avg_hints_used  REAL NOT NULL,
  detected_misconceptions TEXT,          -- JSON array chứa các lỗi sai phổ biến được phát hiện tự động
  analyzed_at     TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE UNIQUE INDEX idx_evd_content_analytics_act ON evd_content_analytics(activity_id);

3. Đặc tả API Endpoints (API Endpoint Specifications)

Tất cả các API route mới được tích hợp dưới nhóm prefix /api/content.

3.1 Quản lý Knowledge Package

POST /api/content/k-packages

Tạo mới hoặc lưu bản nháp một Knowledge Package.

Request Body:

json

{
  "concept_id": "con_algo_binary_search",
  "title": "Thuật toán Tìm kiếm Nhị phân",
  "definition": "Một thuật toán tìm kiếm hiệu quả dựa trên việc chia đôi khoảng tìm kiếm...",
  "core_principles": ["Mảng đầu vào phải được sắp xếp", "Thu hẹp khoảng tìm kiếm theo lũy thừa của 2"],
  "mental_model": "Tìm kiếm một từ trong cuốn từ điển bằng cách mở trang giữa...",
  "visual_analogy": "Trò chơi đoán số từ 1 đến 100 bằng gợi ý 'Lớn hơn' hay 'Nhỏ hơn'",
  "examples": [{"title": "Tìm số 7 trong mảng [1, 3, 5, 7, 9]", "content": "..."}],
  "counter_examples": [{"title": "Tìm trong mảng chưa sắp xếp", "content": "..."}],
  "common_misconceptions": [{"misconception": "Áp dụng được cho mọi mảng", "explanation": "..."}]
}

Response: 201 Created kèm theo kpack_id.

GET /api/content/k-packages/:id/versions
- Lấy danh sách toàn bộ các phiên bản đã tiến hoá của K-Pack.
- Response: 200 OK chứa mảng các bản ghi từ cur_knowledge_package_versions.

3.2 Sinh & Đánh giá Chất lượng

POST /api/content/k-packages/:id/generate
- Kích hoạt Cloudflare Workflow để sinh Learning Activities và chạy kiểm định chất lượng AI.
- Request Body:
  json
```
{
  "target_activity_types": ["lesson", "quiz", "coding"]
}
```
- Response: 202 Accepted kèm workflow_id để theo dõi tiến trình.
GET /api/content/quality-reviews/:workflow_id
- Lấy lịch sử review chi tiết của AI Quality Engine đối với workflow đang chạy hoặc đã chạy xong.
- Response: 200 OK chứa các bản ghi trong ops_ai_quality_reviews.

3.3 Thu thập Telemetry & Phân tích

POST /api/content/telemetry

Nhận dữ liệu telemetry do Learner Client gửi lên theo thời gian thực (throttle định kỳ 10 giây hoặc khi có sự kiện đặc biệt).

Request Body:

json

{
  "activity_id": "act_binary_search_intro",
  "class_id": "cl_grade7_cs",
  "event_type": "hint_usage",
  "time_spent_secs": 45,
  "completion_rate": 0.4,
  "event_context": {
    "hint_id": "hint_bs_boundary",
    "question_id": "q_bs_mid_calc"
  }
}

Response: 200 OK.

GET /api/content/analytics/:activity_id
- Lấy báo cáo hiệu suất chi tiết của hoạt động học tập dựa trên telemetry tích lũy.
- Response: 200 OK chứa thông số từ evd_content_analytics.
POST /api/content/analytics/:activity_id/evolve
- Thủ công hoặc tự động kích hoạt Knowledge Evolution Engine cho một hoạt động học tập có hiệu quả thấp.
- Response: 202 Accepted kèm theo thông tin phiên bản đề xuất (K-Pack v2 nháp) và lý do cải tiến chi tiết.

System Design Document (SDD): AI Content Production Loop ​

Octo101 AI Platform | Version 1.0 ​

1. Kiến trúc Hệ thống & Luồng Dữ liệu (System Architecture & Data Flows) ​

2. Thiết kế Cơ sở dữ liệu (Database Schema Design) ​

2.1 Bảng Gói Tri thức (cur_knowledge_packages) ​

2.2 Bảng Phiên bản Gói Tri thức (cur_knowledge_package_versions) ​

2.3 Bảng Kiểm duyệt Chất lượng AI (ops_ai_quality_reviews) ​

2.4 Bảng Telemetry Tương tác của Học sinh (evd_content_telemetry) ​

2.5 Bảng Phân tích Hiệu năng Nội dung (evd_content_analytics) ​

3. Đặc tả API Endpoints (API Endpoint Specifications) ​

3.1 Quản lý Knowledge Package ​

3.2 Sinh & Đánh giá Chất lượng ​

3.3 Thu thập Telemetry & Phân tích ​