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

module-quest 任务运行时模块说明

日期：2026-04-21

1. package 职责

module-quest 是任务运行时模块 package，当前已经承接下面 4 类纯领域能力：

1. QuestRecord / QuestStep / QuestReward / QuestProgressSignal 等任务状态模型
2. 任务 step 归一化、active step 选择、状态收口规则
3. accept -> apply signal -> acknowledge completion -> turn in 的最小任务状态流转 helper
4. 供 crates/spacetime-module 聚合表与 reducer 复用的纯 Rust 规则函数

2. 当前已落地的真实范围

当前 crate 已经提供：

1. QuestRecordInput / QuestRecordSnapshot
2. QuestProgressSignal / QuestSignalApplyInput / QuestSignalApplyOutcome
3. QuestCompletionAckInput / QuestTurnInInput
4. build_quest_record_snapshot
5. apply_quest_signal
6. acknowledge_quest_completion
7. turn_in_quest_record
8. generate_quest_log_id

补充说明：

1. 当前 crate 仍保持“纯领域规则”定位，不直接依赖 Axum、SpacetimeDB reducer context 或外部平台。
2. spacetime-types feature 只用于在 spacetime-module 中复用这些类型做表字段和 reducer 输入。

3. 当前未落地的范围

本 crate 当前明确还没有承接：

1. AI 任务意图生成
2. 奖励中的货币、好感、情报统一发放
3. runtime snapshot 投影
4. story action 跨域编排
5. Axum 兼容接口 DTO

补充说明：

1. 当前 QuestRewardItem 的字段已经升级到可无损映射 inventory_slot 的粒度，包含 description / stackable / stack_key / equipment_slot_id。
2. 当前 turn_in_quest 已在 crates/spacetime-module 中完成经验奖励到 player_progression / chapter_progression 的最小联动。
3. 当前 turn_in_quest 已在 crates/spacetime-module 中完成物品奖励写入 inventory_slot；module-quest 本身仍只冻结奖励 contract，真实聚合写入继续由 crates/spacetime-module 负责。

这些能力后续分别由 module-ai、module-runtime、module-story、api-server 衔接，不在这里堆成大而全服务。

4. 边界约束

1. module-quest 负责任务状态真相与任务规则，生成型任务草案与外部 AI 编排不直接塞进模块内部。
2. 任务状态最终回写到 crates/spacetime-module 聚合的状态模型中，前端兼容接口由 crates/api-server 暴露。
3. 任务不能再次散落到 story service、runtime service 或前端临时状态里分别维护。
4. 当前真实工程口径以 docs/technical/M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md 为准。