# BÁO CÁO BÀN GIAO THẨM ĐỊNH (HANDOFF REPORT) — EXPLORER M1 PROGRESSION 2 GEN2

> **Người thực hiện**: `explorer_m1_progression_2_gen2` (teamwork_preview_explorer)  
> **Người nhận**: `orchestrator_4` (`6f4a2aa2-4315-4660-8cb7-8352a7220c95`)  
> **Loại Handoff**: Hard Handoff (Hoàn tất phân tích kỹ thuật, cung cấp giải pháp trọn vẹn và kế hoạch kiểm chứng cho Worker M1)  
> **Thời điểm**: 2026-10-01T02:35:00Z  

---

## 1. Observation (Quan Sát Trực Tiếp)

1. **Quan sát về Schema Di Trú và Bỏ Qua Reseed**:
   - `server/world/game_design_matrix_service.py:78-86`: Phương thức `_check_and_migrate_schema` kiểm tra số cột của `progression_benchmarks`. Nếu `< 13` cột, thực hiện `DROP TABLE IF EXISTS progression_benchmarks`.
   - `server/world/game_design_matrix_service.py:88-96`: Phương thức `seed_canonical_data` kiểm tra:
     ```python
     88:     def seed_canonical_data(self, force: bool = False) -> Dict[str, int]:
     ...
     92:             if not force:
     93:                 cur.execute("SELECT COUNT(*) as cnt FROM story_acts")
     94:                 if cur.fetchone()["cnt"] > 0:
     95:                     return {"status": "already_seeded"}
     96:             return seed_all_canonical_data(conn)
     ```
   - Chạy script `.agents/teamwork/reviewer_m1_progression_2/test_migration_adversarial.py`:
     ```
     Post-init columns (13): ['level', 'target_exp', ... 13 columns]
     Post-init progression_benchmarks row count: 0
     seed_canonical_data(force=False) result: {'status': 'already_seeded'}
     Post-seeding progression_benchmarks row count: 0
     Benchmark level 1: None
     ```
     Bảng `progression_benchmarks` vẫn ở trạng thái 0 hàng sau khi nạp dữ liệu với `force=False` trên cơ sở dữ liệu cũ có `story_acts > 0`.

2. **Quan sát về Mypy Typing Error**:
   - Lệnh: `python -m mypy --explicit-package-bases server/world/game_design_matrix_service.py server/world/game_design_matrix_seeder.py server/world/game_design_matrix_types.py`
   - Verbatim Output:
     ```
     server\world\game_design_matrix_service.py:95: error: Dict entry 0 has incompatible type "str": "str"; expected "str": "int"  [dict-item]
     server\world\game_design_matrix_seeder.py:148: error: Argument 2 to "_resolve_quest_zone" has incompatible type "str | None"; expected "str"  [arg-type]
     ```
   - Tại dòng 88 của service, kiểu trả về là `Dict[str, int]`, nhưng dòng 95 trả về `{"status": "already_seeded"}`, gây lỗi không tương thích kiểu dữ liệu.
   - Tại `server/world/game_design_matrix_seeder.py:298`: `def _resolve_quest_zone(quest_id: str, act_id: str) -> str:` trong khi caller tại dòng 148 truyền `q_def.act_id` có kiểu `Optional[str]`.

3. **Quan sát về Vị Trí Hiện Thực Hóa Của `seed_canonical_data`**:
   - `server/world/game_design_matrix_seeder.py:23`: Chỉ có hàm `seed_all_canonical_data(conn: sqlite3.Connection) -> Dict[str, int]:`.
   - `server/world/game_design_matrix_service.py:88`: Chứa phương thức `def seed_canonical_data(self, force: bool = False) -> Dict[str, int]:`.
   - Cả hai file đều cần được điều chỉnh đồng bộ để bảo đảm tính thống nhất cho cả caller hướng connection và caller hướng service.

4. **Quan sát về `ProgressionBenchmarkRow` Trong `game_design_matrix_types.py`**:
   - `server/world/game_design_matrix_types.py:151-167`:
     ```python
     @dataclass(slots=True, frozen=True)
     class ProgressionBenchmarkRow:
         """Mathematical progression milestone per level."""
         level: int
         target_exp: int
         exp_to_next_level: int
         cumulative_exp: int
         player_base_hp: float
         player_benchmark_dps: float
         monster_base_hp: float
         monster_base_dps: float
         max_affix_tier_allowed: int
         death_penalty_ratio: float = 0.0
         level_gap_safe_range: int = 5
         level_gap_penalty_exp: float = 0.60
         monster_benchmark_exp: int = 25
     ```
   - Lớp DTO đã sử dụng `@dataclass(slots=True, frozen=True)` bất biến, khớp 13/13 cột SQLite và hoàn toàn không có lỗi typing.

5. **Quan sát về XPASS Trong E2E Tests**:
   - `tests/e2e/test_level_progression_e2e.py:154, 160, 166`: Ba test cases F02 (`test_f02_progression_benchmarks_delta_column`, `test_f02_progression_benchmarks_death_penalty_column`, `test_f02_progression_benchmarks_cumulative_column`) mang cờ `@pytest.mark.xfail(strict=False, ...)` và hiện tại trả về trạng thái `XPASS` khi chạy kiểm thử.

6. **Quan sát Kiểm Chứng Mô Phỏng Khép Kín**:
   - Chạy script thực nghiệm `.agents/teamwork/explorer_m1_progression_2_gen2/test_seeder_fix_simulation.py`:
     ```
     Result of proposed seed_canonical_data(force=False): seeded_ok
     Row count after proposed seed: 100
     Second call correctly returned already_seeded!
     ALL SIMULATION CHECKS PASSED 100%!
     ```

---

## 2. Logic Chain (Chuỗi Suy Luận)

1. Từ **Observation 1**: Khi di trú từ DB cũ, `story_acts` đã có sẵn dữ liệu (`cnt > 0`), trong khi `progression_benchmarks` bị drop và tạo mới thành bảng rỗng (`cnt == 0`). Vì lệnh kiểm tra hiện tại chỉ kiểm tra `story_acts`, hệ thống nhầm tưởng toàn bộ DB đã được seed đầy đủ và bỏ qua việc seed. Do đó, việc bổ sung kiểm tra đồng thời `story_cnt > 0 and bench_cnt > 0` là điều kiện cần và đủ để tự động reseed bảng rỗng mà không phá vỡ tính năng idempotent khi DB đã seed đủ.
2. Từ **Observation 2**: Giá trị trả về `{"status": "already_seeded"}` chứa string value thay vì int value. Việc đổi kiểu trả về sang `Dict[str, Any]` sẽ triệt tiêu cảnh báo của mypy và phản ánh trung thực bản chất dữ liệu trả về (vừa có thể là stats count dạng `int`, vừa có thể là status message dạng `str`).
3. Từ **Observation 3**: Nhằm thỏa mãn yêu cầu của dispatch và chống hồi quy, ta cung cấp hàm `seed_canonical_data(conn: sqlite3.Connection, force: bool = False) -> Dict[str, Any]` trực tiếp trong `server/world/game_design_matrix_seeder.py`, đồng thời chuẩn hóa phương thức tương ứng trong `server/world/game_design_matrix_service.py`.
4. Từ **Observation 4**: `ProgressionBenchmarkRow` đã đạt chuẩn kỹ thuật tối đa của dự án (Python 3.11+, slots=True, frozen=True, 13 fields). Worker M1 không cần sửa đổi file này, tránh phát sinh thay đổi dư thừa.
5. Từ **Observation 5**: Ba test case F02 trong `tests/e2e/test_level_progression_e2e.py` đang ở trạng thái XPASS vì tính năng schema 13 cột đã hoạt động hoàn hảo. Gỡ bỏ `@pytest.mark.xfail` sẽ biến các test này thành rào chắn kiểm thử dương tính (positive test assertions) vững chắc.
6. Từ **Observation 6**: Script mô phỏng thực nghiệm chứng minh giải pháp sửa đổi hoàn toàn khả thi, giải quyết triệt để vấn đề di trú, tự động điền đủ 100 hàng cấp độ và vượt qua 100% assertions.

---

## 3. Caveats (Các Điểm Cần Lưu Ý)

1. **Phương Thức Seed Hiện Tại Xóa Bảng Khi Reseed**: Hàm `seed_all_canonical_data(conn)` thực hiện xóa toàn bộ các bảng trước khi nạp lại. Trong trường hợp di trú DB thực tế có dữ liệu người chơi tuỳ biến (nếu có sau này), cần lưu ý đây là bảng ma trận thiết kế tĩnh (Design Matrix), không phải bảng lưu dữ liệu nhân vật người chơi nên việc re-seed toàn bộ catalog chuẩn là an toàn 100%.
2. **Không có thêm caveat nào khác.**

---

## 4. Conclusion (Kết Luận & Hành Động Cụ Thể Dành Cho Worker M1)

Kế hoạch thực thi chi tiết cho Worker M1 gồm 3 thao tác mã nguồn:

### Thao tác 1: Cập nhật `server/world/game_design_matrix_service.py`
- Thay đổi chữ ký: `def seed_canonical_data(self, force: bool = False) -> Dict[str, Any]:`
- Sửa điều kiện kiểm tra (lines 92-96):
  ```python
  if not force:
      cur.execute("SELECT COUNT(*) as cnt FROM story_acts")
      story_cnt = cur.fetchone()["cnt"]
      cur.execute("SELECT COUNT(*) as cnt FROM progression_benchmarks")
      bench_cnt = cur.fetchone()["cnt"]
      if story_cnt > 0 and bench_cnt > 0:
          return {"status": "already_seeded"}
  return seed_all_canonical_data(conn)
  ```

### Thao tác 2: Cập nhật `server/world/game_design_matrix_seeder.py`
- Bổ sung hàm `seed_canonical_data(conn: sqlite3.Connection, force: bool = False) -> Dict[str, Any]:`
- Sửa `from typing import Any, Dict, List, Optional` và `def _resolve_quest_zone(quest_id: str, act_id: Optional[str]) -> str:`.

### Thao tác 3: Dọn dẹp `tests/e2e/test_level_progression_e2e.py`
- Gỡ bỏ 3 decorator `@pytest.mark.xfail` tại lines 154, 160, 166.

---

## 5. Verification Method (Phương Pháp Kiểm Chứng Độc Lập)

Các kiểm chứng độc lập sau bắt buộc phải chạy sau khi Worker M1 hoàn thành sửa đổi:

```powershell
# 1. Chạy Unit Test kiểm tra tính toàn vẹn Service
python -m pytest tests/unit/test_game_design_matrix.py -v

# 2. Chạy Adversarial Test kiểm tra di trú và reseed khi DB cũ tồn tại
python .agents/teamwork/reviewer_m1_progression_2/test_migration_adversarial.py

# 3. Chạy Simulation Test khép kín của Explorer
python .agents/teamwork/explorer_m1_progression_2_gen2/test_seeder_fix_simulation.py

# 4. Chạy Linter chống Drift giữa Code, Database và Wiki Specs
python tools/lint/verify_game_design_matrix.py

# 5. Chạy kiểm thử E2E Feature 2 (Progression Benchmarks Schema)
python -m pytest tests/e2e/test_level_progression_e2e.py -k "test_f02" -v

# 6. Kiểm tra Type Annotation nghiêm ngặt bằng mypy
python -m mypy --explicit-package-bases server/world/game_design_matrix_service.py server/world/game_design_matrix_seeder.py server/world/game_design_matrix_types.py

# 7. Kiểm toán vệ sinh mã nguồn nghiêm ngặt
python tools/lint/check_code_and_doc_hygiene.py --strict
```

**Điều kiện bất hiệu hóa (Invalidation Conditions)**:
- `seed_canonical_data(force=False)` trả về `{"status": "already_seeded"}` khi bảng `progression_benchmarks` có 0 hàng.
- Mypy báo lỗi lệch kiểu dữ liệu tại `seed_canonical_data`.
- Bất kỳ bài test nào trong `test_game_design_matrix.py` hoặc `test_f02` bị thất bại (FAIL).
- Phát hiện vi phạm Hard Cap trong `check_code_and_doc_hygiene.py`.