后端重写提交
This commit is contained in:
@@ -0,0 +1,174 @@
|
||||
# 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 与前端成长主链。
|
||||
Reference in New Issue
Block a user