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

module-progression 成长与章节推进模块 crate 说明

日期：2026-04-30

1. crate 职责

module-progression 是成长与章节推进模块 crate，当前与后续负责：

1. player_progression、chapter_progression 的领域快照与校验规则。
2. 等级经验曲线、同级参考强度、敌对战斗生命值与经验掉落的统一数学基线。
3. 章节经验预算、章节实际记账与章节自动定级的纯领域 helper。
4. 与 crates/spacetime-module 的成长真相表、reducer、procedure 聚合对接。

2. 当前阶段说明

当前阶段已完成 DDD 物理拆分收口，已经不再是“真实逻辑集中在 lib.rs、分层文件只占位”的状态：

1. src/domain.rs 承载 LevelBenchmark、PlayerProgressionSnapshot、ChapterProgressionSnapshot、RuntimeEntityLevelProfile 等成长领域类型和值对象。
2. src/commands.rs 承载玩家成长查询/授予经验、章节预算、章节账本和章节自动定级输入。
3. src/application.rs 固化与既有 Node 侧一致的经验曲线、参考强度曲线、章节 pseudo level 曲线、敌对经验/生命值 fallback 和章节账本应用规则。
4. src/events.rs 承载经验授予、章节账本应用和自动定级解析等领域事件。
5. src/errors.rs 承载成长字段错误与中文错误文案。
6. src/lib.rs 只保留模块声明和公开导出，继续保持 module_progression::* 公开 API。
7. 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
5. ../../../docs/technical/SERVER_RS_DDD_WP_RPG_PROGRESSION_DOMAIN_SPLIT_2026-04-30.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 有冲突，必须先校正文档和领域规则，再继续接线。