diff --git a/.planning/phases/04-render-adaptation/04-HERO-MOVER-INTERFACE.md b/.planning/phases/04-render-adaptation/04-HERO-MOVER-INTERFACE.md index 0e9fa9f..dfbc71d 100644 --- a/.planning/phases/04-render-adaptation/04-HERO-MOVER-INTERFACE.md +++ b/.planning/phases/04-render-adaptation/04-HERO-MOVER-INTERFACE.md @@ -156,14 +156,45 @@ Phase 4 第二步(D-17):04-01 的只读对账把主要失配点定位在** | ID | 成员 | 渲染端锚点 | 数据端锚点 | 对账结论 | 说明 | |----|------|------------|------------|----------|------| | #04-02-R-01 | `IHeroMoveControllerHooks` 钩子族(移动 / 位置 / 跟随者子集) | `packages-user/client-modules/src/render/map/extension/hero.ts:81` `packages-user/client-modules/src/render/map/extension/hero.ts:457` | 有对位:`packages-user/data-common/src/common/mover.ts:166` `packages-user/data-common/src/common/mover.ts:216`;有对位:`packages-user/data-base/src/hero/types.ts:277` `packages-user/data-base/src/hero/types.ts:283`;`onSetPosition` / `onStartMove` / `onEndMove` / `onMoveHero` / `onJumpHero` / `onTurnHero` / `onAddFollower` / `onRemoveFollower` / `onRemoveAllFollowers` 无同名对位,最接近:`packages-user/data-common/src/common/mover.ts:166` | 渲染端需改 | `addHook` 注册的移动 / 位置 / 跟随者钩子方法名与数据端现行 hooks 整体不一致,需随 `IHeroMoveControllerHooks` 整体重构;贴图 / alpha 钩子按 D-18 排除,不在本行范围 | +| #04-02-R-02 | `HeroMover` / `IMoveController`(import 源与类型名) | `packages-user/client-modules/src/action/move.ts:4` `packages-user/client-modules/src/action/move.ts:19` `packages-user/client-modules/src/action/move.ts:29` `packages-user/client-modules/src/action/move.ts:33` | `packages-user/data-base/src/hero/mover.ts:22` `packages-user/data-common/src/common/mover.ts:142` | 渲染端需改 | 带 `// @ts-expect-error 需要重构`(`move.ts:3`);`IMoveController` 数据端现名为 `IMoverController`,`HeroMover` 实际在 `@user/data-base`,`@user/data-state` barrel 未导出二者 | +| #04-02-R-03 | `HeroAnimateDirection` | `packages-user/client-modules/src/render/map/extension/hero.ts:6` `packages-user/client-modules/src/render/map/extension/hero.ts:53` `packages-user/client-modules/src/render/map/extension/hero.ts:97` `packages-user/client-modules/src/render/map/extension/types.ts:5` `packages-user/client-modules/src/render/map/extension/types.ts:147` | `packages-user/data-common/src/common/mover.ts:40` | 渲染端需改 | 带 `// @ts-expect-error 需要重构`;数据端现行为 `ObjectAnimDirection`,成员 `Forward` / `Backward` 一一对应 | +| #04-02-R-04 | `IHeroMoveController` | `packages-user/client-modules/src/render/map/extension/hero.ts:8` `packages-user/client-modules/src/render/map/extension/hero.ts:79` `packages-user/client-modules/src/render/map/extension/types.ts:7` `packages-user/client-modules/src/render/map/extension/types.ts:15` `packages-user/client-modules/src/render/map/extension/manager.ts:2` `packages-user/client-modules/src/render/map/extension/manager.ts:18` | `packages-user/data-base/src/hero/types.ts:303` `packages-user/data-base/src/hero/types.ts:399` | 渲染端需改 | 带 `// @ts-expect-error 需要重构`;数据端无此名,已拆为 `IHeroLocation` + `IHeroMover`,`IHeroLocation.mover` 提供 `IHeroMover` | +| #04-02-R-05 | `hero.x` / `hero.y` | `packages-user/client-modules/src/render/map/extension/hero.ts:87` `packages-user/client-modules/src/render/map/extension/hero.ts:88` `packages-user/client-modules/src/render/map/extension/hero.ts:117` `packages-user/client-modules/src/render/map/extension/hero.ts:122` | `packages-user/data-common/src/common/mover.ts:48` `packages-user/data-common/src/common/mover.ts:49` `packages-user/data-common/src/common/mover.ts:58` | 匹配 | `IHeroLocation extends IObjectMovable`(`data-base/src/hero/types.ts:303`),`x` / `y` / `setPos` 均有对位 | +| #04-02-R-06 | `hero.direction` | `packages-user/client-modules/src/render/map/extension/hero.ts:89` `packages-user/client-modules/src/render/map/extension/hero.ts:125` `packages-user/client-modules/src/render/map/extension/hero.ts:193` | `packages-user/data-common/src/common/mover.ts:243` `packages-user/data-common/src/common/mover.ts:245` `packages-user/data-common/src/common/mover.ts:63` | 渲染端需改 | 现行无单成员 `direction`:朝向为 `IObjectMover.faceDirection` / `moveDirection`,只读朝向可经 `IObjectMovable.getCurrentFaceDirection()` | +| #04-02-R-07 | `hero.addHook` | `packages-user/client-modules/src/render/map/extension/hero.ts:81` | `packages-user/data-common/src/common/mover.ts:235` `packages-user/data-common/src/common/mover.ts:216` | 匹配 | `IObjectMover extends IHookable>`;`addHook` 来自 `IHookable`(`packages/common/src/types.ts:81`),返回 `IHookController`,`load` / `unload` 对位 `hero.ts:82` / `:453` | +| #04-02-R-08 | 跟随者增删钩子(`onAddFollower` / `onRemoveFollower` / `onRemoveAllFollowers`) | `packages-user/client-modules/src/render/map/extension/hero.ts:502` `packages-user/client-modules/src/render/map/extension/hero.ts:506` `packages-user/client-modules/src/render/map/extension/hero.ts:510` `packages-user/client-modules/src/render/map/extension/hero.ts:341` | `packages-user/data-base/src/hero/types.ts:486` `packages-user/data-base/src/hero/types.ts:492` `packages-user/data-base/src/hero/types.ts:499` | 渲染端需改 | 现行 `IHeroFollowersControllerHooks` 参数为 `(follower: IHeroFollower, index)`,渲染端按 `(number, string)` / `(string, boolean)`;`onRemoveAllFollowers` 无同名钩子,最接近 `IHeroFollowersController.removeAllFollowers()`(`types.ts:556`) | +| #04-02-R-09 | `HeroKeyMover` 单步启动期望(`oneStep` / `startMove(false, false, false, true)`) | `packages-user/client-modules/src/action/move.ts:125` `packages-user/client-modules/src/action/move.ts:126` | `packages-user/data-common/src/common/mover.ts:293` `packages-user/data-common/src/common/mover.ts:350`;无对位,最接近:`packages-user/data-base/src/hero/mover.ts:22` | 渲染端需改 | `oneStep` / `startMove(...)` 在 `IObjectMover` 无同名方法;对应能力为 `step(dir)` + `start(): Readonly | null`,需改为「追加步 + 启动」组合 | +| #04-02-R-10 | `controller.queue` / `controller.push({ type: 'dir', value })` | `packages-user/client-modules/src/action/move.ts:169` `packages-user/client-modules/src/action/move.ts:170` | 无对位,最接近:`packages-user/data-common/src/common/mover.ts:152` `packages-user/data-common/src/common/mover.ts:132` `packages-user/data-common/src/common/mover.ts:364` | 渲染端需改 | `IMoverController` 无 `queue` 成员(队列私有于 `ObjectMover.moveQueue`);`push` 参数为 `ObjectMoveStep` 而非 `{ type: 'dir', value }`,渲染端需改构造 `IObjectMoveStepDir` | +| #04-02-R-11 | `controller.onEnd` / `controller.stop()` / `mover.on('stepEnd')` | `packages-user/client-modules/src/action/move.ts:130` `packages-user/client-modules/src/action/move.ts:137` `packages-user/client-modules/src/action/move.ts:145` `packages-user/client-modules/src/action/move.ts:180` | `packages-user/data-common/src/common/mover.ts:146` `packages-user/data-common/src/common/mover.ts:163` `packages-user/data-common/src/common/mover.ts:202` | 渲染端需改 | `onEnd` / `stop()` 有对位;`mover.on('stepEnd', ...)` 事件名订阅与 `IObjectMoverHooks.onStepEnd` 回调契约不同,需改订阅方式 | +| #04-02-R-12 | `IMapExtensionManager.heroMap` 键类型 / `addHero` / `removeHero` | `packages-user/client-modules/src/render/map/extension/types.ts:15` `packages-user/client-modules/src/render/map/extension/types.ts:27` `packages-user/client-modules/src/render/map/extension/types.ts:35` `packages-user/client-modules/src/render/map/extension/manager.ts:18` | `packages-user/data-base/src/hero/types.ts:303` `packages-user/data-base/src/hero/types.ts:399` | 渲染端需改 | 键类型 `IHeroMoveController` 需改为 `IHeroLocation` / `IHeroMover`;被注释接线 `client.ts:150` 以 `this.hero.mover`(`IHeroMover`)为参,与 `addHero(state: IHeroMoveController, ...)` 形状不一致 | ## 缺失接口候选 -(Task 3 补齐:候选登记与结论行) +本节登记「渲染端需要而数据端无对位」的**候选**;只记录、不设计、不修复(D-13),未经用户裁决不视为最终缺失清单。 + +### #04-02-G-01:勇士移动语义钩子族(onMoveHero / onJumpHero / onTurnHero / onStartMove / onEndMove) + +- **渲染端需求**:`MapHeroHook` 需要按方向 / 时长的移动语义钩子(`onMoveHero(direction, time)` / `onJumpHero(x, y, time, waitFollower)` / `onTurnHero(direction)` / `onStartMove()` / `onEndMove()`)来驱动 `MapHeroRenderer.move` / `jumpTo` / `turn` / `startMove` / `waitMoveEnd`(`packages-user/client-modules/src/render/map/extension/hero.ts:469` 起)。 +- **数据端现状**:无同名对位;最接近的是面向数据对象事件的 `IObjectMoverHooks`(`packages-user/data-common/src/common/mover.ts:166`,含 `onMoveStart` / `onMoveEnd` / `onStepStart` / `onStepEnd` / `onSetPos`)与 `IHeroLocationHooks`(`packages-user/data-base/src/hero/types.ts:277`,含 `onSetPos`),其参数为 `(tile, mover)` 数据对象而非渲染语义。 +- **待确认**:应由数据端补齐渲染语义钩子,还是渲染端改接数据对象钩子(可能与本表 `#04-02-R-01` 及 `#04-02-R-04` 的整体重构方案重叠)?留待用户裁决(D-13)。 + +### #04-02-G-02:HeroKeyMover 依赖的 oneStep 与控制器 queue + +- **渲染端需求**:`HeroKeyMover.tryStartMove` / `onStepEnd` 依赖 `mover.oneStep(dir)` 与 `controller.queue` / `controller.push({ type: 'dir', value })`(`packages-user/client-modules/src/action/move.ts:125`、`:169`、`:170`)。 +- **数据端现状**:无同名对位;最接近的是 `IObjectMover.step(dir, count?)`(`packages-user/data-common/src/common/mover.ts:293`)、`IMoverController.push(...steps)`(`packages-user/data-common/src/common/mover.ts:152`)与私有队列 `ObjectMover.moveQueue`(`packages-user/data-common/src/common/mover.ts:364`,`IMoverController` 不暴露队列)。 +- **待确认**:`oneStep` 的单步语义与队列可读性应由数据端补齐,还是渲染端改为只用 `step` + `push`(不读取队列)?留待用户裁决(D-13)。 + +**候选结论:** 本步登记 2 项缺失接口候选(未经用户裁决,不视为最终缺失清单,见 D-13) ## 未能从阅读确定(未猜测) -(Task 3 补齐:无法静态定论项) +1. **`controller.queue` 的运行时形状与 `IMoverController` 可达性**:渲染端 `action/move.ts:169` 读取 `con.queue.length`,但 `IMoverController`(`data-common/src/common/mover.ts:142`)无队列成员;队列在 `ObjectMover` 内为受保护成员(`mover.ts:364`)。渲染端是否曾依赖某个已删除的控制器扩展面,无法静态定论。 +2. **`state.hero.location` 是否为当前渲染端可取的入口**:`IHeroState.location` → `IHeroLocation`(`data-base/src/hero/types.ts:889`、`:303`)在静态契约上可达;但 `state` 单例(`data-state/src/ins.ts:10`)运行时是否已暴露与渲染端期望一致的取法,无法仅凭静态阅读确认。 +3. **钩子合并关系**:渲染端 `MapHeroHook`(`hero.ts:457`)与数据端 `IObjectMoverHooks` / `IHeroLocationHooks` / `IHeroFollowersControllerHooks` 的合并方式无法静态定论(见 `#04-02-R-01` / `#04-02-G-01`)。 +4. **移动语义钩子候选与 04-01「未能从阅读确定」第 2 条的重叠关系**:04-01 已登记「勇士 / 跟随者渲染粒度钩子」候选;该条中的贴图 / alpha 子项按 D-18 排除,本步只保留移动子项(`#04-02-G-01`),二者是否应合并为单一缺失项无法静态定论。 +5. **`state.roleFace` 的可达性**:渲染端在 `hero.ts:225` / `:348` / `:407` 读取 `state.roleFace.getFaceOf(...)`,该成员属于本增量对账面还是渲染侧局部能力,无法从勇士移动契约静态定论。 +6. **`IMapHeroRenderer.waitMoveEnd` 签名落差**:接口声明带参(`packages-user/client-modules/src/render/map/extension/types.ts:103`),实现无参(`packages-user/client-modules/src/render/map/extension/hero.ts:295`);属渲染端内部签名落差还是与数据端钩子契约相关,无法静态定论。 +7. **`stepEnd` 事件来源**:渲染端订阅 `mover.on('stepEnd', ...)`(`action/move.ts:137`),数据端现行钩子为 `IObjectMoverHooks.onStepEnd`(`mover.ts:202`)回调而非事件发射器事件;事件名与回调的桥接方式无法静态定论。 ## 处置 @@ -173,3 +204,4 @@ Phase 4 第二步(D-17):04-01 的只读对账把主要失配点定位在** - **范围的另一侧**:勇士移动契约与移动钩子(`IObjectMover` / `IHeroMover` / `IHeroLocationHooks` / `IHeroFollowersControllerHooks` / `IHeroStateHooks`,`onMoveHero` / `onJumpHero` / `onTurnHero` / `onStartMove` / `onEndMove` 等)**在范围内**,照常登记。 - **缺失接口裁决**:缺失接口候选须经用户逐步裁决(D-13),本步只记录、不设计、不修复,未经裁决不视为最终缺失清单。 - **`getHeroStatusOn` 类裸函数**(D-11)属 UI 属性读取,不属本增量范围,不登记为缺失。 +- **只读门禁**:相对基线的零变化(porcelain 条目集合逐条一致 + `基线摘要 sha256` 未变)由机器门禁判定;本 run 只新增本交付文档一个文件,未规划 04-03+ 适配。