docs(03): capture phase context

.planning/phases/03-data-completion/03-CONTEXT.md

@@ -0,0 +1,124 @@
+# Phase 3: 数据端完成 - Context
+
+**Gathered:** 2026-09-10
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+完成 `data-common`、`data-base`、`data-system`、`data-state` 四层数据端的系统整合，使数据端可以在 Node 环境独立创建、执行必要的数据操作并自行播放固定录像。阶段交付包括数据端闭环所需的单元测试、录像修饰与命令注册、顶层模块装配、事件内建函数最小清单、专用 Node 验证入口，以及四层数据包的类型错误和循环引用清零。
+
+渲染端适配、完整 legacy 迁移和阶段 6 的全部核心单测不属于本阶段。接口语义和系统边界由用户主导；AI 负责实现和测试，不得自行发明未确认的公共接口行为。
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 单元测试边界
+- **D-01:** 阶段 3 覆盖每个数据端系统的闭环必需路径、录像播放依赖和当前尚未覆盖的关键模块；阶段 6 再补充完整边界与回归覆盖。
+- **D-02:** 如果单测暴露接口行为未定义或接口与实现不一致，必须暂停并向用户提问，不能由 AI 擅自扩展或猜测公共接口。
+- **D-03:** 新测试优先使用 fake/state fixture 和显式依赖注入；只有验证 legacy bridge 时才保留必要的全局 stub。
+- **D-04:** 数据端已有和新增测试全部通过，使用固定的非 watch 测试命令；不把无关渲染端测试作为阶段 3 门禁。
+
+### 录像修饰器与回放
+- **D-05:** 录像修饰器只覆盖外部可调用、会改变可存档游戏状态且可能由录像重放触发的状态入口；纯查询、纯计算和内部辅助函数不重复修饰。
+- **D-06:** 被修饰的异步动作必须等待完整 Promise 动作结束后再完成其录像语义，适用于移动、事件链和战斗等长动作。
+- **D-07:** Node 回放遇到命令无法执行、结果不一致或状态校验失败时立即停止，并报告首个分歧的命令索引、命令码、参数和失败原因。
+- **D-08:** 录像命令码由顶层统一注册并保持稳定；各子系统提供命令实现或默认注册项，避免模块间编号冲突。
+
+### 顶层整合与注册
+- **D-09:** 以显式工厂入口创建数据端实例为主，供 Node 和渲染端分别创建；当前 singleton 仅在确有兼容需求时保留，不作为 Node 唯一入口。
+- **D-10:** 顶层负责初始化顺序和最终装配，各系统模块负责提供自己的默认注册函数或注册项，避免把实现细节复制到 `CoreState`。
+- **D-11:** 事件系统只注册 Node 回放和当前闭环实际需要、且接口已明确的最小内建函数清单；不擅自补齐尚未确定的完整 legacy 事件函数清单。
+- **D-12:** Node 数据端默认不依赖 DOM 或渲染全局。legacy 数据转换通过可注入依赖处理，渲染通知只能经 `r()`/`rf()` 或 hook，缺少渲染宿主时必须安全跳过。
+
+### Node 验收与质量门禁
+- **D-13:** 使用固定、可重复的端到端录像 fixture，覆盖顶层初始化、至少一个玩家动作、事件或状态变化以及正常播放结束。
+- **D-14:** 验收不仅要求每条命令成功和录像正常结束，还要将关键数据端状态与预期快照精确比较，保证播放结果可重复。
+- **D-15:** 提供专用 Node 验证命令，直接创建顶层实例、加载录像并在失败时返回非零状态；它与数据端单测门禁分开执行。
+- **D-16:** `data-common`、`data-base`、`data-system`、`data-state` 四层的 TypeScript 错误全部清零，并针对这四层检查循环引用。渲染端或 legacy-only 的无关问题不扩大为本阶段范围。
+- **D-17:** 本阶段系统级任务较多，遇到任何接口语义、系统边界、依赖关系或实现路径上的不确定问题，都必须暂停并提问确认，不得擅自选择“看起来合理”的方案绕过问题。
+
+### the agent's Discretion
+没有授权 AI 在接口语义或系统边界上自行决策的事项。
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Project and phase requirements
+- `.planning/PROJECT.md` — project architecture, data/render separation, AI implementation boundary, and quality constraints
+- `.planning/REQUIREMENTS.md` — DATA-01 requirement and explicit Phase 3 / Phase 6 boundaries
+- `.planning/ROADMAP.md` — Phase 3 goal, success criteria, dependency order, and out-of-scope neighboring phases
+- `.planning/STATE.md` — prior phase decisions, existing quality-gate concerns, and current repository state
+- `dev.md` — four-layer data architecture, Node replay requirement, dependency direction, and coding rules
+
+### Existing data-side contracts and implementation anchors
+- `packages-user/data-common/src/types.ts` — `IDataCommon` public Layer 0 contract
+- `packages-user/data-base/src/types.ts` — `IStateBase` Layer 1 contract
+- `packages-user/data-system/src/types.ts` — `IStateSystem` Layer 2 contract
+- `packages-user/data-state/src/types.ts` — `ICoreState` Layer 3 contract
+- `packages-user/data-common/src/replay/types.ts` — replay command, sandbox, route, and state reset contracts
+- `packages-user/data-common/src/replay/system.ts` — replay command registration and route recording implementation
+- `packages-user/data-common/src/replay/sandbox.ts` — sequential replay execution and failure behavior
+- `packages-user/data-common/src/replay/func.ts` — existing replay safety decorators
+- `packages-user/data-system/src/event/system.ts` — event interpreter and built-in function registration point
+- `packages-user/data-system/src/event/executor.ts` — event invocation and reduction behavior
+- `packages-user/data-state/src/core.ts` — current top-level four-layer construction and legacy initialization path
+- `packages-user/data-state/src/ins.ts` — current singleton entry point and its transition note
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `ReplaySystem`, `ReplaySandbox`, `ReplayArray`, and `IReplaySystem` — existing recording, command registration, sequential playback, and route storage primitives
+- `shouldReplay` and `ignoreReplay` in `packages-user/data-common/src/replay/func.ts` — existing replay-safety decorator mechanism to audit before extending
+- `CoreState` — current L0-L3 construction, saveable registration, combat/event wiring, and legacy data loading integration point
+- `GameEventSystem` and `EventExecutor` — existing event interpreter and invocation dispatch path; `GameEventSystem` currently initializes with an empty built-in function list
+- Existing Vitest tests in `data-common`, `data-base`, `data-system`, and `data-state` — patterns for data-side fixtures and current global stubs
+
+### Established Patterns
+- Dependency direction is `src -> packages-user -> packages`; data layers are `data-common -> data-base -> data-system -> data-state`.
+- Public contracts are expressed through `types.ts` and barrel exports; user-owned interface decisions must not be inferred by implementation agents.
+- Data-side code must remain DOM-free. Rendering communication is gated through `r()`/`rf()` or hooks.
+- `pnpm test:ci` is the existing deterministic non-watch test command; Phase 3 needs a dedicated Node replay command in addition to the data-side test gate.
+- The current top-level path still exports `state = new CoreState()` and uses legacy globals for initial data loading, so factory creation and injectable legacy conversion require careful compatibility handling.
+
+### Integration Points
+- `packages-user/data-state/src/core.ts` is the top-level orchestration point for system construction, default registration, saveable content, replay commands, and event built-ins.
+- `packages-user/data-state/src/ins.ts` is the compatibility boundary for the existing singleton entry point.
+- `packages-user/data-system/src/event/system.ts` is the event built-in registration boundary.
+- `packages-user/data-common/src/replay/system.ts` is the replay command registry and recording boundary.
+- The four package indexes and their `types.ts` files are the public export and contract boundaries that the Node entry must consume without introducing cycles.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- The user defined the phase as a system-level integration effort: data-side systems must be unit-tested, necessary methods must participate in replay debugging, top-level registration must be completed, and the final validation must make Node play a recording independently.
+- The final validation is also intended to cover the Phase 1 verification target, so the fixed replay fixture must exercise the event path rather than only testing isolated data structures.
+- Any uncertainty must be surfaced to the user before implementation; no silent assumptions are allowed for this phase.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Complete unit-test coverage beyond the data-side replay closure belongs to Phase 6.
+- Full legacy system removal and migration belongs to Phase 5.
+- Full mobile/desktop rendering integration belongs to Phase 4.
+- A complete legacy event built-in catalog remains deferred until its interfaces and scope are explicitly decided; Phase 3 registers only the minimum closed-loop set.
+
+</deferred>
+
+---
+
+*Phase: 3-数据端完成*
+*Context gathered: 2026-09-10*

.planning/phases/03-data-completion/03-DISCUSSION-LOG.md

@@ -0,0 +1,77 @@
+# Phase 3: 数据端完成 - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-09-10
+**Phase:** 3-数据端完成
+**Areas discussed:** 单元测试边界, 录像修饰器与回放, 顶层整合与注册, Node 验收与质量门禁
+
+---
+
+## 单元测试边界
+
+| Decision | Alternatives considered | Selected |
+|----------|-------------------------|----------|
+| 阶段边界 | 只做闭环必需覆盖；本阶段全部补齐；只做冒烟测试 | 闭环必需覆盖 ✓ |
+| 接口歧义 | 停下等待接口决定；按现有实现补齐；局部推断后实现 | 停下等待接口决定 ✓ |
+| 测试隔离 | 新测试优先注入依赖；统一沿用全局 stub；先彻底移除 bridge | 新测试优先注入依赖 ✓ |
+| 测试门禁 | 数据端全套通过；仓库全套通过；按系统逐批通过 | 数据端全套通过 ✓ |
+
+**User's choice:** 阶段 3 做数据端闭环必需测试，阶段 6 再补完整覆盖；接口不明确时必须停下提问。
+**Notes:** 新测试使用显式依赖和 fixture，只有 bridge 测试保留必要的 legacy 全局 stub。
+
+---
+
+## 录像修饰器与回放
+
+| Decision | Alternatives considered | Selected |
+|----------|-------------------------|----------|
+| 修饰范围 | 外部可调用状态入口；所有状态写入函数；只修饰顶层命令 | 外部可调用状态入口 ✓ |
+| 异步语义 | 等待完整动作；只包同步调用；调用/完成拆分 | 等待完整动作 ✓ |
+| 回放失败 | 首个分歧立即失败；记录后继续；仅安全检查警告 | 首个分歧立即失败 ✓ |
+| 命令注册 | 顶层统一注册；各系统自注册；保留旧协议优先 | 顶层统一注册 ✓ |
+
+**User's choice:** 录像修饰器只加在外部可调用状态入口；异步动作必须等待结束；回放首个分歧立即失败并报告；命令码由顶层统一注册。
+**Notes:** 纯查询、纯计算和内部辅助函数不应制造重复录像语义。
+
+---
+
+## 顶层整合与注册
+
+| Decision | Alternatives considered | Selected |
+|----------|-------------------------|----------|
+| 顶层初始化 | 工厂创建为主；保留 singleton；双入口并行维护 | 工厂创建为主 ✓ |
+| 事件内建函数 | 最小闭环清单；一次补齐 legacy 清单；只注册扩展机制 | 最小闭环清单 ✓ |
+| 装配职责 | 顶层编排、模块提供默认项；全部写在 CoreState；各系统自行初始化 | 顶层编排、模块提供默认项 ✓ |
+| Node 隔离 | Node 默认无渲染依赖；沿用完整 legacy 环境；阶段 3 先不接 bridge | Node 默认无渲染依赖 ✓ |
+
+**User's choice:** 工厂入口是主路径，顶层控制顺序，各模块提供默认注册项；事件只注册当前闭环需要且接口明确的最小清单。
+**Notes:** legacy 数据转换允许作为可注入依赖，Node 无 DOM/渲染全局；渲染通知仍只能走 `r()`/`rf()` 或 hook。
+
+---
+
+## Node 验收与质量门禁
+
+| Decision | Alternatives considered | Selected |
+|----------|-------------------------|----------|
+| 最终录像 | 固定端到端录像；复用现有游戏录像；系统级最小录像集 | 固定端到端录像 ✓ |
+| 验收断言 | 状态快照精确一致；命令全部成功；最终结果一致 | 状态快照精确一致 ✓ |
+| 质量范围 | 四层数据包全清零；仓库全清零；仅本阶段改动清零 | 四层数据包全清零 ✓ |
+| Node 入口 | 专用 Node 验证命令；Vitest Node 测试；构建后运行产物 | 专用 Node 验证命令 ✓ |
+
+**User's choice:** 使用固定端到端录像和精确状态快照，专用 Node 命令失败返回非零；四个数据层包的类型错误与循环引用全部清零。
+**Notes:** 最终录像应覆盖顶层初始化、玩家动作、事件或状态变化和正常结束，并承担 Phase 1 验证目标。
+
+---
+
+## the agent's Discretion
+
+None. The user explicitly requires clarification before any uncertain interface, system-boundary, dependency, or implementation-path decision.
+
+## Deferred Ideas
+
+- Full core-system test coverage remains in Phase 6 after the Phase 3 replay closure.
+- Full legacy migration remains in Phase 5.
+- Full rendering integration remains in Phase 4.
+- The complete legacy event built-in catalog remains deferred until its interfaces and scope are explicitly decided.