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

M4 Module Progression SpacetimeDB 基座记录（2026-04-21）

更新时间：2026-04-21

0. 文档目标

本文件只记录一件事：

把 module-progression 从“只有 README 占位”推进到“SpacetimeDB 侧已有最小可编译成长真相基座”的真实落地结果。

本轮先落等级/经验/章节计划与记账的最小领域骨架，并补上任务交付与战斗胜利的自动联动；不扩到完整 custom-world 章节蓝图编译或 Axum facade 全链迁移。

---

1. 本轮落地范围

本轮按 LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md 与 SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md 的交叉口径，只落实下面 6 件事：

1. 新增 server-rs/crates/module-progression/ 真实 crate，而不是继续停留在 README 占位。
2. 在 module-progression 中冻结 LevelBenchmark、PlayerProgressionSnapshot、ChapterProgressionSnapshot、RuntimeEntityLevelProfile 的首版领域类型。
3. 在 module-progression 中落地与当前 Node 版一致的等级经验曲线、参考强度曲线、章节 pseudo level 曲线与敌对战斗 fallback 规则。
4. 在 server-rs/crates/spacetime-module/ 中新增 player_progression、chapter_progression 两张表。
5. 在 spacetime-module 中新增 get_player_progression_or_default、grant_player_progression_experience、upsert_chapter_progression、apply_chapter_progression_ledger_entry 及对应 procedure。
6. 用 module-story / module-quest 同口径方式，把成长状态固定成“单用户成长表 + 单章节计划/记账表”的最小可编译基座。

---

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

2.1 新增 crate

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

2.2 workspace 与主工程聚合

1. server-rs/Cargo.toml
   • 已把 crates/module-progression 纳入 workspace members
2. server-rs/crates/spacetime-module/Cargo.toml
   • 已接入 module-progression 依赖
3. server-rs/crates/spacetime-module/src/lib.rs
   • 已接入 module-progression 类型
   • 已新增 player_progression
   • 已新增 chapter_progression
   • 已新增成长相关 reducer / procedure

---

3. 当前冻结的数据口径

3.1 player_progression

当前首版字段冻结为：

1. user_id
2. level
3. current_level_xp
4. total_xp
5. xp_to_next_level
6. pending_level_ups
7. last_granted_source
8. created_at
9. updated_at

当前策略：

1. player_progression 保持 private 真相表口径。
2. 当前统一按 user_id 单行持久化，不在本轮拆历史 grant 日志表。
3. 若记录不存在，procedure 返回 Lv.1 / 0 XP 默认快照，但不额外写库。

3.2 chapter_progression

当前首版字段冻结为：

1. chapter_progression_id
2. user_id
3. chapter_id
4. chapter_index
5. total_chapters
6. entry_pseudo_level_millis
7. exit_pseudo_level_millis
8. entry_level
9. exit_level
10. planned_total_xp
11. planned_quest_xp
12. planned_hostile_xp
13. actual_quest_xp
14. actual_hostile_xp
15. expected_hostile_defeat_count
16. actual_hostile_defeat_count
17. level_at_entry
18. level_at_exit
19. pace_band
20. created_at
21. updated_at

当前策略：

1. chapter_progression 先用一张表同时承接 ChapterProgressionPlan 与 ChapterExperienceLedger。
2. 当前不再额外拆计划表和记账表，避免首轮 schema 还没稳定就二次改表。
3. 主键固定为 user_id + chapter_id 组合衍生 ID，保证同一玩家每章只有一条真相记录。

---

4. 当前 reducer / procedure 口径

4.1 get_player_progression_or_default

当前负责：

1. 按 user_id 读取 player_progression
2. 若不存在则返回默认 Lv.1 / 0 XP
3. 不产生额外写入

4.2 grant_player_progression_experience

当前负责：

1. 读取当前 player_progression，不存在则按默认成长态开始
2. 根据 PlayerProgressionGrantInput 发放经验
3. 统一更新 level / current_level_xp / total_xp / xp_to_next_level / pending_level_ups
4. 固定 last_granted_source

4.3 upsert_chapter_progression

当前负责：

1. 写入或覆盖某玩家某章节的计划快照
2. 固定章节预算、目标等级带与预期击杀数
3. 把实际记账字段初始化为 0

4.4 apply_chapter_progression_ledger_entry

当前负责：

1. 在已存在的章节计划上累计 actual_quest_xp
2. 累计 actual_hostile_xp
3. 累计 actual_hostile_defeat_count
4. 可选更新 level_at_exit

---

5. 当前刻意未做

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

1. 还没有把 sceneChapterBlueprints 的完整编译逻辑迁到 Rust。
2. 还没有落 repeatPenalty、超预算衰减与章节偏差评级输出。
3. 还没有把完整章节蓝图、掉落和全量 quest signal 都自动串进 player_progression / chapter_progression。
4. 还没有新增 Axum 的 progression facade。
5. 还没有把前端 Lv. 展示、任务奖励经验提示或敌对等级徽标切到 Rust 后端真相源。

也就是说，本轮只是把 module-progression 的 SpacetimeDB 成长基座立起来，不宣称已经完成成长系统迁移。

---

6. 验证要求

本轮工程变更完成后，至少执行下面两类验证：

1. npm run check:encoding
2. cargo test -p module-progression
3. cargo check -p spacetime-module

---

7. 下一步建议

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

1. 先把章节预算编译从 Node chapterProgressionPlanner 平移到 Rust 领域层。
2. 再把 npc / combat 入口改为消费 RuntimeEntityLevelProfile 和 chapter_progression。
3. 再把掉落、任务物品、好感奖励并入统一奖励结算。
4. 最后再接 Axum facade、兼容 DTO 与前端成长主链。