Genarrative/server-rs/crates/module-progression/README.md

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
2. ../../../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md
3. ../../../docs/technical/M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md
4. ../../../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 有冲突，必须先校正文档和领域规则，再继续接线。