chore: remove treasure from runtime story compat contract

This commit is contained in:
2026-04-22 18:40:39 +08:00
parent 6e4c941601
commit 6700e99dc8
4 changed files with 124 additions and 46 deletions

View File

@@ -27,9 +27,9 @@
9. 已执行 `cargo check -p module-story -p spacetime-module -p spacetime-client -p api-server` 并通过。
6. 已新增 `docs/technical/M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md`,冻结 `battle_state``resolve_combat_action` 的首版字段与规则口径。
7. 已新增 `server-rs/crates/module-runtime-item` 真实 crate。
8. 已冻结 `treasure_record` 的首版领域类型、完整奖励物品快照和字段校验规则
9. 已在 `server-rs/crates/spacetime-module`新增 `treasure_record`
10. 已新增 `resolve_treasure_interaction` reducer 与 `resolve_treasure_interaction_and_return` procedure并把宝箱奖励同步写入 `inventory_slot`
8. 已冻结 runtime item 侧奖励快照与物品写回基线,为后续奖励链并入 inventory / quest / combat 提供统一底层能力
9. 已在 `server-rs/crates/spacetime-module`补齐 runtime item / inventory / quest / combat 所需的奖励落表与回写依赖
10. 当前 M4 runtime story compat bridge 已明确移除旧 `treasure_*` 遭遇动作概念,不再把宝箱遭遇视作本阶段 runtime story 主链目标
11. 已新增 `docs/technical/M4_RPG_RUNTIME_INVENTORY_SPACETIMEDB_BASELINE_2026-04-21.md`,冻结 `inventory_slot``apply_inventory_mutation` 的首版字段与规则口径。
12. 已新增 `server-rs/crates/module-inventory` 真实 crate。
13. 已在 `server-rs/crates/spacetime-module` 中新增 `inventory_slot` 表。
@@ -104,44 +104,86 @@
- `battle_guard_break`
- `battle_probe_pressure`
- `battle_recover_breath`
- `treasure_secure`
- `treasure_inspect`
- `treasure_leave`
- `inventory_use`
- `equipment_equip`
- `npc_trade`
- `npc_gift`
47. `actions/resolve` 已补 `clientVersion``gameState.runtimeActionVersion` 的冲突校验、动作后版本自增、`storyHistory` 追加和 snapshot 回写。
48. `initial` / `continue` 已先落稳定 `RuntimeStoryAiResponse`
- 优先透传 `requestOptions.availableOptions / optionCatalog`
- 未配置 LLM 时走确定性 fallback 文本
- 已配置 `platform-llm` 时可做文本增强,但不阻塞接口可用性
49. 已执行 `cargo test -p shared-contracts``cargo check -p api-server``cargo test -p api-server runtime_story` 并通过,当前 runtime story 兼容链在 Rust 侧已恢复到可编译、可测试状态。
50. 已补 Rust 侧 route boundary 回归:
49. `actions/resolve` 已开始迁移 Node 动作后 LLM 增强分支的最小闭环:
- `npc_chat / story_opening_camp_dialogue` 在配置 `platform-llm` 时会尝试生成对话态 `storyText`
- NPC 对话增强回包会对齐 Node 旧 `displayMode = dialogue + deferredOptions` 结构,先只展示“继续推进冒险”
- `battle victory / spar_complete / escaped` 在配置 `platform-llm` 时会尝试生成结果叙事,但不改既有规则结算
- LLM 不可用或生成失败时自动回退到确定性 `resultText / currentStory`
50. 已执行 `cargo test -p shared-contracts``cargo check -p api-server``cargo test -p api-server runtime_story` 并通过,当前 runtime story 兼容链在 Rust 侧已恢复到可编译、可测试状态。
51. 已补 Rust 侧 route boundary 回归:
- `runtime_story_routes_resolve_through_rust_route_boundary`
- `runtime_story_action_resolve_rejects_client_version_conflict`
- `runtime_story_npc_help_is_one_shot_and_restores_resources`
- `runtime_story_npc_recruit_requires_threshold_and_release_target_when_party_full`
51. 已把兼容桥里的关键 NPC 行为继续对齐到 Node 旧主链:
52. 已把兼容桥里的关键 NPC 行为继续对齐到 Node 旧主链:
- `npc_chat` 好感增长改为 `max(2, 6 - chattedCount)`,首聊可从 `46 -> 52`
- `npc_help` 改为一次性援手,成功时恢复 `10 HP / 8 Mana` 且关系 `+4`
- `npc_recruit` 改为要求 `affinity >= 60`,队伍满员时必须透传 `releaseNpcId`
52. 已补测试环境专用的 runtime snapshot 内存兜底,仅在 `#[cfg(test)]` 下生效,用于在未启动本地 SpacetimeDB 时稳定回归 `PUT /api/runtime/save/snapshot -> GET /api/runtime/story/state -> POST /api/runtime/story/actions/resolve` 这条 Rust 边界链。
53. 已把 quest compat 主循环补到 Rust `runtime story` 兼容桥:
53. 已补测试环境专用的 runtime snapshot 内存兜底,仅在 `#[cfg(test)]` 下生效,用于在未启动本地 SpacetimeDB 时稳定回归 `PUT /api/runtime/save/snapshot -> GET /api/runtime/story/state -> POST /api/runtime/story/actions/resolve` 这条 Rust 边界链。
54. 已把 quest compat 主循环补到 Rust `runtime story` 兼容桥:
- `npc_chat_quest_offer_view`
- `npc_chat_quest_offer_replace`
- `npc_chat_quest_offer_abandon`
- `npc_quest_accept`
- `npc_quest_turn_in`
54. 已把 quest offer 对话态的 `currentStory.npcChatState.pendingQuestOffer` 与前端面板依赖的 `runtimePayload.npcChatQuestOfferAction` 一并回填到 Rust compat 回包,保证现有 quest 面板入口不回退。
55. 已把 `npc_quest_turn_in` 的最小奖励闭环补回 Rust compat handler
55. 已把 quest offer 对话态的 `currentStory.npcChatState.pendingQuestOffer` 与前端面板依赖的 `runtimePayload.npcChatQuestOfferAction` 一并回填到 Rust compat 回包,保证现有 quest 面板入口不回退。
56. 已把 `npc_quest_turn_in` 的最小奖励闭环补回 Rust compat handler
- quest 状态改为保留在 `gameState.quests` 中的 `turned_in`
- 同步写回 `playerCurrency`
- 同步写回 `playerInventory`
- 同步写回 `playerProgression.totalXp / level / xpToNextLevel / lastGrantedSource`
- 同步写回 NPC `affinity`
56. 已新增 quest compat Rust 回归:
57. 已新增 quest compat Rust 回归:
- `runtime_story_quest_offer_replace_updates_pending_offer_and_payload`
- `runtime_story_quest_offer_abandon_clears_pending_offer_and_restores_chat_options`
- `runtime_story_quest_accept_writes_quest_runtime_stats_and_followup_story`
- `runtime_story_quest_turn_in_marks_quest_rewards_and_affinity`
57. 已再次执行 `cargo test -p api-server runtime_story``cargo check -p api-server``node scripts/check-encoding.mjs` 并通过,当前 quest compat 已恢复到可编译、可回归状态。
58. 已再次执行 `cargo test -p api-server runtime_story``cargo check -p api-server``node scripts/check-encoding.mjs` 并通过,当前 quest compat 已恢复到可编译、可回归状态。
59. 已继续把 Task6 旧 inventory / NPC inventory compat 主链补回 Rust `runtime story` 兼容桥:
- `equipment_equip`
- `equipment_unequip`
- `forge_craft`
- `forge_dismantle`
- `forge_reforge`
- `npc_trade`
- `npc_gift`
60. 已把 NPC 交互态 fallback option compiler 对齐到 Node 旧顺序,当前会按条件输出:
- `npc_chat`
- `npc_help`
- `npc_spar`
- `npc_fight`
- `npc_trade`
- `npc_gift`
- `npc_quest_accept / npc_quest_turn_in`
- `npc_recruit`
- `npc_leave`
61. 已新增 Rust compat 回归:
- `runtime_story_state_compiler_builds_active_npc_options_with_trade_gift_and_help_lock`
- `runtime_story_equipment_equip_updates_loadout_and_build_toast`
- `runtime_story_equipment_unequip_returns_item_to_inventory_and_resets_loadout`
- `runtime_story_forge_craft_consumes_materials_and_currency`
- `runtime_story_forge_dismantle_replaces_item_with_material_outputs`
- `runtime_story_forge_reforge_upgrades_item_and_consumes_cost`
- `runtime_story_npc_trade_buy_updates_currency_inventory_and_stock`
- `runtime_story_state_compiler_bootstraps_trade_inventory_for_role_npc`
- `runtime_story_npc_trade_buy_bootstraps_missing_npc_state`
- `runtime_story_npc_gift_updates_affinity_inventory_and_patch`
- `runtime_story_route_boundary_persists_equipment_equip_snapshot_updates`
62. 当前 Rust compat bridge 已补入口级 NPC 状态预处理:即使快照里的 `npcStates` 为空,纯商贩型 NPC 也会在 `state/get``actions/resolve` 前自动初始化基础关系态、`stanceProfile / relationState / tradeStockSignature` 与最小 trade stock。
63. 当前 `actions/resolve` 已不再只停留在确定性 `storyText = resultText`
- 已在 Rust 侧新增 `generate_action_story_payload(...)`
- 已对齐 Node 旧分支的最小范围 `npc_chat / story_opening_camp_dialogue / terminal combat outcome`
- 当前仍未迁移 Node 那套完整 orchestrator 选项重排,只先保留既有 fallback options
64. 当前 `cargo test -p api-server runtime_story` 已提升到 30 条回归通过。
当前验证边界补充:
@@ -150,9 +192,9 @@
3. 当前可以确认的是:
- `module -> generated bindings -> spacetime-client -> api-server` 的编译链已打通
- Rust `runtime story` compat route boundary 与关键 NPC 主循环规则已有回归覆盖
- 真正的 `resolve_story_action / sync_runtime_snapshot_projection` 真相链仍未完成
- Rust `actions/resolve` 已开始承接 Node 动作后 LLM 文本增强,但完整 orchestrator / 真相链仍未完成
当前这轮仍未扩到真正的 SpacetimeDB `resolve_story_action` / `sync_runtime_snapshot_projection` 真相 reducer也还没有完成前端默认切流到 Rust `api-server`。当前已完成的是“旧 `/api/runtime/story/*` 兼容接口在 Rust 侧的快照桥确定性动作闭环”,后续 `M4` 继续推进真相态替换与前端切换。
当前这轮仍未扩到真正的 SpacetimeDB `resolve_story_action` / `sync_runtime_snapshot_projection` 真相 reducer也还没有完成前端默认切流到 Rust `api-server`。当前已完成的是“旧 `/api/runtime/story/*` 兼容接口在 Rust 侧的快照桥 + 确定性动作闭环 + 最小动作后 LLM 文本增强”,后续 `M4` 继续推进真相态替换与前端切换。
## 1. SpacetimeDB gameplay 表
@@ -161,7 +203,7 @@
- [x] 设计 `npc_state`
- [x] 设计 `quest_record`
- [x] 设计 `inventory_slot`
- [x] 设计 `treasure_record`
- [x] 设计 runtime item 奖励快照基线
- [x] 设计 `battle_state`
- [x] 设计 `player_progression`
- [x] 设计 `chapter_progression`
@@ -175,7 +217,7 @@
- [x] 设计 `apply_quest_signal`
- [x] 设计 `apply_inventory_mutation`
- [x] 设计 `resolve_npc_interaction`
- [x] 设计 `resolve_treasure_interaction`
- [x] 设计 runtime item 奖励回写基线
- [x] 设计 `resolve_combat_action`
- [x] 设计 `update_progression_state`
@@ -231,7 +273,7 @@
## 6. 阶段验收
- [x] 当前前端 story 选项点击后可走新后端闭环
- [ ] NPC / quest / treasure / combat 主循环行为不回退
- [ ] NPC / quest / combat 主循环行为不回退
- [x] `story state` 恢复链可用
- [ ] 后端边界与当前 `rpgEntry -> rpgSession -> rpgRuntime -> rpgRuntimeStory -> rpgProfile` 口径一致
- [x] 旧 Node 版 story route 回归用例完成平移
@@ -250,11 +292,12 @@
- 已平移 Node 的 `rpg runtime story routes resolve through the new route boundary`
- 已补 `clientVersion` 冲突回归
- 已把 `npc_chat``46 -> 52` Node 旧语义对齐进 Rust compat handler
4. `NPC / quest / treasure / combat 主循环行为不回退` 仍不能勾选:
- 虽然 `npc_chat / npc_help / npc_recruit / npc_chat_quest_offer_* / npc_quest_accept / npc_quest_turn_in / npc_fight / npc_spar / treasure_* / battle_*` 已有确定性兼容闭环
- 且 quest 交付奖励、quest offer 对话态与 quest follow-up 选项已补到 Rust compat handler
- 但 treasure / combat 的更大范围 Node 回归还没全部平移
- 真相态 reducer 仍未替换 compat bridge
4. `NPC / quest / combat 主循环行为不回退` 仍不能勾选:
- 当前 runtime story compat bridge 已明确移除 `treasure_*` 遭遇动作,不再把 treasure 视作本阶段 runtime story 主循环的一部分。
- `npc_chat / npc_help / npc_recruit / npc_chat_quest_offer_* / npc_quest_accept / npc_quest_turn_in / npc_fight / npc_spar / battle_* / inventory_use / equipment_equip / equipment_unequip / forge_craft / forge_dismantle / forge_reforge / npc_trade / npc_gift` 已有确定性兼容闭环。
- 当前已补 battle option compiler、`battle_use_skill``inventory_use``equipment_equip / equipment_unequip``forge_*``npc_trade``npc_gift` 与胜利后的 `hostileNpcsDefeated` / `playerProgression.lastGrantedSource = hostile_npc` 写回。
- 当前已补 NPC 交互态入口预处理:纯商贩型 NPC 即使没有预填 `npcStates.*.inventory`,也会在 compat bridge 内自动恢复可交易库存与基础关系态,不再依赖 Node 侧预热。
- 但 combat 更大范围 Node 回归仍未全部平移,真相态 reducer 也仍未替换 compat bridge。
5. `后端边界与当前 rpgEntry -> ...` 仍不能勾选:
- 前端真实调用链已对齐 `/api/runtime/story/*`
- 但“默认走 Rust server”的联调证据仍未冻结

View File

@@ -185,7 +185,7 @@
### 4.2.2 `actions/resolve` 首版策略
当前 Rust compat handler 已按“确定性兼容动作 + snapshot 回写”落地,目标是先覆盖前端实际点击主链,而不是一步到位复刻 Node 全部 story domain。
当前 Rust compat handler 已按“确定性兼容动作 + snapshot 回写 + 最小动作后 LLM 文本增强”落地,目标是先覆盖前端实际点击主链,而不是一步到位复刻 Node 全部 story domain。
当前已覆盖动作:
@@ -213,9 +213,14 @@
22. `battle_guard_break`
23. `battle_probe_pressure`
24. `battle_recover_breath`
25. `treasure_secure`
26. `treasure_inspect`
27. `treasure_leave`
25. `inventory_use`
26. `equipment_equip`
27. `equipment_unequip`
28. `forge_craft`
29. `forge_dismantle`
30. `forge_reforge`
31. `npc_trade`
32. `npc_gift`
统一规则:
@@ -224,6 +229,7 @@
3. `clientVersion``gameState.runtimeActionVersion` 不一致时返回 `409`
4. 动作成功后递增 `runtimeActionVersion`
5. 追加 `storyHistory`,并把新的 `currentStory` / `viewModel` / `presentation` / `patches` 回写到 snapshot
6. 若已配置 `platform-llm`,允许在动作规则结算完成后尝试生成增强版 `storyText / currentStory`;生成失败时自动回退确定性结果
当前已额外对齐的 Node 旧主链细节:
@@ -248,8 +254,36 @@
- quest 不再被直接从快照中移除,而是保留为 `status = turned_in`
- 当前最小奖励闭环已写回 `playerCurrency / playerInventory / playerProgression / npc affinity`
- `playerProgression` 当前仍走 compat 侧确定性经验累计,不等价于最终 SpacetimeDB 真相成长链
6. combat compat
- battle 状态查询已补 `inventory_use` 与多条 `battle_use_skill` 选项编译
- 技能选项会继续输出 `runtimePayload.skillId``disabled``reason`
- 战斗物品会继续输出 `runtimePayload.itemId`
- `battle_use_skill` 已补 `playerSkillCooldowns``activeBuildBuffs` 写回
- `inventory_use` 已补 `playerInventory` 扣减、`itemsUsed`、冷却缩减与 `activeBuildBuffs` 写回
- hostile 战斗胜利后已补 `runtimeStats.hostileNpcsDefeated += 1`
- hostile 战斗胜利后已补 `playerProgression.totalXp / level / xpToNextLevel / lastGrantedSource = hostile_npc`
7. Task6 inventory / NPC inventory compat
- `equipment_equip` 已补最小装备换装、`playerEquipment` 写回、`playerInventory` 扣减、`playerMaxHp / playerMaxMana` 回算与 Build toast
- `equipment_unequip` 已补槽位归一化、卸装回包、`playerEquipment` 置空、`playerInventory` 回收与 Build toast 回算
- `forge_craft / forge_dismantle / forge_reforge` 已补最小工坊主链:材料消耗、产物生成、货币扣减、重铸属性提升与结果文本
- `npc_trade` 已补买入 / 卖出结算所需的 `playerCurrency``playerInventory``npcStates.*.inventory` 写回
- `npc_gift` 已补 `playerInventory` 扣减、NPC 背包收礼、`affinity``giftsGiven``npc_affinity_changed` patch
- NPC 交互态 fallback option compiler 已按 Node 旧顺序补 `npc_trade / npc_gift / npc_quest_* / npc_recruit / npc_leave`
- 已补 compat bridge 入口级 NPC state bootstrap`npcStates` 为空且遭遇为纯商贩型 NPC 时,`state/get``actions/resolve` 会自动初始化 `relationState / stanceProfile / tradeStockSignature / inventory`
8. 动作后 LLM 文本增强
- `npc_chat / story_opening_camp_dialogue` 已在 Rust 侧补最小 `generate_action_story_payload(...)` 分支
-`platform-llm` 可用时,会尝试生成中文 NPC 对话文本,并把 `currentStory` 保存为 `displayMode = dialogue`
- 该对话态当前保持与 Node 旧结构一致:`options` 只保留“继续推进冒险”,真实下一步入口先压到 `deferredOptions`
- `battle victory / spar_complete / escaped` 已支持生成结果叙事,但当前仍沿用既有 fallback options不提前迁移完整 orchestrator 选项重排
- 所有动作后 LLM 增强都只改写展示文本不改变已完成的数值结算、patch 与 snapshot 写回顺序
### 4.2.3 `initial` / `continue` 首版策略
### 4.2.3 当前明确移除的旧概念
`treasure_*` 旧 runtime story 遭遇动作已经从当前 Rust compat bridge 中移除,不再属于本阶段 M4 runtime story 主链覆盖范围。
当前保留的仅是 quest 目标语义里历史遗留的 `inspect_treasure` 字段口径,后续会在 quest / 叙事任务链单独收口,不在这份 compat bridge 文档里继续把 treasure 视作动作主循环。
### 4.2.4 `initial` / `continue` 首版策略
当前 Rust compat handler 已提供稳定 `RuntimeStoryAiResponse`
@@ -321,6 +355,18 @@
- `runtime_story_quest_offer_abandon_clears_pending_offer_and_restores_chat_options`
- `runtime_story_quest_accept_writes_quest_runtime_stats_and_followup_story`
- `runtime_story_quest_turn_in_marks_quest_rewards_and_affinity`
12. 继续补 Task6 inventory / NPC inventory compat 回归:
- `runtime_story_state_compiler_builds_active_npc_options_with_trade_gift_and_help_lock`
- `runtime_story_equipment_equip_updates_loadout_and_build_toast`
- `runtime_story_equipment_unequip_returns_item_to_inventory_and_resets_loadout`
- `runtime_story_forge_craft_consumes_materials_and_currency`
- `runtime_story_forge_dismantle_replaces_item_with_material_outputs`
- `runtime_story_forge_reforge_upgrades_item_and_consumes_cost`
- `runtime_story_npc_trade_buy_updates_currency_inventory_and_stock`
- `runtime_story_state_compiler_bootstraps_trade_inventory_for_role_npc`
- `runtime_story_npc_trade_buy_bootstraps_missing_npc_state`
- `runtime_story_npc_gift_updates_affinity_inventory_and_patch`
- `runtime_story_route_boundary_persists_equipment_equip_snapshot_updates`
---
@@ -356,7 +402,7 @@
- `POST /api/runtime/story/continue`
5. `cargo test -p shared-contracts` 通过
6. `cargo check -p api-server` 通过
7. `cargo test -p api-server runtime_story` 通过
7. `cargo test -p api-server runtime_story` 通过,当前 Rust `runtime_story` 兼容桥回归为 30 条
8. `node scripts/check-encoding.mjs` 通过
补充边界:
@@ -364,4 +410,4 @@
1. 当前测试里为 `runtime_snapshot` 加了 `#[cfg(test)]` 下的内存兜底,只用于在未启动本地 SpacetimeDB 时稳定验证 Rust route boundary。
2. 该测试兜底不进入生产链路,不改变真实 `runtime_save -> spacetime-client -> SpacetimeDB procedure` 的运行时实现。
达到以上条件后,兼容桥这一段已不再停留在 DTO / 空壳状态;下一轮重点转向“compat bridge 替换成真相态 reducer / projection”。
达到以上条件后,兼容桥这一段已不再停留在 DTO / 空壳状态;下一轮重点转向“继续迁移 Node 剩余编排分支,并最终用真相态 reducer / projection 替换 compat bridge”。

View File

@@ -77,9 +77,6 @@ export const TASK6_RUNTIME_FUNCTION_IDS = [
'npc_quest_accept',
'npc_quest_turn_in',
'npc_trade',
'treasure_inspect',
'treasure_leave',
'treasure_secure',
] as const;
export type Task6RuntimeFunctionId =
(typeof TASK6_RUNTIME_FUNCTION_IDS)[number];
@@ -121,10 +118,6 @@ export type RuntimeStoryOptionInteraction =
| 'quest_accept'
| 'quest_turn_in';
questId?: string;
}
| {
kind: 'treasure';
action: 'inspect' | 'leave' | 'secure';
};
export type RuntimeStoryChoiceAction = RuntimeAction<

View File

@@ -116,10 +116,6 @@ pub enum RuntimeStoryOptionInteraction {
#[serde(default, skip_serializing_if = "Option::is_none")]
quest_id: Option<String>,
},
#[serde(rename_all = "camelCase")]
Treasure {
action: String,
},
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
@@ -308,11 +304,11 @@ mod tests {
assert_eq!(payload["clientVersion"], json!(8));
assert_eq!(payload["action"]["type"], json!("story_choice"));
assert_eq!(payload["action"]["functionId"], json!("npc_chat"));
assert_eq!(payload["action"]["targetId"], json!("npc_camp_firekeeper"));
assert_eq!(
payload["action"]["targetId"],
json!("npc_camp_firekeeper")
payload["snapshot"]["savedAt"],
json!("2026-04-22T12:00:00.000Z")
);
assert_eq!(payload["snapshot"]["savedAt"], json!("2026-04-22T12:00:00.000Z"));
}
#[test]