Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,204 +0,0 @@
|
||||
# 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 与前端任务主链。
|
||||
Reference in New Issue
Block a user