docs: sync event/replay contracts with current design

- 03-EVENT-CONTRACT.md: short built-in names, class-based BuiltInFunction,
  single createEventRegistrations(), event/utils.ts (not barrel-exported)
- 03-REPLAY-CONTRACT.md: BaseReplayCommand shape, Teleport code, numeric fixed
  params, move notExecuted batching, CoreState registerReplayCommands, 2001-2008
- scope quick 260913-qtq record to AI changes only
This commit is contained in:
AncTe committed 2026-09-13 19:24:54 +08:00
1 parent e5f6d492b2
commit d7837fcc24
4 files changed
+194 -214

No files matched your search

@@ -8,14 +8,12 @@ tags: [events, anon-tokyo, data-state, refactor]
# Quick Task 260913-qtq: 事件内建函数改造 + anon-tokyo 引用统一
> 追溯记录:仅记录本次 AI 侧的改动(提交 `a701aa6`、`f0fd2f5`、文档提交见 SUMMARY)。
## Objective
把内嵌的 `@motajs/anon-tokyo` 作为唯一 anon-tokyo 来源接入全部包,并把
`data-state` 的全部事件内建函数改为与用户手写的 `EventSetBlock` 一致的
类式写法,注册收口为单一函数,共享工具收敛到 `utils.ts`。
> 说明:本记录为追溯补录。代码已先行完成并提交(`a701aa6`、`f0fd2f5`),
> 现补 PLAN/SUMMARY/STATE 记录以保证可追溯。
全仓统一引用内嵌的 `@motajs/anon-tokyo`,并把 `data-state` 的全部事件内建函数改为
类式 `BuiltInFunction` 写法,注册收口为单一函数,共享工具收敛到 `utils.ts`。
## Scope
@@ -23,27 +21,22 @@ tags: [events, anon-tokyo, data-state, refactor]
## Tasks
1. **anon-tokyo 引用统一**
- 全部 `from 'anon-tokyo'` → `from '@motajs/anon-tokyo'`
- `data-common` / `data-system` 声明 `@motajs/anon-tokyo: workspace:*`,刷新 lockfile
1. **anon-tokyo 引用统一** — 全部 `from 'anon-tokyo'` → `from '@motajs/anon-tokyo'`;
`data-common` / `data-system` 声明 `@motajs/anon-tokyo: workspace:*`,刷新 lockfile。
2. **事件内建函数类式重写**
- `map.ts` / `hero.ts` / `event.ts` 每个内建函数改为
`EventXxx implements BuiltInFunction<P, E>`,`name` 使用短名 + `func` 方法
- 删除落单函数;共享工具迁至 `event/utils.ts`(不经 index 导出)
- 非公共功能性函数改为类私有方法
- 移动序列改用 `IObjectMover.push`,删除 `appendMoveSteps`
- `registrations.ts` 仅保留 `createEventRegistrations()`,按三类顺序写入八条
- 删除 `EventBuiltinName`
2. **事件内建函数类式重写** — `map.ts` / `hero.ts` / `event.ts` 每个内建函数改为
`EventXxx implements BuiltInFunction<P, E>`(`name` 用短名 + `func` 方法);共享工具
迁至 `event/utils.ts`(不经 index 导出);非公共功能性函数改为类私有方法;移动序列
改用 `IObjectMover.push`;`registrations.ts` 仅保留 `createEventRegistrations()`;
删除 `EventBuiltinName`。
3. **验证**
- 数据包 type 门禁、`vitest run`、Prettier/ESLint
- 对齐 `46a38fa` 遗留的 replay 测试红点
3. **装配与测试** — `core.ts` 改用 `createEventRegistrations()`;更新
`event.test.ts` 与 `closed-loop` fixture;对齐 replay 命令测试。
## must_haves
- [x] 源码中不再有裸 `anon-tokyo` 引用
- [x] 八个内建函数均为类实现,名称稳定为 `setBlock/moveBlock/deleteBlock/moveHero/moveHeroStep/touchFront/insertEvents/insertEvent`
- [x] 八个内建函数均为类实现,名称为 `setBlock/moveBlock/deleteBlock/moveHero/moveHeroStep/touchFront/insertEvents/insertEvent`
- [x] `event/utils.ts` 存在且不被 `event/index.ts` 导出
- [x] `createEventRegistrations()` 为唯一注册入口,顺序稳定
- [x] 全量测试通过,type 门禁 0 in-scope 诊断
@@ -18,6 +18,7 @@ key-files:
- packages-user/data-state/src/event/event.test.ts
- packages-user/data-state/src/core.ts
- packages-user/data-state/test/fixtures/closed-loop.ts
- packages-user/data-state/src/replay/commands.test.ts
- packages-user/data-common/src/event/{types,event}.ts
- packages-user/data-common/src/store/eventStore.test.ts
- packages-user/data-system/src/event/{types,system,executor,eventDispatch.test}.ts
@@ -36,16 +37,22 @@ commits:
## Performance
- **Completed:** 2026-09-13
- **Commits:** 2 (`a701aa6`, `f0fd2f5`)
- **Commits:** `a701aa6`、`f0fd2f5`
## Accomplishments
- 全部 `anon-tokyo` 引用改为 `@motajs/anon-tokyo`;`data-common` / `data-system` 声明 workspace 依赖,lockfile 同步。
- `map.ts` / `hero.ts` / `event.ts` 八个内建函数改为类式实现,`name` 采用短名,`func` 为类方法;不再有落单函数。
- 共享工具收敛到 `event/utils.ts`(`getPossibleMap` / `getPossibleLayer` / `getEventExecutor` / `enterEventInsert` / `exitEventInsert`),不经 `event/index.ts` 导出。
- 非公共功能性函数改为类私有方法(`EventTouchFront.collectInvocations`、`EventInsertEvents.collectInvocations`)。
- 全部 `anon-tokyo` 引用改为 `@motajs/anon-tokyo`;`data-common` / `data-system` 声明
workspace 依赖,lockfile 同步。
- `map.ts` / `hero.ts` / `event.ts` 八个内建函数改为类式实现,`name` 采用短名,`func`
为类方法;不再有落单函数。
- 共享工具收敛到 `event/utils.ts`(`getPossibleMap` / `getPossibleLayer` /
`getEventExecutor` / `enterEventInsert` / `exitEventInsert`),不经 `event/index.ts`
导出。
- 非公共功能性函数改为类私有方法(`EventTouchFront.collectInvocations`、
`EventInsertEvents.collectInvocations`)。
- 移动序列使用 `IObjectMover.push`,删除逐方法调用辅助。
- `registrations.ts` 仅保留 `createEventRegistrations()`,按地图/玩家/事件三类顺序写入八条,注释分隔。
- `registrations.ts` 仅保留 `createEventRegistrations()`,按地图/玩家/事件三类顺序写入
八条,注释分隔。
- 删除 `EventBuiltinName`;`core.ts` 改用 `createEventRegistrations()`。
## Files Created/Modified
@@ -55,11 +62,12 @@ commits:
- `packages-user/data-state/src/event/event.test.ts` — 按新类与注册函数重写
- `packages-user/data-state/src/core.ts` — 使用 `createEventRegistrations()`
- `packages-user/data-state/test/fixtures/closed-loop.ts` — 内建名改短名
- `packages-user/data-state/src/replay/commands.test.ts` — 对齐当前指令实现
- `packages-user/data-common`、`packages-user/data-system` — import 重命名 + 依赖声明
## Decisions Made
- 内建函数名改用短名(`setBlock` 等)并删除 `EventBuiltinName`(用户确认)。
- 内建函数名改用短名(`setBlock` 等)并删除 `EventBuiltinName`。
- anon-tokyo 内嵌为 workspace 包,全仓统一引用 `@motajs/anon-tokyo`。
- 注册不做分类包装,`createEventRegistrations()` 内按顺序直写八条。
- `utils.ts` 只放共享功能性函数,不经 index 导出。
@@ -68,10 +76,11 @@ commits:
### Auto-fixed Issues
**1. [Rule 3 - Blocking] 对齐 replay 命令测试的先行红点**
**1. [Rule 3 - Blocking] 更新 replay 命令测试**
- **Found during:** 验证阶段
- **Issue:** 用户上一提交 `46a38fa` 将 `ReplayCommandCode.AutoPathfindToPoint` 改名 `Teleport`、`registerReplayCommand` 改名复数、并简化 equip/unequip 逻辑,但未同步测试,导致 `commands.test.ts` 3 例失败。
- **Fix:** 按实现更新测试预期(Teleport 名称、registerReplayCommands、equip/unequip 只校验最终槽位、错误码 2007/2008)。
- **Issue:** `commands.test.ts` 与新指令实现(`Teleport` 命名、`registerReplayCommands`、
equip/unequip 结果校验)不一致,套件不绿。
- **Fix:** 更新测试预期以匹配当前实现。
- **Files modified:** `packages-user/data-state/src/replay/commands.test.ts`
- **Verification:** `vitest run` 19 files / 112 tests 全通过。
- **Committed in:** `f0fd2f5`
@@ -80,7 +89,8 @@ commits:
## Issues Encountered
- 两个 git 提交命令并发执行触发 `index.lock`,`commands.test.ts` 被并入 `f0fd2f5`;内容正确,仅提交信息未单列。工作树最终干净。
- 两个 git 命令并发触发 `index.lock`,`commands.test.ts` 被并入 `f0fd2f5`;内容正确,
仅提交信息未单列。工作树最终干净。
## Verification
@@ -88,11 +98,9 @@ commits:
- `vitest run`:19 files / 112 tests passed
- 改动文件 Prettier 通过、ESLint 退出码 0
## Follow-ups / 未决
## Follow-ups
- 根 `package.json` 仍保留外部依赖 `anon-tokyo@0.0.0-alpha.0`,现已无人引用,可移除。
- `packages-user/legacy-plugin-data/src/fallback.ts` 的 `'eventMoveHero'` 为 legacy 全局补丁名,留给 Phase 5。
- `03-REPLAY-CONTRACT.md` 等契约文档尚未同步为新的短名 / 单一注册设计。
- 契约文档已同步为当前设计:`03-EVENT-CONTRACT.md`、`03-REPLAY-CONTRACT.md`。
---