44 lines
3.1 KiB
Markdown
44 lines
3.1 KiB
Markdown
# module-progression 成长与章节推进模块 crate 说明
|
||
|
||
日期：`2026-04-21`
|
||
|
||
## 1. crate 职责
|
||
|
||
`module-progression` 是成长与章节推进模块 crate，当前与后续负责：
|
||
|
||
1. `player_progression`、`chapter_progression` 的领域快照与校验规则。
|
||
2. 等级经验曲线、同级参考强度、敌对战斗生命值与经验掉落的统一数学基线。
|
||
3. 章节经验预算、章节实际记账与章节自动定级的纯领域 helper。
|
||
4. 与 `crates/spacetime-module` 的成长真相表、reducer、procedure 聚合对接。
|
||
|
||
## 2. 当前阶段说明
|
||
|
||
当前阶段已不再是目录占位，已经完成以下首版落地：
|
||
|
||
1. 新增 `Cargo.toml` 与 `src/lib.rs`，形成真实可编译 crate。
|
||
2. 冻结 `LevelBenchmark`、`PlayerProgressionSnapshot`、`ChapterProgressionSnapshot`、`RuntimeEntityLevelProfile` 等首版领域类型。
|
||
3. 固化与 Node 侧一致的经验曲线、参考强度曲线、章节 pseudo level 曲线与敌对经验/生命值 fallback 规则。
|
||
4. 提供 `create_initial_player_progression`、`grant_player_experience`、`build_chapter_progression_snapshot`、`apply_chapter_progression_ledger` 等领域原语。
|
||
5. 提供 `build_chapter_auto_level_profile`、`build_hostile_experience_reward`、`resolve_hostile_battle_max_hp`，为后续 `quest / combat / npc` 联动提供统一成长基线。
|
||
6. `spacetime-module` 已把 `turn_in_quest` 与 `resolve_combat_action(Victory)` 接到 `player_progression / chapter_progression` 最小经验结算链。
|
||
|
||
当前这轮刻意未做的范围：
|
||
|
||
1. 还没有把 `custom-world` 章节蓝图编译直接迁进 Rust。
|
||
2. 还没有把 `repeatPenalty`、超预算衰减和完整章节偏差审计表独立拆出。
|
||
3. 还没有在 crate 内直接承接 HTTP、Axum、LLM 或 OSS 副作用。
|
||
|
||
## 3. 当前已冻结关联文档
|
||
|
||
1. [../../../docs/design/LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md](../../../docs/design/LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md)
|
||
2. [../../../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](../../../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
|
||
3. [../../../docs/technical/M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md](../../../docs/technical/M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md)
|
||
4. [../../../docs/technical/M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md](../../../docs/technical/M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md)
|
||
|
||
## 4. 边界约束
|
||
|
||
1. `module-progression` 保持纯领域规则与状态建模，不直接承接 HTTP、JWT、OSS、LLM 或本地文件副作用。
|
||
2. 等级、经验、章节预算、自动定级必须以本 crate 的规则为唯一数学基线，不能再次散落回 route handler 或前端临时推导。
|
||
3. `player_progression` 与 `chapter_progression` 的持久化真相由 `crates/spacetime-module` 聚合，前端兼容输出与后端 facade 由 `crates/api-server` 暴露。
|
||
4. 若后续 `module-custom-world` 的章节蓝图 Rust 化与当前 helper 有冲突，必须先校正文档和领域规则，再继续接线。
|