# M4 module-npc SpacetimeDB 基座记录（2026-04-21）

更新时间：`2026-04-21`

## 0. 文档目标

本文件只记录一件事：

**把 `module-npc` 从“只有占位 README”推进到“已有可编译 Rust 领域 contract，并接入 `SpacetimeDB` 最小 `npc_state` 真相表与社交动作 reducer/procedure”的真实落地结果。**

本轮只做最小基座，不扩到完整 `npc_trade / npc_gift / npc_recruit` 的全链结算迁移，也不改前端 UI。

---

## 1. 本轮落地范围

本轮只落实下面 6 件事：

1. 新增 `server-rs/crates/module-npc/` 真实 crate，而不是继续停留在目录占位。
2. 在 `module-npc` 中冻结 `relation_state / stance_profile / npc_state` 的首版领域类型与校验 helper。
3. 在 `module-npc` 中补齐 `build_initial_stance_profile`、`normalize_npc_state_snapshot`、`apply_npc_social_action` 等最小规则原语。
4. 在 `server-rs/crates/spacetime-module/` 中新增 `npc_state` 表。
5. 在 `spacetime-module` 中新增 `upsert_npc_state`、`resolve_npc_social_action` 及对应 procedure，形成最小可编译写入口。
6. 在 `module-npc` 中新增 `resolve_npc_interaction` 的首版领域 contract，并在 `spacetime-module` 中补对应 reducer / procedure。

---

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

### 2.1 新增 crate

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

### 2.2 workspace 与主工程聚合

1. `server-rs/Cargo.toml`
   - 已把 `crates/module-npc` 纳入 workspace members
2. `server-rs/crates/spacetime-module/Cargo.toml`
   - 已接入 `module-npc` 依赖
3. `server-rs/crates/spacetime-module/src/lib.rs`
   - 已接入 `module-npc` 类型
   - 已新增 `npc_state`
   - 已新增 `upsert_npc_state`
   - 已新增 `upsert_npc_state_and_return`
   - 已新增 `resolve_npc_social_action`
   - 已新增 `resolve_npc_social_action_and_return`
   - 已新增 `resolve_npc_interaction`
   - 已新增 `resolve_npc_interaction_and_return`

---

## 3. 当前冻结的数据口径

### 3.1 `relation_state`

当前首版冻结为：

1. `affinity`
2. `stance`

`stance` 当前只冻结 5 档：

1. `Hostile`
2. `Guarded`
3. `Neutral`
4. `Cooperative`
5. `Bonded`

当前阈值直接对齐现有前端 / Node 原语：

1. `< 0` -> `Hostile`
2. `< 15` -> `Guarded`
3. `< 30` -> `Neutral`
4. `< 60` -> `Cooperative`
5. `>= 60` -> `Bonded`

### 3.2 `stance_profile`

当前首版冻结为：

1. `trust`
2. `warmth`
3. `ideological_fit`
4. `fear_or_guard`
5. `loyalty`
6. `current_conflict_tag`
7. `recent_approvals`
8. `recent_disapprovals`

字段策略：

1. 数值统一收敛到 `0 ~ 100`。
2. 最近好评 / 反感文本统一只保留最近 `3` 条。
3. `current_conflict_tag` 仍允许为空，不在本轮强绑世界线程 ID。

### 3.3 `npc_state`

当前首版字段冻结为：

1. `npc_state_id`
2. `runtime_session_id`
3. `npc_id`
4. `npc_name`
5. `affinity`
6. `relation_state`
7. `help_used`
8. `chatted_count`
9. `gifts_given`
10. `recruited`
11. `trade_stock_signature`
12. `revealed_facts`
13. `known_attribute_rumors`
14. `first_meaningful_contact_resolved`
15. `seen_backstory_chapter_ids`
16. `stance_profile`
17. `created_at`
18. `updated_at`

当前策略：

1. `npc_state` 保持 private 真相表口径。
2. `npc_state_id` 允许由 `runtime_session_id + npc_id` 自动派生，避免外部每次重复拼接。
3. `relation_state` 作为显式冗余字段落表，避免每次读取都重复派生。
4. `npc_name` 当前保留为调试与兼容聚合字段，不承担唯一键职责。

---

## 4. 当前 reducer / procedure 口径

### 4.1 `upsert_npc_state`

当前负责：

1. 校验 `runtime_session_id / npc_id / npc_name`
2. 归一化 `stance_profile`
3. 归一化 `relation_state`
4. 以 `npc_state_id` 为主键执行幂等写入

### 4.2 `resolve_npc_social_action`

当前只承接 **纯 NPC 关系状态** 的最小变更，不负责背包、任务、队伍、战斗副作用。

当前动作冻结为：

1. `Chat`
2. `Help`
3. `Gift`
4. `Recruit`
5. `QuestAccept`

当前规则：

1. `Chat`
   - 默认按 `max(2, 6 - chatted_count)` 推进好感
   - 递增 `chatted_count`
   - 强制标记 `first_meaningful_contact_resolved = true`
2. `Help`
   - 若已使用过援手则拒绝
   - 默认推进 `4` 点好感
   - 写入 `help_used = true`
3. `Gift`
   - 递增 `gifts_given`
   - 默认按 `4` 点好感推进，允许外部显式传入覆盖值
4. `Recruit`
   - 若当前好感 `< 60` 则拒绝
   - 写入 `recruited = true`
   - 同时标记首遇已完成
5. `QuestAccept`
   - 默认推进 `3` 点好感
   - 只改 NPC 关系侧立场数据，不直接落 quest 真相

当前 procedure 仅返回最新 `NpcStateSnapshot`，不在本轮提前扩出 story patch / UI 文案 contract。

### 4.3 `resolve_npc_interaction`

当前首版 `resolve_npc_interaction` 不直接承担所有跨子域副作用，而是先固定 **NPC 单次正式交互** 的最小统一结果口径。

当前输入冻结为：

1. `runtime_session_id`
2. `npc_id`
3. `npc_name`
4. `interaction_function_id`
5. `updated_at_micros`
6. `release_npc_id`（仅为后续招募换队预留，当前不在 Rust 侧正式消费）

当前支持的 function 只冻结为：

1. `npc_preview_talk`
2. `npc_chat`
3. `npc_help`
4. `npc_recruit`
5. `npc_fight`
6. `npc_spar`
7. `npc_leave`

当前输出冻结为：

1. `npc_state`
2. `interaction_status`
3. `action_text`
4. `result_text`
5. `story_text`
6. `battle_mode`
7. `encounter_closed`
8. `affinity_changed`
9. `previous_affinity`
10. `next_affinity`

当前规则：

1. `npc_preview_talk`
   - 只把交互状态切到 `Previewed`
   - 不改好感
2. `npc_chat`
   - 复用 `resolve_npc_social_action(Chat)` 的关系推进
   - 返回 `interaction_status = Dialogue`
3. `npc_help`
   - 复用 `resolve_npc_social_action(Help)`
   - 返回 `interaction_status = Resolved`
4. `npc_recruit`
   - 当前只负责把 `npc_state.recruited = true`
   - 不在本轮承担 companion / roster 真相写入
   - 返回 `interaction_status = Recruited`
5. `npc_fight`
   - 不改 `npc_state.affinity`
   - 返回 `interaction_status = BattlePending`
   - `battle_mode = Fight`
6. `npc_spar`
   - 不改 `npc_state.affinity`
   - 返回 `interaction_status = BattlePending`
   - `battle_mode = Spar`
7. `npc_leave`
   - 不改关系真相
   - 返回 `interaction_status = Left`
   - `encounter_closed = true`

当前刻意不做：

1. 不直接生成 `RuntimeStoryPatch`
2. 不直接写 `companions / roster / inventory_slot`
3. 不直接把玩家 HP / MP、切磋战斗目标、战斗奖励塞进这个 reducer

也就是说，这一层当前只负责把 **Node 侧 `resolveNpcInteraction` 的统一入口语义** 先冻结为可编译 contract，不宣称已经迁完全部副作用。

---

## 5. 当前刻意未做

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

1. 还没有落 `npc_trade` 的库存与价格正式结算
2. 还没有落 `npc_gift` 的背包扣减与物品收益结算
3. 还没有落 `npc_recruit` 的队伍替换与 companion 真相迁移
4. `npc_fight / npc_spar` 的正式 `battle_state` 初始化编排不在 `module-npc` crate 内部完成，而是下沉到 `spacetime-module` 聚合 procedure
5. 还没有把 `custom world` 的 `narrativeProfile / backstoryReveal` 真正投影进 SpacetimeDB
6. 还没有把 Node 侧 `npcInteractionService` 全量切到 `server-rs`
7. 还没有给前端接入 `SpacetimeDB` 的 NPC 订阅读模型

也就是说，本轮只是把 **NPC 关系状态基座** 立起来，不宣称已经完成完整 NPC 子域迁移。

---

## 6. 下一步建议

后续应继续按下面顺序推进：

1. 把 `npc_recruit` 的 companion / roster 真相迁移拆成 `module-npc + module-runtime + module-story` 的联合 reducer 设计。
2. 在 `spacetime-client` / Axum 侧继续把 `npc_fight / npc_spar` 的 `battle_state` 联合编排接口接出来。
3. 把 `npc_trade / npc_gift` 的正式库存、扣减与收益迁到 `inventory / runtime-item` 联动链。
4. 把 `backstoryReveal / privateChatUnlockAffinity / narrativeProfile` 的可见性规则投成显式读模型。
5. 再接 `api-server` 的 NPC facade 与前端 runtime action。