# 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` 为准。