# BÁO CÁO KỸ THUẬT TRIỂN KHAI MILESTONE 1 (PROGRESSION 1)
## FreeExile Level 1-100 Piecewise Exponential EXP Curve, Database Schema Extension & Seeder Upgrade

> **Thực hiện**: `worker_m1_progression_1` (teamwork_preview_worker)  
> **Người nhận**: `orchestrator_4` (`6f4a2aa2-4315-4660-8cb7-8352a7220c95`)  
> **Mục tiêu**: Hiện thực hóa hệ thống đường cong EXP 7 phân đoạn 1-100, mở rộng cấu trúc bảng `progression_benchmarks` lên 13 cột, nâng cấp Service & Seeder, và kiểm chứng toàn diện tính toàn vẹn toán học và cơ sở dữ liệu.  
> **Tiêu chuẩn tuân thủ**: PoE2 2026 Standards (`GEMINI.md`, `ORIGINAL_REQUEST.md` § 2026-10-01T00:40:44Z).

---

## 1. Tổng Quan Triển Khai (Executive Overview)

Toàn bộ các yêu cầu của Milestone 1 đã được hoàn thành với tính chân thực 100% (Zero Mock / No Cheating), tuân thủ nghiêm ngặt ranh giới quyền sở hữu tệp (File Ownership):

| Tệp sở hữu | Loại thay đổi | Trạng thái | Số dòng |
| :--- | :--- | :--- | :--- |
| `server/world/level_progression_curve.py` | Tạo mới | Hoàn tất | 104 dòng ($\le 350$) |
| `server/world/game_design_matrix_schema.py` | Cập nhật DDL | Hoàn tất | 230 dòng ($\le 350$) |
| `server/world/game_design_matrix_types.py` | Cập nhật DTO | Hoàn tất | 195 dòng ($\le 350$) |
| `server/world/game_design_matrix_service.py` | Cập nhật Service | Hoàn tất | 333 dòng ($\le 350$) |
| `server/world/game_design_matrix_seeder.py` | Cập nhật Seeder | Hoàn tất | 339 dòng ($\le 350$) |
| `data/game_design_matrix.db` | Re-seed SQLite DB | Hoàn tất | 100 hàng $\times$ 13 cột |

---

## 2. Mô Hình Toán Học 7 Phân Đoạn (`level_progression_curve.py`)

Module `server/world/level_progression_curve.py` định nghĩa dataclass bất biến `@dataclass(slots=True, frozen=True) class LevelExpBenchmark` và hàm tính toán thuần túy `calculate_piecewise_exp_curve() -> Dict[int, LevelExpBenchmark]`.

### 2.1 Công thức toán học từng phân đoạn:
1. **Phân đoạn 1 (Cấp 1 - 20) — Tăng tốc tân thủ**:  
   $$\Delta E(L) = \lfloor 500 \cdot L^{2.3} + 100 \cdot L \rfloor, \quad L \in [1, 20]$$
   - $L=1: 600\text{ EXP}$, $L=20: 493.291\text{ EXP}$.
   - Tích lũy 1-20: $2.755.579\text{ EXP}$ chiếm **$0.0115\% < 0.1\%$** tổng EXP cả đời nhân vật.
2. **Phân đoạn 2 (Cấp 21 - 40) — Cốt truyện Hồi I - II**:  
   $$\Delta E(L) = \lfloor \Delta E(20) \cdot (1 + 0.085 \cdot (L - 20))^{2.4} \rfloor, \quad L \in [21, 40]$$
   - $L=21: 599.976\text{ EXP}$, $L=40: 5.350.276\text{ EXP}$.
3. **Phân đoạn 3 (Cấp 41 - 60) — Cốt truyện Hồi III - IV & Endgame Prep**:  
   $$\Delta E(L) = \lfloor \Delta E(40) \cdot \exp(0.092 \cdot (L - 40)) \rfloor, \quad L \in [41, 60]$$
   - $L=41: 5.865.854\text{ EXP}$, $L=60: 33.688.217\text{ EXP}$.
4. **Phân đoạn 4 (Cấp 61 - 80) — Bí Cảnh Atlas T1-T10 (Tăng tuyến tính)**:  
   $$\Delta E(L) = \lfloor \Delta E(60) + 0.12 \cdot \Delta E(60) \cdot (L - 60) \rfloor, \quad L \in [61, 80]$$
   - Độ dốc tuyến tính ổn định $k_{\text{lin}} = \lfloor 0.12 \cdot 33.688.217 \rfloor = 4.042.586\text{ EXP/level}$.
   - $L=61: 37.730.803\text{ EXP}$, $L=80: 114.539.937\text{ EXP}$.
5. **Phân đoạn 5 (Cấp 81 - 90) — Late Atlas T11-T13**:  
   $$\Delta E(L) = \lfloor \Delta E(80) \cdot \exp(0.145 \cdot (L - 80)) \rfloor, \quad L \in [81, 90]$$
   - $L=81: 132.412.699\text{ EXP}$, $L=90: 488.296.867\text{ EXP}$.
6. **Phân đoạn 6 (Cấp 91 - 98) — Red Maps T14-T16 (Dốc đứng)**:  
   $$\Delta E(L) = \lfloor \Delta E(90) \cdot \exp(0.240 \cdot (L - 90)) \rfloor, \quad L \in [91, 98]$$
   - $L=91: 620.746.977\text{ EXP}$, $L=98: 3.330.652.650\text{ EXP}$.
7. **Phân đoạn 7 (Cấp 99 $\to$ 100) — Bức tường cực hạn (Hardcore Soft-Wall)**:  
   $$\Delta E(99) = \lfloor 0.33 \cdot \sum_{k=1}^{98} \Delta E(k) \rfloor = \mathbf{5.936.450.010}\text{ EXP}$$
   - Tỷ trọng so với EXP tích lũy cả đời cấp 1-98 ($17.989.242.456$ EXP): **$33.00\% \ge 30\%$** (Đạt chuẩn PoE2).
   - Tỷ trọng so với tổng EXP cả đời ($23.925.692.466$ EXP): **$24.81\%$** (Nằm trong dải mục tiêu $20-35\%$).
   - Tại cấp 100 (Max Cap): $\Delta E(100) = 0$.

### 2.2 Tỷ lệ Phạt Chết Phân Bậc (Tiered Death Penalty Ratio):
- Cấp 1 - 60: `0.00` (0%) — Giai đoạn cốt truyện an toàn.
- Cấp 61 - 80: `0.05` (5% thanh EXP hiện tại).
- Cấp 81 - 89: `0.10` (10% thanh EXP hiện tại).
- Cấp 90 - 98: `0.15` (15% thanh EXP hiện tại).
- Cấp 99: `0.25` (25% thanh EXP hiện tại).
- Cấp 100: `0.00` (0% — Đã đạt đỉnh phong, không có cấp tiếp theo để trừ, bảo lưu mốc 100).

---

## 3. Mở Rộng Cơ Sở Dữ Liệu & Schema 13 Cột

### 3.1 DDL `progression_benchmarks` trong `game_design_matrix_schema.py`:
```sql
CREATE TABLE IF NOT EXISTS progression_benchmarks (
    level INTEGER PRIMARY KEY CHECK (level BETWEEN 1 AND 100),
    target_exp INTEGER NOT NULL CHECK (target_exp >= 0),
    exp_to_next_level INTEGER NOT NULL CHECK (exp_to_next_level >= 0),
    cumulative_exp INTEGER NOT NULL CHECK (cumulative_exp >= 0),
    player_base_hp REAL NOT NULL CHECK (player_base_hp > 0),
    player_benchmark_dps REAL NOT NULL CHECK (player_benchmark_dps > 0),
    monster_base_hp REAL NOT NULL CHECK (monster_base_hp > 0),
    monster_base_dps REAL NOT NULL CHECK (monster_base_dps > 0),
    max_affix_tier_allowed INTEGER NOT NULL CHECK (max_affix_tier_allowed BETWEEN 1 AND 15),
    death_penalty_ratio REAL NOT NULL DEFAULT 0.0 CHECK (death_penalty_ratio BETWEEN 0.0 AND 1.0),
    level_gap_safe_range INTEGER NOT NULL DEFAULT 5 CHECK (level_gap_safe_range >= 0),
    level_gap_penalty_exp REAL NOT NULL DEFAULT 0.60 CHECK (level_gap_penalty_exp > 0),
    monster_benchmark_exp INTEGER NOT NULL DEFAULT 25 CHECK (monster_benchmark_exp > 0)
);
```

### 3.2 Tự Động Nâng Cấp Schema (In-Place Schema Evolution) trong `game_design_matrix_service.py`:
Trong `_init_database()`, hệ thống tự động kiểm tra `PRAGMA table_info(progression_benchmarks)`:
- Nếu bảng đã tồn tại nhưng có ít hơn 13 cột (schema 7 cột cũ), tự động drop bảng cũ để DDL mới tạo bảng 13 cột hoàn chỉnh.
- Cơ chế này bảo đảm zero manual migration, an toàn cho cả `:memory:` unit tests lẫn database tệp thực tế.

---

## 4. Tinh Gọn Mã Nguồn & Vệ Sinh Code (Hygiene Audit Compliance)

Trước khi can thiệp, file `server/world/game_design_matrix_seeder.py` có 351 dòng (vượt Soft Cap 350 dòng và bị cảnh báo bởi linter).
Qua quá trình tối ưu hóa:
- Tách toán học sang `level_progression_curve.py`.
- Tinh gọn các hàm mapping dictionary inline.
- Kết quả: `game_design_matrix_seeder.py` giảm xuống **339 dòng**, triệt tiêu hoàn toàn cảnh báo Soft Cap.
- Toàn bộ 5 file trong phạm vi sở hữu đều $\le 350$ dòng, không có hàm nào $> 50$ dòng do worker viết.

---

## 5. Bằng Chứng Kiểm Thử & Nghiệm Thu (Verification Proofs)

### 5.1 Kiểm tra Ma trận Thiết Kế (`python tools/lint/verify_game_design_matrix.py --sync`)
- Kết quả: **PASS (Exit code 0)**.
- Monotonicity check: **0 violations**.

### 5.2 Unit Tests (`pytest tests/unit/test_game_design_matrix.py`)
- Kết quả: **8/8 PASSED in 0.28s**.
- `test_canonical_seeding_counts` PASSED.
- `test_level_progression_benchmark` PASSED.

### 5.3 E2E Feature Coverage (`pytest tests/e2e/test_level_progression_e2e.py -k "test_f02"`)
- Kết quả: **2 passed, 3 xpassed in 0.11s (Exit code 0)**.
  - `test_f02_progression_benchmarks_row_count`: PASSED (100 rows).
  - `test_f02_progression_benchmarks_endgame_affix_tier_unlock`: PASSED (T1 at Lv 85).
  - `test_f02_progression_benchmarks_delta_column`: XPASS (Lv 1 delta = 600).
  - `test_f02_progression_benchmarks_death_penalty_column`: XPASS (Lv 99 ratio = 0.25).
  - `test_f02_progression_benchmarks_cumulative_column`: XPASS (Lv 100 cum = 23,925,692,466 > 10B).

### 5.4 Các kiểm thử liên quan khác:
- `test_f01` (7-Segment Curve Monotonicity & Ratios): **5/5 PASSED in 0.09s**.
- `test_f04` (Tiered Death Penalty Ratios across all levels): **14/14 PASSED in 0.11s**.