docs(port-plan): close migration prerequisite gaps

docs/PORT-PLAN.md

@@ -27,7 +27,7 @@ metin2-client 是 40250 Windows 客户端的跨平台版本（macOS / Windows /
 | 2026-09-22 | 数据源统一改为 40250（`Client/Eternexus` 的 root/uiscript/locale，以及 `Client/pack` 的资源），**不再用**仓库里 m2dev 版本的 `assets/root`、`assets/uiscript`、`assets/locale` | 两者有实质差异，见第 5 节 |
 | 2026-09-22 | 现有 `project/ui/*.gd`（60 个文件，依据的是错误版本的脚本）不再维护，由 Python 层取代 | — |
 | 2026-09-22 | 照抄时保持 40250 的**宽度和溢出语义**（Win32 下 `long` 为 32 位），序列化结构用定宽类型并 `static_assert` 大小 | 64 位平台 `long` 是 8 字节，机械照抄会破坏 proto/封包/EPK 布局和 TEA |
-| 2026-09-22 | 迁移期新旧路径共存，新路径接通运行后才在同一提交删除旧逻辑；先做最小纵向切片 2V | `main` 始终可玩；运行时不可达的新代码不算实现 |
+| 2026-09-22 | 迁移期新旧路径共存，新路径接通运行后才在同一提交删除旧逻辑；纵向切片拆成 2V0–2V3 | `main` 始终可玩；运行时不可达的新代码不算实现 |
 
 ## 3. 三个层和代码位置
 
@@ -51,13 +51,15 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
 
 - 40250 调用平台类的地方，调用 `extension/src/platform/` 下同名的适配接口，ported 代码里不直接写 Godot 调用。
 - 40250 的单例（`CPythonPlayer`、`CPythonCharacterManager`、`CPythonNetworkStream`）归扩展所有，GDScript 不持有玩法状态。
-- **保持 40250 的宽度和溢出语义，不是机械保留 C++ 类型名。** 40250 是 Win32（ILP32/LLP64）：`long`/`unsigned long`
-  是 32 位，指针是 32 位。64 位的 macOS/Linux/Android/iOS 上 `long` 是 64 位，照抄会改变结构大小、TEA 的读取宽度和
-  溢出行为。统一由 `port/common/Win32Types.h`（批次 2A）把 `LONG`/`DWORD`/`long` 等映射到 `int32_t`/`uint32_t`：
+- **保持 40250 的宽度和溢出语义，不是机械保留 C++ 类型名。** 40250 可执行文件目标是 32 位 Win32（ILP32）：
+  `long`/`unsigned long` 和指针都是 32 位；移植目标则可能是 LP64 或 LLP64。`port/common/Win32Types.h`（批次 2A）
+  只为 `BYTE`/`WORD`/`DWORD`/`LONG`/`BOOL`/`UINT` 等 Win32 **标量别名**提供定宽定义，不能重定义 C++ 关键字 `long`：
   - 凡是参与序列化的结构（proto 记录、封包、EPK 索引、msa/msm 二进制）一律用定宽类型，`#pragma pack` 与 40250 相同，
     并对 40250 已知大小加 `static_assert(sizeof(...) == N)`（如 `TItemTable` == 156）；
-  - 纯计算里的 `long` 如依赖 32 位回绕，也换成 `int32_t`；
-  - 指针存进 `DWORD` 的写法（句柄、`SetUserData` 等）改成 `uintptr_t`，并在 port-map 的 `note` 里记下。
+  - 纯计算里的 `long` 按语义改成 `int32_t`/`uint32_t`；依赖 32 位回绕时使用无符号运算或显式 wrapping helper，不能依赖
+    C++ 有符号溢出的未定义行为；
+  - `HANDLE`、`HWND`、`WPARAM`、`LPARAM` 等句柄/指针类型保持指针宽度并隔离在 platform adapter；指针存进 `DWORD`
+    的原写法改成 `uintptr_t`，在 port-map 的 `note` 里记录适配不变式。
 - 单位保持 40250 的（`TPixelPosition` 用 cm，时间是 `ELTimer_GetMSec` 的毫秒，角度用度），只在适配层换算。
 - 迁移来源：`net_play.gd`、`net_world.gd`、`game_scene.gd`、`player_controller.gd`、`entity_store.cpp`。**旧逻辑只在新路径
   已接通运行时之后才删除**（见第 4 节"迁移方式"），删除与接通在同一次提交完成。
@@ -74,9 +76,12 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
 | **2R** | 资源包能力盘点：EPK 类型/密钥/覆盖顺序/路径大小写/移动端交付 | **下一步**，可与 2A 并行（只读分析 + 独立工具） |
 | 2P | CPython 2.7.18 编进 libmtgodot，五个平台分别配置和验证 | 2A 之后 |
 | 2D | 数据源切到 40250（msm 路径、proto、资源根、严格资源测试） | proto 部分在 2A 之后；资源根在 2R 之后 |
-| **2V** | 最小纵向切片：`CPythonLauncher` → `system.py` → `wndMgr` → 登录/选角 → GamePhase → 本地角色移动 | 需要 2A、2P、2D；**这是第一个可运行的新架构里程碑** |
-| 2 | 其余 P0 角色/移动单元，按依赖拓扑移植 | 2V 之后 |
-| 3 | P1 战斗/技能 → P2 游戏阶段封包 → P3 物品；Python 层（窗口系统 → `*Module.cpp`） | 未开始 |
+| **2V0** | UI 壳：真实 `PythonLauncher/wndMgr/grp/app` + platform UI，其他玩法模块用桩，显示并操作 Logo/Popup | 需要 2A、2P 和 root/uiscript 子集 |
+| **2V1** | 登录/选角：真实 `net` phase、登录/选角脚本及所需模块，走到 Loading | 2V0 之后 |
+| **2V2** | GamePhase：真实角色管理、主角创建和最小渲染，进入游戏并显示角色 | 2V1、2D 之后 |
+| **2V3** | 本地移动：真实 player/input/event/movement 链，输入、位置和移动封包切到新路径 | 2V2 之后；**第一个可玩的新架构里程碑** |
+| 2 | 2V3 未覆盖的其余 P0 角色/移动单元，按依赖拓扑移植 | 2V3 之后 |
+| 3 | 剩余 Python 模块和窗口 → P1 战斗/技能 → P2 游戏阶段封包 → P3 物品 | 未开始 |
 | 4 | `NEEDS_LIVE` 真服验证 | 未开始 |
 
 ### 迁移方式：始终保持可玩
@@ -88,16 +93,19 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
   没有接通前，port-map 状态保持 `TODO`，`note` 写"已照抄，未接通"。
 - 每个接通步骤的提交同时：切换调用方到新路径、删除被取代的旧逻辑、跑一遍能覆盖该路径的运行测试（离线 FakeClient
   或真服 e2e）。
-- `main` 在任意提交上都能进游戏走动；`legacy` 路径在 2V 完成、默认值切到 `port` 并稳定后整体删除。
+- 每次接通都同时跑 `legacy` 和 `port` 两套路由的相关回归；共享 extension 的改动不能破坏默认的 legacy 路径。
+- `main` 在任意提交上都能进游戏走动；`legacy` 路径在 2V3 完成、默认值切到 `port` 并稳定后整体删除。
 
 ### 批次 2A：基础
 
-1. `extension/src/port/common/`：`Win32Types.h`（`BYTE`/`WORD`/`DWORD`/`LONG`/`BOOL`/`UINT`/`HANDLE` 等的定宽映射）、
+1. `extension/src/port/common/`：`Win32Types.h`（`BYTE`/`WORD`/`DWORD`/`LONG`/`BOOL`/`UINT` 等标量的定宽映射；
+   `HANDLE`/窗口句柄/消息参数另用指针宽度的平台类型）、
    40250 用到的 Win32/CRT 宏和函数（`ZeroMemory`、`_snprintf`、`stricmp`、`timeGetTime` 等）的最小实现、
    `StdAfx.h` 等价物。
 2. 参考公共头的最小闭包：从第一批要移植的单元出发（`PythonPlayerEventHandler.h` 依赖 `ActorInstance.h`、`FlyHandler.h`、
    `PythonNetworkStream.h`、`InstanceBase.h`），用脚本列出 `#include` 闭包，把闭包里的头文件先照抄为可编译的声明。
-3. `port_logic` 静态库 CMake 目标，链接进 `libmtgodot`；在 macOS 和 Android 两个工具链上编译。
+3. `port_logic` 静态库 CMake 目标，链接进 `libmtgodot`；macOS、Android、iOS、Linux、Windows 五个平台分别编译。
+   某个平台的工具链暂不可用时，2A 对该平台保持 `BLOCKED`，不能用其他平台的通过结果替代。
 4. `extension/src/platform/` 接口骨架：闭包里出现的平台类（`CGraphicThingInstance`、`CSoundManager` 等）只声明
    40250 调用方用到的方法，先给空实现。
 5. 门禁：`port/**` 下每个头文件单独编译通过（header self-containment），序列化结构的 `static_assert` 全部通过。
@@ -115,7 +123,9 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
 1. 写一个只读的扫描工具（Python，放在 `tools/`），解析所有 `.eix`，统计每个包、每种 `compressed_type` 的文件数和字节数。
 2. 按统计结果决定：
    - 只有 `NONE/COMPRESS/SECURITY` 的包可以离线解出；
-   - `PANAMA`/`HYBRIDCRYPT*` 如存在，确认密钥来源：本地的 `Index`/配置，还是服务器 `GC_HYBRIDCRYPT_KEYS`/`SDB` 下发。需要服务器密钥的包，要么移植密钥链，要么在开发期用一次真服登录抓取密钥后离线解包（密钥不进仓库）。
+   - `PANAMA`/`HYBRIDCRYPT*` 如存在，确认密钥来源：本地的 `Index`/配置，还是服务器 `GC_HYBRIDCRYPT_KEYS`/`SDB` 下发。
+     一次真服登录抓取仅可用于确认格式和密钥来源，不能作为构建或发布依赖；正式方案必须是可重复的运行时密钥链，或经过
+     授权、可重复并有来源清单的重新打包流程，密钥本身不进仓库。
 3. 验证 `Index` 文件列出的包顺序和同名文件的覆盖优先级，与 `CEterPackManager` 一致。
 4. 路径归一化：40250 在 Windows 上大小写不敏感，并把 `d:/ymir work/` 等前缀映射到包内路径。确定统一的小写化规则，扫描大小写冲突。
 5. 移动端交付：决定最终形式（例如解包后重新打成我们自己的 `mtpack`，或直接在设备上读 EPK），给出 Android/iOS 的包体积、首包与按需下载的划分，以及更新方式。`MT_ASSETS` 只是开发期覆盖。
@@ -125,7 +135,11 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
 
 1. CPython 2.7.18 源码放进 `extension/third_party/cpython-2.7.18/`。**共用源码清单和静态模块清单**（`Modules/Setup` 中启用的 C 模块，见 `tools/py_embed_android/build-and-run.sh`）；**每个平台各自一份 `pyconfig.h`**（由该平台的 configure 生成后提交，或 Windows 用 `PC/pyconfig.h`），因为它是对目标平台类型大小和系统 API 的探测结果，不能共用。已知平台差异：Android API 24 需关掉 `HAVE_LANGINFO_H`。
 2. 静态链接进 `libmtgodot`，照抄 `ScriptLib/PythonLauncher.cpp`。
-3. `pack` 模块通过 `asset_io` 读取，标准库的纯 Python 文件放进资源包，由 `system.py` 自带的导入钩子加载。
+3. `pack` 模块通过 `asset_io` 读取 40250 的 root/uiscript。标准库沿用已验证的 `python27.zip + sys.path`：
+   - 桌面端把 zip 放在 CPython 可读的真实文件系统路径；
+   - Android/iOS 首次启动从应用资源复制到应用沙盒，校验提交在资源清单中的 sha256，再加入 `sys.path`；
+   - `zipimport` 静态编进解释器。`system.py` 的导入钩子只负责 pack 内的简单 root 模块，不能用来加载标准库 package、
+     dotted import 或 `encodings`。
 4. 五个平台分别验证：编译、链接无未定义符号、`Py_Initialize`、静态 C 模块逐个 `import`、在 app 进程里跑 `system.py` → `prototype.RunApp()`（对照结果：74 个模块中 66 个加载成功，引导期调用 33 个 C++ 函数）。
 
    | 平台 | 状态 |
@@ -136,6 +150,27 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
    | Linux x86_64 | 未做 |
    | Windows x64 | 未做（用 `PCbuild` 的源码清单和 `PC/pyconfig.h`，不走 configure） |
 
+### 批次 2V0–2V3：纵向切片
+
+2A 先根据真实 `#include` 和 Python import 生成每个切片的机器可读单元清单；清单提交到 `audit/`，进入切片前不得仍有
+“后续批次才实现”的隐式依赖。未列出的 native 模块可以使用行为可观察、会记录调用的桩，但桩函数不能计为移植完成。
+
+1. **2V0 — UI 壳**：真实 `ScriptLib/PythonLauncher.cpp`、`PythonPackModule.cpp`、
+   `EterPythonLib/PythonWindow*.cpp`、`PythonWindowManager*.cpp`、`PythonGraphic*Module.cpp`、
+   `PythonApplicationModule.cpp` 和所需 platform UI adapter；玩法模块先用桩。验收为 app 进程内运行 `system.py`，显示并可操作
+   Logo/Popup，输入、焦点、裁剪、文本和图片至少各有一个运行测试。
+2. **2V1 — 登录/选角**：加入 `PythonNetworkStream{,PhaseHandShake,PhaseLogin,PhaseSelect,PhaseLoading}.cpp`、
+   `PythonNetworkStreamModule.cpp`、AccountConnector 及登录/选角脚本真实调用到的模块。验收为 FakeServer 离线完成 phase 顺序，
+   再以真服 smoke 证明登录、角色列表和选择进入 Loading；未验证的服务器分支记 `NEEDS_LIVE`。
+3. **2V2 — GamePhase/角色显示**：加入 GamePhase 的最小分派闭包、`PythonCharacterManager`、`InstanceBase`、`ActorInstance`
+   及角色模型/动画/资源 adapter。验收为进入游戏、创建主角并显示可辨认的静止角色；这个切片要求 2D 的 proto 和所需资源通过
+   strict gate。
+4. **2V3 — 本地移动**：加入 `PythonPlayer`、`PythonPlayerInput*`、`PythonPlayerEventHandler`、
+   `InstanceBaseMovement`、`ActorInstance{Motion,Event,Position,Rotation,CollisionDetection}` 的实际依赖闭包。验收为输入经过新路径
+   改变位置/朝向、发送与 40250 相同的移动封包，并在离线边界测试和真服 smoke 中通过。接通时删除对应 legacy 玩法逻辑。
+
+每个切片都必须同时跑 legacy/port 双路回归；只有 2V3 稳定并把默认路由切到 `port` 后，才能删除总开关和剩余 legacy 宿主。
+
 ## 5. 数据源切换：m2dev assets → 40250
 
 现在的渲染和逻辑读的是 `assets/`，这是从 m2dev 的包解出来的。2026-09-22 与 40250 `Client/Eternexus` 逐项对比的结果：
@@ -160,21 +195,23 @@ extension/third_party/cpython-2.7.18/                  # 静态库（2P 批次
 2. proto 读取按 40250 移植：`EterBase/tea.cpp`、`GameLib/ItemData.h` 的 `TItemTable`、`CPythonNonPlayer` 的 mob 表，放进镜像文件（使用 2A 的定宽类型和 `static_assert`），替换 `extension/src/proto/proto.cpp` 里的 m2dev 格式。
 3. 资源测试严格模式：
    - 统一资源环境变量：C++ 测试（`extension/CMakeLists.txt` 目前只透传 `M2_ASSETS`）和 GDScript（`MT_ASSETS`）统一读 `MT_ASSETS`，过渡期两者都透传；
-   - 新增 `MT_ASSETS_STRICT=1`：指定了 40250 资源时，缺文件必须失败，不能跳过；
+   - 新增 `MT_ASSETS_STRICT=1`：该模式下 `MT_ASSETS` 未设置、来源清单缺失、sha256 不匹配或必需文件缺失都必须失败，不能跳过；
    - 为 40250 的 root、locale、proto 和关键包生成来源清单（路径 + sha256），提交到 `audit/`，测试开始时核对。
-4. 资源根切换方式按 2R 的结论执行，跑渲染和解析测试，更新本节状态。
+4. 新增并在 CI/发布前强制运行 `script/run_40250_asset_gate.sh`；它设置/校验 `MT_ASSETS_STRICT=1`，运行 native proto/pack/formats
+   测试和 Godot root/locale/render 测试。脚本在没有 40250 资源时必须失败，不能把跳过报告成 PASS。
+5. 资源根切换方式按 2R 的结论执行，跑严格门禁，更新本节状态。
 
 ## 6. 进度与 port-map 基线
 
 实时数字用 `port_map.py status` 查看。
 
-2A 时做一次重新基线，之后的数字才代表新架构的进度：
+本次方案修订已经重置旧的 6 个完成状态；2A 完成工具和基础目标后再次确认基线：
 
-- 之前"完成"的 6 个函数（`PythonPlayerEventHandler.cpp`）作废：OnMove/OnMoving/OnStop 的实现在 `net_play.gd`，属于迁移来源；
-  3 个 `N_A`（单例、构造、析构，理由是"由 NetPlay 场景节点持有"）与"单例归扩展所有"冲突。全部回退为 `TODO`。
-- 原样运行的 Python 脚本函数**不标 `N_A`**（`N_A` 只用于没有玩法语义的平台胶水）。新增状态 `RUN_AS_IS`：
-  `impl` 指向随包运行的原脚本，`evidence` 要求该函数所在模块在目标平台的运行证据（导入成功且被运行路径调用到）。
-  需要同步修改 `port_map.py` 和 `references/audit-schema.md`。
+- 之前"完成"的 6 个函数（`PythonPlayerEventHandler.cpp`）已作废并回退为 `TODO`：OnMove/OnMoving/OnStop 的实现在
+  `net_play.gd`，属于迁移来源；3 个 `N_A`（单例、构造、析构）与"单例归扩展所有"冲突。
+- 原样运行的 Python 脚本函数**不标 `N_A`**（`N_A` 只用于没有玩法语义的平台胶水）。状态 `RUN_AS_IS`：
+  `impl` 指向随包运行的原脚本，`evidence` 要求目标平台的导入/运行证据；单元的 reference hash 与资源来源清单共同证明
+  运行的是完全相同的字节。`port_map.py`、SKILL 和 schema 已同步支持并把它计入 done。
 
 2026-09-22 基线前的数字（仅供参考）：logic 3285 个函数、python 4890、platform 2229，完成数视为 0。