---
doc_id: "DOC-STD-001"
title: "Tôn Chỉ Kỹ Thuật & Quy Tắc Phát Triển Chuẩn Công Nghiệp 2026"
category: "standards"
diataxis_type: "reference"
status: "canonical"
version: "2026.1"
owner_role: "lead_documentation_architect"
last_updated: "2026-10-02"
tags: ["engineering-standards", "clean-code", "tdd", "diataxis", "file-hygiene", "reactive-i18n"]
related_code:
  - "tools/lint/check_code_and_doc_hygiene.py"
  - "tools/lint/check_i18n_hygiene.py"
  - "client/webapp/js/data/i18n.js"
related_docs:
  - "docs/DOCUMENTATION_SYSTEM_ARCHITECTURE.md"
  - "docs/standards/GLOBAL_LOCALIZATION_DICTIONARY.md"
summary: "Quy chuẩn mã nguồn Python/TypeScript/Metal, giới hạn độ dài file/hàm, kiến trúc reactive i18n không reload trang, chu trình TDD khép kín, văn hóa Docs-as-Code."
---

# FREEEXILE: TÔN CHỈ KỸ THUẬT & QUY TẮC PHÁT TRIỂN CHUẨN CÔNG NGHIỆP 2026
> **Bản quyền**: FreeExile Autonomous Game Studio  
> **Phiên bản chuẩn hóa**: 2026.1-RELEASE  
> **Cấp độ kỹ thuật**: Elite Industry Standards (Principal / Staff Systems Engineer Standard)
---
## 1. TÔN CHỈ KỸ THUẬT CỐT LÕI (CORE ENGINEERING TENETS - 8 BẤT BIẾN)

```mermaid
flowchart TD
    T1["1. Action-Driven, Zero Lip-Service\n(Nói bằng code, test & benchmark)"]
    T2["2. Spec-Driven & Schema-First\n(Single Source of Truth)"]
    T3["3. Zero-Trust Server Authority\n(Máy chủ uy quyền tuyệt đối)"]
    T4["4. Zero-Dupe Event Sourcing\n(Sổ cái bất biến, 2PC giao dịch)"]
    T5["5. Mechanical Sympathy\n(120Hz ProMotion, O(1) Grid, Zero-Alloc)"]
    T6["6. Strict Type-Safety & Defensive\n(Không uncaught exceptions, Result type)"]
    T7["7. Autonomous Closed-Loop Verification\n(TDD Red-Green, Swarm 1M CCU)"]
    T8["8. Docs-as-Code & Living Knowledge\n(Diátaxis framework, ADR bất biến)"]

    T1 --> T2 --> T3 --> T4
    T4 --> T5 --> T6 --> T7 --> T8
```

1. **Action-Driven, Zero Lip-Service (Thực thi là chân lý)**:
   - Không tranh luận lý thuyết suông; mọi quy chuẩn hoặc giải pháp kiến trúc phải được cụ thể hóa bằng mã nguồn có thể chạy được, bộ test suite kiểm chứng, benchmark định lượng và tài liệu hóa trực tiếp vào repository.
2. **Spec-Driven & Schema-First (Single Source of Truth)**:
   - Mọi thực thể dữ liệu, API và gói tin mạng đều bắt nguồn từ hợp đồng định nghĩa chuẩn (Protobuf v3, JSON Schema, OpenAPI). Tuyệt đối cấm client hoặc server tự suy đoán hay định nghĩa payload ngầm (magic payload).
3. **Zero-Trust Server Authority (Máy chủ uy quyền tuyệt đối)**:
   - Phía Client chỉ là cỗ máy mô phỏng hiển thị và dự đoán trạng thái (Client Prediction & Interpolation). Server nắm giữ 100% quyền phán quyết: tọa độ thực tế, tầm nhìn raycast, xác suất trúng/né, sát thương và rơi đồ.
4. **Zero-Duplication Ledger & Event Sourcing (Bất biến tài chính ảo)**:
   - Kinh tế Bản Vị Huyết Thạch không tồn tại tiền vàng lạm phát. Mọi biến động tài sản (linh thạch, phù lục, đan dược) phải được ghi vào luồng Event Sourcing bất biến và khóa giao dịch phân tán 2 pha (2PC). Không một vật phẩm nào được phép tồn tại ở hai nơi cùng lúc.
5. **Mechanical Sympathy & Hard Real-Time Constraints (Thấu hiểu phần cứng)**:
   - Client đạt chuẩn ProMotion 120Hz ($8.33\text{ ms/frame}$). Tuyệt đối không sinh rác bộ nhớ (Zero Allocation) trong các vòng lặp nóng (`update(dt)`, render pass). Tận dụng tối đa Apple Metal Compute Shaders và CPU cache lines.
   - Server phân chia không gian Spatial Grid $O(1)$, AoI (Area of Interest) broadcast cục bộ để phục vụ đồng thời 1.000.000+ CCU với p99 latency < 25ms.
6. **Strict Type-Safety & Defensive by Design (An toàn kiểu loại & Phòng thủ chủ động)**:
   - Cấm triệt để việc bỏ qua kiểu dữ liệu (`Any`, `unknown` không kiểm tra, `pass` trong exception). Mọi nhánh rẽ lỗi phải được mô hình hóa tường minh qua `Result[T, E]` hoặc exception chuyên biệt.
7. **Autonomous Closed-Loop Verification (Kiểm thử tự hành khép kín)**:
   - Quy trình TDD nghiêm ngặt: Viết test trước -> Xác nhận FAIL (Negative Baseline) -> Viết code tối thiểu -> Tự sửa lỗi (Self-Healing tối đa 5 vòng lặp) -> PASS 100% mới commit.
8. **Docs-as-Code & Living Knowledge (Tài liệu sống đồng hành cùng mã nguồn)**:
   - Mọi tài liệu nằm chung repository với mã nguồn, được phiên bản hóa qua Git, áp dụng khung Diátaxis và cập nhật đồng bộ trong cùng atomic commit với tính năng.
---
## 2. MÔ HÌNH VẬN HÀNH AI-NATIVE & KỸ SƯ TỰ HÀNH 2026

Năm 2026 đánh dấu bước chuyển mình toàn diện từ "AI gợi ý code đơn lẻ" sang **Mô hình Studio Đa Tác Nhân Tự Hành (Autonomous Multi-Agent Game Studio)**:

```mermaid
sequenceDiagram
    autonumber
    actor Dev as Principal Architect / User
    participant Producer as Studio Producer (Host Agent)
    participant Specialist as Specialized Subagent (Branch Worktree)
    participant OCR as Alibaba Open Code Review
    participant CI as Autonomous TDD & Verification
    participant Repo as Master Branch & Mem0

    Dev->>Producer: Yêu cầu tính năng / Refactoring kiến trúc
    Producer->>Repo: mem0_search (Tra cứu context & thói quen)
    Producer->>Specialist: invoke_subagent (Workspace: 'branch')
    Specialist->>CI: 1. Viết Negative Test (Xác nhận FAIL)
    Specialist->>Specialist: 2. Triển khai code chuẩn 2026
    Specialist->>CI: 3. TDD Loop (Self-Healing tối đa 5 lần)
    CI-->>Specialist: Test GREEN (100% Pass)
    Specialist-->>Producer: Bàn giao branch worktree
    Producer->>OCR: ocr delegate preview & rule
    Producer->>Producer: Gemini Suy luận & Đối soát Line-level
    Producer->>Repo: Fast-forward Merge + mem0_add (Lưu trữ bài học)
    Producer-->>Dev: Báo cáo kết quả nghiệm thu + Metrics
```

- **Nguyên tắc phân nhánh Worktree**: Mọi tác vụ có độ phức tạp cao, refactor đa module hoặc nâng cấp bảo mật đều chạy trong môi trường Git Worktree cô lập (`Workspace: 'branch'`), ngăn chặn tuyệt đối việc làm hỏng trạng thái làm việc chính.
- **Kỹ nghệ Cú pháp AST**: Thay thế hoàn toàn regex thô sơ bằng `ast-grep` và LSP (`ast_grep_search`, `lsp_definition`, `lsp_references`). Quy trình 2 pha: Preview (`apply: false`) -> Mutation (`apply: true`).
- **Bộ nhớ Thích ứng Dài hạn**: Khai thác dịch vụ Mem0 chạy ngầm (`http://127.0.0.1:8765/sse`, Qdrant embedded) để tích lũy kiến trúc và quy ước code xuyên suốt dự án.
---
## 3. QUY CHUẨN VIẾT CODE BẬC THẦY (ELITE CODE STANDARDS)

### 3.1. Nguyên Tắc Thiết Kế Kiến Trúc Chung
1. **Phân tách Ranh giới Vực miền (Domain Boundary Isolation)**:
   - `Domain Model`: Chứa toàn bộ nghiệp vụ thuần túy (võ học Bát Mạch, công thức sát thương, trạng thái nhân vật). Không phụ thuộc vào database, framework hay thư viện mạng.
   - `Application / Service Layer`: Điều phối luồng xử lý (combat engine, trade manager, session manager).
   - `Infrastructure / Transport`: Quản lý socket, database connection pool, redis cache, kafka producers.
2. **Explicit over Implicit (Tường minh hơn ngầm định)**:
   - Không sử dụng hằng số ma thuật (Magic Numbers/Strings). Mọi giá trị số học (tỷ lệ bạo kích, tick interval, kích thước grid cell) phải khai báo trong `enum` hoặc hằng số có tài liệu giải thích đơn vị đo lường (ví dụ: `TICK_RATE_MS = 50`, `MAX_INTERPOLATION_BUFFER_SIZE = 10`).
3. **Idempotency & Replayability (Tính lũy đẳng & Khả năng phát lại)**:
   - Mọi command gửi lên server phải kèm `client_sequence_id` hoặc `nonce`. Server xử lý trùng lặp tự động bằng idempotency cache.
---
### 3.2. Quy Chuẩn Lõi Server: Native C++20 SIMD Core & Python 3.11+ Orchestration

Hệ thống Server của FreeExile áp dụng mô hình **Kiến trúc Lai Cao Cấp (Hybrid Polyglot Architecture)**:
1. **Lõi Native C++20 SIMD (Hot Paths)**:
   - Toàn bộ tính toán tần số cao (30Hz World Simulation, Flat Spatial Hash Grid, Capsule 2.5D Collision, Q16.16 Fixed Point Math, và Movement Authority) được viết $100\%$ bằng **C++20 tối ưu hóa AVX2 SIMD** với `server_cpp/` làm đầu mối build duy nhất (xuất bản `freeexile_sim_core.dll` và `freeexile_zone_server.exe`).
   - Cấm cấp phát bộ nhớ động (`new`/`malloc`) trong vòng lặp tick loop; sử dụng Structure of Arrays (SoA) và pre-allocated memory arenas để đạt hiệu năng xử lý $< 0.07\text{ ms}$ cho $10.000$ entities.
2. **Tầng Điều Phối Python 3.11+ (Orchestration & Rules)**:
   - Python đảm nhận tầng kịch bản bậc cao: nhiệm vụ (Quests), sự kiện thế giới, quản lý phiên và giao tiếp sổ cái Kafka/Redis.
   - Bắt buộc kiểm tra kiểu chặt chẽ với `mypy --strict`. Tuyệt đối không dùng `Any` trừ trường hợp FFI C-types.
   - Sử dụng `dataclass(slots=True, frozen=True)` cho các DTO và Domain Value Objects nhằm giảm 40% RAM và tăng tốc độ truy cập.

```python
# CHUẨN KỸ SƯ 2026: Immutability, Slots, Explicit Types
from dataclasses import dataclass

@dataclass(slots=True, frozen=True)
class MeridianNode:
    node_id: int
    name_key: str
    element_type: int
    base_bonus_stat: float
    required_level: int
    def validate_activation(self, level: int) -> bool:
        return level >= self.required_level
```

#### B. Đồng Thì Có Cấu Trúc (Structured Concurrency) & Asynchronous Safety
- Sử dụng `asyncio.TaskGroup` (Python 3.11+) để quản lý các tác vụ song song, tự động hủy bỏ tác vụ anh em khi một nhánh bị lỗi (`Fail-Fast`).
- Mọi thao tác I/O BẮT BUỘC có `asyncio.timeout(seconds)`. Cấm vĩnh viễn việc chờ đợi vô hạn định (hanging tasks).
- **CẤM BLOCKING CALLS**: Cấm `time.sleep()`, synchronous `open()`, synchronous `requests` bên trong async event loop. Dùng `asyncio.sleep()`, `aiofiles`, `aiohttp`/`httpx`.

```python
# CHUẨN KỸ SƯ 2026: Structured Concurrency & Explicit Timeout
async def broadcast_spatial_events(session_ids: Sequence[str], packet_bytes: bytes) -> None:
    async with asyncio.timeout(0.025), asyncio.TaskGroup() as tg:  # SLA p99 < 25ms
        for sid in session_ids:
            tg.create_task(send_to_session(sid, packet_bytes))
```

#### C. Xử Lý Lỗi Phòng Thủ (Defensive Error Handling)
- Tuyệt đối cấm cú pháp:
  ```python
  # CẤM TUYỆT ĐỐI (Antipattern)
  try:
      do_something()
  except:
      pass
  ```
- Định nghĩa phân cấp Domain Exceptions rõ ràng; bắt chính xác lớp lỗi và log kèm `correlation_id` / `session_id`.
---
### 3.3. Quy Chuẩn TypeScript & Apple Metal Client Engine

Phía Client chịu trách nhiệm vận hành mượt mà 120 FPS trên màn hình ProMotion của thiết bị Apple (iPhone / iPad), đồng thời cung cấp bản WebApp PWA giả lập tương ứng.

#### A. Triết Lý Zero Garbage Allocation trong Game Loop
- **Nguyên tắc sống còn**: Trong các hàm chạy theo chu kỳ mỗi frame như `update(deltaTime)`, `render(ctx)`, `interpolate()`, **TUYỆT ĐỐI KHÔNG** khởi tạo object mới (`new Vector2()`, `new Rect()`, `[]`, `{}`). Việc cấp phát liên tục sẽ kích hoạt Garbage Collector (GC pause), làm tụt FPS từ 120 xuống 40, gây khựng hình (stuttering).
- **Giải pháp**: Sử dụng **Object Pool** và **Scratch Memory** tái sử dụng biến toàn cục hoặc biến thành viên cấp struct.

```typescript
// CHUẨN KỸ SƯ 2026: Zero-Allocation Scratch Vector
export class Vector2 {
  public static readonly ZERO = new Vector2(0, 0);
  private static readonly _scratch = new Vector2(0, 0);
  constructor(public x: number = 0, public y: number = 0) {}
  public set(x: number, y: number): this { this.x = x; this.y = y; return this; }
  public static add(a: Vector2, b: Vector2, out: Vector2): Vector2 {
    out.x = a.x + b.x; out.y = a.y + b.y; return out;
  }
}
```

#### B. Định Kiểu Bất Biến & Type-Narrowing
- Bật 100% các flag an toàn trong [tsconfig.json](file:///c:/Projects/FreeExile/client/tsconfig.json): `strict: true`, `noImplicitAny: true`, `strictNullChecks: true`, `exactOptionalPropertyTypes: true`.
- Sử dụng `readonly` cho mảng và các trạng thái cấu hình không biến đổi.
- Ưu tiên Discriminated Unions để loại bỏ type casting ép kiểu nguy hiểm.

```typescript
// CHUẨN KỸ SƯ 2026: Discriminated Union Network Message
export type ServerMessage =
  | { readonly type: 'AUTH_SUCCESS'; readonly sessionToken: string; readonly serverTick: number }
  | { readonly type: 'COMBAT_HIT'; readonly attackerId: number; readonly damage: number };

export function handleServerMessage(msg: ServerMessage): void {
  if (msg.type === 'AUTH_SUCCESS') initSession(msg.sessionToken, msg.serverTick);
  else if (msg.type === 'COMBAT_HIT') renderHitVFX(msg.attackerId, msg.damage);
}
```

#### C. Tối Ưu Hóa Metal Compute Shaders
- Các shader Metal (`.metal`) chịu trách nhiệm tính toán hạt ngũ hành (Five Elements) và Isometric Tilemap:
  - Cấu trúc struct chia sẻ giữa CPU và GPU (MSL) phải canh lề (memory alignment) theo quy tắc SIMD: `vector_float2` canh lề 8-byte, `vector_float4` canh lề 16-byte.
  - Sử dụng Metal Threadgroup Memory cho các phép tính tương tác lân cận nhằm giảm băng thông VRAM chính.
---
### 3.4. Giao Thức Mạng & Schema-First Protobuf

Mọi thông điệp mạng giữa Client và Server được định nghĩa tại thư mục [proto/](file:///c:/Projects/FreeExile/proto/):
- **Tương thích Ngược & Tiến (Backward/Forward Compatibility)**:
  - Không bao giờ thay đổi số thứ tự thẻ (tag number) của trường đã phát hành.
  - Khi một trường bị loại bỏ, bắt buộc đánh dấu `reserved` số thẻ và tên trường đó để tránh việc lập trình viên khác tái sử dụng gây xung đột dữ liệu cũ.
- **Nén & Tối ưu hóa Băng thông**:
  - Tọa độ thế giới được nhân với hằng số cố định (Fixed-point: $\times 1000$) và truyền dưới dạng `int32` thay vì `float64` để tiết kiệm byte và triệt tiêu sai số dấu phẩy động đa nền tảng.
  - Timestamp được đo bằng mili-giây dạng Delta Tick kể từ mốc tick bắt đầu trận đánh.
---
### 3.5. Quy Chuẩn Module Hóa, Phân Tách File & Giới Hạn Định Lượng

Nhằm triệt tiêu hiện tượng mã nguồn cồng kềnh, monolithic classes và trùng lặp logic, toàn bộ phòng ban bắt buộc tuân thủ ma trận định lượng sau:

| Danh Mục | Soft Cap (Cảnh Báo) | Hard Cap (Bắt Buộc Tách File) | Biện Pháp Khắc Phục Bắt Buộc |
| :--- | :--- | :--- | :--- |
| **Logic Code Files** (`.py`, `.ts`, `.cpp`) | $\le 350$ dòng | $\le 500$ dòng | Tách models (`*_types.py`), tách catalog (`*_catalog.py`), tách helpers. |
| **Declarative Catalog Files** (`*_catalog.py`) | $\le 700$ dòng | $\le 1000$ dòng | Chia tách catalog theo nhóm cấp bậc (Normal, Hidden, Epic) hoặc seed files. |
| **Function / Method Length** | $\le 30$ dòng | $\le 50$ dòng | Extract method, chuyển sang pure functions trong `utils/` hoặc `helpers/`. |
| **Cyclomatic Complexity** | $\le 7$ | $\le 10$ | Giảm lồng ghép `if/else`, dùng Early Return (Guard Clauses), Pattern Matching. |
| **Tài Liệu Markdown** (`.md`) | $\le 400$ dòng | $\le 600$ dòng | Áp dụng Diátaxis chia thành sub-documents, chuyển văn xuôi thành bảng specs. |

#### A. Phân Tầng `common/`, `utils/`, `helpers/` Chuẩn Mực
1. **`common/` (Universal Contracts & Core Types)**:
   - Chứa contracts, constants, base error classes, shared core protocols xuyên suốt hệ thống (ví dụ: `server/common/math_utils.py`, `server/common/time_utils.py`).
   - Cấm chứa logic nghiệp vụ đặc thù của bất kỳ domain cụ thể nào.
2. **`utils/` (Pure Stateless Functions)**:
   - Chứa các hàm toán học, xử lý chuỗi, thời gian, mã hóa thuần túy (no side-effects, no global state).
   - Tuyệt đối không duplicate logic tính khoảng cách 2D/3D (dùng `euclidean_distance_2d`, `is_within_radius_2d`) hay timestamp (dùng `now_ms()`).
   - Cấm biến `utils` thành bãi rác ("junk drawer"): Gom nhóm chức năng có tên rõ ràng.
3. **`helpers/` (Domain-Scoped Stateful Facilitators)**:
   - Chứa các hàm bổ trợ luồng xử lý riêng cho một domain (ví dụ `server/world/helpers/`).
   - Đặt trong chính thư mục của domain đó, không đặt ở root.

#### B. Phân Tách Dứt Khoát Giữa Dữ Liệu Hạt Giống (Catalog) và Bộ Máy Thực Thi (Engine)
- **Anti-pattern nghiêm cấm**: Nhồi nhét hàng trăm dòng khai báo dictionaries nhiệm vụ, bản đồ, kỹ năng vào bên trong file `*_engine.py`.
- **Mô hình chuẩn 3 tầng**:
  - `*_types.py`: Chứa Enums, Dataclasses, Protocol definitions (nhẹ, < 150 dòng).
  - `*_catalog.py`: Chứa dữ liệu danh mục tĩnh, seed functions (tập trung dữ liệu).
  - `*_engine.py`: Chứa logic xử lý nghiệp vụ tinh gọn (< 350 dòng).
---
### 3.6. Quy Chuẩn Kiến Trúc Đa Ngôn Ngữ (i18n) & Phản Ứng Tức Thì Đa Nền Tảng (Cross-Platform Reactive i18n Protocol)

1. **Centralized Reactive Event Bus Architecture**:
   - Quản lý tập trung qua `FreeExileI18n` ([client/webapp/js/data/i18n.js](file:///c:/Projects/FreeExile/client/webapp/js/data/i18n.js)). Mọi controller UI (Chat, Settings, HUD) đăng ký qua `FreeExileI18n.subscribe((newLocale, prevLocale, dict) => void)` hoặc lắng nghe CustomEvent `window.addEventListener('freeexile:localeChanged', handler)`.
   - **Strict Zero Page Reload Rule**: Tuyệt đối CẤM gọi `location.reload()` khi đổi ngôn ngữ. Tất cả DOM elements, channel tabs, badges, placeholders và tooltips phải cập nhật tại chỗ (in-place atomic re-render) trong cùng frame loop.
   - **Template Mount Hooks & Cross-Window Sync**: Tự động áp dụng i18n cho các view động qua sự kiện `freeexile:templateMounted` / `freeexile:templatesMounted`. Đồng bộ tức thì giữa các tab/window qua listener `window.addEventListener('storage', ...)`.
2. **Zero-Hardcoded UI String Rule (Tuyệt đối không hardcode chuỗi giao diện)**:
   - Nghiêm cấm đưa chuỗi hiển thị thô (tiếng Việt/tiếng Anh) vào file JS logic hoặc markup tĩnh.
   - Khai báo declarative trong DOM qua thuộc tính `data-i18n="key"` hoặc `data-chat-i18n="key"`.
   - Trong JS controller, bắt buộc dùng `FreeExileI18n.t(key, params, fallback)` hỗ trợ nội suy tham số (`{channel}`, `{sec}`, `{level}`).
3. **9-Language Parity Mandate & Microcopy Bounds**:
   - 100% khóa ngôn ngữ bắt buộc hiện diện đầy đủ trên cả 9 ngôn ngữ: `vi`, `en`, `zh`, `ja`, `ko`, `th`, `de`, `ru`, `es` ([GLOBAL_LOCALIZATION_DICTIONARY.md](file:///c:/Projects/FreeExile/docs/standards/GLOBAL_LOCALIZATION_DICTIONARY.md)).
   - **Microcopy Limits**: Nút bấm, tab, badge giới hạn $\le 2$ từ và $\le 12$ ký tự để không tràn vỡ layout mobile HUD (375pt).
   - **Zero Bilingual Parentheses**: Tuyệt đối CẤM ngoặc đơn song ngữ rườm rà (ví dụ: cấm `Thế Giới (World)`).
4. **Multi-Tiered Anti-Regression Gate**:
   - Bắt buộc chạy công cụ kiểm toán tĩnh trước khi commit và trong CI:
     ```bash
     python tools/lint/check_i18n_hygiene.py --strict
     ```
   - Xác thực 3 quy tắc: Rule 1 (0 hardcoded VI strings), Rule 2 (9-language parity), Rule 3 (0 dangling keys).
   - Kết hợp unit test `tests/unit/test_i18n_event_bus.py` (23 test cases) và E2E browser test `tests/e2e/test_i18n_reactive_switching_e2e.py`.
5. **Developer Checklist Khi Phát Triển UI Mới**:
   - [ ] 1. Khai báo key mới đầy đủ 9 ngôn ngữ trong `chat_i18n_catalog.js` hoặc `i18n_catalog.js`.
   - [ ] 2. Gắn cờ `data-i18n` / `data-chat-i18n` trên markup hoặc gọi `FreeExileI18n.t()`.
   - [ ] 3. Đăng ký listener `freeexile:localeChanged` hoặc `FreeExileI18n.subscribe()` trong controller.
   - [ ] 4. Kiểm tra re-render tại chỗ không reload trang (`location.reload()` = 0).
   - [ ] 5. Chạy `python tools/lint/check_i18n_hygiene.py --strict` đạt exit code 0.
---
## 4. QUY CHUẨN KIỂM THỬ KHÉP KÍN (TDD CLOSED-LOOP & VERIFICATION STACK)

Quy trình phát triển tại FreeExile áp dụng triệt để nguyên lý **Autonomous Test-Driven Development (TDD)** không cần can thiệp thủ công:

```mermaid
stateDiagram-v2
    [*] --> TestFirst: 1. Tiếp nhận tính năng / bug
    TestFirst --> NegativeBaseline: 2. Viết Unit / Integration Test
    NegativeBaseline --> RunTestFail: 3. Chạy test runner
    RunTestFail --> CheckFailed: Test có FAIL không?
    CheckFailed --> FixTestAssertion: Không (False-Positive) -> Sửa test case
    FixTestAssertion --> RunTestFail
    CheckFailed --> ImplementCode: Có (Negative Baseline Hợp Lệ)
    ImplementCode --> RunTestGreen: 4. Viết code nghiệp vụ tối thiểu
    RunTestGreen --> SelfHealing: Test FAIL?
    SelfHealing --> AnalyzeTraceback: Phân tích Traceback & Root-cause
    AnalyzeTraceback --> PatchCode: Áp dụng bản vá (Tối đa 5 vòng lặp)
    PatchCode --> RunTestGreen
    RunTestGreen --> TestPassed: 100% Test GREEN
    TestPassed --> AtomicCommit: 5. Tạo Atomic Git Commit + Log Mem0
    AtomicCommit --> [*]
```

### Kim Tự Tháp Kiểm Thử (Test Pyramid)
1. **Unit Tests (`tests/unit/`)**: Kiểm tra logic thuật toán thuần túy (tính sát thương ngũ hành, mở huyệt vị Bát Mạch, mã hóa ChaCha20). Thời gian thực thi < 2 giây cho toàn bộ suite.
2. **Integration Tests (`tests/integration/`)**: Kiểm tra phối hợp giữa Gateway, Session Manager và Spatial Grid.
3. **Security & Fuzzing Tests (`tests/security_fuzzing/`)**: Gửi các gói tin biến dị, replay attack, tấn công dupe đồ 2PC để xác minh khả năng tự phòng thủ của server.
4. **Load & Swarm Simulation (`tests/load_simulation/`)**: Khởi tạo bầy bot ảo từ 10.000 đến 1.000.000 CCU đo lường p95/p99 latency, jitter và tiêu hao RAM máy chủ.
---
## 5. QUY CHUẨN VIẾT TÀI LIỆU ĐỈNH CA (DOCS-AS-CODE & DIÁTAXIS FRAMEWORK)

Tài liệu không phải là việc làm phụ sau khi code, mà là **bộ phận cấu thành của sản phẩm**. Dự án áp dụng bộ khung chuẩn quốc tế **Diátaxis Framework**, chia tài liệu thành 4 trụ cột rạch ròi:

### 5.1. Khung Tài Liệu Diátaxis 4 Trụ Cột

Bốn trụ cột phân tách theo trục Thực hành - Lý thuyết và Học tập - Nhiệm vụ:

| Phân Loại | Mục Tiêu Cốt Lõi | Đặc Trưng Bắt Buộc | Ví Dụ Trong Dự Án |
| :--- | :--- | :--- | :--- |
| **Tutorials** | Dành cho người mới tiếp cận hệ thống, dẫn dắt từng bước để đạt kết quả đầu tiên. | Giọng điệu thân thiện, không giả định kiến thức trước, các bước 1-2-3 thực thi được ngay. | Hướng dẫn chạy Client WebApp mô phỏng iPhone trên máy dev nội bộ. |
| **How-To Guides** | Dành cho kỹ sư đang thực hiện tác vụ cụ thể trong dự án. | Giải quyết vấn đề mục tiêu, có checklist rõ ràng, không giải thích lý thuyết dông dài. | Cách thêm một huyệt vị mới vào Huyết Cốt Ma Đồ; Cách triển khai cụm Gateway test load. |
| **Reference** | Tra cứu thông số kỹ thuật chuẩn xác, không dư thừa lời văn. | Đầy đủ, ngắn gọn, chuẩn xác 100%, cấu trúc bảng biểu, schema definitions. | Bảng mã lỗi mạng, [GLOBAL_LOCALIZATION_DICTIONARY.md](file:///c:/Projects/FreeExile/docs/standards/GLOBAL_LOCALIZATION_DICTIONARY.md), Protobuf specs. |
| **Explanation** | Phân tích lý do thiết kế, trade-offs kiến trúc, tầm nhìn hệ thống. | Đi sâu vào bản chất "Tại sao?", so sánh các phương án đã loại bỏ, sơ đồ luồng dữ liệu. | [ARCHITECTURE_MILLION_CCU.md](file:///c:/Projects/FreeExile/docs/architecture/ARCHITECTURE_MILLION_CCU.md), Lý giải Two-Phase Commit trong Kỳ Trân Các. |
---
### 5.2. Quy Trình Ghi Nhận Quyết Định Kiến Trúc (ADR & RFC)

- **Mẫu ADR chuẩn**: Tiêu đề `# ADR-NNNN: [Tên Quyết Định]`, cấu trúc bắt buộc 4 phần: `Trạng Thái (Status)` (Accepted/Proposed), `Bối Cảnh (Context)` (vấn đề phân tán/race condition), `Quyết Định (Decision)` (giải pháp kỹ thuật cụ thể), và `Hệ Quả (Consequences)` (đánh giá trade-offs hai chiều Tích cực & Tiêu cực). Mọi ADR lưu tại `docs/adr/`.
---
### 5.3. Định Dạng Văn Bản & Trực Quan Hóa Living Docs
1. **GitHub-Style Alerts**: Sử dụng cảnh báo trực quan để nhấn mạnh các yếu tố then chốt:
   - `> [!NOTE]`: Thông tin bổ trợ, ngữ cảnh môi trường.
   - `> [!TIP]`: Mẹo tối ưu hóa hiệu năng, phím tắt, cú pháp ngắn gọn.
   - `> [!IMPORTANT]`: Quy tắc bắt buộc phải tuân thủ, không được bỏ qua.
   - `> [!WARNING]`: Rủi ro tương thích ngược, khả năng gây crash nếu cấu hình sai.
   - `> [!CAUTION]`: Rủi ro mất mát dữ liệu, lỗ hổng bảo mật hoặc tài chính game.
2. **Sơ Đồ Hóa Trực Quan (Diagrams First)**:
   - Thay vì mô tả 5 trang văn bản phức tạp, kỹ sư đỉnh cao sử dụng sơ đồ Mermaid (`sequenceDiagram`, `flowchart TD`, `stateDiagram-v2`).
   - Sơ đồ phải có chú thích nhãn rõ ràng, logic một chiều từ trên xuống hoặc từ trái qua phải.
3. **Liên Kết Mã Nguồn Tương Tác (Clickable Links)**:
   - Mọi đề cập đến file, class, interface, struct hoặc API endpoint trong tài liệu PHẢI kèm liên kết Markdown nhấp được: `[SpatialGrid](file:///c:/Projects/FreeExile/server/world/spatial_grid.py#L10-L25)`.
4. **Docs-as-Code Đồng Bộ Nguyên Tử (Atomic Synchronization)**:
   - Cấm tình trạng code đã sửa nhưng tài liệu vẫn ghi thông số cũ. Mọi Pull Request hoặc Commit sửa logic nghiệp vụ đều phải cập nhật tài liệu liên quan trong cùng commit.
---
### 5.4. Tiêu Chuẩn Viết Tài Liệu Khoa Học, Súc Tích & Mật Độ Thông Tin Cao

- **Nguyên Tắc Information Density (Mật độ thông tin cao)**:
  - Tuyệt đối CẤM văn xuôi dài dòng, tự sự cảm tính, viết lan man không đem lại giá trị kỹ thuật.
  - Cấu trúc chuẩn 5 phần cho mọi tài liệu kỹ thuật:
    1. **Mục tiêu & SLA**: 2-3 câu định lượng rõ ràng.
    2. **Thông số Kỹ thuật (Specs)**: 100% trình bày dưới dạng Bảng (Tables).
    3. **Sơ đồ Kiến trúc & Luồng Dữ liệu**: Sơ đồ Mermaid súc tích.
    4. **API / Data Contract**: Interface, Protobuf hoặc Typed Dataclass.
    5. **Xử lý Biên & Lỗi**: Bảng mã lỗi và chiến lược fallback.
- **Giới Hạn Độ Dài Tài Liệu**:
  - Soft Cap $\le 400$ dòng. Hard Cap $\le 600$ dòng.
  - Khi một tài liệu vượt quá 400 dòng, tác giả BẮT BUỘC phải phân tách thành các sub-documents chuyên biệt theo Diátaxis (ví dụ: `_SPECS.md`, `_ARCHITECTURE.md`, `_HOWTO.md`) và sử dụng liên kết điều hướng nhấp được (`file:///c:/Projects/FreeExile/...`).
---
## 6. QUY TRÌNH REVIEW MÃ NGUỒN, TỰ CHỮA LÀNH & KIỂM TOÁN VỆ SINH

### 6.1. Quy Trình Review 5 Bước Với Alibaba Open Code Review (Delegation Mode)

Dự án áp dụng mô hình **Hybrid Architecture Review**: Kết hợp năng lực kỹ thuật xác định (Deterministic Engineering) của công cụ **Open Code Review (Alibaba Group - Delegation Mode)** với năng lực suy luận sâu của **Gemini Host Agent**.

```mermaid
flowchart TD
    S1["Bước 1: ocr delegate preview --format json (Lọc file rác, xác định files)"]
    S2["Bước 2: ocr delegate rule --format json (Lấy checklist quy tắc Alibaba)"]
    S3["Bước 3: git diff <ref> -- <path> (Lấy diff thay đổi thực tế)"]
    S4["Bước 4: Gemini Suy Luận & Đối Soát (Định vị dòng, phân cấp severity)"]
    S5["Bước 5: Báo Cáo & Auto-Fix (Tự động sửa Critical/High tức thì)"]
    S1 --> S2 --> S3 --> S4 --> S5
```

### Tiêu Chuẩn Phân Loại Mức Độ Nghiêm Trọng (Severity Classification)
- `CRITICAL`: Lỗ hổng bảo mật nghiêm trọng (RCE, bypass xác thực, dupe tài sản), crash server diện rộng hoặc deadlock luồng. Yêu cầu block merge ngay lập tức.
- `HIGH`: Sai lệch logic game (công thức sát thương sai lệch, desync trạng thái client-server), rò rỉ bộ nhớ (memory leak), vi phạm SLA p99 > 25ms.
- `MEDIUM`: Code thiếu test case bao phủ, thiếu type annotations, blocking I/O trong async loop, cấu trúc dữ liệu chưa tối ưu.
- `LOW`: Đặt tên biến chưa chuẩn, thiếu docstring giải thích tham số, phong cách định dạng chưa đồng nhất.
---
### 6.2. Kiểm Toán Vệ Sinh Mã Nguồn, Tài Liệu & Đa Ngôn Ngữ Tự Động (Hygiene Gate CLI)

Nhằm đảm bảo quy chuẩn không chỉ là lời hứa suông (Action-Driven, Zero Lip-Service), hệ thống tích hợp 2 CLI kiểm toán tự động bắt buộc:
```bash
python tools/lint/check_code_and_doc_hygiene.py --strict
python tools/lint/check_i18n_hygiene.py --strict
```
- **Quy tắc chặn Release**: Khi chạy với cờ `--strict`, công cụ sẽ trả về exit code `1` nếu phát hiện bất kỳ file logic nào $> 500$ dòng, tài liệu $> 600$ dòng, chuỗi UI tiếng Việt hardcoded hoặc sai lệch parity 9 ngôn ngữ.
- Bắt buộc chạy trong quy trình CI/CD và trước mỗi lần commit.
---
## 7. CAM KẾT KỶ LUẬT & VĂN HÓA KỸ SƯ (ENGINEERING MINDSET & CRAFTSMANSHIP)

1. **Quy Tắc Hướng Đạo Sinh (Boy Scout Rule)**:
   > *"Luôn để khu cắm trại sạch hơn lúc bạn đến."*  
   Khi chạm vào bất kỳ file mã nguồn nào để sửa tính năng hoặc fix bug, hãy dành 5 phút để dọn dẹp biến thừa, bổ sung type annotation hoặc hoàn thiện unit test còn thiếu của file đó.
2. **Văn Hóa Mổ Xẻ Không Đổ Lỗi (Blameless Post-Mortem)**:
   - Khi phát sinh sự cố production (server crash, gián đoạn giao dịch), mục tiêu không phải là tìm người chịu trách nhiệm cá nhân, mà là phân tích **5 Whys (5 câu hỏi Tại sao)** để tìm ra lỗ hổng trong quy trình tự động hóa và bổ sung test case ngăn ngừa tái diễn vĩnh viễn.
3. **Thước Đo Duy Nhất**:
   - Uy tín của một kỹ sư đỉnh cao không đo bằng số dòng code viết ra, mà đo bằng:
     - Độ ổn định của hệ thống dưới tải lớn ($99.999\%$ uptime).
     - Tốc độ khung hình mượt mà của người chơi (vững vàng $120\text{ FPS}$).
     - Độ trong sáng, tự giải thích (self-explanatory) của mã nguồn và độ tin cậy của tài liệu đi kèm.
---
*Tài liệu này là kim chỉ nam bắt buộc cho toàn bộ kỹ sư, cộng tác viên và các Sub-Agent tự hành trong dự án FreeExile.*