Genarrative/docs/technical/M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md

M4 RPG Runtime Quest SpacetimeDB 基座记录（2026-04-21）

更新时间：2026-04-21

0. 文档目标

本文件只记录一件事：

把 module-quest 从“只有 README 占位”推进到“SpacetimeDB 侧已有最小可编译任务运行时基座”的真实落地结果。

本轮只落任务主状态、任务日志与最小 reducer，并补上任务交付到成长表、背包表的最小联动；不扩到完整奖励结算、Axum facade、前端任务面板或 story action 全量迁移。

---

1. 本轮落地范围

本轮按 AI_NATIVE_QUEST_SYSTEM_PRD_2026-04-02.md、AI_NATIVE_TASK_DRIVEN_GOAL_EXPERIENCE_PRD_2026-04-07.md 与 SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md 的交叉口径，只落实下面 5 件事：

1. 新增 server-rs/crates/module-quest/ 真实 crate，而不是继续停留在 README 占位。
2. 在 module-quest 中冻结 QuestRecord、QuestStep、QuestReward、QuestProgressSignal 的首版 Rust 领域类型与校验/归一化 helper。
3. 在 server-rs/crates/spacetime-module/ 中新增 quest_record、quest_log 两张表。
4. 在 spacetime-module 中新增 accept_quest、apply_quest_signal、acknowledge_quest_completion、turn_in_quest 四个 reducer。
5. 用 module-story 同口径方式，把任务推进固定成“主记录 + 日志追加”的最小可编译基座。
6. 把 turn_in_quest.reward.items 显式映射为 InventoryMutation::GrantItem，在任务交付时同步写入 inventory_slot。

---

2. 本轮新增的真实工程落点

2.1 新增 crate

1. server-rs/crates/module-quest/Cargo.toml
2. server-rs/crates/module-quest/src/lib.rs

2.2 workspace 与主工程聚合

1. server-rs/Cargo.toml
   • 已把 crates/module-quest 纳入 workspace members
2. server-rs/crates/spacetime-module/Cargo.toml
   • 已接入 module-quest 依赖
3. server-rs/crates/spacetime-module/src/lib.rs
   • 已接入 module-quest 类型
   • 已新增 quest_record
   • 已新增 quest_log
   • 已新增 accept_quest
   • 已新增 apply_quest_signal
   • 已新增 acknowledge_quest_completion
   • 已新增 turn_in_quest

---

3. 当前冻结的数据口径

3.1 quest_record

当前首版字段冻结为：

1. quest_id
2. runtime_session_id
3. story_session_id
4. actor_user_id
5. issuer_npc_id
6. issuer_npc_name
7. scene_id
8. chapter_id
9. act_id
10. thread_id
11. contract_id
12. title
13. description
14. summary
15. objective
16. progress
17. status
18. completion_notified
19. reward
20. reward_text
21. narrative_binding
22. steps
23. active_step_id
24. visible_stage
25. hidden_flags
26. discovered_fact_ids
27. related_carrier_ids
28. consequence_ids
29. created_at
30. updated_at
31. completed_at
32. turned_in_at

当前策略：

1. quest_record 保持 private 真相表口径。
2. 当前仍沿用“一个任务一条主记录”的最小可编译策略，不在本轮拆 quest_step 独立表。
3. objective / progress / active_step_id / status 统一由 steps 归一化导出，避免旧接口和新真相源在同一条记录里出现漂移。

3.2 quest_log

当前首版字段冻结为：

1. log_id
2. quest_id
3. runtime_session_id
4. actor_user_id
5. event_kind
6. status_after
7. signal_kind
8. signal
9. step_id
10. step_progress
11. created_at

当前策略：

1. quest_log 先作为 private 结构化日志表，不提前做 public event table。
2. 当前只承接 Accepted / Progressed / Completed / CompletionAcknowledged / TurnedIn 五类事件。
3. 后续若要接前端实时提示，再决定是否补 event table 或投影表，而不是现在先塞 UI 专用字段。

---

4. 当前 reducer 口径

4.1 accept_quest

当前负责：

1. 校验 QuestRecordInput
2. 拒绝重复 quest_id
3. 写入 quest_record
4. 追加一条 Accepted 日志

4.2 apply_quest_signal

当前负责：

1. 校验 QuestSignalApplyInput
2. 校验目标 quest_record 必须存在
3. 只对当前 active step 应用任务信号
4. 在命中信号时推进 step progress、刷新 objective / active_step_id / progress / status
5. 命中且未完成时追加 Progressed
6. 最后一条 step 完成时追加 Completed

补充约束：

1. 已经 Completed / ReadyToTurnIn / TurnedIn / Failed / Expired 的任务不会被重复推进。
2. 信号未命中当前 active step 时，本轮 reducer 允许静默 no-op，保持幂等。

4.3 acknowledge_quest_completion

当前负责：

1. 把 completion_notified 标为 true
2. 追加一条 CompletionAcknowledged 日志

4.4 turn_in_quest

当前负责：

1. 校验任务已处于 Completed / ReadyToTurnIn
2. 固定所有 step progress 为完成态
3. 把任务状态切到 TurnedIn
4. 补齐 turned_in_at
5. 追加一条 TurnedIn 日志
6. 若存在 reward.items，同步发放到 inventory_slot
7. 若存在 reward.items，同步发放到 inventory_slot
8. 若 reward.experience > 0，同步发放 player_progression 经验
9. 若存在已初始化的 chapter_progression，同步累计章节任务经验账本

---

5. 当前刻意未做

本轮明确没有扩到以下范围：

1. 还没有落任务奖励的货币、好感、情报统一发放 reducer
2. 还没有接 runtime_snapshot projection / sync
3. 还没有接 story_session、npc_state 的更多跨域联动
4. 还没有新增 Axum 的 runtime quest facade
5. 还没有把 server-node 现有 quest API 切到 server-rs
6. 还没有把 Goal Director、章节目标 handoff、前端任务 UI 切到 SpacetimeDB 真相源

也就是说，本轮只是把 module-quest 的 SpacetimeDB 任务基座立起来，不宣称已经完成任务系统迁移。

---

6. 验证要求

本轮工程变更完成后，至少执行下面两类验证：

1. npm run check:encoding
2. cargo test -p module-quest
3. cargo check -p spacetime-module

---

7. 下一步建议

按当前节奏，后续应继续按下面顺序推进：

1. 先把 quest_record 与 runtime_snapshot 的投影边界补清。
2. 再把 resolve_story_action 内的 quest signal 分发迁到 apply_quest_signal。
3. 再把 turn_in_quest 与 npc affinity / currency / intel projection 的奖励结算接成显式 reducer。
4. 再把 quest reward item 的映射 helper 上提到独立领域 crate，减少 spacetime-module 聚合层重复转换。
5. 最后再接 Axum facade、兼容 DTO 与前端任务主链。