@@ -210,3 +210,23 @@ npm.cmd run build
|
||||
- 没有人手逐个点击整局游戏所有 function 的视觉回放，本轮重点是自动化测试、服务端测试、内容校验与 smoke 门禁。
|
||||
|
||||
因此，本审计可以说明“当前 function 系统的自动化测试层状况”，但不等于“所有视觉演出与在线模型联动都已人工验证完毕”。
|
||||
|
||||
## 8. 执行回填（2026-04-28，修复聊天任务领取入口）
|
||||
|
||||
- 问题现象：
|
||||
- NPC 聊天中的待领取任务，点击“查看任务”进入详情后，再点“领取任务”没有把面板切到正式已接任务状态，表现上像“无法领取”。
|
||||
- 根因：
|
||||
- `npcChatQuestOfferUi.acceptPendingOffer()` 会异步把 `npc_quest_accept` 发到服务端。
|
||||
- 但 [`src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`](../../src/components/rpg-runtime-panels/RpgAdventurePanel.tsx) 里“待领取任务详情弹层”的 `onAcceptPendingNpcQuestOffer` 只返回了 `questId`，没有把它写入共享的 `pendingAcceptedQuestId`。
|
||||
- 结果是本来负责等待 quest 真正进入 `quests` 后再统一收口面板状态的 `useEffect` 根本不会触发。
|
||||
- 修复：
|
||||
- 在 `onAcceptPendingNpcQuestOffer` 中补写 `setPendingAcceptedQuestId(acceptedQuestId)`，让待领取任务详情弹层复用普通 `npc_quest_accept` 已有的异步收口链。
|
||||
- 新增 [`src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx`](../../src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx)，覆盖“查看任务 -> 领取任务 -> 服务端异步写回 quest log -> 面板切到正式任务状态”的回归路径。
|
||||
- 本次回归验证：
|
||||
- `src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx`
|
||||
- `src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx`
|
||||
- `src/hooks/rpg-runtime-story/npcEncounterActions.test.ts`
|
||||
- `src/hooks/rpg-runtime-story/choiceActions.test.ts`
|
||||
- `src/hooks/rpg-runtime-story/runtimeStoryCoordinator.test.ts`
|
||||
- `src/hooks/rpg-runtime-story/sessionActions.test.ts`
|
||||
- 共 `57` 条测试通过。
|
||||
|
||||
48
docs/audits/RPG_REVIVE_CONTINUE_FLOW_FIX_2026-04-28.md
Normal file
48
docs/audits/RPG_REVIVE_CONTINUE_FLOW_FIX_2026-04-28.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# RPG 复活后继续冒险链路修复记录 2026-04-28
|
||||
|
||||
## 问题现象
|
||||
|
||||
RPG 运行态里，角色在战斗死亡并复活后，面板会显示一个“继续前进”入口。
|
||||
|
||||
此前这一步只有 `story_continue_adventure` 控制项，没有同步挂出复活后首场景应该展示的 `deferredOptions`。因此玩家点击继续后，系统会把它当作一次普通剧情续推入口，而不是单纯展示“复活后的下一批可选动作”。
|
||||
|
||||
在带有场景章节主 NPC 的自定义世界里，这会让玩家看起来像是“刚复活就直接和对面主 NPC 聊天”，造成复活后第一拍体验被主 NPC 对话链抢走。
|
||||
|
||||
## 根因结论
|
||||
|
||||
根因不在 NPC 聊天函数本身，而在死亡复活链没有沿用 `story_continue_adventure -> deferredOptions` 的延迟展示协议。
|
||||
|
||||
- 战后胜利链已经使用 `story_continue_adventure + deferredOptions`
|
||||
- 死亡复活链此前只保留了 `story_continue_adventure`
|
||||
- 结果是“继续前进”点击后无法走纯展示分支，只能落回普通续推
|
||||
|
||||
## 本次修复
|
||||
|
||||
本次在 `src/hooks/rpg-runtime-story/postBattleFlow.ts` 与复活调用链中补齐：
|
||||
|
||||
- `buildDeathStory(...)` 现在支持在复活文案上同步挂出 `deferredOptions`
|
||||
- 这些 `deferredOptions` 复用 `buildFallbackStoryForState(...)` 产出的复活后可用入口
|
||||
- 点击“继续前进”时只揭示这些入口，不再额外触发一次普通剧情推演
|
||||
|
||||
## 当前行为规则
|
||||
|
||||
角色死亡复活后：
|
||||
|
||||
1. 先显示“你在战斗中倒下，随后重新醒来”
|
||||
2. 面板只展示一个 `story_continue_adventure`
|
||||
3. 点击后展示复活后首场景已有的后续动作
|
||||
4. 不应直接自动推进到主 NPC 聊天执行态
|
||||
|
||||
## 回归覆盖
|
||||
|
||||
已补两条测试：
|
||||
|
||||
- `src/hooks/rpg-runtime-story/choiceActions.test.ts`
|
||||
- 覆盖本地战斗失败后的复活链
|
||||
- `src/hooks/rpg-runtime-story/storyChoiceRuntime.test.ts`
|
||||
- 覆盖服务端战斗失败后的复活链
|
||||
|
||||
两条测试都要求复活文案返回：
|
||||
|
||||
- `story_continue_adventure`
|
||||
- 非空 `deferredOptions`
|
||||
65
docs/experience/BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md
Normal file
65
docs/experience/BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 大鱼作品列表 `items_json` 兼容修复 2026-04-28
|
||||
|
||||
## 背景
|
||||
|
||||
大鱼吃小鱼作品列表在 `server-rs` 链路里由 SpacetimeDB procedure 返回 `items_json`，再由 `spacetime-client` 反序列化成 `BigFishWorkSummaryRecord`。
|
||||
|
||||
本轮出现的线上报错为：
|
||||
|
||||
```text
|
||||
big fish works items_json 非法: missing field `owner_user_id`
|
||||
```
|
||||
|
||||
这说明：
|
||||
|
||||
1. 客户端 record 结构已经把 `owner_user_id` 当成必填字段。
|
||||
2. 某些历史 `items_json` 仍是旧字段集，没有带上 `owner_user_id`。
|
||||
3. 一旦直接按新结构强反序列化，整个 works 列表接口都会失败，而不是只丢失单字段。
|
||||
|
||||
## 根因判断
|
||||
|
||||
这不是前端展示问题，也不是 Axum 路由参数问题，而是：
|
||||
|
||||
1. SpacetimeDB procedure 输出 JSON 的结构发生过升级。
|
||||
2. `spacetime-client` 映射层没有为旧 JSON 做向后兼容。
|
||||
3. 作品列表是聚合读模型，一条旧记录就可能拖垮整批列表读取。
|
||||
|
||||
## 本次落地口径
|
||||
|
||||
本次只做最小风险修复，不改前端契约，不改现有表结构：
|
||||
|
||||
1. `server-rs/crates/spacetime-client/src/mapper.rs`
|
||||
- 大鱼 works 反序列化改为先读兼容结构。
|
||||
- `owner_user_id` 改为兼容层里的可缺省字段。
|
||||
|
||||
2. 私有 works 列表
|
||||
- 若旧 JSON 缺 `owner_user_id`，用当前查询的 `owner_user_id` 回填。
|
||||
- 这样不会破坏创作中心里依赖 `ownerUserId` 的恢复、归属和 key 逻辑。
|
||||
|
||||
3. 公开 gallery 列表
|
||||
- 若旧 JSON 缺 `owner_user_id`，先回填空串，保证列表接口不再整体失败。
|
||||
- 后续若公开画廊明确需要作者归属真相，再补模块端回填或数据修复。
|
||||
|
||||
4. 新增定向测试
|
||||
- 覆盖“私有 works 旧 JSON 缺字段仍可回填”
|
||||
- 覆盖“公开 works 旧 JSON 缺字段不再报错”
|
||||
|
||||
## 经验结论
|
||||
|
||||
以后只要是 `procedure -> items_json -> client record` 这类链路，都要默认遵守下面两条：
|
||||
|
||||
1. 聚合读模型的 JSON 字段升级不能假设全量历史数据同步完成。
|
||||
2. `spacetime-client` 的映射层必须承担兼容旧 JSON 的责任，不能把结构升级风险直接抛给上层接口。
|
||||
|
||||
尤其是 works / gallery / library 这种平台入口级接口：
|
||||
|
||||
1. 允许单字段降级
|
||||
2. 不允许整批列表因单字段缺失而 500 / 400
|
||||
|
||||
## 后续建议
|
||||
|
||||
如果后面继续演进大鱼 works 字段，推荐优先遵守：
|
||||
|
||||
1. 新增字段优先 `Option` 或兼容层解析。
|
||||
2. 聚合 JSON 升级时同步补回归测试。
|
||||
3. 如果字段已经进入前端关键逻辑，再决定是在模块端回填、客户端兜底，还是补历史数据迁移。
|
||||
@@ -31,3 +31,4 @@
|
||||
- [RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md](./RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md)：记录 RPG 发布后首页 / 分类页公开作品列表刷新链路。
|
||||
- [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
|
||||
- [BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md](./BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md)：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
|
||||
- [BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md](./BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md)：记录大鱼作品列表 `items_json` 字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# 拼图结果页自动保存与标签发布门槛修复
|
||||
|
||||
## 背景
|
||||
|
||||
拼图结果页此前存在两个串联问题：
|
||||
|
||||
1. 创作者在结果页修改 `关卡名`、新增标签、删除标签，只会改前端本地 `editState`，不会立即写回拼图作品 profile。
|
||||
2. 发布弹窗同时混用了旧 session 内的 `publishReady` 与前端本地编辑态，导致标签已经在界面里补够，但发布校验仍然盯着旧草稿里的标签数量，用户无法通过发布检验。
|
||||
|
||||
这会直接破坏拼图创作主链的可用性：用户明明已经在结果页补齐正式标签，却因为没有自动保存、也没有按当前编辑态重算门槛而卡在发布前。
|
||||
|
||||
## 修复目标
|
||||
|
||||
1. 拼图结果页中的 `关卡名`、`添加标签`、`删除标签` 统一接入自动保存。
|
||||
2. 自动保存复用现有 `PUT /api/runtime/puzzle/works/:profileId`，不新增新系统。
|
||||
3. 前端发布门槛与后端 `module-puzzle` 规则显式对齐，统一采用 `3~6` 个正式标签。
|
||||
4. 发布弹窗要基于“当前可编辑态”判断是否通过，不再被旧 session 中可由本地编辑修复的 blocker 卡死。
|
||||
|
||||
## 实现口径
|
||||
|
||||
### 1. 结果页自动保存
|
||||
|
||||
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
- 为拼图结果页显式透传稳定 `profileId`。
|
||||
- 草稿结果页默认按 `puzzle-session-* -> puzzle-profile-*` 规则推导 profileId；已发布作品优先复用 `publishedProfileId`。
|
||||
|
||||
- `src/components/puzzle-result/PuzzleResultView.tsx`
|
||||
- 当 `levelName / summary / themeTags` 相对当前 `draft` 发生变化时，触发防抖自动保存。
|
||||
- 自动保存复用 `updatePuzzleWork(...)`，同步写回：
|
||||
- `levelName`
|
||||
- `summary`
|
||||
- `themeTags`
|
||||
- 当前正式图 `coverImageSrc / coverAssetId`
|
||||
- 顶部只展示轻量保存状态角标：`保存中 / 已自动保存 / 保存失败`。
|
||||
|
||||
### 2. 发布门槛统一
|
||||
|
||||
- 前端结果页发布判定不再使用“至少 1 个标签”的旧口径。
|
||||
- 统一改为和后端 `module-puzzle` 一致的规则：正式标签数量必须在 `3 到 6` 之间。
|
||||
|
||||
### 3. 结果页 blocker 重算策略
|
||||
|
||||
`session.resultPreview.blockers` 中与可编辑字段直接相关的 blocker：
|
||||
|
||||
- `MISSING_LEVEL_NAME`
|
||||
- `INVALID_TAG_COUNT`
|
||||
- `MISSING_COVER_IMAGE`
|
||||
|
||||
这些项不再原样阻断前端发布按钮，而是改由结果页基于当前 `editState + formalImageSrc` 重新计算。
|
||||
其余后端 blocker 仍继续保留，避免前端绕过真正不可编辑的发布门禁。
|
||||
|
||||
## 验收点
|
||||
|
||||
1. 修改拼图关卡名后，不点发布也会自动写回作品 profile。
|
||||
2. 添加标签、删除标签后，不点发布也会自动写回作品 profile。
|
||||
3. 标签少于 `3` 个时，发布弹窗明确提示“正式标签数量必须在 3 到 6 之间”。
|
||||
4. 标签补到 `3~6` 个后，无需刷新页面即可通过前端发布校验。
|
||||
5. 结果页顶部能看到轻量自动保存状态，不额外堆叠说明文案。
|
||||
@@ -4,6 +4,7 @@
|
||||
|
||||
## 文档列表
|
||||
|
||||
- [PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md](./PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md)：记录拼图结果页名称与标签编辑自动保存、发布门槛统一到 `3~6` 标签，以及前端发布校验不再被旧 session blocker 卡死的修复口径。
|
||||
- [SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md](./SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md)：记录发布包 `start.sh` 只输出“SpacetimeDB 进程在就绪前退出”时的诊断补强，启动失败或超时时自动回显 `logs/spacetimedb.log`、`server ping`、端口监听和 root-dir 相关进程。
|
||||
- [RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md](./RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md)：记录 RPG 运行时 NPC 聊天、RPG/自定义世界 Agent 与大鱼 Agent 从“拼完整 SSE 字符串后一次性返回”改为 `mpsc + Sse<Event>` 真流式输出的后端落地口径。
|
||||
- [SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md](./SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md)：记录发布包 `start.sh` root-dir 占用检测把 `grep -F .../.spacetimedb` 误判为 SpacetimeDB 实例的根因、脚本修复和现场处理方式。
|
||||
|
||||
@@ -96,6 +96,9 @@
|
||||
4. 前端 `storyChoiceContinuation` / `useRpgRuntimeNpcInteraction`：
|
||||
- `fight_defeat` 不能再被当成“本地 NPC 战斗胜利”进入战后收束
|
||||
- 玩家死亡后必须直接走死亡复活链，且复活时重置到开局场景第一幕，不能先推进下一幕
|
||||
5. 前端 `postBattleFlow`：
|
||||
- 复活回到开局场景时，必须重新走首幕 encounter preview 恢复链
|
||||
- 第一幕主交互 NPC 与同幕陪衬 NPC 要继续沿用既有场景槽位，不能退化成全部站成一排
|
||||
|
||||
## 继续收口（2026-04-28）
|
||||
|
||||
@@ -118,6 +121,24 @@
|
||||
- 非 NPC 通用敌对战斗 `!inBattle`
|
||||
5. 这样可以保证作品测试、幕预览与正式游戏在“死亡后回开局第一幕”这一口径上继续对齐
|
||||
|
||||
## 继续收口：复活后首幕 NPC 与站位恢复（2026-04-28）
|
||||
|
||||
在继续复测后，又确认死亡复活链还有一层表现问题：
|
||||
|
||||
1. 角色虽然已经回到开局场景第一幕；
|
||||
2. 但复活态旧实现只是重置 `currentSceneActState`，没有重新恢复第一幕 encounter preview；
|
||||
3. 于是画布只能把第一幕 NPC 都按普通 ambient 角色绘制；
|
||||
4. 视觉上就会表现为：
|
||||
- 主交互 NPC 没有按首幕重新成为前景目标
|
||||
- 同幕 NPC 失去原本的前后排关系
|
||||
- 最终看起来像“所有人站成一排”
|
||||
|
||||
本轮补充修正如下：
|
||||
|
||||
1. `buildRevivedFirstSceneState(...)` 在重置到首幕之后，立即复用 `ensureSceneEncounterPreview(...)`
|
||||
2. 这样复活链与“开局进入世界 / 场景正常进场”继续共用同一套首幕恢复逻辑
|
||||
3. 第一幕主交互 NPC、同幕陪衬 NPC 与既有槽位会一起恢复，不再额外发明一套复活专用站位规则
|
||||
|
||||
## 结论
|
||||
|
||||
本次修复后，RPG 战斗 compat 主链的胜负判定口径变为：
|
||||
|
||||
@@ -200,3 +200,47 @@
|
||||
|
||||
1. 自定义世界角色型敌人在战斗态不会再重复叠加场景立绘下沉偏移；
|
||||
2. 相关战斗编队、runtime gateway 与 battle plan 既有回归继续通过。
|
||||
|
||||
## 9. 本轮继续修正：战斗结束后和平态站位被战斗坐标污染
|
||||
|
||||
在前面解决“开战瞬间跳位”后，用户继续反馈战斗结束时敌对角色站位仍会被改掉。继续顺着 NPC 战斗收尾链核对后，确认这次的问题不在画布层，而在“战后恢复使用了哪一份 encounter 真相”。
|
||||
|
||||
### 9.1 根因梳理
|
||||
|
||||
此前 `fight_victory` 收尾时，恢复 `currentEncounter` 的优先级仍可能落到：
|
||||
|
||||
1. 战斗中的 `currentEncounter`
|
||||
2. `activeBattleHostiles[0]?.encounter`
|
||||
|
||||
这两份 encounter 都已经是战斗态里被压到前排中心位后的数据，`xMeters` 往往已经变成 `3.2`。因此即使战前和平态 NPC 原本站在更靠后的场景位置，战斗结束后也会被错误恢复到战斗中心位，表现为“打完架后角色站位被改掉”。
|
||||
|
||||
### 9.2 本次收口
|
||||
|
||||
这次修正把“战前原始 encounter 保存”和“战后 encounter 恢复”两端一起收口：
|
||||
|
||||
1. `sceneEncounterPreviews.ts`
|
||||
- NPC 自动开战时立即保存战前原始 encounter
|
||||
- 复用现有 `sparReturnEncounter` 存槽，避免新增一套并行状态
|
||||
2. `rpgRuntimeStoryGateway.ts`
|
||||
- 若服务端战斗快照未带回 `sparReturnEncounter`
|
||||
- 网关自动沿用进入战斗前的原始 NPC encounter 回填
|
||||
3. `useRpgRuntimeNpcInteraction.ts`
|
||||
- `fight_victory` 恢复和平态时，优先使用保存下来的战前 encounter
|
||||
- 只在缺失时才退回到 battle encounter / fallback encounter
|
||||
|
||||
### 9.3 效果
|
||||
|
||||
这样处理后：
|
||||
|
||||
1. 战斗结束后恢复到场景中的 NPC，会回到战前那份 encounter 对应的位置；
|
||||
2. 不会再把战斗前排中心位误带回和平态；
|
||||
3. `fight` 与 `spar` 两条 NPC 战斗收尾链恢复口径保持一致；
|
||||
4. 作品测试、幕预览与正式运行的战后站位表现继续对齐。
|
||||
|
||||
### 9.4 验证
|
||||
|
||||
本轮新增并通过了以下回归验证：
|
||||
|
||||
1. 负好感 NPC 自动开战后会保存战前 encounter；
|
||||
2. `npc_fight` 服务端空战场快照桥接后会保留战前 encounter；
|
||||
3. `fight_victory` 收尾时会恢复战前 encounter，而不是战斗态 encounter。
|
||||
|
||||
Reference in New Issue
Block a user