Genarrative/docs/technical/M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md

M4 Runtime Item Treasure SpacetimeDB 基座记录（2026-04-21）

更新时间：2026-04-21

0. 文档目标

本文件只记录一件事：

把 module-runtime-item 从“只有 README 占位”推进到“SpacetimeDB 侧已有 treasure_record 真相表、resolve_treasure_interaction reducer/procedure，以及可桥接 inventory_slot 的奖励 contract”的真实落地结果。

本轮目标不是一次性迁完 Node 版所有 runtime item 玩法，而是先把宝藏奖励记录、奖励字段口径与后续背包接入边界固定下来。

---

1. 本轮落地范围

本轮只落实下面 5 件事：

1. 新增 server-rs/crates/module-runtime-item/ 真实 crate，而不是继续停留在 README 占位。
2. 在 module-runtime-item 中冻结 TreasureResolveInput / TreasureRecordSnapshot / RuntimeItemRewardItemSnapshot 的首版领域类型与校验 helper。
3. 在 server-rs/crates/spacetime-module/ 中新增 treasure_record 表。
4. 在 spacetime-module 中新增 resolve_treasure_interaction reducer 与 resolve_treasure_interaction_and_return procedure。
5. 把宝藏奖励物品字段扩到可无损映射 inventory_slot 的粒度，并在聚合层接通宝藏奖励到背包真相表的最小发物链。

---

2. 当前冻结的数据口径

2.1 treasure_record

当前首版字段冻结为：

1. treasure_record_id
2. runtime_session_id
3. story_session_id
4. actor_user_id
5. encounter_id
6. encounter_name
7. scene_id
8. scene_name
9. action
10. reward_items
11. reward_hp
12. reward_mana
13. reward_currency
14. story_hint
15. created_at
16. updated_at

当前策略：

1. treasure_record 保持 private 真相表口径。
2. Inspect / Secure / Leave 都会留下正式记录，避免宝藏交互继续散落在 runtime snapshot 大 JSON 或 story 文本里。
3. Leave 允许不发物；Inspect / Secure 的奖励字段当前已经通过聚合层同步写入 inventory_slot。
4. 同一 treasure_record_id 重放时直接返回既有记录，不重复执行发物，保证宝藏奖励幂等。

2.2 RuntimeItemRewardItemSnapshot

当前奖励物品字段冻结为：

1. item_id
2. category
3. item_name
4. description
5. quantity
6. rarity
7. tags
8. stackable
9. stack_key
10. equipment_slot_id

当前策略：

1. 奖励物品不再只保留 item_id + item_name + quantity 的轻量占位结构。
2. 当前字段已经与 inventory_slot 的首版真相字段对齐到可桥接程度，避免后续发物时再回头猜品类、堆叠策略和装备位。
3. build_inventory_item_snapshot_from_reward_item(...) 负责把宝藏奖励快照稳定映射为 module-inventory::InventoryItemSnapshot。

---

3. 当前 reducer / procedure 口径

3.1 resolve_treasure_interaction

当前负责：

1. 校验 TreasureResolveInput
2. 校验 story_session_id / runtime_session_id / actor_user_id 作用域一致
3. 同一 treasure_record_id 重放时直接返回已落库快照
4. 初次落库时写入 treasure_record
5. 初次落库后把 reward_items 同步发放到 inventory_slot

3.2 resolve_treasure_interaction_and_return

当前负责：

1. 复用同一套 treasure_record upsert 规则
2. 返回最终 TreasureRecordSnapshot
3. 避免 Axum facade 再额外读取 private table

---

4. 当前刻意未做

本轮明确没有扩到以下范围：

1. 还没有把 reward_hp / reward_mana / reward_currency 接到运行时资源真相表
2. 还没有把 runtime item director 的完整物品导演链迁到 Rust
3. 还没有新增 Axum 的 runtime treasure facade
4. 还没有把前端 treasureInteractions.ts 主链切到 server-rs

也就是说，本轮只是把宝藏结算真相表和奖励 contract 立起来，不宣称已经完成完整宝藏奖励迁移。

---

5. 本轮新增的真实工程落点

5.1 新增 crate

1. server-rs/crates/module-runtime-item/Cargo.toml
2. server-rs/crates/module-runtime-item/src/lib.rs

5.2 workspace 与主工程聚合

1. server-rs/Cargo.toml
   • 已把 crates/module-runtime-item 纳入 workspace members
2. server-rs/crates/spacetime-module/Cargo.toml
   • 已接入 module-runtime-item 依赖
3. server-rs/crates/spacetime-module/src/lib.rs
   • 已接入 module-runtime-item 类型
   • 已新增 treasure_record
   • 已新增 resolve_treasure_interaction
   • 已新增 resolve_treasure_interaction_and_return

---

6. 下一步建议

按当前节奏，后续应继续按下面顺序推进：

1. 先把 treasure / quest / battle 的奖励发物 helper 继续收敛，减少 spacetime-module 聚合层的重复映射代码。
2. 再补 runtime 资源恢复、货币与 story projection 的跨域聚合写入。
3. 最后再接 Axum facade 与前端真实 treasure 主链切换。