---
doc_id: "DOC-ROADMAP-002"
title: "Kế Hoạch Phát Triển Phiên Bản Kế Tiếp (v2026.2 Development Plan)"
category: "operations"
diataxis_type: "how-to"
status: "canonical"
version: "2026.2"
owner_role: "server_systems_architect"
tags: ["development-plan", "version-2026-2", "dual-brain", "metal-120fps", "2pc-ledger", "sprint-plan"]
related_code:
  - "server/world/agent_orb_service.py"
  - "server/agent/agent_decision_core.py"
  - "server/agent/llm_provider_client.py"
related_docs:
  - "docs/roadmap/ROADMAP_2026_2027.md"
  - "docs/standards/ENGINEERING_STANDARDS_2026.md"
  - "docs/architecture/DISTRIBUTED_ENGINE_1M_CCU_ARCHITECTURE.md"
summary: "Kế hoạch kỹ thuật chi tiết phiên bản v2026.2: Kiến trúc Não Kép AI Agent, tối ưu Apple Metal 120 FPS, sổ cái 2PC chống dupe và lộ trình 4 sprints."
---

# KẾ HOẠCH PHÁT TRIỂN PHIÊN BẢN KẾ TIẾP (v2026.2 DEVELOPMENT PLAN)

> **Cơ quan ban hành**: Khối Kỹ Thuật Máy Chủ & Khối Đồ Họa Client FreeExile  
> **Chủ trì**: `server_systems_architect` & `worker_m3_1`  
> **Tài liệu tham chiếu**: [ROADMAP_2026_2027.md](file:///c:/Projects/FreeExile/docs/roadmap/ROADMAP_2026_2027.md)  
> **Quy chuẩn kỹ thuật**: [ENGINEERING_STANDARDS_2026.md](file:///c:/Projects/FreeExile/docs/standards/ENGINEERING_STANDARDS_2026.md)  

---

## 1. PHẠM VI PHÁT TRIỂN PHIÊN BẢN v2026.2 (NEXT VERSION SCOPE)

Phiên bản **v2026.2** tập trung vào 4 trọng điểm kỹ thuật mang tính nền móng:
1. **Kiến Trúc Não Kép AI Agent (Dual-Brain Cognition)**: Triển khai trọn vẹn 3 cơ chế đột phá của Chiến Hồn Tế Cốt [agent_orb_service.py](file:///c:/Projects/FreeExile/server/world/agent_orb_service.py) (Khắc Ấn Thần Niệm, Chiến Hồn Hồi Ký, Khóa Huyết Ấn Tàn Tích).
2. **Tối Ưu Hóa Apple Metal Engine 120 FPS**: Đạt ngân sách khung hình khắt khe $8.33\text{ ms/frame}$ (120 FPS ProMotion) trên chip Apple Silicon và WebGL Hybrid.
3. **Sổ Cái Khóa Giao Dịch Hai Pha (2PC) & Ký Số HMAC**: Triệt tiêu hoàn toàn nguy cơ nhân bản (dupe đồ), sửa đổi gói tin kết toán hoặc can thiệp bộ nhớ.
4. **Quy Trình Kiểm Thử TDD Khép Kín & Fuzzing An Ninh**: Đạt tỷ lệ bao phủ test 100%, vượt qua Cổng Phủ Quyết Release của CISO.

---

## 2. ĐẶC TẢ KIẾN TRÚC NÃO KÉP AI AGENT (DUAL-BRAIN ARCHITECTURE)

```mermaid
sequenceDiagram
    autonumber
    actor Player as Người Chơi (Web / iOS)
    participant UI as Client HUD (#input-feral-intent)
    participant CloudLLM as Cloud LLM Intent Compiler
    participant Blackboard as Intent Blackboard (Lockless)
    participant FastBrain as ServerEngineLoop (Local 30Hz)
    participant Ledger2PC as 2PC Transactional Ledger

    Player->>UI: Nhập thần niệm: "Né đòn boss, săn quái Mộc, nhặt đá T3+"
    UI->>CloudLLM: Gửi NLP Prompt (Bất đồng bộ / Out-of-band)
    CloudLLM->>CloudLLM: Phân tích & Ép kiểu -> DynamicTacticalRuleset JSON
    CloudLLM-->>Blackboard: Ghi Ruleset vào Bộ nhớ Nguyên Tử (Atomic Slot)
    
    loop Nhịp Tick 30Hz Server (dt = 33.33ms)
        FastBrain->>Blackboard: Đọc Ruleset lockless (<0.01ms)
        FastBrain->>FastBrain: Heuristic 0ms: Né đòn i-frame 250ms, xuất chiêu khắc hệ
        FastBrain->>UI: Stream dòng suy nghĩ (agent-thought-stream)
    end

    Note over Player, FastBrain: Người chơi kết thúc phiên uỷ thác (reclaim_control)
    Player->>FastBrain: Gửi yêu cầu thu hồi quyền kiểm soát
    FastBrain->>Ledger2PC: Prepare 2PC: Ký số HMAC-SHA256 kết toán thu hoạch
    Ledger2PC-->>FastBrain: 2PC Commit OK (Khóa Huyết Ấn is_scourge_soulbound=True)
    FastBrain-->>UI: Hiển thị Báo cáo Thu Hoạch & Chiến Hồn Hồi Ký
```

### Thông Số Kỹ Thuật Tầng Phản Xạ & Chiến Lược
- **Tầng Phản Xạ 30Hz Cục Bộ ([agent_decision_core.py](file:///c:/Projects/FreeExile/server/agent/agent_decision_core.py))**:
  - Thời gian xử lý: $< 0.1\text{ ms}$ cho mỗi lượt đánh giá điều kiện.
  - Phản xạ sinh tử: $\text{HP} < 25\%$ lập tức kích hoạt Huyễn Ảnh Bộ (250ms i-frame) hoặc phục dược.
  - Ngũ hành tương khắc: Tự động đảo vũ khí hoặc xuất chiêu khắc chế tăng $+25\%$ sát thương.
- **Tầng Chiến Lược Bất Đồng Bộ ([llm_provider_client.py](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py))**:
  - Chu kỳ quét: $0.5\text{ Hz} - 1.0\text{ Hz}$ (1-2 giây một lần), hoàn toàn nằm ngoài vòng lặp 30Hz.
  - Dự phòng an toàn (Zero-Latency Fallback): Tự động chuyển về Heuristic 0ms nếu API Cloud LLM timeout quá $2.0\text{s}$.

---

## 3. TỐI ƯU HÓA ENGINE APPLE METAL 120 FPS (8.33ms BUDGET ALLOCATION)

Để đảm bảo hiệu năng 120 FPS ProMotion mượt mà trên iPhone và iPad Pro, toàn bộ pipeline đồ họa phải tuân thủ ngân sách thời gian:

| Phân Hệ Pipeline Client | Ngân Sách ($120\text{ FPS}$) | Cơ Chế Tối Ưu Hóa Kỹ Thuật |
| :--- | :--- | :--- |
| **Input & Virtual Touch Joystick** | $0.80\text{ ms}$ | Concurrency Lockless Event Ring Buffer |
| **Spatial AOI Grid & Depth Sort** | $1.00\text{ ms}$ | Thuật toán Monotonic Key $Y \times 10.0 + Z$ $O(K)$ |
| **Tactical AI Reflex Evaluation** | $0.50\text{ ms}$ | Heuristic Fallback $< 0.1\text{ ms}$, đọc Intent Blackboard |
| **Movement Authority & Collision**| $1.20\text{ ms}$ | Capsule 2.5D Collision & Fixed Point Q16.16 Math |
| **Combat & Five Elements Matrix** | $1.00\text{ ms}$ | Bảng tra cứu tương khắc O(1), i-frame bitmask |
| **Render Passes, Shaders & VFX** | $2.83\text{ ms}$ | Metal Compute Shaders SIMD16/Float4, Particle Pooling |
| **Dự phòng An Toàn (Jitter Margin)**| $1.00\text{ ms}$ | Đệm chống hiện tượng nghẽn rác bộ nhớ (GC Pauses) |
| **TỔNG CỘNG KHUNG HÌNH** | **$8.33\text{ ms}$** | **Vững vàng $120\text{ FPS}$ ProMotion ($100\%$ Zero-Drop)** |

### Nguyên Tắc Cốt Lõi: Zero Allocation Trong Hot Paths
- **Cấm cấp phát bộ nhớ động**: Tuyệt đối không gọi `new Vector2()`, khởi tạo mảng tạm hoặc closure trong các hàm `update(dt)`, `render()`, `interpolate()`.
- **Tái sử dụng qua Object Pools**: Toàn bộ hạt VFX, đường đạn, dư ảnh Huyễn Ảnh Bộ và nhãn số sát thương phải được cấp phát trước (Pre-allocated Object Pools) khi khởi động scene.

---

## 4. BẢO MẬT & SỔ CÁI HAI PHA (2PC ANTI-DUPE LEDGER)

1. **Khóa Cố Định Huyết Ấn Tàn Tích (`is_scourge_soulbound = True`)**:
   - Mọi tài sản thu hoạch từ phiên uỷ thác tự động khóa cứng vào nhân vật.
   - Chặn đứng 100% chiều nạp vào Rương Chung Bang Hội và niêm yết Hắc Thị.
2. **Ký Số HMAC-SHA256 Chống Sửa Gói Tin**:
   - Gói tin kết toán mang chữ ký `HMAC-SHA256(secret_key, session_id + exp + drops + timestamp)`.
   - Máy chủ đối soát chữ ký trước khi cộng tài nguyên, loại bỏ nguy cơ memory hacking.
3. **Giao Thức Khóa Phân Tán Hai Pha (2PC)**:
   - Pha 1 (Prepare): Khóa bản ghi nhân vật trên SQLite (WAL mode) và kiểm tra tính lũy đẳng (Idempotency Token).
   - Pha 2 (Commit): Ghi đồng thời vào CSDL trạng thái và Sổ cái Giao dịch Bất biến.

---

## 5. KẾ HOẠCH SPRINT CHI TIẾT (4 SPRINTS / 8 TUẦN)

```mermaid
flowchart LR
    S1["Sprint 1 (Tuần 1-2):<br/>Core AI & Ruleset Compiler"]
    S2["Sprint 2 (Tuần 3-4):<br/>Scourge-Soulbound & 2PC Ledger"]
    S3["Sprint 3 (Tuần 5-6):<br/>Metal 120Hz & Client HUD Stream"]
    S4["Sprint 4 (Tuần 7-8):<br/>Hardening, Fuzzing & QA Audit"]

    S1 --> S2 --> S3 --> S4
```

### Sprint 1: Core AI & Ruleset Compiler (Tuần 1 - Tuần 2)
- Định nghĩa schema `DynamicTacticalRuleset` và bộ lọc dữ liệu bounds.
- Xây dựng Cloud LLM Intent Compiler chuyển hóa NLP thành JSON có cấu trúc.
- Tích hợp Intent Blackboard đọc lockless vào nhịp tick $30\text{Hz}$ của [server_engine_loop.py](file:///c:/Projects/FreeExile/server/world/server_engine_loop.py).

### Sprint 2: Scourge-Soulbound & 2PC Ledger (Tuần 3 - Tuần 4)
- Triển khai cờ `is_scourge_soulbound` trên toàn bộ vật phẩm thu hoạch Tế Cốt.
- Hiện thực hóa module xác thực chữ ký HMAC-SHA256 và giao dịch 2PC.
- Thiết kế phụ bản Thí Luyện Ma Khảo T16+ phục vụ cơ chế Giải Trừ Huyết Ấn.

### Sprint 3: Metal 120Hz & Client HUD Stream (Tuần 5 - Tuần 6)
- Tối ưu Metal Shaders, căn chỉnh cấu trúc dữ liệu theo SIMD16/Float4 trên chip Apple Silicon.
- Triển khai Object Pooling cho toàn bộ hạt VFX và dư ảnh Huyễn Ảnh Bộ.
- Tích hợp ô nhập liệu thần niệm `#input-feral-intent` và hiển thị Hồi Ký lên Client WebApp.

### Sprint 4: Hardening, Fuzzing & QA Audit (Tuần 7 - Tuần 8)
- Diễn tập tấn công giả lập: chèn race condition 2PC, giả mạo chữ ký HMAC và tiêm prompt injection.
- Kiểm toán an ninh độc lập với `python tools/security/run_independent_security_audit.py`.
- Chạy kiểm toán vệ sinh mã nguồn và tài liệu đảm bảo 100% tuân thủ tiêu chuẩn.

---

## 6. TIÊU CHÍ NGHIỆM THU & QUY TRÌNH KIỂM CHỨNG TDD

Để nghiệm thu phiên bản v2026.2, toàn bộ các lệnh kiểm tra sau bắt buộc trả về kết quả đạt (exit code 0):

```bash
# 1. Kiểm tra đơn vị hệ thống AI Agent và Dịch vụ Tế Cốt
pytest tests/unit/test_agent_decision_core.py tests/unit/test_agent_orb_service.py tests/unit/test_llm_provider_client.py -v

# 2. Kiểm tra quy tắc phân vùng an toàn PoE2
pytest tests/unit/test_zone_monster_spawning_rules.py -v

# 3. Kiểm toán vệ sinh mã nguồn và độ dài file
python tools/lint/check_code_and_doc_hygiene.py --strict

# 4. Kiểm toán hệ thống tài liệu chuẩn Diátaxis
python tools/lint/check_documentation_system.py --strict
```

---

## 7. LIÊN KẾT ĐIỀU HƯỚNG

- [Lộ Trình Phát Triển Chiến Lược 2026-2027](file:///c:/Projects/FreeExile/docs/roadmap/ROADMAP_2026_2027.md)
- [Quy Chuẩn Kỹ Thuật 2026](file:///c:/Projects/FreeExile/docs/standards/ENGINEERING_STANDARDS_2026.md)
- [Kiến Trúc Máy Chủ 1M CCU](file:///c:/Projects/FreeExile/docs/architecture/DISTRIBUTED_ENGINE_1M_CCU_ARCHITECTURE.md)
- [Bản Đồ Tài Liệu Tổng Thể](file:///c:/Projects/FreeExile/docs/README.md)