--- doc_id: "DOC-META-001" title: "Kiến Trúc Hệ Thống Tài Liệu Chuẩn Diátaxis & AI-Native (Doc-as-Code 2026)" category: "standards" diataxis_type: "explanation" status: "canonical" version: "2026.1" owner_role: "lead_documentation_architect" last_updated: "2026-09-29" tags: ["doc-architecture", "diataxis", "ai-friendly", "yaml-frontmatter", "docs-as-code"] related_code: - "tools/lint/check_documentation_system.py" - "tools/lint/check_code_and_doc_hygiene.py" related_docs: - "docs/README.md" - "docs/standards/ENGINEERING_STANDARDS_2026.md" summary: "Quy chuẩn thiết kế, phân chia module, cấu trúc metadata YAML frontmatter và kiểm thử tự động hệ thống tài liệu FreeExile." --- # KIẾN TRÚC HỆ THỐNG TÀI LIỆU DỰ ÁN FREEEXILE (DOCS-AS-CODE & AI-NATIVE 2026) ## 1. TỔNG QUAN KIẾN TRÚC & TRIẾT LÝ THIẾT KẾ Hệ thống tài liệu của FreeExile được xây dựng như một **Hệ Thống Phần Mềm Thực Thụ (Docs-as-Code)**, phục vụ đồng thời hai nhóm đối tượng độc lập: 1. **Con người (Kỹ sư, Nhà thiết kế, Nhà vận hành)**: Tra cứu nhanh, cấu trúc phân tầng khoa học, sơ đồ trực quan hóa cao, không lan man. 2. **Autonomous AI Agents (Antigravity Agent, Gemini Kernel, Sub-Agents)**: Định tuyến chính xác không ảo giác (Zero Hallucination), nạp ngữ cảnh tối ưu token, tương tác máy tính đọc hiểu qua **Metadata Schema Chuẩn Hóa**. ```mermaid flowchart TD subgraph DiataxisFramework ["Khung Phân Loại Diátaxis 2.0"] direction TB T["TUTORIALS
(Học tập & Onboarding)"] H["HOW-TO GUIDES
(Thao tác & Runbooks)"] R["REFERENCE
(Thông số, APIs, Schemas)"] E["EXPLANATION / ADR
(Kiến trúc & Quyết định)"] end subgraph ModularTaxonomy ["8 Phân Hệ Tài Liệu (Domain Modules)"] direction TB M1["1. architecture/
(Lõi phân tán, Actor, Network, Persistence)"] M2["2. game_design/
(GDD, PoE2 Spirit, Võ học, Kinh tế Barter)"] M3["3. client/
(Metal 120Hz, Isometric 2.5D, PWA Testing)"] M4["4. security/
(Hiến chương CISO, Zero-Trust, Anti-Dupe 2PC)"] M5["5. operations/
(Roadmap 8 tuần, Payment, Feedback Store)"] M6["6. standards/
(Quy chuẩn kỹ thuật, Design Pipeline, Lexicon)"] M7["7. adr/
(Bản ghi quyết định kiến trúc NNNN)"] M8["8. design_requests/ & audit/
(Pipeline nghiệm thu & Audit)"] end subgraph AIEngineering ["AI-Native Layer & Tooling"] YAML["YAML Frontmatter Schema
(doc_id, category, diataxis, tags, owner)"] IndexJSON["documentation_index.json
(Catalog máy tính đọc tự động)"] Linter["check_documentation_system.py
(CI/CD Quality Gate & Audit)"] end DiataxisFramework --> ModularTaxonomy ModularTaxonomy --> AIEngineering ``` --- ## 2. PHÂN HỆ MODULE HÓA & TRÁCH NHIỆM PHÒNG BAN Hệ thống tài liệu triệt tiêu hoàn toàn hiện tượng "để phẳng file ở thư mục gốc", phân bổ về 8 thư mục module chuyên biệt: | Phân Hệ Module | Thư Mục Vật Lý | Trách Nhiệm Chủ Trì | Mục Đích Trọng Tâm | | :--- | :--- | :--- | :--- | | **0. Master Index** | `docs/README.md` | `lead_documentation_architect` | Bản đồ tri thức toàn cục, điều hướng tức thì, danh bạ tài liệu. | | **1. Architecture** | `docs/architecture/` | `server_systems_architect` | Phân tán 1M CCU, Spatial Grid, QUIC Gateway, Actor Model, 2PC Sổ cái. | | **2. Game Design** | `docs/game_design/` | `poe2_game_designer` | GDD Cổ Võ Hoang Dã, Huyết Cốt Ma Đồ, Chiêu thức PoE2, Kinh tế Barter. | | **3. Client Engine** | `docs/client/` | `ios_client_engineer` | Apple Metal API, ProMotion 120Hz, Tọa độ Isometric 2.5D, PWA Simulator. | | **4. Security** | `docs/security/` | `ciso_agent` | Hiến chương CISO, Zero-Trust, Apple App Attest, Touch Biometrics AI. | | **5. Operations** | `docs/operations/` | `studio_producer` | Lộ trình 8 tuần, Cổng thanh toán MegaShop, CSDL Góp ý & Báo lỗi SQLite. | | **6. Standards** | `docs/standards/` | `lead_documentation_architect` | Quy chuẩn kỹ thuật 2026, Asset Pipeline DRQ, Từ điển 9 ngôn ngữ. | | **7. ADR** | `docs/adr/` | `server_systems_architect` | Các bản ghi quyết định kiến trúc có đánh đổi (WASM, 2PC, Guild, AI). | | **8. Design Pipeline**| `docs/design_requests/`| `tech_art_pipeline` | Luồng yêu cầu mỹ thuật (inbox, in_progress, pending_review, approved). | --- ## 3. CHUẨN METADATA AI-NATIVE (YAML FRONTMATTER SPECIFICATION) Mọi tệp tin `.md` trong hệ thống bắt buộc bắt đầu bằng khối YAML Frontmatter chuẩn mực: ```yaml --- doc_id: "DOC-ARCH-001" # Mã định danh duy nhất (Ký tự hoa, chuẩn hóa) title: "Kiến Trúc Phân Tán Triệu CCU" # Tiêu đề tài liệu khoa học category: "architecture" # architecture | game_design | client | security | operations | standards | adr diataxis_type: "explanation" # tutorial | how-to | reference | explanation status: "canonical" # draft | review | canonical | deprecated version: "2026.1" # Phiên bản chuẩn hóa owner_role: "server_systems_architect" # Vai trò phòng ban phụ trách trực tiếp last_updated: "2026-09-29" # Ngày cập nhật chuẩn ISO 8601 tags: ["distributed", "1m-ccu", "actor-model"] # Danh sách nhãn cho tìm kiếm vector/grep related_code: # Danh sách mã nguồn thực thi trực tiếp - "server/world/spatial_grid.py" related_docs: # Danh sách tài liệu liên kết hữu cơ - "docs/architecture/DISTRIBUTED_ENGINE_1M_CCU_ARCHITECTURE.md" summary: "Tóm tắt 1-3 dòng súc tích, mật độ thông tin cao, không lời thừa." --- ``` ### Lợi ích Đối với Autonomous AI Agents: 1. **Deterministic Indexing**: Agent chỉ cần đọc 15 dòng đầu tiên để lập bản đồ liên kết mã nguồn (`related_code`) mà không cần tốn token đọc toàn văn bản. 2. **Graph Traversal**: Tự động giải quyết cây phụ thuộc tài liệu (`related_docs`) phục vụ tác vụ refactor đa module. 3. **Role Routing**: Tự động phân công subagent phù hợp dựa vào `owner_role`. --- ## 4. QUY CHUẨN VIẾT TÀI LIỆU KHOA HỌC & NGẮN GỌN (HIGH-DENSITY WRITING) ### 4.1. Quy Tắc Giới Hạn Độ Dài (Length Caps) - **Soft Cap**: $\le 400\text{ dòng}$ (Ngưỡng khuyến nghị tối ưu token). - **Hard Cap**: $\le 600\text{ dòng}$ (Ngưỡng chặn tuyệt đối; vi phạm sẽ bị CI linter đánh trượt). - **Giải pháp khi vượt ngưỡng**: Chia nhỏ thành các module độc lập theo Diátaxis (ví dụ: tách tài liệu hướng dẫn `how-to` riêng, bảng tra cứu `reference` riêng). ### 4.2. Nguyên Tắc Trình Bày (Presentation Principles) - **Zero Lip-Service / Fluff-Free**: Loại bỏ hoàn toàn các đoạn mở đầu chào hỏi, văn xuôi dẫn nhập cảm tính ("Trong thế giới game phát triển nhanh chóng...", "Như chúng ta đã biết..."). Đi thẳng vào định nghĩa, thông số và kiến trúc. - **Table-First Design**: Mọi thông số, so sánh cơ chế, mã lỗi bắt buộc chuẩn hóa dưới dạng bảng (Markdown Tables). - **Mermaid Diagrams**: Mọi luồng xử lý hoặc cấu trúc dữ liệu phức tạp phải được biểu diễn bằng Mermaid: - `flowchart TD / LR`: Sơ đồ kiến trúc & phân luồng. - `sequenceDiagram`: Luồng giao thức mạng, handshake, 2PC transactions. - `stateDiagram-v2`: Vòng đời nhân vật, trạng thái quái vật, instance lifecycle. - **Clickable Links**: Toàn bộ tham chiếu tệp mã nguồn hoặc tài liệu liên quan bắt buộc dùng cú pháp liên kết tuyệt đối máy chủ: `[README.md](file:///c:/Projects/FreeExile/docs/README.md)` (ví dụ minh họa liên kết tuyệt đối). --- ## 5. BỘ CÔNG CỤ TỰ ĐỘNG HÓA & QUALITY GATE (AUTOMATED TOOLING) Hệ thống tài liệu được bảo vệ bởi công cụ tự động hóa khép kín: - **CLI Linter**: `python tools/lint/check_documentation_system.py` - Quét 100% tài liệu trong `docs/`. - Kiểm tra tính đầy đủ và hợp lệ của YAML Frontmatter. - Kiểm tra độ dài file so với Soft/Hard Cap. - Kiểm tra tính toàn vẹn của liên kết nội bộ (Broken Link Detection). - Tự động biên dịch cơ sở dữ liệu `docs/documentation_index.json` phục vụ Agentic AI RAG / Semantic Retrieval. - **Tích Hợp CI/CD**: Kiểm tra vệ sinh tổng hợp qua `python tools/lint/check_code_and_doc_hygiene.py`.