GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

后端重写提交

Browse Source
This commit is contained in:
kdletters
2026-04-22 12:34:49 +08:00
parent cf8da3f50f
commit 997a8daada
438 changed files with 53355 additions and 865 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/planning/CURRENT_AGENT_CREATION_FLOW_OPTIMIZATION_PLAN_2026-04-20.md
View File

@@ -1,6 +1,6 @@
# 当前 Agent 创作流程优化执行规划（大白话版）
更新时间：`2026-04-20`
更新时间：`2026-04-21`
## 先把话说死
@@ -16,6 +16,22 @@
这份规划就是基于 [AGENT_TO_DRAFT_TO_WORLD_PIPELINE_AUDIT_2026-04-20.md](../audits/AGENT_TO_DRAFT_TO_WORLD_PIPELINE_AUDIT_2026-04-20.md) 里已经确认的问题，重新收束出来的一版执行方案。
## 0.1 当前正式执行基线
从 `2026-04-21` 起，当前仓库里和这条创作主链直接对应的文件级拆分、阶段验收、工作包进度，统一以以下文档为准：
1. [../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
2. `docs/technical/CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_*_PROGRESS_2026-04-21.md`
3. [../technical/CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md](../technical/CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md)
本文件继续承担的职责只剩 3 件事：
1. 解释为什么当前版本只收口现有 Agent 创作动线，不再扩一套新流程
2. 冻结这轮明确不做的能力边界
3. 给出高层执行顺序与判断标准
凡是涉及目录落位、命名规范、前后端真相源边界、阶段完成度和工作包状态，统一以后面的技术执行文档为准。
---
## 1. 现在最大的问题，用大白话讲是什么
@@ -328,17 +344,17 @@
**让用户走起来更顺，让系统找回内容更稳定。**
## 第三阶段：再处理旧 pipeline 的降级和冻结
## 第三阶段：清理旧链残留表述与剩余兼容误导
再做：
1. 旧 `custom-world/sessions` 链降级
2. 结果页直改 profile 的旧能力收紧
3. 兼容链保留边界写清楚
1. 清理旧 `custom-world/sessions` 已删除链路在文档、索引、任务清单里的残留表述
2. 结果页直改 profile 的旧能力继续收紧
3. 把仍保留的兼容 façade / 兼容字段边界写清楚
这一阶段的目标是：
**减少系统自己和自己打架。**
**减少旧链文档误导和兼容边界漂移。**
## 第四阶段：最后做文档清理
@@ -382,8 +398,8 @@
应该看到：
1. 重复 pipeline 明显减少
2. 旧链不再继续吞主流程职责
1. 已删除旧链不再继续出现在当前执行清单里
2. 剩余兼容层的保留边界更清楚
3. 后续开发不会再不知道该往哪条链上接
## 阶段四做完

20
docs/planning/CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md
View File

@@ -15,6 +15,15 @@
**现在的优先级不是“继续扩玩法宽度”，而是“先把底层规则、主流程边界和工程可维护性补齐，再扩玩法深度”。**
补充更新（`2026-04-21`）：
当前与“主流程边界补齐”直接对应的执行基线，已经从泛化的 `GameShell / useStoryGeneration / customWorld` 热点讨论，收口成两条正式技术方案：
1. [../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：负责创作入口 -> Agent session -> result preview -> published profile 主链。
2. [../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：负责平台入口 -> 继续游戏/开始游戏 -> RPG runtime -> runtime story 主链。
因此本文里的 `P0-2`，当前应按这两条主线落地，而不是继续围绕旧 `GameShell` / `PreGameSelectionFlow` / `runtimeRoutes.ts` 命名做泛化式重构。
---
## 优先级清单
@@ -57,9 +66,9 @@
### 本阶段要做什么
- 把 `useStoryGeneration` 收敛为 orchestration 层，不再直接吞下 NPC、任务、背包、锻造、聊天、奖励等全部细节
- 把 `useCombatFlow` 进一步拆成“战斗结算”与“播放/演出同步”
- 让 `GameShell` 回到流程壳层职责，把 selection flow、overlay、scene transition 继续下沉
- 按 [../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md) 收口创作链，统一 `Agent session -> result preview -> published profile`
- 按 [../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md) 收口 `rpgEntry -> rpgSession -> rpgRuntime -> rpgRuntimeStory -> rpgProfile`
- 旧 `GameShell / PreGameSelectionFlow / runtimeRoutes.ts / storyActionService.ts` 只作为历史热区名或兼容 façade，不再作为当前新任务默认落点
### 做到什么算完成
@@ -231,7 +240,7 @@
- 继续横向扩 NPC 交互种类，但不补统一规则底座
- 继续堆宝藏、掉落、锻造分支，但不先做统一物品导演层
- 继续增加任务模板数量，但不升级任务 contract
- 继续往 `useStoryGeneration` / `useCombatFlow` / `GameShell` 里直接塞新逻辑
- 继续往 `useStoryGeneration` / `useCombatFlow` / `GameShell` / `PreGameSelectionFlow` / `runtimeRoutes.ts` / `storyActionService.ts` 里直接塞新逻辑
原因很简单：
@@ -244,7 +253,8 @@
### 第一阶段：先稳住工程与主流程
1. 绿色基线与门禁收紧
2. 运行时主链拆分
2. 创作链按 `CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 收口
3. RPG 进入游戏与运行时链按 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 收口
### 第二阶段：先补统一语义底座

5
docs/planning/README.md
View File

@@ -4,7 +4,9 @@
- [ENGINEERING_DEAD_CODE_AND_HIDDEN_BRANCH_CLEANUP_PLAN_2026-04-21.md](./ENGINEERING_DEAD_CODE_AND_HIDDEN_BRANCH_CLEANUP_PLAN_2026-04-21.md)：面向无用历史代码、隐形多数据链路和半成品实现的一轮工程大清洗执行计划，强调先建台账、再删重收口、最后恢复主工程可读性。
- [CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md](./CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md)：当前阶段最值得优先做什么、为什么，以及它和审计/PRD 的对应关系。
- [CURRENT_AGENT_CREATION_FLOW_OPTIMIZATION_PLAN_2026-04-20.md](./CURRENT_AGENT_CREATION_FLOW_OPTIMIZATION_PLAN_2026-04-20.md)：在不新增前端创作流程的前提下，围绕当前 Agent 创作动线做收口、删重、补通和文档收束的大白话执行规划。
- [../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：当前创作入口、Agent session、结果页自动保存、作品库与进入世界主链的正式文件级重构基线；涉及目录落位、命名规范、阶段验收与工作包拆分时优先看这一份。
- [../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)：当前平台入口、继续游戏、角色选择、RPG runtime 与 runtime story 主链的正式文件级重构基线；涉及入口壳层、session、runtime、story、route/service/repository 拆分时优先看这一份。
- [CURRENT_AGENT_CREATION_FLOW_OPTIMIZATION_PLAN_2026-04-20.md](./CURRENT_AGENT_CREATION_FLOW_OPTIMIZATION_PLAN_2026-04-20.md)：创作链高层目标、冻结边界与执行顺序说明；文件级拆分与阶段验收以创作链重构执行方案为准。
- [EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md](./EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md)：基于“前端只做表现、逻辑与数据全部后端化”的工程重构规划。
- [EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md](./EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md)：将后端化重构拆成可并行推进、尽量不冲突的任务流与协作顺序。
- [BEIJING_POLICY_APPLICATION_OVERVIEW_13_21_24_2026-04-14.md](./BEIJING_POLICY_APPLICATION_OVERVIEW_13_21_24_2026-04-14.md)：北京市方向 13 / 21 / 24 的统一判断、共用材料框架和准备顺序。
@@ -15,4 +17,5 @@
## 使用建议
- 需要排期、拆阶段、判断先修基线还是先加功能时，先看这份。
- 当前如果要推进创作链或 RPG 运行时主链重构，先看上面的两份 `2026-04-21` 执行方案，再回来看高层优先级和冻结边界。
- 这份文档大量引用了经验文档、工程审查和 PRD，适合作为跨文档导航页使用。

97
docs/technical/API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,97 @@
# `api-server` 接入 `platform-llm` 最小代理设计（2026-04-21）
## 1. 目标
在 `platform-llm` 已落成真实 Rust crate 后，`api-server` 需要尽快拥有一条可正式消费的平台接线面，避免平台层只停留在“可编译但未接入”状态。
本次目标只做最小闭环：
1. 在 `api-server` 配置层补齐 LLM 文本网关环境变量
2. 在 `AppState` 注入 `platform-llm::LlmClient`
3. 提供 `/api/llm/chat/completions` 非流式兼容代理
4. 保持与旧 Node 路由的鉴权位置和基本请求形态一致
## 2. 本次范围
### 2.1 本次实现
1. `AppConfig` 新增 LLM provider / base url / api key / model / timeout / retry 配置
2. `AppState` 初始化 `LlmClient`
3. 新增 `shared-contracts::llm`
4. 新增 `api-server/src/llm.rs`
5. 路由挂载到 `/api/llm/chat/completions`
### 2.2 本次不实现
1. 不实现 SSE 流式透传
2. 不实现通用原样 body 转发
3. 不实现媒体模型路由
4. 不把 `module-ai` 编排接进来
## 3. 兼容口径
保持与旧 Node `POST /api/llm/chat/completions` 一致的基本语义：
1. 需要登录态
2. 接收 `model? + stream + messages[]`
3. 当前 `stream=true` 明确返回 `501`，避免伪装支持
4. 非流式返回统一后的文本结果，而不是原样上游 JSON
## 4. 返回结构
Rust 首版返回：
1. `id`
2. `model`
3. `content`
4. `finishReason`
原因：
1. 当前 Rust 平台层已经把上游 `choices[0].message.content` 归一完成
2. `api-server` 首版先保持稳定、可消费的文本结果接口
3. 真正需要 OpenAI 完全兼容响应体时，再单独补“原样代理模式”
## 5. 验收
1. `api-server` 能在配置合法时成功构建 `AppState`
2. `/api/llm/chat/completions` 能通过测试打到 mock 上游
3. `stream=true` 返回明确错误
4. crate 级 `check/test` 通过
## 6. 环境变量与默认值
`api-server` 首版按以下优先级解析 LLM 配置，保证兼容仓库现有 `.env` 口径：
1. provider：`GENARRATIVE_LLM_PROVIDER` -> `LLM_PROVIDER`
2. base url：`GENARRATIVE_LLM_BASE_URL` -> `LLM_BASE_URL`
3. api key：`GENARRATIVE_LLM_API_KEY` -> `LLM_API_KEY` -> `ARK_API_KEY`
4. model：`GENARRATIVE_LLM_MODEL` -> `LLM_MODEL` -> `VITE_LLM_MODEL`
5. timeout：`GENARRATIVE_LLM_REQUEST_TIMEOUT_MS` -> `LLM_REQUEST_TIMEOUT_MS`
6. max retries：`GENARRATIVE_LLM_MAX_RETRIES` -> `LLM_MAX_RETRIES`
7. retry backoff：`GENARRATIVE_LLM_RETRY_BACKOFF_MS` -> `LLM_RETRY_BACKOFF_MS`
默认值统一对齐 `platform-llm`：
1. provider：`ark`
2. base url：`https://ark.cn-beijing.volces.com/api/v3`
3. model：`doubao-1-5-pro-32k-character-250715`
4. request timeout：`30000`
5. max retries：`1`
6. retry backoff：`500`
补充约束：
1. 如果 `api key` 未配置，`api-server` 允许继续启动，但 `/api/llm/chat/completions` 返回 `503`
2. 如果 provider 字符串非法，回退到默认 `ark`，避免因为环境变量拼写问题阻断开发态服务
## 7. 错误映射
`platform-llm` 到 HTTP 的错误映射固定如下：
1. `InvalidRequest` -> `400 BAD_REQUEST`
2. `InvalidConfig` -> `503 SERVICE_UNAVAILABLE`
3. `Timeout` / `Connectivity` / `Transport` / `Deserialize` / `EmptyResponse` / `StreamUnavailable` -> `502 BAD_GATEWAY`
4. `Upstream(status=429)` -> `429 TOO_MANY_REQUESTS`
5. 其他 `Upstream` -> `502 BAD_GATEWAY`
6. `stream=true` 首版直接返回 `501 NOT_IMPLEMENTED`

70
docs/technical/ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md Normal file
View File

@@ -0,0 +1,70 @@
# 编码检查与临时工作区噪音收口方案（2026-04-22）
日期：`2026-04-22`
## 1. 背景
当前仓库根目录存在多份本地临时工作区与 Cargo cache 目录，例如：
1. `.codex-cargo-home-stage4*`
2. `server-rs-codex-stage4-*`
3. `server-rs/target-*`
这些目录属于本地验证产物，不属于主工程源码、文档或正式资源，但 `npm run check:encoding` 仍会通过 `git ls-files --cached --others --exclude-standard` 把其中大量未跟踪文本文件纳入扫描，导致：
1. 编码检查耗时被临时目录放大
2. 检查结果容易被本地 cache / verify copy 噪音污染
3. 仓库级 UTF-8 检查无法稳定反映真实工程文件状态
同时，当前脚本没有把 `.rs` 纳入文本扩展名集合，这与仓库约束“Rust / 工程代码中的中文注释也必须保证 UTF-8 正常”不一致。
## 2. 本次冻结规则
本轮对编码检查口径做以下冻结：
1. `scripts/check-encoding.mjs` 只检查主工程真实文本文件，不扫描临时 Cargo cache、临时 verify copy 和 `server-rs/target-*` 目录。
2. `.rs` 必须纳入 UTF-8 编码检查，避免 Rust 文件中的中文注释或中文错误文案被写坏后漏检。
3. `.encoding-check-ignore` 继续只承载少量已知历史坏文本白名单，不用于掩盖大目录级临时产物。
4. 对临时目录的处理优先通过 `.gitignore` 与脚本排除规则完成，不要求物理删除本地 cache。
## 3. 具体落地点
### 3.1 `.gitignore`
新增忽略规则：
1. `/.codex-cargo-home-*/`
2. `/server-rs-codex-*/`
3. `/server-rs/target-*/`
目的：
1. 让 `git ls-files --others --exclude-standard` 不再把这些临时目录当作待检查仓库文件。
2. 与既有噪音清理基线保持一致，继续把本地检查产物留在仓库视野之外。
### 3.2 `scripts/check-encoding.mjs`
脚本同步收紧两点：
1. 增加对上述临时前缀目录的显式排除，避免脚本在显式传参或忽略规则未生效时仍误扫临时目录。
2. 把 `.rs` 加入文本扩展名集合，确保 Rust 源文件进入 UTF-8 校验面。
## 4. 完成定义
当以下条件满足时，本次修复视为完成：
1. `npm run check:encoding` 不再被临时 Cargo / verify 目录拖慢或污染结果。
2. 真实工程中的 Rust 文件会参与 UTF-8 检查。
3. 不需要清理用户本地 cache 目录，也不会对现有并行工作区造成破坏。
## 5. 不在本轮范围
本轮不处理：
1. `.encoding-check-ignore` 中历史坏文本的逐条修复
2. 各类本地 cache / verify 目录的物理删除
3. 与 UTF-8 检查无关的 lint / typecheck / cargo 输出目录清理策略
## 6. 相关文档
1. [./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)

299
docs/technical/M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,299 @@
# M3：browse history Axum + SpacetimeDB 落地设计
日期：`2026-04-21`
关联任务：
- [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)
- [./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
关联现状：
- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
- `packages/shared/src/contracts/runtime.ts`
## 1. 文档目的
`02_M3_RUNTIME_PROFILE.md` 已经把 `user_browse_history` 和 `browse history` facade 列入 M3，但还没有冻结到可直接编码的字段、去重规则、路由兼容方式和错误语义。
本文只解决 `browse history` 这一个最小闭环切片：
1. `user_browse_history` 真相表
2. `GET /api/runtime/profile/browse-history`
3. `POST /api/runtime/profile/browse-history`
4. `DELETE /api/runtime/profile/browse-history`
5. `/api/profile/browse-history` 兼容路径
本文不新建 checklist，不替代 [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)，只补足本轮编码所需的冻结口径。
## 2. 旧实现冻结口径
当前 Node 侧行为来自：
- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
冻结行为如下。
### 2.1 路由
主路径与兼容路径都必须保留：
1. `GET /api/runtime/profile/browse-history`
2. `POST /api/runtime/profile/browse-history`
3. `DELETE /api/runtime/profile/browse-history`
4. `GET /api/profile/browse-history`
5. `POST /api/profile/browse-history`
6. `DELETE /api/profile/browse-history`
所有路径都要求 Bearer JWT。
### 2.2 数据字段
单条浏览记录字段与 `packages/shared/src/contracts/runtime.ts` 保持一致：
1. `ownerUserId`
2. `profileId`
3. `worldName`
4. `subtitle`
5. `summaryText`
6. `coverImageSrc`
7. `themeMode`
8. `authorDisplayName`
9. `visitedAt`
### 2.3 POST 请求体兼容
`POST` 同时支持两种形态：
1. 单条对象
2. `{ entries: [...] }` 批量对象
批量最多 `100` 条。
### 2.4 归一化规则
旧 Node 仓储不是严格校验，而是宽松归一化：
1. `ownerUserId`、`profileId`、`worldName` 去首尾空白后必须非空，否则该条忽略。
2. `subtitle`、`summaryText`、`coverImageSrc` 去首尾空白，空串按空值处理。
3. `themeMode` 不做严格枚举校验，未知值统一回落到 `mythic`。
4. `authorDisplayName` 空值回落到 `玩家`。
5. `visitedAt` 缺失时回落到当前时间。
### 2.5 去重与排序规则
旧 Node 仓储的关键行为必须保持：
1. 去重键：`ownerUserId + profileId`
2. 同一批写入时，先按 `visitedAt DESC` 排序，再去重，只保留最新一条
3. 表内最终查询结果按 `visitedAt DESC` 返回
### 2.6 清空行为
`DELETE` 清空当前用户的全部浏览历史，并返回：
```json
{
"entries": []
}
```
## 3. Rust 落位决议
### 3.1 crate 分工
本切片固定按以下边界落位：
1. `crates/module-runtime`
- 定义 `browse history` DTO、字段校验、去重排序与宽松归一化规则。
2. `crates/spacetime-module`
- 定义 `user_browse_history` 表。
- 提供 `list / upsert / clear` 三个 procedure。
3. `crates/spacetime-client`
- 提供 `list_platform_browse_history`
- 提供 `upsert_platform_browse_history_entries`
- 提供 `clear_platform_browse_history`
4. `crates/shared-contracts`
- 冻结 Axum facade 的请求/响应 DTO。
5. `crates/api-server`
- 提供双路径兼容 facade。
- 保持 envelope / 错误格式与当前 `runtime settings` 一致。
### 3.2 身份边界
本轮仍沿用 Axum Bearer JWT 作为唯一鉴权边界：
1. `require_bearer_auth` 校验 token。
2. 从 claims 中提取 `user_id`。
3. `user_id` 作为 procedure 入参传入 SpacetimeDB。
当前阶段不把浏览历史直接暴露给前端直连订阅。
## 4. SpacetimeDB 表设计
### 4.1 表名
`user_browse_history`
### 4.2 字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `browse_history_id` | `String` | 主键，格式为 `user_id:owner_user_id:profile_id` |
| `user_id` | `String` | 当前登录用户 |
| `owner_user_id` | `String` | 被浏览世界所属用户 |
| `profile_id` | `String` | 被浏览世界 profile |
| `world_name` | `String` | 世界名 |
| `subtitle` | `String` | 副标题 |
| `summary_text` | `String` | 摘要 |
| `cover_image_src` | `Option<String>` | 封面图 |
| `theme_mode` | `RuntimeBrowseHistoryThemeMode` | 主题枚举 |
| `author_display_name` | `String` | 作者显示名 |
| `visited_at` | `Timestamp` | 最近访问时间 |
| `created_at` | `Timestamp` | 首次写入时间 |
| `updated_at` | `Timestamp` | 最近更新时间 |
### 4.3 索引
至少保留以下访问路径：
1. 主键 `browse_history_id`
2. `(user_id, visited_at)` 用于当前用户按时间倒序列出
3. `(user_id, owner_user_id, profile_id)` 用于幂等 upsert
### 4.4 设计决议
1. 不额外引入自增 ID，直接把幂等键收口成主键。
2. `visited_at` 单独持久化成 `Timestamp`，避免把时间排序退回字符串比较。
3. `theme_mode` 在表内固定为枚举，但 Axum 输入仍宽松接受字符串。
## 5. Procedure 设计
### 5.1 procedure 列表
1. `list_platform_browse_history`
2. `upsert_platform_browse_history_and_return`
3. `clear_platform_browse_history_and_return`
统一返回：
```text
RuntimeBrowseHistoryProcedureResult {
ok
entries
error_message
}
```
### 5.2 行为约束
`list_platform_browse_history`
1. 校验 `user_id`
2. 读取当前用户所有记录
3. 按 `visited_at DESC` 返回
`upsert_platform_browse_history_and_return`
1. 校验 `user_id`
2. 接受单批最多 `100` 条
3. 先按旧 Node 规则宽松归一化
4. 先按 `visitedAt DESC` 排序，再按 `ownerUserId + profileId` 去重
5. 用 `browse_history_id` 幂等 upsert
6. 返回当前用户完整倒序列表
`clear_platform_browse_history_and_return`
1. 校验 `user_id`
2. 删除当前用户全部记录
3. 返回空列表
## 6. Axum facade 设计
### 6.1 双路径兼容
两组路径必须共用同一组 handler：
1. `/api/runtime/profile/browse-history`
2. `/api/profile/browse-history`
只允许路由名不同，不允许行为分叉。
### 6.2 GET
行为：
1. Bearer JWT 校验
2. 读取 claims 中的 `user_id`
3. 调 `spacetime_client.list_platform_browse_history`
4. 返回 `PlatformBrowseHistoryResponse`
### 6.3 POST
行为：
1. Bearer JWT 校验
2. 通过 `serde(untagged)` 同时接单条和批量 shape
3. 不对 `themeMode` 做严格 400 拒绝
4. 对 `ownerUserId`、`profileId`、`worldName` 的缺失或空串按旧 Node 路由规则直接返回 `400`
5. 写入成功后返回最新完整列表
### 6.4 DELETE
行为：
1. Bearer JWT 校验
2. 清空当前用户全部记录
3. 返回 `entries: []`
### 6.5 错误映射
1. JSON 解析失败：`400 BAD_REQUEST`
2. DTO 构建失败：`400 BAD_REQUEST`
3. SpacetimeDB 调用失败：`502 BAD_GATEWAY`
4. JWT 缺失或失效：沿用当前 `401 UNAUTHORIZED`
错误 `details.provider` 固定为：
1. `browse-history`
2. `spacetimedb`
## 7. 测试策略
### 7.1 必跑测试
1. `module-runtime`
- 宽松 theme 归一化
- `visitedAt` 默认值
- 去重与倒序逻辑
2. `api-server`
- 未登录返回 `401`
- 兼容路径与主路径一致
- `POST` 同时支持单条和批量
- envelope 打开时错误结构稳定
### 7.2 可选联调测试
保留 `#[ignore]` 的本地 SpacetimeDB 集成测试：
1. `POST -> GET`
2. `DELETE -> GET`
## 8. 本文完成定义
当以下条件成立时，本设计视为完成：
1. `user_browse_history` 表字段、主键和排序规则已冻结。
2. 双路径 facade、请求 shape 和错误契约已冻结。
3. 后续编码不再需要猜测：
- `themeMode` 是否严格校验
- `POST` 是否支持单条/批量双 shape
- 去重时机与排序依据
## 9. 2026-04-22 实际落地进度
1. `module-runtime` 已切换为“API 入口严格校验 + 领域层静默过滤”的旧 Node 对齐模式。
2. `api-server` 已补齐双路径 browse history handler，并补 `401`、`400`、批量 shape、兼容路径一致性测试。
3. 剩余阻塞主要在工作树内其他并行任务带来的 Rust 编译占用与跨模块联调，不属于 browse history 方案本身。

410
docs/technical/M3_PROFILE_DASHBOARD_AXUM_SPACETIMEDB_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,410 @@
# M3：profile dashboard / wallet ledger / play stats Axum + SpacetimeDB 落地设计
日期：`2026-04-22`
关联任务：
- [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)
- [../../backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md](../../backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md)
关联现状：
- [M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
- [M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
- [NODE_BACKEND_MODULE_AND_API_INDEX.md](./NODE_BACKEND_MODULE_AND_API_INDEX.md)
- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
## 1. 文档目的
当前 M3 checklist 已经列出：
1. `profile_dashboard_state`
2. `profile_wallet_ledger`
3. `profile_played_world`
4. `/api/runtime/profile/dashboard`
5. `/api/runtime/profile/wallet-ledger`
6. `/api/runtime/profile/play-stats`
但仓库里还没有把这一组 profile 只读 facade 细化到可以直接编码的程度。本文件补足：
1. 旧 Node 行为冻结
2. SpacetimeDB projection 表字段
3. procedure 返回 contract
4. Axum 双路径 facade 与错误映射
5. 本轮只做读链、不提前承诺 snapshot 写入的边界
本文件不新增新的 M3 checklist，只服务于现有 [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md) 的后续落地。
## 2. 本轮范围
本轮只覆盖以下 6 条兼容路由：
1. `GET /api/runtime/profile/dashboard`
2. `GET /api/profile/dashboard`
3. `GET /api/runtime/profile/wallet-ledger`
4. `GET /api/profile/wallet-ledger`
5. `GET /api/runtime/profile/play-stats`
6. `GET /api/profile/play-stats`
本轮不做：
1. `runtime_snapshot`
2. `save archive`
3. snapshot -> profile projection 自动刷新
4. profile projection 的写 procedure
这样拆分的原因是：
1. 这组三个 profile 接口本质上都是 projection 读接口。
2. 旧 Node 读语义已经稳定，且空数据时都有明确默认值。
3. 先把读 contract 和表结构固定住，后续 `runtime_snapshot / save archive` 接上 projection writer 时不会再改 facade contract。
## 3. 旧 Node 行为冻结
Node 侧入口位于：
1. `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
2. `server-node/src/repositories/runtimeRepository.ts`
冻结口径如下。
### 3.1 dashboard
路由：
1. `GET /api/runtime/profile/dashboard`
2. `GET /api/profile/dashboard`
返回：
```json
{
"walletBalance": 0,
"totalPlayTimeMs": 0,
"playedWorldCount": 0,
"updatedAt": null
}
```
语义：
1. `walletBalance` 从 `profile_dashboard_state.wallet_balance` 读取。
2. `totalPlayTimeMs` 从 `profile_dashboard_state.total_play_time_ms` 读取。
3. `playedWorldCount` 通过 `profile_played_world` 的当前用户记录数计算。
4. `updatedAt` 为空时返回 `null`。
5. 当用户尚无任何 projection 时，仍返回默认零值，不返回 `404`。
### 3.2 wallet ledger
路由：
1. `GET /api/runtime/profile/wallet-ledger`
2. `GET /api/profile/wallet-ledger`
返回：
```json
{
"entries": [
{
"id": "ledger_001",
"amountDelta": 20,
"balanceAfter": 120,
"sourceType": "snapshot_sync",
"createdAt": "2026-04-22T10:00:00Z"
}
]
}
```
语义：
1. 只返回当前用户的流水。
2. 按 `createdAt DESC` 排序。
3. 最多返回最近 `50` 条。
4. 当前旧 Node 仅冻结 `sourceType = "snapshot_sync"` 一种来源。
5. 没有流水时返回 `{ "entries": [] }`。
### 3.3 play stats
路由：
1. `GET /api/runtime/profile/play-stats`
2. `GET /api/profile/play-stats`
返回：
```json
{
"totalPlayTimeMs": 0,
"playedWorks": [],
"updatedAt": null
}
```
其中 `playedWorks` 单项字段冻结为：
```json
{
"worldKey": "builtin:WUXIA",
"ownerUserId": null,
"profileId": null,
"worldType": "WUXIA",
"worldTitle": "武侠世界",
"worldSubtitle": "",
"firstPlayedAt": "2026-04-20T10:00:00Z",
"lastPlayedAt": "2026-04-22T10:00:00Z",
"lastObservedPlayTimeMs": 120000
}
```
语义：
1. `totalPlayTimeMs` 与 dashboard 共用 `profile_dashboard_state.total_play_time_ms`。
2. `playedWorks` 来自 `profile_played_world`。
3. 按 `lastPlayedAt DESC` 排序。
4. `updatedAt` 与 dashboard 共用 `profile_dashboard_state.updated_at`。
5. 没有 projection 时返回空列表和零值，不返回 `404`。
## 4. 本轮边界决议
### 4.1 先做 projection 读链
本轮 profile 三接口只做：
1. projection 表 schema
2. procedure 读接口
3. Axum facade
4. shared contract
不做 snapshot 写链，原因：
1. `runtime_snapshot` 仍未冻结最终表结构。
2. save archive 还未把“领域表真相 + 聚合快照”方案完全落到文档。
3. 若现在提前补写逻辑，后续大概率要因为 snapshot 方案调整而返工。
### 4.2 默认值必须前置兼容
虽然 projection 还没有 writer，但 facade 仍要先兼容旧 Node 默认值：
1. dashboard 返回零值
2. wallet ledger 返回空数组
3. play stats 返回零值 + 空数组
这样前端不会因为表暂时为空而收到 `404` 或 `null` 结构漂移。
## 5. SpacetimeDB 表设计
### 5.1 `profile_dashboard_state`
字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `user_id` | `String` | 主键，绑定平台用户 |
| `wallet_balance` | `u64` | 当前钱包余额 |
| `total_play_time_ms` | `u64` | 累积游玩时长 |
| `created_at` | `Timestamp` | projection 首次建立时间 |
| `updated_at` | `Timestamp` | projection 最近刷新时间 |
设计决议：
1. 一名用户只保留一行 dashboard 聚合状态。
2. `playedWorldCount` 不单独持久化，读取时直接统计 `profile_played_world`。
3. 钱包余额与总游玩时长都固定为非负整数，不保留浮点。
### 5.2 `profile_wallet_ledger`
字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `wallet_ledger_id` | `String` | 主键，流水 ID |
| `user_id` | `String` | 用户 ID |
| `amount_delta` | `i64` | 本次余额增减 |
| `balance_after` | `u64` | 变动后的余额 |
| `source_type` | `RuntimeProfileWalletLedgerSourceType` | 当前只冻结 `snapshot_sync` |
| `created_at` | `Timestamp` | 流水发生时间 |
设计决议：
1. 钱包流水是 append-only，不提供 update。
2. 本轮只冻结 `snapshot_sync` 一种来源，避免前后端散落裸字符串。
3. 读取排序由 procedure 保证，不依赖表天然顺序。
### 5.3 `profile_played_world`
字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `played_world_id` | `String` | 主键，固定为 `user_id:world_key` |
| `user_id` | `String` | 用户 ID |
| `world_key` | `String` | 世界唯一键，兼容内置世界与自定义世界 |
| `owner_user_id` | `Option<String>` | 自定义世界作者用户 ID |
| `profile_id` | `Option<String>` | 自定义世界 profile ID |
| `world_type` | `Option<String>` | 内置世界类型，例如 `WUXIA` |
| `world_title` | `String` | 世界标题 |
| `world_subtitle` | `String` | 世界副标题 |
| `first_played_at` | `Timestamp` | 首次游玩时间 |
| `last_played_at` | `Timestamp` | 最近游玩时间 |
| `last_observed_play_time_ms` | `u64` | 最近一次观测到的该世界累计游玩时长 |
设计决议：
1. 每个用户每个 `world_key` 只保留一行。
2. `played_world_id = user_id:world_key`，避免额外自增 ID。
3. `lastObservedPlayTimeMs` 保留在表中，为后续 snapshot sync 计算增量时长服务。
## 6. module-runtime DTO 设计
本轮在 `module-runtime` 新增以下类型族：
1. `RuntimeProfileDashboardSnapshot`
2. `RuntimeProfileDashboardProcedureResult`
3. `RuntimeProfileDashboardGetInput`
4. `RuntimeProfileWalletLedgerEntrySnapshot`
5. `RuntimeProfileWalletLedgerProcedureResult`
6. `RuntimeProfileWalletLedgerListInput`
7. `RuntimeProfilePlayedWorldSnapshot`
8. `RuntimeProfilePlayStatsSnapshot`
9. `RuntimeProfilePlayStatsProcedureResult`
10. `RuntimeProfilePlayStatsGetInput`
同时新增 record 层 DTO，供 `spacetime-client` 返回给 Axum：
1. `RuntimeProfileDashboardRecord`
2. `RuntimeProfileWalletLedgerEntryRecord`
3. `RuntimeProfilePlayedWorldRecord`
4. `RuntimeProfilePlayStatsRecord`
字段规则：
1. 所有时间在 snapshot 内部统一保存为 `*_micros`。
2. record 层统一格式化成 RFC3339 字符串。
3. `updated_at_micros` 使用 `Option<i64>`，避免继续沿用 `0` 这种弱语义占位值。
## 7. Procedure 设计
本轮只新增 3 个只读 procedure：
1. `get_profile_dashboard`
2. `list_profile_wallet_ledger`
3. `get_profile_play_stats`
行为要求：
### 7.1 `get_profile_dashboard`
1. 校验 `user_id` 非空。
2. 读取 `profile_dashboard_state`。
3. 统计当前用户 `profile_played_world` 数量。
4. 如果 dashboard 状态不存在，返回零值快照。
### 7.2 `list_profile_wallet_ledger`
1. 校验 `user_id` 非空。
2. 读取当前用户全部流水。
3. 按 `created_at DESC` 排序。
4. 截断到最近 `50` 条。
### 7.3 `get_profile_play_stats`
1. 校验 `user_id` 非空。
2. 从 `profile_dashboard_state` 读取 `total_play_time_ms` 和 `updated_at`。
3. 读取当前用户 `profile_played_world`。
4. 按 `last_played_at DESC` 排序。
5. 如果 dashboard 状态不存在，仍返回零值与空数组。
## 8. spacetime-client 设计
新增 3 个调用封装：
1. `get_profile_dashboard(user_id)`
2. `list_profile_wallet_ledger(user_id)`
3. `get_profile_play_stats(user_id)`
错误映射保持当前链路习惯：
1. 本地 DTO 构建失败 -> `SpacetimeClientError::Runtime`
2. procedure 执行失败 -> `SpacetimeClientError::Procedure`
不在 client 层做默认值兜底；默认值由 `spacetime-module` procedure 保证，避免多个调用方重复实现。
## 9. Axum facade 设计
### 9.1 路由
本轮 Rust facade 固定暴露 6 条路由：
1. `/api/runtime/profile/dashboard`
2. `/api/profile/dashboard`
3. `/api/runtime/profile/wallet-ledger`
4. `/api/profile/wallet-ledger`
5. `/api/runtime/profile/play-stats`
6. `/api/profile/play-stats`
全部要求 Bearer JWT。
### 9.2 响应结构
1. dashboard 直接返回 `ProfileDashboardSummaryResponse`
2. wallet-ledger 返回 `ProfileWalletLedgerResponse`
3. play-stats 返回 `ProfilePlayStatsResponse`
字段名保持 camelCase，与旧 Node contract 对齐。
### 9.3 错误映射
1. JWT 缺失或失效：沿用现有 `401`
2. 本地 DTO 准备失败：`400`
3. SpacetimeDB 调用失败：`502`
`details.provider` 规则：
1. 本地 DTO 错误使用当前接口自己的 provider
2. 下游 SpacetimeDB 错误统一使用 `spacetimedb`
## 10. 本轮暂不处理的事项
以下事项在本设计中显式延后：
1. `runtime_snapshot` 写入时如何刷新三张 profile projection 表
2. `profile_wallet_ledger` 的更多 `source_type`
3. `profile_played_world` 的世界标题修复、补字段或回填历史迁移
4. `save archive` 与 `play stats` 之间的联动
这些都等 `runtime_snapshot / save archive` 主链文档冻结后继续推进。
## 11. 测试策略
### 11.1 必跑
1. `module-runtime`
- `user_id` 非空校验
- record 层时间格式化
- wallet ledger source type 字符串格式化
2. `shared-contracts`
- dashboard / wallet-ledger / play-stats 的 camelCase 序列化
3. `api-server`
- 未登录返回 `401`
- 6 条 facade 都已挂接
- SpacetimeDB 未发布时返回 `502`
- 主路径与兼容路径错误 envelope 一致
### 11.2 本轮不强制
1. 不强制本地 SpacetimeDB 联调测试
2. 不强制 projection 写入集成测试
原因是这两类测试都依赖后续 `runtime_snapshot` 写链补齐。
## 12. 本文完成定义
当以下条件满足时，本设计文档视为完成：
1. `profile_dashboard_state / profile_wallet_ledger / profile_played_world` 字段与 ID 规则已冻结。
2. `dashboard / wallet-ledger / play-stats` 的 procedure 名、返回结构、排序与默认值已冻结。
3. `api/runtime/*` 与兼容 `/api/profile/*` 双路径已冻结。
4. 可以据此直接开始 `module-runtime`、`shared-contracts`、`spacetime-module`、`spacetime-client`、`api-server` 编码。

276
docs/technical/M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,276 @@
# M3：runtime settings Axum + SpacetimeDB 落地设计
日期：`2026-04-21`
关联任务：
- [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)
- [../../backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md](../../backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md)
关联现状：
- [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
- [NODE_BACKEND_MODULE_AND_API_INDEX.md](./NODE_BACKEND_MODULE_AND_API_INDEX.md)
- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
## 1. 文档目的
`02_M3_RUNTIME_PROFILE.md` 已经冻结了 M3 的任务范围，但还没有把首批可编码切片细化到表字段、procedure、Axum facade、兼容错误格式和测试策略。
本文件只解决 M3 第一批最小纵向切片：
1. `GET /api/runtime/settings`
2. `PUT /api/runtime/settings`
以及其在 Rust 重写中的完整落位：
1. `module-runtime` 的字段约束与 DTO
2. `crates/spacetime-module` 的 `runtime_setting` 表与 procedure
3. `crates/spacetime-client` 的 procedure 调用封装
4. `crates/api-server` 的兼容 facade 与响应 contract
本文件不新增 checklist，不替代 [../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md](../../backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md)，只补足可以直接编码的技术口径。
## 2. 为什么先做 runtime settings
在 M3 范围内，`runtime settings` 是当前最适合先迁移的纵向切片：
1. 读写模型最小，只依赖 `user_id + music_volume + platform_theme`。
2. 旧 Node 逻辑没有跨表聚合、副作用和复杂 projection。
3. 前端 contract 清晰，兼容路径只有一条，不涉及 `/api/profile/*` 双路径。
4. 可以先把 `Axum -> JWT -> SpacetimeDB procedure -> 标准 envelope` 主链跑通，为后续 `browse history / snapshot / save archive / dashboard` 复用。
## 3. 旧实现冻结口径
当前 Node 侧 `runtime settings` 行为来自：
- `server-node/src/routes/rpg-profile/rpgProfileRoutes.ts`
- `server-node/src/repositories/runtimeRepository.ts`
冻结行为如下：
### 3.1 路由
- `GET /api/runtime/settings`
- `PUT /api/runtime/settings`
两条接口都要求 JWT。
### 3.2 请求体
`PUT /api/runtime/settings` 请求体：
```json
{
"musicVolume": 0.42,
"platformTheme": "light"
}
```
校验规则：
1. `musicVolume` 必须在 `0 ~ 1`。
2. `platformTheme` 只接受 `light | dark`。
### 3.3 默认值
默认值来自 `packages/shared/src/contracts/runtime.ts`：
1. `DEFAULT_MUSIC_VOLUME = 0.42`
2. `DEFAULT_PLATFORM_THEME = "light"`
当用户从未写入过设置时，读取接口必须返回默认值，而不是 `404` 或 `null`。
### 3.4 归一化规则
旧 Node 写入时会做以下归一化：
1. `musicVolume` 强制 clamp 到 `0 ~ 1`
2. `platformTheme` 如果不是 `dark`，统一回退到 `light`
Rust 重写阶段仍保持同样语义，避免前端产生行为漂移。
## 4. Rust 落位决议
### 4.1 crate 分工
本切片固定按以下边界落位：
1. `crates/module-runtime`
- 定义 `RuntimeSettings` 领域 DTO、默认值、字段校验与归一化规则。
2. `crates/spacetime-module`
- 定义 `runtime_setting` 表。
- 提供 `upsert_runtime_setting_and_return` procedure。
3. `crates/spacetime-client`
- 提供 `get_runtime_settings`、`put_runtime_settings` 调用封装。
4. `crates/api-server`
- 提供 `GET/PUT /api/runtime/settings`。
- 保持当前 envelope / 错误格式 / 请求头兼容。
### 4.2 身份边界
当前阶段前端仍只访问 Axum，不直连 SpacetimeDB。
因此：
1. 用户身份仍由 Axum 侧 JWT middleware 校验。
2. Axum 从已校验的 access token claims 中取 `user_id`。
3. `user_id` 作为 procedure 入参写入 `runtime_setting`。
注意：
1. 这不是最终的 SpacetimeDB 原生身份透传形态。
2. 在 M3 首批切片里，先以 Axum 作为唯一鉴权边界，保证与当前前端 contract 一致。
## 5. SpacetimeDB 表设计
### 5.1 表名
`runtime_setting`
### 5.2 字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `user_id` | `String` | 主键，绑定平台用户 |
| `music_volume` | `f32` | 音量，持久化归一化后的值 |
| `platform_theme` | `RuntimePlatformTheme` | 平台主题枚举 |
| `created_at` | `Timestamp` | 首次创建时间 |
| `updated_at` | `Timestamp` | 最近更新时间 |
### 5.3 设计决议
1. 每个用户只保留一行设置，不做历史版本表。
2. `user_id` 直接作为主键，避免再引入无业务价值的自增 ID。
3. `platform_theme` 固定为枚举，不把 `light/dark` 继续散落成字符串字面量。
4. 首批阶段不把设置拆成多行 KV 表，避免简单需求被过度抽象。
## 6. Procedure 设计
### 6.1 不单独暴露 reducer 给 Axum
本切片优先提供 procedure，而不是让 Axum 直接调 reducer + 再查询表。
原因：
1. 当前 `spacetime-client` 已经以 procedure 返回结果的模式承接资产链。
2. 设置接口需要同步返回最终写入结果，procedure 可减少一次额外查询。
3. 当前 `runtime_setting` 不需要客户端订阅，private table + procedure 更直接。
### 6.2 Procedure 列表
1. `get_runtime_setting_or_default`
2. `upsert_runtime_setting_and_return`
返回 DTO 固定为：
```text
RuntimeSettingSnapshot {
user_id
music_volume
platform_theme
created_at_micros
updated_at_micros
}
```
如果用户还没有设置记录：
1. `get_runtime_setting_or_default` 返回默认值快照。
2. 但不强制立即插入表，避免纯读取请求制造无意义写入。
## 7. Axum facade 设计
### 7.1 GET /api/runtime/settings
行为：
1. 走 `require_bearer_auth`。
2. 从 `claims.user_id` 取用户 ID。
3. 调 `spacetime_client.get_runtime_settings(user_id)`。
4. 返回：
```json
{
"musicVolume": 0.42,
"platformTheme": "light"
}
```
### 7.2 PUT /api/runtime/settings
行为：
1. 走 `require_bearer_auth`。
2. 使用 Axum `Json` + `serde` 解析请求。
3. 在 `module-runtime` 内做归一化。
4. 调 `spacetime_client.put_runtime_settings(user_id, payload)`。
5. 返回归一化后的最终值。
### 7.3 错误映射
1. 请求体解析失败：`400 BAD_REQUEST`
2. 字段校验失败：`400 BAD_REQUEST`
3. SpacetimeDB 调用失败：`502 BAD_GATEWAY`
4. JWT 缺失或失效：沿用现有 `401 UNAUTHORIZED`
错误 `details.provider` 固定为：
1. `runtime-settings`：本地字段归一化或 DTO 构建失败
2. `spacetimedb`：procedure 调用失败
## 8. 首批测试策略
本切片测试分两层：
### 8.1 必跑测试
1. `module-runtime`
- 默认值
- clamp 规则
- theme 归一化
2. `api-server`
- 未登录返回 `401`
- 请求 envelope 打开时返回标准 `ok/data/error/meta`
- JSON 结构与字段名兼容
### 8.2 可选联调测试
补一条 `#[ignore]` 的集成测试：
1. 需要本地 SpacetimeDB 已启动
2. 需要当前 `spacetime-module` 已发布
3. 验证 `PUT -> GET` 能往返一致
原因：
1. 当前仓库已有资产链的 `#[ignore]` 集成测试模式。
2. 在未稳定建立测试 harness 前，不强制把 SpacetimeDB 作为默认单测前置条件。
## 9. 后续扩展顺序
`runtime settings` 完成后，M3 后续能力按以下顺序推进：
1. `user_browse_history`
2. `runtime_snapshot`
3. `profile_save_archive`
4. `profile_dashboard_state + profile_wallet_ledger + profile_played_world`
顺序原因：
1. `browse_history` 仍是单表为主，只带去重与排序规则。
2. `snapshot` 和 `save_archive` 依赖兼容聚合策略，复杂度更高。
3. `dashboard / play-stats / wallet-ledger` 依赖 projection，更适合放在 snapshot 规则固定后收口。
## 10. 本文完成定义
当以下条件成立时，本设计文档视为完成：
1. `runtime settings` 的字段、默认值、归一化规则、procedure 与 Axum facade 已书面冻结。
2. 后续编码无需再猜测：
- 表字段名
- 主键策略
- 默认值来源
- Axum 与 SpacetimeDB 的职责边界
3. 可以直接据此开始 `module-runtime`、`spacetime-module`、`spacetime-client`、`api-server` 编码。

147
docs/technical/M4_COMBAT_REWARD_INVENTORY_INTEGRATION_2026-04-22.md Normal file
View File

@@ -0,0 +1,147 @@
# M4 Combat Reward Inventory Integration（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结一件事：
**把 `resolve_combat_action(Victory)` 从“只发经验”推进到“经验与战利品可在同一事务内结算”的最小主链口径。**
本轮不回收完整 runtime item 导演层，也不在 `module-combat` 内直接做 AI 语义生成；只承接已经编译好的 reward item 快照。
---
## 1. 本轮落地范围
本轮只落实下面 4 件事：
1. 在 `module-combat` 中为 `battle_state` 补充 `reward_items` 字段。
2. 允许 `BattleStateInput` 在初始化时携带已经编译好的战利品快照。
3. 在 `spacetime-module::resolve_combat_action` 中，当结果为 `Victory` 时同步把 `reward_items` 写入 `inventory_slot`。
4. 保持 `module-combat` 仍然是纯规则 crate，不直接依赖 `module-inventory`。
---
## 2. 当前冻结的战利品口径
### 2.1 `battle_state.reward_items`
首版字段固定复用 `module-runtime-item::RuntimeItemRewardItemSnapshot`。
原因：
1. 宝箱链已经用这套 reward item contract 打通到 `inventory_slot`。
2. 任务奖励当前仍有独立 `QuestRewardItem`，但战斗奖励更接近 runtime item 导演层。
3. 先复用现有 reward item 快照，避免本轮再发明第三套 combat 专属掉落结构。
### 2.2 battle 初始化来源
当前 `battle_state.reward_items` 不在战斗 reducer 内生成，只允许由上游在创建 battle 时传入：
1. `resolve_npc_battle_interaction_and_return`
2. 后续 Axum façade / runtime story orchestration
3. 其它明确的 battle create 聚合入口
也就是说：
1. `module-combat` 只消费已确定的 reward item 快照
2. 不在 reducer 内做随机、提示词、外部世界图谱推导
当前已接通：
1. `resolve_npc_battle_interaction_and_return`
2. `POST /api/story/npc/battle`
3. `POST /api/story/battles`
这几条入口都只负责透传已编译奖励，不负责现场生成掉落。
---
## 3. Victory 发物规则
当 `resolve_combat_action` 结算结果满足：
1. `outcome == Victory`
则 `spacetime-module` 需要继续执行：
1. `experience_reward > 0` 时写 `player_progression / chapter_progression`
2. `reward_items.len() > 0` 时写 `inventory_slot`
### 3.1 发物方式
当前固定规则：
1. 每个 reward item 显式映射成一条 `InventoryMutation::GrantItem`
2. `source_kind = CombatDrop`
3. `source_reference_id = battle_state_id`
4. 同一 `battle_state_id` 只允许发放一次
### 3.2 幂等约束
本轮先采用与 quest / treasure 一致的“按来源引用查重”思路：
1. 若当前 actor 的 `inventory_slot` 中已经存在 `source_reference_id = battle_state_id`
2. 视为该 battle reward 已发放
3. Victory 再次重放时跳过发物，但不影响 battle_state 已收束结果
---
## 4. 与既有链路的边界
### 4.1 与 `module-combat`
`module-combat` 继续只负责：
1. `battle_state` 结构
2. `resolve_combat_action` 状态推进
3. 胜负结果收束
不负责：
1. inventory 写表
2. progression 写表
3. runtime item 生成
### 4.2 与 `module-runtime-item`
本轮不把战斗奖励映射 helper 上提到 `module-runtime-item`。
原因：
1. 当前 `RuntimeItemRewardItemSnapshot -> InventoryItemSnapshot` 的 helper 语义固定为 `TreasureReward`
2. 若直接复用，会把 `source_kind` 写错成 `TreasureReward`
3. 本轮先在 `spacetime-module` 里补一个 combat 专用映射，后续再统一抽象
---
## 5. 当前刻意未做
本轮明确不做下面这些扩张：
1. 不把 Node 版 `monster_drop` AI 导演层整体迁到 Rust
2. 不在 `resolve_npc_battle_interaction_and_return` 里现场计算掉落
3. 不处理 battle reward 的货币、好感、情报
4. 不处理战斗内 `inventory_use`
5. 不把掉落展示或 Battle Reward 面板接到前端
---
## 6. 验证要求
本轮完成后至少执行：
1. `npm run check:encoding`
2. `cargo test -p module-combat --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
3. `cargo check -p module-combat -p spacetime-module --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
---
## 7. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 把 Node 侧 `monster_drop` runtime item 编译逻辑迁到 Rust 聚合层。
2. 视复用收益决定是否把 battle / treasure 的 reward item 归一化 helper 上提到 `module-runtime-item`。
3. 最后再把 battle reward 展示、story patch 和前端接口切到新后端。

306
docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,306 @@
# M4 module-ai Axum facade 设计（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结一件事：
**把已经在 `spacetime-module` 落地的 `module-ai` 任务真相表与最小 procedure / reducer，继续向上接到 `shared-contracts`、`spacetime-client` 与 `api-server`，形成可由 HTTP 直接调用的 AI task mutation facade。**
本轮只做最小同步 mutation 链，不扩到 SSE、真实模型供应商请求或前端订阅。
---
## 1. 本轮要解决的问题
当前仓库已经具备：
1. `module-ai`
- 统一 `AiTaskKind / AiTaskStageKind / AiResultReferenceKind`
- 统一任务、阶段、文本片段、结果引用领域模型
2. `spacetime-module`
- `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference`
- `create / append / complete / attach / fail / cancel` 最小 procedure
- `start_ai_task / start_ai_task_stage` reducer
3. `spacetime-client`
- 已生成 AI 相关 Rust bindings
但当前仍缺三层：
1. `shared-contracts` 还没有 AI task HTTP DTO
2. `spacetime-client` 还没有 AI facade 方法与 record 映射
3. `api-server` 还没有 `/api/ai/tasks*` 路由
因此本轮只补下面三层：
1. `shared-contracts` AI DTO
2. `spacetime-client` AI facade
3. `api-server` AI tasks HTTP route
---
## 2. 当前明确不做的事
本轮明确不做：
1. 不接入真实 `platform-llm` 流式回调
2. 不提供 SSE 增量推送接口
3. 不增加 AI task 查询 / 订阅 projection
4. 不把 story / npc / quest / custom-world 旧入口自动迁到这组新接口
5. 不修改 `spacetime-client/src/module_bindings/*` 生成文件
原因很直接：
1. 当前先把 AI task mutation 的最小 HTTP contract 固定下来
2. SSE 与查询态必须等待后续订阅策略或 query procedure 冻结
3. 业务编排入口切换应该在上层模块各自评估，不在本轮提前硬迁
---
## 3. 路由冻结
本轮首版新增以下路由：
1. `POST /api/ai/tasks`
2. `POST /api/ai/tasks/{taskId}/start`
3. `POST /api/ai/tasks/{taskId}/stages/{stageKind}/start`
4. `POST /api/ai/tasks/{taskId}/chunks`
5. `POST /api/ai/tasks/{taskId}/stages/{stageKind}/complete`
6. `POST /api/ai/tasks/{taskId}/references`
7. `POST /api/ai/tasks/{taskId}/complete`
8. `POST /api/ai/tasks/{taskId}/fail`
9. `POST /api/ai/tasks/{taskId}/cancel`
### 3.1 同步返回路由
当前下列路由走 `procedure`，成功时同步返回 `aiTask` 快照：
1. `POST /api/ai/tasks`
2. `POST /api/ai/tasks/{taskId}/chunks`
3. `POST /api/ai/tasks/{taskId}/stages/{stageKind}/complete`
4. `POST /api/ai/tasks/{taskId}/references`
5. `POST /api/ai/tasks/{taskId}/complete`
6. `POST /api/ai/tasks/{taskId}/fail`
7. `POST /api/ai/tasks/{taskId}/cancel`
其中：
1. `chunks` 额外返回 `aiTextChunk`
2. 其他 mutation 当前只返回 `aiTask`
### 3.2 Accepted 路由
当前下列路由只接 `reducer`，不会同步返回快照：
1. `POST /api/ai/tasks/{taskId}/start`
2. `POST /api/ai/tasks/{taskId}/stages/{stageKind}/start`
因此本轮明确冻结为：
1. HTTP 成功状态码返回 `202 Accepted`
2. body 只返回：
- `accepted`
- `taskId`
- `action`
- `stageKind`（仅 stage start）
3. 不伪装成“已经拿到最新任务快照”
后续如果要让这两条路由也同步返回快照，应先在 `spacetime-module` 增加对应 procedure。
---
## 4. 请求与响应 DTO 冻结
### 4.1 创建任务请求
`POST /api/ai/tasks` 请求体冻结为：
1. `taskKind`
2. `requestLabel`
3. `sourceModule`
4. `sourceEntityId`
5. `requestPayloadJson`
6. `stageKinds`
其中：
1. `taskId` 不接受外部写入，由 Axum 使用 `generate_ai_task_id(nowMicros)` 生成
2. `ownerUserId` 不接受外部写入，必须取自 Bearer token
3. `stageKinds` 为空时，由 `module-ai` 根据 `taskKind.default_stage_blueprints()` 自动补齐默认阶段蓝图
### 4.2 追加文本片段请求
`POST /api/ai/tasks/{taskId}/chunks` 请求体冻结为：
1. `stageKind`
2. `sequence`
3. `deltaText`
### 4.3 完成阶段请求
`POST /api/ai/tasks/{taskId}/stages/{stageKind}/complete` 请求体冻结为：
1. `textOutput`
2. `structuredPayloadJson`
3. `warningMessages`
### 4.4 绑定结果引用请求
`POST /api/ai/tasks/{taskId}/references` 请求体冻结为：
1. `referenceKind`
2. `referenceId`
3. `label`
### 4.5 失败请求
`POST /api/ai/tasks/{taskId}/fail` 请求体冻结为：
1. `failureMessage`
### 4.6 成功响应
本轮统一返回以下 payload：
1. `AiTaskPayload`
2. `AiTaskStagePayload`
3. `AiResultReferencePayload`
4. `AiTextChunkPayload`
5. `AiTaskMutationResponse`
6. `AiTaskAcceptedResponse`
时间字段继续统一为 RFC3339 字符串。
---
## 5. `spacetime-client` 冻结口径
本轮新增以下 facade：
1. `create_ai_task`
2. `start_ai_task`
3. `start_ai_task_stage`
4. `append_ai_text_chunk`
5. `complete_ai_stage`
6. `attach_ai_result_reference`
7. `complete_ai_task`
8. `fail_ai_task`
9. `cancel_ai_task`
### 5.1 输入边界
1. procedure 输入直接复用 `module-ai` 领域输入结构
2. `start_ai_task` 与 `start_ai_task_stage` 直接复用 reducer 输入结构
3. 不让 `api-server` 直接依赖 generated binding 类型
### 5.2 输出边界
`spacetime-client` 新增下列 record，供 `api-server` 直接消费：
1. `AiTaskRecord`
2. `AiTaskStageRecord`
3. `AiTextChunkRecord`
4. `AiResultReferenceRecord`
5. `AiTaskMutationRecord`
字符串字段规范：
1. `taskKind` 使用：
- `story_generation`
- `character_chat`
- `npc_chat`
- `custom_world_generation`
- `quest_intent`
- `runtime_item_intent`
2. `stageKind` 使用 `module-ai::AiTaskStageKind::as_str()`
3. `status` 使用 snake_case
4. `referenceKind` 使用 snake_case
### 5.3 错误映射
AI facade 在 `spacetime-client` 内部按以下规则区分：
1. procedure / reducer 返回的业务拒绝
- 映射为 `SpacetimeClientError::Runtime`
2. SDK 调用、连接、超时、意外缺字段
- 映射为 `Build / Procedure / ConnectDropped / Timeout`
这样 `api-server` 才能稳定把业务错误映射成 `400`。
---
## 6. `api-server` 冻结口径
### 6.1 鉴权与身份
所有 `/api/ai/tasks*` 路由继续统一挂 Bearer 鉴权。
其中：
1. `ownerUserId` 必须来自 `AuthenticatedAccessToken.claims().user_id()`
2. 不接受前端自行写入任务所有者
### 6.2 时间与 ID
以下字段不接受外部写入：
1. `taskId`
2. `createdAtMicros`
3. `startedAtMicros`
4. `completedAtMicros`
统一由 Axum 在请求进入时生成。
### 6.3 字段解析
`api-server` 负责把 HTTP 字符串解析为领域枚举：
1. `taskKind`
2. `stageKind`
3. `referenceKind`
解析失败统一返回 `400`，`details.provider` 分别写：
1. `ai-task`
2. `ai-task-stage`
3. `ai-task-reference`
---
## 7. 错误映射
本轮 AI facade 的错误策略冻结如下：
1. 请求 JSON 非法、路径字段非法、枚举解析失败：`400`
2. `SpacetimeClientError::Runtime(_)`：`400`
3. 其他 `SpacetimeClientError`：`502`
`details.provider` 统一写：
1. 路由入参准备错误：`ai-task`
2. SpacetimeDB 上游错误：`spacetimedb`
---
## 8. 本轮验收口径
满足以下条件，视为本轮 facade 基线完成：
1. `shared-contracts` 已新增 `ai.rs`
2. `spacetime-client` 已新增 AI facade 方法与 record 映射
3. `api-server` 已新增 `ai_tasks.rs`
4. `/api/ai/tasks*` 路由已注册并挂 Bearer 鉴权
5. `cargo fmt -p shared-contracts -p spacetime-client -p api-server` 通过
6. `cargo check -p shared-contracts -p spacetime-client -p api-server` 通过
---
## 9. 下一步建议
本轮完成后，后续最稳的顺序是：
1. 为 `start_ai_task / start_ai_task_stage` 增加同步 procedure
2. 增加 AI task 查询态或订阅 projection
3. 再把 `platform-llm` 流式回调真正接到 `append_ai_text_chunk / complete_ai_stage / fail_ai_task`
4. 最后再把 story / npc / custom-world / quest / runtime-item 的 AI 编排主链逐步切到这组新接口

233
docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,233 @@
# `module-ai` 首版基座设计
日期：`2026-04-21`
## 1. 文档目标
本文只冻结一件事：
**为 `server-rs/crates/module-ai` 建立一套可以直接编码落地的首版领域模型与最小服务边界。**
本轮不做以下内容：
1. 不直接接入真实供应商 SDK。
2. 不在 `SpacetimeDB` 里提前写完整 `ai_task` 表。
3. 不提前改造 `api-server` 的 story/chat/custom world 路由。
本轮只解决两个问题：
1. `module-ai` 不能再停留在“目录占位 + README 口号”状态。
2. 后续 `api-server`、`platform-llm`、`spacetime-module` 接线时，需要先有稳定的任务、阶段、流式片段、结果引用领域模型可复用。
## 2. 依据
本文以以下现有文档和代码为准：
1. [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
2. [NODE_BACKEND_MODULE_AND_API_INDEX.md](./NODE_BACKEND_MODULE_AND_API_INDEX.md)
3. [EXPRESS_BACKEND_TASK4_AI_ORCHESTRATION_STATUS_2026-04-08.md](./EXPRESS_BACKEND_TASK4_AI_ORCHESTRATION_STATUS_2026-04-08.md)
4. `server-node/src/modules/ai/storyOrchestrator.ts`
5. `server-node/src/modules/ai/chatOrchestrator.ts`
6. `server-node/src/modules/ai/customWorldOrchestrator.ts`
## 3. 现状问题
当前 `server-rs/crates/module-ai` 只有 README，占位描述虽然说明了“AI 编排模块”的方向，但还缺失编码级约束：
1. 没有任务主键、阶段主键、结果引用 ID 的统一前缀。
2. 没有 story/chat/custom world/quest/runtime-item 六类任务的共用枚举。
3. 没有“排队中/运行中/已完成/失败/已取消”的状态模型。
4. 没有“流式片段如何暂存与聚合”的领域对象。
5. 没有“结果引用”与“最终文本/结构化结果”的最小抽象。
6. 没有可供 `api-server` 直接依赖的最小内存服务。
如果继续在没有这层基座的前提下直接接 `platform-llm` 或 `api-server`，后续很容易再次把：
1. 阶段枚举散落在 handler 里，
2. 流式文本拼接散落在路由里，
3. 结果引用结构散落在 story/custom-world/quest 各模块里。
## 4. 首版职责冻结
`module-ai` 首版只负责以下职责：
1. 定义统一 AI 任务类型、任务状态、阶段状态、任务快照。
2. 定义统一流式片段、阶段输出、结果引用、最终结果快照。
3. 提供最小编排服务，支持：
- 创建任务
- 启动任务
- 记录阶段开始/完成
- 追加流式文本片段
- 绑定结果引用
- 成功完成 / 失败 / 取消
4. 提供一套内存态 store，作为 `api-server` 首轮联调和测试 fallback。
`module-ai` 首版明确不负责：
1. 真实 HTTP 请求、重试、超时和供应商切换。
2. SSE 协议写回。
3. 数据库存储与表结构。
4. 业务模块自己的 prompt 组装细节。
## 5. 任务类型范围
首版统一冻结以下任务类型：
1. `StoryGeneration`
2. `CharacterChat`
3. `NpcChat`
4. `CustomWorldGeneration`
5. `QuestIntent`
6. `RuntimeItemIntent`
说明：
1. 这 6 类直接来自当前 Node 后端已经存在的正式运行时 AI 主链。
2. 不提前引入媒体类资产生成任务，因为资产生成后续归 `module-assets + platform-oss` 主导。
3. 如果后续要增加 `NarrativeRepair`、`ProfileRepair` 这类内部子任务，应作为新枚举值追加，不复用现有值的语义。
## 6. 阶段模型
首版阶段固定支持以下通用阶段语义：
1. `PreparePrompt`
2. `RequestModel`
3. `RepairResponse`
4. `NormalizeResult`
5. `PersistResult`
说明：
1. 不是每种任务都必须走满 5 个阶段。
2. 任务创建时应携带自己的阶段蓝图，按需要裁剪。
3. 阶段蓝图是显示给上层 orchestration 的稳定数据，不把“阶段名字符串”重新散落到 handler。
首版建议默认蓝图：
| 任务类型 | 默认阶段 |
| --- | --- |
| `StoryGeneration` | `PreparePrompt` -> `RequestModel` -> `RepairResponse` -> `NormalizeResult` |
| `CharacterChat` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
| `NpcChat` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
| `CustomWorldGeneration` | `PreparePrompt` -> `RequestModel` -> `RepairResponse` -> `NormalizeResult` -> `PersistResult` |
| `QuestIntent` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
| `RuntimeItemIntent` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
## 7. 结果模型
首版结果拆成三层：
### 7.1 流式片段
用于记录模型增量输出：
1. `chunk_id`
2. `task_id`
3. `stage_kind`
4. `sequence`
5. `delta_text`
6. `created_at_micros`
这层只负责“增量片段”，不直接宣称是最终结果。
### 7.2 阶段输出
用于记录阶段收口后的聚合内容：
1. `stage_kind`
2. `text_output`
3. `structured_payload_json`
4. `warning_messages`
### 7.3 结果引用
用于让 AI 编排结果和其他模块的记录形成稳定绑定：
1. `result_ref_id`
2. `task_id`
3. `reference_kind`
4. `reference_id`
5. `label`
首版 `reference_kind` 冻结为：
1. `StorySession`
2. `StoryEvent`
3. `CustomWorldProfile`
4. `QuestRecord`
5. `RuntimeItemRecord`
6. `AssetObject`
## 8. 服务边界
首版 `AiTaskService` 只暴露纯领域操作，不直接暴露供应商能力：
1. `create_task`
2. `start_task`
3. `start_stage`
4. `append_text_chunk`
5. `complete_stage`
6. `attach_result_reference`
7. `complete_task`
8. `fail_task`
9. `cancel_task`
10. `get_task`
这层返回的都是领域快照，不返回 HTTP DTO。
## 9. 与其他 crate 的边界
### 9.1 与 `platform-llm`
`platform-llm` 负责：
1. 真实模型请求
2. 流式回调
3. 超时 / 重试 / 供应商错误
`module-ai` 负责：
1. 把这些外部回调映射为任务快照与阶段快照
2. 把供应商响应组织成稳定的模块领域状态
### 9.2 与 `api-server`
`api-server` 负责：
1. HTTP 入参校验
2. SSE 输出
3. Bearer/Cookie 鉴权
4. response envelope
`module-ai` 不负责 HTTP。
### 9.3 与 `spacetime-module`
后续 `spacetime-module` 负责：
1. 任务真相表
2. 阶段表 / 事件表 / 结果引用表
3. reducer / procedure
本轮 `module-ai` 只提供后续可映射到 SpacetimeDB 的稳定领域结构。
## 10. 首版编码要求
首版 crate 必须满足：
1. 提供 `Cargo.toml`
2. 提供 `src/lib.rs`
3. 默认不依赖 `platform-llm`
4. 默认不依赖 `SpacetimeDB`
5. 可选提供 `spacetime-types` feature，便于后续映射表结构
6. 提供完整中文注释与基础测试
## 11. 本轮验收口径
本轮完成后，以下条件同时满足才算 `module-ai` 首版落地：
1. `server-rs/Cargo.toml` 已把 `module-ai` 纳入 workspace。
2. `module-ai` 不再只有 README，而是有真实可编译源码。
3. 任务/阶段/结果引用/流式片段领域模型已存在。
4. 有最小内存服务可供后续 `api-server` 直接复用。
5. 至少有任务创建、流式片段聚合、阶段完成、结果引用绑定、任务失败/取消等测试。

266
docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,266 @@
# M4 module-ai SpacetimeDB 基座记录（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只记录一件事：
**把 `module-ai` 从“只有领域模型和内存态服务”推进到“SpacetimeDB 侧已有最小 AI 任务真相表与 procedure 骨架”的真实落地结果。**
本轮只做最小可编译基座，不扩到真实模型请求、SSE 输出或前端订阅联调。
---
## 1. 本轮落地范围
本轮只落实下面 5 件事：
1. 在 `server-rs/crates/module-ai/` 中补齐面向 `SpacetimeDB` 接线的输入类型。
2. 在 `server-rs/crates/spacetime-module/` 中新增 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 四张 private 表。
3. 在 `spacetime-module` 中新增 AI 任务的最小 reducer / procedure。
4. 把 `module-ai` 的领域快照与 `SpacetimeDB` 行结构之间的转换 helper 固定下来。
5. 补充 crate README 与技术索引，明确当前 AI 真相源边界。
---
## 2. 新增的真实工程落点
### 2.1 `module-ai`
1. `server-rs/crates/module-ai/src/lib.rs`
- 补充 `AiTaskStartInput`
- 补充 `AiTaskStageStartInput`
- 补充 `AiTextChunkAppendInput`
- 补充 `AiResultReferenceInput`
- 补充 `AiTaskFinishInput`
- 补充 `AiTaskCancelInput`
- 补充 `AiTaskFailureInput`
- 补充 `AI_TASK_STAGE_ID_PREFIX`
- 补充 `AiTaskStageKind::as_str()`
- 补充 `generate_ai_task_stage_id()`
### 2.2 `spacetime-module`
1. `server-rs/crates/spacetime-module/src/lib.rs`
- 新增 `ai_task`
- 新增 `ai_task_stage`
- 新增 `ai_text_chunk`
- 新增 `ai_result_reference`
- 新增 `create_ai_task`
- 新增 `create_ai_task_and_return`
- 新增 `start_ai_task`
- 新增 `start_ai_task_stage`
- 新增 `append_ai_text_chunk_and_return`
- 新增 `complete_ai_stage_and_return`
- 新增 `attach_ai_result_reference_and_return`
- 新增 `complete_ai_task_and_return`
- 新增 `fail_ai_task_and_return`
- 新增 `cancel_ai_task_and_return`
---
## 3. 当前冻结的数据口径
### 3.1 `ai_task`
当前首版字段冻结为：
1. `task_id`
2. `task_kind`
3. `owner_user_id`
4. `request_label`
5. `source_module`
6. `source_entity_id`
7. `request_payload_json`
8. `status`
9. `failure_message`
10. `latest_text_output`
11. `latest_structured_payload_json`
12. `version`
13. `created_at`
14. `started_at`
15. `completed_at`
16. `updated_at`
当前策略：
1. `ai_task` 只保留任务级聚合字段，不在单行内嵌套 `Vec<stage>`。
2. 阶段、增量文本、结果引用全部拆到独立表，避免后续更新整行大对象。
3. `version` 继续沿用 `module-ai` 的任务快照版本语义。
### 3.2 `ai_task_stage`
当前首版字段冻结为：
1. `task_stage_id`
2. `task_id`
3. `stage_kind`
4. `label`
5. `detail`
6. `order`
7. `status`
8. `text_output`
9. `structured_payload_json`
10. `warning_messages`
11. `started_at`
12. `completed_at`
当前策略：
1. 一条 stage 一行。
2. `task_stage_id` 使用 `generate_ai_task_stage_id(task_id, stage_kind)`，保持同任务内幂等。
3. 当前不单独存“阶段版本”，统一归任务版本递增。
### 3.3 `ai_text_chunk`
当前首版字段冻结为：
1. `text_chunk_row_id`
2. `chunk_id`
3. `task_id`
4. `stage_kind`
5. `sequence`
6. `delta_text`
7. `created_at`
当前策略：
1. `chunk_id` 保留领域侧 ID 语义。
2. 表级主键使用 `text_chunk_row_id`，避免 `generate_ai_text_chunk_id(seed, sequence)` 在不同任务之间碰撞。
3. 流式文本聚合结果仍写回 `ai_task_stage.text_output` 和 `ai_task.latest_text_output`。
### 3.4 `ai_result_reference`
当前首版字段冻结为：
1. `result_reference_row_id`
2. `result_ref_id`
3. `task_id`
4. `reference_kind`
5. `reference_id`
6. `label`
7. `created_at`
当前策略：
1. `result_ref_id` 保留领域侧 ID 语义。
2. 表级主键使用 `result_reference_row_id`，避免只按时间种子生成的领域 ID 在并发情况下直接作为主键带来碰撞风险。
---
## 4. 当前 reducer / procedure 口径
### 4.1 `create_ai_task`
当前负责：
1. 校验 `AiTaskCreateInput`
2. 拒绝重复 `task_id`
3. 写入 `ai_task`
4. 按蓝图写入 `ai_task_stage`
### 4.2 `start_ai_task`
当前负责：
1. 校验目标任务存在
2. 把 `ai_task.status` 从 `Pending` 推进到 `Running`
3. 填充 `started_at`
### 4.3 `start_ai_task_stage`
当前负责：
1. 校验目标任务与目标阶段存在
2. 推进任务为 `Running`
3. 推进对应 stage 为 `Running`
### 4.4 `append_ai_text_chunk_and_return`
当前负责：
1. 校验任务与阶段存在
2. 追加 `ai_text_chunk`
3. 按 `task_id + stage_kind + sequence` 聚合文本
4. 回写 `ai_task_stage.text_output`
5. 回写 `ai_task.latest_text_output`
### 4.5 `complete_ai_stage_and_return`
当前负责：
1. 更新 stage 状态、阶段输出、warning 列表
2. 回写 `ai_task.latest_text_output`
3. 回写 `ai_task.latest_structured_payload_json`
4. 递增任务版本
### 4.6 `attach_ai_result_reference_and_return`
当前负责：
1. 追加 `ai_result_reference`
2. 更新任务 `updated_at`
3. 递增任务版本
### 4.7 `complete_ai_task_and_return`
当前负责：
1. 推进任务为 `Completed`
2. 填充 `completed_at`
### 4.8 `fail_ai_task_and_return`
当前负责：
1. 推进任务为 `Failed`
2. 写入 `failure_message`
3. 填充 `completed_at`
### 4.9 `cancel_ai_task_and_return`
当前负责：
1. 推进任务为 `Cancelled`
2. 填充 `completed_at`
---
## 5. 当前刻意未做
本轮明确没有扩到以下范围：
1. 还没有做 AI 任务公开订阅表。
2. 还没有做 `api-server` 的 AI facade 路由。
3. 还没有做 `platform-llm` 真实流式回调接线。
4. 还没有做 story / custom-world / quest / runtime-item 对 AI 任务的自动建链。
5. 还没有做清理旧任务、旧 chunk 的 schedule reducer。
也就是说，本轮只是把 AI 任务真相表和最小写入口立起来，不宣称已经完成 AI runtime 主链迁移。
---
## 6. 当前边界判断
当前仍保持以下职责划分：
1. `module-ai`
- 负责领域模型、校验、快照结构与最小内存服务。
2. `spacetime-module`
- 负责任务真相表、事务性持久化与 procedure 聚合返回。
3. `platform-llm`
- 后续负责真实模型调用、超时、重试、供应商错误。
4. `api-server`
- 后续负责 HTTP / SSE / 鉴权与外部 contract。
---
## 7. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 先把 `platform-llm` 的文本网关正式接到 `append_ai_text_chunk_and_return / complete_ai_stage_and_return`。
2. 再给 `api-server` 增加 AI 任务 facade，把 HTTP/SSE 对外 contract 冻结下来。
3. 再把 story、custom-world、quest、runtime-item 各自的 AI 编排入口切到 `module-ai + spacetime-module`。
4. 最后再根据订阅需求评估是否补 public projection 表或事件表。

251
docs/technical/M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,251 @@
# M4 module-combat Axum facade 设计（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只冻结一件事：
**把已经完成 reducer 化的 `module-combat` 再向上接一层最小同步返回链，让 `api-server` 可以显式创建战斗、推进单次战斗动作，并立即拿到 battle 快照结果。**
这份文档不是完整 `runtime story actions/resolve` 兼容方案，也不替代后续的 `resolve_story_action` 编排设计。
---
## 1. 本轮要解决的问题
当前 `module-combat` 已具备：
1. `battle_state` 真相表
2. `create_battle_state` reducer
3. `resolve_combat_action` reducer
4. `fight / spar` 两种模式下的纯规则推进
但当前仍缺一层明确能力：
1. Axum 还不能同步拿到 battle 快照
2. `spacetime-client` 还没有 battle procedure 调用封装
3. `api-server` 还没有独立的战斗 facade
因此本轮只补下面三层：
1. `spacetime-module` battle procedure
2. `spacetime-client` battle procedure 调用与返回值映射
3. `api-server` 最小战斗 HTTP facade
---
## 2. 当前明确不做的事
本轮刻意不做：
1. 不兼容旧 `POST /api/runtime/story/actions/resolve`
2. 不兼容旧 `GET /api/runtime/story/state/:sessionId`
3. 不把 `inventory_use` 提前接回战斗主链
4. 不把 `quest / progression / npc / story_event` 自动联动写回
5. 不把 battle 直接拼进 `RuntimeStoryActionResponse`
原因很直接：
1. 这些属于更高层的 runtime story 编排问题
2. 当前 battle 子域应该先把“独立可调用、同步可返回”这一层固定下来
3. 先补 procedure + facade，后续 `resolve_story_action` 才有稳定下游可调入口
---
## 3. `spacetime-module` 的新增口径
### 3.1 reducer 继续保留
已有 reducer 继续保留：
1. `create_battle_state`
2. `resolve_combat_action`
职责不变：
1. reducer 仍然只负责 battle 真相写入
2. reducer 不直接向调用方返回业务快照
### 3.2 新增 procedure
本轮新增两个 procedure：
1. `create_battle_state_and_return`
2. `resolve_combat_action_and_return`
职责冻结如下：
1. procedure 只包一层 `try_with_tx`
2. procedure 内部复用 reducer 共享的写入 helper
3. procedure 负责把最终 `battle_state` 或 `resolve result` 同步返回给 Axum
### 3.3 返回类型
本轮冻结两种返回 DTO：
1. `BattleStateProcedureResult`
2. `ResolveCombatActionProcedureResult`
字段口径统一为：
1. `ok`
2. `snapshot` 或 `result`
3. `error_message`
这样能与现有 `story / treasure / npc` procedure 返回风格保持一致。
---
## 4. `spacetime-client` 的新增口径
`spacetime-client` 本轮新增两条最小调用链：
1. `create_battle_state`
2. `resolve_combat_action`
调用策略继续沿用当前已验证模式：
1. 先建立 `DbConnection`
2. 等待 `on_connect`
3. 再调用对应 procedure
4. 统一经 `oneshot + timeout` 收口结果
当前不做：
1. battle 订阅
2. battle cache 读模型
3. battle 长连接复用策略
---
## 5. `api-server` 的新增 facade 口径
### 5.1 路由
本轮新增两条最小路由：
1. `POST /api/story/battles`
2. `POST /api/story/battles/resolve`
这两条路由的定位不是旧 runtime 兼容层，而是：
1. 面向新 Rust 后端内部联调
2. 面向后续 `resolve_story_action` 编排层调用
### 5.2 `POST /api/story/battles`
请求体只提交 battle 建立所需的业务字段：
1. `storySessionId`
2. `runtimeSessionId`
3. `targetNpcId`
4. `targetName`
5. `battleMode`
6. `playerHp`
7. `playerMaxHp`
8. `playerMana`
9. `playerMaxMana`
10. `targetHp`
11. `targetMaxHp`
由 Axum 自动补齐：
1. `battleStateId`
2. `actorUserId`
3. `createdAtMicros`
响应返回：
1. `battleState`
### 5.3 `POST /api/story/battles/resolve`
请求体只提交单次动作推进所需字段：
1. `battleStateId`
2. `functionId`
3. `actionText`
4. `baseDamage`
5. `manaCost`
6. `heal`
7. `manaRestore`
8. `counterMultiplierBasisPoints`
由 Axum 自动补齐：
1. `updatedAtMicros`
响应返回：
1. `battleState`
2. `combat`
其中 `combat` 至少包含：
1. `damageDealt`
2. `damageTaken`
3. `outcome`
---
## 6. 认证与字段真相边界
### 6.1 `actorUserId`
`actorUserId` 不接受前端自填。
必须由：
1. `AuthenticatedAccessToken`
2. `claims.user_id`
直接生成。
### 6.2 时间字段
`createdAtMicros` 与 `updatedAtMicros` 不接受外部写入。
必须由 Axum 在请求时生成，原因如下：
1. 避免客户端伪造 battle 创建时间
2. 保持 Rust 后端各 facade 的时间字段风格一致
3. 让后续 battle / story / npc 联调时便于统一日志与排障
---
## 7. 错误映射口径
当前 battle facade 的错误映射冻结如下：
1. battle mode 非法、请求 JSON 非法、字段校验失败：`400`
2. `SpacetimeClientError::Runtime(_)`：`400`
3. 其他 `SpacetimeClientError`：`502`
返回 `details.provider` 统一写：
1. battle 输入准备错误：`story-battle`
2. SpacetimeDB 上游错误：`spacetimedb`
---
## 8. 本轮验收
满足以下条件，视为本轮 facade 基线完成：
1. `module-combat` 已新增 procedure 返回 DTO
2. `spacetime-module` 已新增 `create_battle_state_and_return`
3. `spacetime-module` 已新增 `resolve_combat_action_and_return`
4. `spacetime-client` 已可同步创建战斗并推进单次动作
5. `api-server` 已新增两条最小 battle facade 路由
6. `cargo check -p module-combat -p spacetime-client -p api-server -p spacetime-module` 通过
---
## 9. 下一步建议
本轮完成后，后续最稳的顺序是：
1. 把 battle facade 接入 `resolve_story_action`
2. 设计 battle 结束后的 `story_event` 追加口径
3. 再把 `quest / progression / inventory` 的联动收回到显式子域流程里

336
docs/technical/M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,336 @@
# M4 module-combat SpacetimeDB 基线设计（2026-04-21）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结一件事：
**把 `module-combat` 从“只有 README 占位”推进到“首版 battle_state 与 resolve_combat_action 可真实编码、可编译、可继续扩展”的工程基线。**
本轮不宣称完成完整 `runtime story action` 迁移，也不把 `inventory / npc / story AI 续写` 直接耦进战斗 reducer；跨子域写入继续收敛在 `spacetime-module` 聚合层。
---
## 1. 本轮落地范围
本轮只做下面 5 件事：
1. 新增 `server-rs/crates/module-combat/` 真实 crate。
2. 冻结 `battle_state` 的首版领域类型、枚举、输入结构与字段校验 helper。
3. 冻结 `resolve_combat_action` 的首版输入、输出与纯规则推进逻辑。
4. 在 `server-rs/crates/spacetime-module/` 中新增 `battle_state` 表。
5. 在 `spacetime-module` 中新增 `create_battle_state`、`resolve_combat_action` 两个 reducer。
---
## 2. 当前冻结的实现边界
### 2.1 首版必须支持的战斗 function
首版与 [../prd/AI_NATIVE_BATTLE_SINGLE_ACTION_FUNCTION_PRD_2026-04-18.md](../prd/AI_NATIVE_BATTLE_SINGLE_ACTION_FUNCTION_PRD_2026-04-18.md) 保持一致，只支持以下单行为入口：
1. `battle_attack_basic`
2. `battle_recover_breath`
3. `battle_use_skill`
4. `battle_escape_breakout`
5. 旧兼容攻击类：
- `battle_all_in_crush`
- `battle_guard_break`
- `battle_probe_pressure`
- `battle_feint_step`
- `battle_finisher_window`
本轮刻意不接入：
1. `inventory_use`
2. 技能与物品的正式外部明细读取
3. 与 `quest_record`、`npc_state` 的联动写入
4. 脱战后 `story_event` 追加与 AI 续写触发
### 2.2 为什么先不做 `inventory_use`
当前 Rust 侧还没有 `inventory_slot` 正式表，也没有稳定的战斗内物品快照输入。
如果现在把 `inventory_use` 硬塞进 `module-combat`，只会出现两种坏结果：
1. reducer 内部引入并不存在的 inventory 真相依赖；
2. 退回成“让 Axum 先算完再写 battle_state”的伪迁移。
因此本轮明确冻结为：
1. `module-combat` 先完成纯战斗状态推进；
2. `inventory_use` 留到 `inventory_slot` 与 runtime snapshot projection 口径稳定后再接。
---
## 3. `battle_state` 首版字段
首版 `battle_state` 冻结为以下字段：
1. `battle_state_id`
2. `story_session_id`
3. `runtime_session_id`
4. `actor_user_id`
5. `target_npc_id`
6. `target_name`
7. `battle_mode`
8. `status`
9. `player_hp`
10. `player_max_hp`
11. `player_mana`
12. `player_max_mana`
13. `target_hp`
14. `target_max_hp`
15. `chapter_id`
16. `experience_reward`
17. `reward_items`
18. `turn_index`
19. `last_action_function_id`
20. `last_action_text`
21. `last_result_text`
22. `last_damage_dealt`
23. `last_damage_taken`
24. `last_outcome`
25. `version`
26. `created_at`
27. `updated_at`
### 3.1 设计意图
首版只解决下面这些真相问题：
1. 当前战斗是否存在、是否仍在进行中；
2. 玩家与当前目标的 HP / MP 最小数值状态；
3. 当前是 `fight` 还是 `spar`；
4. 当前战斗归属哪个章节；
5. 本场战斗若胜利应发多少经验；
6. 本场战斗若胜利应发哪些已编译好的 reward item；
7. 最近一次动作结算了什么；
8. 当前 battle reducer 是否发生过版本推进。
### 3.2 当前刻意不放入的字段
本轮明确不放：
1. 多目标列表
2. 技能冷却 map
3. build buff 详情
4. 掉落预算、好感预算、剧情上下文大对象
5. 大型 `rawGameState` 镜像字段
原因很直接：这些都属于后续跨子域联动层，不适合在 `battle_state` 首版里重新堆一个大 JSON。
---
## 4. 枚举与动作口径
### 4.1 `BattleMode`
只保留两种：
1. `Fight`
2. `Spar`
### 4.2 `BattleStatus`
只保留三种：
1. `Ongoing`
2. `Resolved`
3. `Aborted`
说明：
1. `Resolved` 表示战斗已正常收束，包括胜利、切磋结束、成功逃脱。
2. `Aborted` 预留给后续 session 中断、外部清理、投影回滚等异常收束场景。
### 4.3 `CombatOutcome`
首版冻结：
1. `Ongoing`
2. `Victory`
3. `SparComplete`
4. `Escaped`
这与当前共享契约里的 `RuntimeBattlePresentation.outcome` 一致，避免首版就制造新的枚举翻译成本。
---
## 5. `resolve_combat_action` 首版规则
### 5.1 输入
首版 reducer 输入只包含：
1. `battle_state_id`
2. `function_id`
3. `action_text`
4. `base_damage`
5. `mana_cost`
6. `heal`
7. `mana_restore`
8. `counter_multiplier`
9. `updated_at_micros`
### 5.2 为什么允许输入 `base_damage`
本轮 `module-combat` 的职责是把战斗推进规则固定到 SpacetimeDB。
但玩家技能、装备 build、物品 buff、成长曲线这些正式真相仍未迁完，因此首版允许上游把已算好的 `base_damage / mana_cost / heal / mana_restore` 作为确定输入传进 reducer。
这意味着当前模块边界是：
1. `module-combat` 负责状态推进、反击、逃跑、战斗收束规则；
2. 更高层的 build / skill / item 数值来源仍可在后续模块中逐步收敛；
3. 等 `inventory / progression / runtime build` 真相表稳定后，再继续把这些输入收得更窄。
### 5.3 动作规则
#### A. `battle_escape_breakout`
直接结束战斗：
1. `status = Resolved`
2. `last_outcome = Escaped`
3. `last_damage_dealt = 0`
4. `last_damage_taken = 0`
#### B. `battle_recover_breath`
恢复类动作：
1. 玩家回复 `heal`
2. 玩家回复 `mana_restore`
3. 若战斗仍持续，则按 `counter_multiplier` 吃一次敌方反击
#### C. `battle_attack_basic` / 旧兼容攻击类 / `battle_use_skill`
攻击类动作：
1. 目标扣除 `base_damage`
2. 若目标已收束，则按 `battle_mode` 进入 `Victory / SparComplete`
3. 若目标未收束，则玩家按 `counter_multiplier` 吃一次敌方反击
### 5.4 反击规则
首版固定：
1. `fight` 下敌方基础反击伤害 = `max(4, round(target_max_hp * 0.14 * counter_multiplier))`
2. `spar` 下敌方基础反击伤害固定为 `1`
这是对当前 Node 逻辑的直接收敛，先保证行为方向不漂移，不在本轮发明新的战斗公式。
### 5.5 HP 下限规则
1. `fight` 下正常下限为 `0`
2. `spar` 下双方 HP 最低保留为 `1`
这样能保留当前“切磋点到为止”的旧行为，不把 `spar` 错结算成死亡战斗。
---
## 6. `spacetime-module` 接线口径
### 6.1 battle_state 表
`spacetime-module` 首版只新增一张 private 真相表：
1. `battle_state`
建议索引：
1. `by_story_session_id`
2. `by_runtime_session_id`
3. `by_actor_user_id`
### 6.2 reducer
当前仍只保留两个战斗 reducer：
1. `create_battle_state`
2. `resolve_combat_action`
职责：
1. `create_battle_state` 只负责插入 battle 真相，不负责故事会话编排。
2. `resolve_combat_action` 负责推进 battle 真相。
3. 当 `Victory` 收束时，由 `spacetime-module` 聚合层继续把 `experience_reward` 联动写入 `player_progression / chapter_progression`。
4. 当 `Victory` 收束且 `reward_items` 非空时，由 `spacetime-module` 聚合层继续把战利品写入 `inventory_slot`。
5. `resolve_combat_action` 仍不负责 AI 续写和 quest signal 全量分发。
---
## 7. 与后续子域的边界
### 7.1 与 `story`
当前关系：
1. `story` 负责更高层 action 路由与后续 story_event 追加；
2. `combat` 只返回 battle 真相推进结果。
后续再补：
1. 战斗结束时的 `story_event`
2. 脱战后的 `continue_story` / `resolve_story_action`
### 7.2 与 `inventory`
当前不直接耦合到 `module-combat` reducer。
后续再补：
1. 战斗内 `inventory_use`
2. 消耗品扣减
3. 战斗 buff 写入
当前已存在的聚合层联动：
1. `Victory` 时可把 `battle_state.reward_items` 写入 `inventory_slot`
### 7.3 与 `progression`
当前不直接在 `module-combat` reducer 内发经验与等级变更。
后续再补：
1. hostile scaling 与 reward 编译口径
当前已存在的聚合层联动：
1. `fight_victory` 的经验发放
2. 章节账本写入
### 7.4 与 `npc`
当前不直接改好感。
后续再补：
1. `spar_complete` 的 affinity 变化
2. `fight / spar` 与 encounter 状态同步
---
## 8. 本轮验收口径
满足以下条件，视为本轮 `module-combat` 基线完成：
1. `server-rs/crates/module-combat` 已从 README 占位升级为真实 crate。
2. `battle_state`、`BattleMode`、`BattleStatus`、`CombatOutcome`、`ResolveCombatActionInput` 已冻结到代码。
3. `spacetime-module` 已新增 `battle_state` 表。
4. `spacetime-module` 已新增 `create_battle_state` 与 `resolve_combat_action` reducer。
5. `cargo check -p module-combat -p spacetime-module` 通过。
---
## 9. 下一步建议
在本轮基线稳定后，下一步按以下顺序推进最稳：
1. 设计 `inventory_slot` 与战斗内 `inventory_use` 的最小真相输入。
2. 设计 `resolve_story_action` 如何编排 `story + combat + npc + quest + inventory`。
3. 把 `battle_state` 结束事件接入 `story_event`。
4. 再把 Axum facade 与 `RuntimeStoryActionResponse.battle` 真正打通。

202
docs/technical/M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,202 @@
# M4 module-combat battle state 查询设计（2026-04-22）
更新时间：`2026-04-22`
补充状态：`2026-04-22`
当前 battle query 纵切片已经完成到“真实可编译、可生成 binding、可被 Axum 调用”的状态：
1. `spacetime-module` 中的 `get_battle_state` procedure 已稳定存在。
2. `spacetime-client/src/module_bindings` 已重新执行 `spacetime generate`，当前已真实包含：
- `battle_state_query_input_type`
- `get_battle_state_procedure`
- `battle_state.reward_items` 对应字段
3. `spacetime-client/src/lib.rs` 里原本返回“binding 尚未生成”的占位 `get_battle_state(...)` 已替换为真实 procedure 调用。
4. `cargo check -p spacetime-client` 与 `cargo check -p api-server` 已再次通过。
当前仍未完成的只有长时回归验证：
1. `cargo test -p api-server --bin api-server story_battles --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 在当前机器上编译耗时较长，尚未在单次时窗内拿到最终断言结果。
2. `npm run check:encoding` 已启动但尚未在单次时窗内跑完。
## 0. 文档目标
本文件只冻结当前 `M4` 的一个最小新增切片：
**新增 `GET /api/story/battles/:battleStateId`，让 Axum 能从 `SpacetimeDB` 同步读取单个 `battle_state` 当前快照，不提前承诺旧 runtime story state 兼容。**
这轮目标不是实现旧 `GET /api/runtime/story/state/:sessionId` 的战斗子视图兼容，也不是把 `battle + story_event + currentStory` 一次性收口进 `resolve_story_action`。
---
## 1. 为什么先补这个切片
当前 battle 链路已经具备：
1. `module-combat` 已冻结 `battle_state` 领域类型与纯结算规则。
2. `spacetime-module` 已有 `create_battle_state_and_return`、`resolve_combat_action_and_return`。
3. `spacetime-client` 与 `api-server` 已能创建战斗并推进单次动作。
但现在仍缺一个最基本的恢复能力：
1. battle 建立后，Axum 还不能按 `battle_state_id` 重新读取真相态。
2. 页面刷新、重连或后续 story 编排都缺一个稳定的单战斗查询入口。
3. 后续若要把 battle 收口进 `resolve_story_action`，也需要先有独立 battle query 可复用。
因此本轮先补最小 `battle state` 查询切片，不提前跳到更重的 runtime story 兼容。
---
## 2. 当前冻结范围
本轮只包含以下能力：
1. 新增公开接口：`GET /api/story/battles/:battleStateId`
2. 认证方式：Bearer JWT
3. 数据来源：`SpacetimeDB procedure get_battle_state`
4. 返回体只包含：
- `battleState`
本轮明确不做：
1. 不兼容旧 `GET /api/runtime/story/state/:sessionId`
2. 不补 battle 列表查询
3. 不做 `battle_state` 订阅与 cache 读模型
4. 不在查询链路里拼装 `story_event / npc / quest / inventory`
5. 不把 battle query 直接拼回旧 `RuntimeStoryActionResponse`
---
## 3. 接口 contract
### 3.1 请求
- 方法：`GET`
- 路径：`/api/story/battles/:battleStateId`
- 认证：必须携带 Bearer JWT
- 路径参数：
- `battleStateId`：目标战斗状态 ID
### 3.2 成功响应
成功响应延续当前 `api-server` 统一 envelope，`data` 字段结构为：
```json
{
"battleState": {
"battleStateId": "battle_xxx",
"storySessionId": "storysess_xxx",
"runtimeSessionId": "runtime_xxx",
"actorUserId": "user_xxx",
"chapterId": "chapter_xxx",
"targetNpcId": "npc_xxx",
"targetName": "黑爪狼",
"battleMode": "fight",
"status": "ongoing",
"playerHp": 42,
"playerMaxHp": 60,
"playerMana": 12,
"playerMaxMana": 20,
"targetHp": 18,
"targetMaxHp": 30,
"experienceReward": 18,
"rewardItems": [],
"turnIndex": 1,
"lastActionFunctionId": "battle_attack_basic",
"lastActionText": "普通攻击",
"lastResultText": "普通攻击命中了黑爪狼，本次攻击已经完成结算。",
"lastDamageDealt": 12,
"lastDamageTaken": 4,
"lastOutcome": "ongoing",
"version": 2,
"createdAt": "2026-04-22T00:00:00.000000Z",
"updatedAt": "2026-04-22T00:01:00.000000Z"
}
}
```
### 3.3 错误响应
当前延续 battle facade 已有策略：
1. `SpacetimeClientError::Runtime(_)` 映射为 `400`
2. 其他 `SpacetimeClientError` 映射为 `502`
3. 错误 `details.provider` 固定为 `spacetimedb`
---
## 4. 分层职责
### 4.1 `module-combat`
职责：
1. 冻结 `BattleStateQueryInput`
2. 负责 query input builder 与 validator
3. 继续复用 `BattleStateProcedureResult` 作为最小查询返回壳
不负责：
1. HTTP 路径解析
2. JWT 鉴权
3. battle view model 编译
### 4.2 `spacetime-module`
职责：
1. 读取 `battle_state`
2. 校验 `battle_state_id`
3. 返回单个 `BattleStateSnapshot`
### 4.3 `spacetime-client`
职责：
1. 构造 `BattleStateQueryInput`
2. 调用 `get_battle_state`
3. 把 generated binding 结果映射为 `BattleStateRecord`
当前实现补充：
1. `reward_items` 已按 generated binding 映射回 `BattleStateRecord.reward_items`，不再用空集合占位。
2. battle query 当前不再依赖 façade stub 或手写假返回。
### 4.4 `api-server`
职责：
1. 暴露 `GET /api/story/battles/:battleStateId`
2. 做 Bearer JWT 鉴权
3. 透传 `battleStateId`
4. 把 `BattleStateRecord` 映射到 battle JSON payload
---
## 5. 验收口径
本轮验收只要求以下几点：
1. `api-server` 路由树已真实挂出该接口
2. 未登录访问返回 `401`
3. 在 `SpacetimeDB` 未发布或未连通时返回 `502`
4. `cargo test -p api-server story_battles` 可通过
5. `cargo check -p module-combat -p spacetime-module -p spacetime-client -p api-server` 可通过
6. `npm run check:encoding` 已执行，确保新增中文文档没有编码损坏
当前验证状态：
1. 第 5 条已达成。
2. 第 4、6 条仍在继续追，不应提前宣称通过。
---
## 6. 后续边界
这条最小 battle query 落地后，后续再继续拆下一层：
1. 评估 battle 查询是否需要补 actor ownership 校验
2. 设计 battle 结束事件如何接入 `story_event`
3. 再把 battle query 与 `story state / resolve_story_action / currentStory` 汇总到更高层编排
在这些 contract 未冻结前，不应把当前接口误称为“旧 runtime story state 已迁移完成”。

188
docs/technical/M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,188 @@
# M4 module-npc battle Axum facade 设计（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结一件事：
**把已经在 `spacetime-module` 落地的 `resolve_npc_battle_interaction_and_return` procedure 再向上接到 `spacetime-client` 与 `api-server`，并允许 HTTP 侧透传已编译好的 `experience_reward / reward_items`，形成可直接调用的 NPC 开战同步返回链。**
这不是完整 `resolve_story_action` 兼容设计，也不替代后续 runtime story 总入口编排。
---
## 1. 本轮要解决的问题
当前仓库已经具备：
1. `module-npc`
- `resolve_npc_interaction`
- `npc_fight / npc_spar -> BattlePending`
2. `module-combat`
- `battle_state`
- `resolve_combat_action`
3. `spacetime-module`
- `resolve_npc_battle_interaction_and_return`
- 同事务写入 `npc_state + battle_state`
但当前仍缺两层：
1. `spacetime-client` 还没有对应 facade
2. `api-server` 还没有独立 NPC 开战 HTTP 入口
因此本轮只补下面两层：
1. `spacetime-client` facade
2. `api-server` HTTP route
---
## 2. 当前刻意不做的事
本轮明确不做：
1. 不兼容旧 `POST /api/runtime/story/actions/resolve`
2. 不把 `npc_chat / npc_help / npc_recruit / npc_leave` 一起搬成统一 HTTP facade
3. 不在接口层现场计算章节自动定级、经验奖励、掉落、story_event 自动联动
4. 不把 battle 结果直接拼进旧 `RuntimeStoryActionResponse`
原因很直接：
1. 这轮目标只是把 `npc_fight / npc_spar` 的同步返回链闭环
2. 更高层 story action 编排仍应等待 `resolve_story_action` 统一设计
---
## 3. `spacetime-client` 口径
### 3.1 新增 facade
本轮新增：
1. `resolve_npc_battle_interaction`
### 3.2 输入
直接复用 `spacetime-module` procedure 输入：
1. `ResolveNpcBattleInteractionInput`
客户端 facade 负责：
1. 调 `resolve_npc_battle_interaction_and_return`
2. 把 binding 结果映射成 Rust record
3. 统一沿用现有 `oneshot + timeout` 返回模式
### 3.3 输出
本轮冻结新的 client record：
1. `NpcStateRecord`
2. `NpcInteractionRecord`
3. `NpcBattleInteractionRecord`
这样可以避免 `api-server` 直接依赖 generated binding 结构。
---
## 4. `api-server` 口径
### 4.1 路由
本轮新增：
1. `POST /api/story/npc/battle`
这条路由的定位是：
1. 独立的 NPC 开战 facade
2. 明确只处理 `npc_fight / npc_spar`
3. 返回：
- `npcInteraction`
- `battleState`
### 4.2 输入
首版 HTTP 请求字段冻结为：
1. `storySessionId`
2. `runtimeSessionId`
3. `npcId`
4. `npcName`
5. `interactionFunctionId`
- 当前只允许：
- `npc_fight`
- `npc_spar`
6. `releaseNpcId`
7. `battleStateId`
8. `playerHp`
9. `playerMaxHp`
10. `playerMana`
11. `playerMaxMana`
12. `targetHp`
13. `targetMaxHp`
14. `experienceReward`
- 默认 `0`
- 只接受上游已编译好的确定值
15. `rewardItems`
- 默认空数组
- 每项字段与 `RuntimeItemRewardItemSnapshot` 对齐
- `rarity` 固定使用：
- `common`
- `uncommon`
- `rare`
- `epic`
- `legendary`
- `equipmentSlotId` 当前只允许：
- `weapon`
- `armor`
- `relic`
### 4.3 返回
当前 HTTP 成功响应冻结为：
1. `npcInteraction`
2. `battleState`
其中：
1. `npcInteraction` 保留：
- `npcState`
- `interactionStatus`
- `actionText`
- `resultText`
- `storyText`
- `battleMode`
- `encounterClosed`
- `affinityChanged`
- `previousAffinity`
- `nextAffinity`
2. `battleState` 继续复用 battle facade 已有 payload 结构
---
## 5. 错误策略
与现有 `story_battles` / `story_sessions` 保持一致：
1. `SpacetimeClientError::Runtime`
- 映射 `400`
2. 其他 Spacetime 调用错误
- 映射 `502`
错误 body 继续统一返回：
1. `provider`
2. `message`
---
## 6. 后续建议
在这条 facade 稳定后，下一步按下面顺序推进：
1. 让前端 runtime story action 先走这条独立 NPC 开战入口
2. 再把 battle 初始化所需的 NPC 等级、经验奖励、reward item 编译来源、章节信息收口进更高层编排
3. 最后再统一进完整 `resolve_story_action`

151
docs/technical/M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,151 @@
# M4 module-npc 与 module-combat 联合编排基线（2026-04-21）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结一件事：
**在不污染 `module-npc` 纯领域边界的前提下，把 `npc_fight / npc_spar` 从“只返回 `BattlePending` 语义”推进到“可在 `spacetime-module` 聚合层同步创建 `battle_state`”的最小联合编排口径。**
这不是完整 `resolve_story_action` 设计，也不是完整战斗奖励编译、经验预算和剧情续写迁移。
---
## 1. 本轮落地范围
本轮只落实下面 4 件事：
1. 明确 `module-npc` 继续只负责 NPC 交互语义，不直接依赖 `module-combat`。
2. 在 `spacetime-module` 聚合层新增 `resolve_npc_battle_interaction_and_return` procedure。
3. 让该 procedure 在同一事务内完成：
- `resolve_npc_interaction`
- `battle_state` 初始化写入
4. 返回统一结果，供后续 `spacetime-client` / Axum facade 直接消费。
---
## 2. 为什么不把 battle 初始化塞进 module-npc
原因很直接：
1. `module-npc` 当前职责是 `npc_state / relation_state / stance_profile / interaction contract`。
2. `battle_state` 属于 `module-combat` 真相，不应倒灌进 NPC 领域 crate。
3. 如果把玩家 HP / MP、战斗生命、故事会话 ID 这些字段直接塞进 `ResolveNpcInteractionInput`，会把 `module-npc` 再次膨胀成跨子域入口。
因此本轮明确冻结为：
1. `module-npc`
- 继续只返回 `BattlePending + battle_mode`
2. `spacetime-module`
- 负责把 NPC 交互结果编排成真正的 `battle_state`
---
## 3. 新增 procedure 口径
### 3.1 名称
新增：
1. `resolve_npc_battle_interaction_and_return`
### 3.2 输入
首版输入冻结为：
1. `npc_interaction`
- 原样复用 `ResolveNpcInteractionInput`
- 当前只允许 `npc_fight / npc_spar`
2. `story_session_id`
3. `actor_user_id`
4. `battle_state_id`
- 允许为空
- 为空时按 `updated_at_micros` 自动派生
5. `player_hp`
6. `player_max_hp`
7. `player_mana`
8. `player_max_mana`
9. `target_hp`
10. `target_max_hp`
11. `experience_reward`
- 由上游作为已编译好的确定奖励透传
- 当前允许为 `0`
12. `reward_items`
- 类型固定为 `Vec<module-runtime-item::RuntimeItemRewardItemSnapshot>`
- 只承接已经编译好的战利品快照，不在 procedure 内现场生成
### 3.3 输出
当前返回：
1. `interaction`
- `module-npc::NpcInteractionResult`
2. `battle_state`
- `module-combat::BattleStateSnapshot`
也就是说，这个 procedure 明确是一个**聚合返回口径**，不是新的底层领域真相。
---
## 4. 当前事务流程
单次调用按下面顺序执行：
1. 校验 `story_session_id / actor_user_id`
2. 校验 `interaction_function_id` 必须是：
- `npc_fight`
- `npc_spar`
3. 先执行 `resolve_npc_interaction_record`
- 写入最新 `npc_state`
- 拿到 `NpcInteractionResult`
4. 从 `NpcInteractionResult.battle_mode` 映射出 `BattleMode`
5. 组装 `BattleStateInput`
- 透传 `experience_reward`
- 透传 `reward_items`
6. 复用 `module-combat` 的 `validate_battle_state_input`
7. 插入 `battle_state`
8. 返回：
- `interaction`
- `battle_state`
---
## 5. 当前刻意未做
本轮明确不做下面这些扩张：
1. 不在这个 procedure 里直接发经验
2. 不在这个 procedure 里直接记 `chapter_progression`
3. 不在这个 procedure 里直接写 `story_event`
4. 不在这个 procedure 里现场计算掉落或经验预算
5. 不在这个 procedure 里直接执行 `inventory_slot` 发物
5. 不在这个 procedure 里直接接 `resolve_combat_action`
6. 不在这个 procedure 里推导敌方等级、强度、掉落预算
也就是说，这一层当前只解决：
**NPC 宣告开战后，如何立刻把 battle 真相表连同已编译奖励真相一起建立起来。**
---
## 6. 与现有文档的关系
本文件是对下面两份基线文档的补充，而不是替代：
1. `M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md`
- 继续定义 NPC 领域 contract
2. `M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md`
- 继续定义 battle_state 与单行为战斗推进规则
新增编排只发生在 `spacetime-module` 聚合层。
---
## 7. 下一步建议
在这条最小联合编排稳定后，后续按下面顺序推进最稳：
1. 把 Node 侧 `monster_drop` / hostile reward 编译逻辑收口到 Rust 聚合层。
2. 再把章节自动定级、敌对经验预算和 `chapter_progression` 所需章节上下文收口进 battle 初始化编译器。
3. 最后把这条链收口进完整 `resolve_story_action`。

273
docs/technical/M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,273 @@
# 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。

174
docs/technical/M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,174 @@
# M4 Module Progression SpacetimeDB 基座记录（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只记录一件事：
**把 `module-progression` 从“只有 README 占位”推进到“SpacetimeDB 侧已有最小可编译成长真相基座”的真实落地结果。**
本轮先落等级/经验/章节计划与记账的最小领域骨架，并补上任务交付与战斗胜利的自动联动；不扩到完整 `custom-world` 章节蓝图编译或 Axum facade 全链迁移。
---
## 1. 本轮落地范围
本轮按 `LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md` 与 `SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md` 的交叉口径，只落实下面 6 件事：
1. 新增 `server-rs/crates/module-progression/` 真实 crate，而不是继续停留在 README 占位。
2. 在 `module-progression` 中冻结 `LevelBenchmark`、`PlayerProgressionSnapshot`、`ChapterProgressionSnapshot`、`RuntimeEntityLevelProfile` 的首版领域类型。
3. 在 `module-progression` 中落地与当前 Node 版一致的等级经验曲线、参考强度曲线、章节 pseudo level 曲线与敌对战斗 fallback 规则。
4. 在 `server-rs/crates/spacetime-module/` 中新增 `player_progression`、`chapter_progression` 两张表。
5. 在 `spacetime-module` 中新增 `get_player_progression_or_default`、`grant_player_progression_experience`、`upsert_chapter_progression`、`apply_chapter_progression_ledger_entry` 及对应 procedure。
6. 用 `module-story / module-quest` 同口径方式，把成长状态固定成“单用户成长表 + 单章节计划/记账表”的最小可编译基座。
---
## 2. 本轮新增的真实工程落点
### 2.1 新增 crate
1. `server-rs/crates/module-progression/Cargo.toml`
2. `server-rs/crates/module-progression/src/lib.rs`
### 2.2 workspace 与主工程聚合
1. `server-rs/Cargo.toml`
- 已把 `crates/module-progression` 纳入 workspace members
2. `server-rs/crates/spacetime-module/Cargo.toml`
- 已接入 `module-progression` 依赖
3. `server-rs/crates/spacetime-module/src/lib.rs`
- 已接入 `module-progression` 类型
- 已新增 `player_progression`
- 已新增 `chapter_progression`
- 已新增成长相关 reducer / procedure
---
## 3. 当前冻结的数据口径
### 3.1 `player_progression`
当前首版字段冻结为：
1. `user_id`
2. `level`
3. `current_level_xp`
4. `total_xp`
5. `xp_to_next_level`
6. `pending_level_ups`
7. `last_granted_source`
8. `created_at`
9. `updated_at`
当前策略：
1. `player_progression` 保持 private 真相表口径。
2. 当前统一按 `user_id` 单行持久化，不在本轮拆历史 grant 日志表。
3. 若记录不存在，`procedure` 返回 `Lv.1 / 0 XP` 默认快照，但不额外写库。
### 3.2 `chapter_progression`
当前首版字段冻结为：
1. `chapter_progression_id`
2. `user_id`
3. `chapter_id`
4. `chapter_index`
5. `total_chapters`
6. `entry_pseudo_level_millis`
7. `exit_pseudo_level_millis`
8. `entry_level`
9. `exit_level`
10. `planned_total_xp`
11. `planned_quest_xp`
12. `planned_hostile_xp`
13. `actual_quest_xp`
14. `actual_hostile_xp`
15. `expected_hostile_defeat_count`
16. `actual_hostile_defeat_count`
17. `level_at_entry`
18. `level_at_exit`
19. `pace_band`
20. `created_at`
21. `updated_at`
当前策略：
1. `chapter_progression` 先用一张表同时承接 `ChapterProgressionPlan` 与 `ChapterExperienceLedger`。
2. 当前不再额外拆计划表和记账表，避免首轮 schema 还没稳定就二次改表。
3. 主键固定为 `user_id + chapter_id` 组合衍生 ID，保证同一玩家每章只有一条真相记录。
---
## 4. 当前 reducer / procedure 口径
### 4.1 `get_player_progression_or_default`
当前负责：
1. 按 `user_id` 读取 `player_progression`
2. 若不存在则返回默认 `Lv.1 / 0 XP`
3. 不产生额外写入
### 4.2 `grant_player_progression_experience`
当前负责：
1. 读取当前 `player_progression`，不存在则按默认成长态开始
2. 根据 `PlayerProgressionGrantInput` 发放经验
3. 统一更新 `level / current_level_xp / total_xp / xp_to_next_level / pending_level_ups`
4. 固定 `last_granted_source`
### 4.3 `upsert_chapter_progression`
当前负责：
1. 写入或覆盖某玩家某章节的计划快照
2. 固定章节预算、目标等级带与预期击杀数
3. 把实际记账字段初始化为 `0`
### 4.4 `apply_chapter_progression_ledger_entry`
当前负责：
1. 在已存在的章节计划上累计 `actual_quest_xp`
2. 累计 `actual_hostile_xp`
3. 累计 `actual_hostile_defeat_count`
4. 可选更新 `level_at_exit`
---
## 5. 当前刻意未做
本轮明确没有扩到以下范围：
1. 还没有把 `sceneChapterBlueprints` 的完整编译逻辑迁到 Rust。
2. 还没有落 `repeatPenalty`、超预算衰减与章节偏差评级输出。
3. 还没有把完整章节蓝图、掉落和全量 quest signal 都自动串进 `player_progression / chapter_progression`。
4. 还没有新增 Axum 的 progression facade。
5. 还没有把前端 `Lv.` 展示、任务奖励经验提示或敌对等级徽标切到 Rust 后端真相源。
也就是说，本轮只是把 `module-progression` 的 SpacetimeDB 成长基座立起来，不宣称已经完成成长系统迁移。
---
## 6. 验证要求
本轮工程变更完成后，至少执行下面两类验证：
1. `npm run check:encoding`
2. `cargo test -p module-progression`
3. `cargo check -p spacetime-module`
---
## 7. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 先把章节预算编译从 Node `chapterProgressionPlanner` 平移到 Rust 领域层。
2. 再把 `npc` / `combat` 入口改为消费 `RuntimeEntityLevelProfile` 和 `chapter_progression`。
3. 再把掉落、任务物品、好感奖励并入统一奖励结算。
4. 最后再接 Axum facade、兼容 DTO 与前端成长主链。

154
docs/technical/M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md Normal file
View File

@@ -0,0 +1,154 @@
# M4 成长与 quest/combat 联动设计（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只冻结一件事：
**把 `player_progression / chapter_progression` 从“可单独调用的成长基座”推进到“任务交付与战斗胜利可自动写入的最小联动闭环”。**
本轮只落 `turn_in_quest` 和 `resolve_combat_action(Victory)` 两条经验链，不扩到完整章节蓝图 Rust 化、掉落分配、好感奖励或前端展示切换。
---
## 1. 本轮联动范围
本轮只接下面两条确定链路：
1. `turn_in_quest` 成功后，把 `quest_record.reward.experience` 发放到 `player_progression`。
2. `resolve_combat_action` 结算为 `Victory` 后，把 `battle_state.experience_reward` 发放到 `player_progression`。
补充规则：
1. 若存在 `chapter_id`，同时尝试把经验记到 `chapter_progression` 账本。
2. 若对应 `chapter_progression` 不存在，联动必须静默跳过，不能让任务交付或战斗结算失败。
3. `SparComplete`、`Escaped`、`Ongoing` 都不发经验。
---
## 2. `turn_in_quest` 联动口径
### 2.1 经验来源
任务交付经验固定读取：
1. `quest_record.reward.experience.unwrap_or(0)`
### 2.2 成长写入
当经验值 `> 0` 时，`spacetime-module::turn_in_quest` 需要在任务状态切换为 `TurnedIn` 后调用：
1. `upsert_player_progression_after_grant_tx`
写入参数固定为：
1. `user_id = next.actor_user_id`
2. `amount = reward_experience`
3. `source = PlayerProgressionGrantSource::Quest`
4. `updated_at_micros = next.updated_at_micros`
### 2.3 章节账本写入
若 `next.chapter_id` 存在，则在成长写入后继续尝试调用章节账本 helper：
1. `granted_quest_xp = reward_experience`
2. `granted_hostile_xp = 0`
3. `hostile_defeat_increment = 0`
4. `level_at_exit = Some(updated_player.level)`
若章节记录不存在：
1. 静默跳过
2. 保留任务交付成功
3. 不把“章节计划尚未初始化”视为任务错误
---
## 3. `resolve_combat_action` 联动口径
### 3.1 battle_state 新增字段
为避免在 reducer 里临时反查外部上下文，本轮给 `BattleStateInput / BattleStateSnapshot / battle_state` 表补两个最小字段：
1. `chapter_id: Option<String>`
2. `experience_reward: u32`
设计意图：
1. `chapter_id` 决定战斗胜利时是否记章节账本。
2. `experience_reward` 作为已编译好的确定奖励，避免本轮就把章节蓝图和敌对档位计算重新耦回 battle reducer。
### 3.2 胜利经验发放
当 `resolve_combat_action` 返回：
1. `CombatOutcome::Victory`
则 `spacetime-module` 需要继续执行：
1. `upsert_player_progression_after_grant_tx`
写入参数固定为：
1. `user_id = result.snapshot.actor_user_id`
2. `amount = result.snapshot.experience_reward`
3. `source = PlayerProgressionGrantSource::HostileNpc`
4. `updated_at_micros = result.snapshot.updated_at_micros`
补充规则：
1. 只有 `experience_reward > 0` 时才真正写成长表。
2. `SparComplete` 不发经验，因为切磋不算敌对击杀。
### 3.3 章节账本写入
若 `result.snapshot.chapter_id` 存在，且本次为 `Victory`，则继续尝试：
1. `granted_quest_xp = 0`
2. `granted_hostile_xp = experience_reward`
3. `hostile_defeat_increment = 1`
4. `level_at_exit = Some(updated_player.level)`
同样地，若章节记录不存在：
1. 静默跳过
2. 仍保留 battle_state 的正常收束结果
---
## 4. reducer 分层约束
本轮保持以下分层不变：
1. `module-combat` 仍只承接纯战斗状态推进，不直接依赖 `module-progression`。
2. `module-quest` 仍只承接纯任务状态流转，不直接依赖 `module-progression`。
3. 真正的跨域写入统一放在 `crates/spacetime-module` reducer / transaction helper 中完成。
这样做的原因是：
1. 领域 crate 保持纯规则，便于后续单测和重用。
2. SpacetimeDB 事务内的表写顺序集中在同一层，避免跨 crate 重复持久化策略。
---
## 5. 本轮明确不做
本轮明确不扩到以下内容：
1. 还不把 battle reward 在 reducer 内现场计算为经验值。
2. 还不把 `quest` 奖励里的物品、货币、好感奖励统一并入同一事务。
3. 还不把 `quest signal` 自动从战斗/剧情全量分发到任务系统。
4. 还不把 `chapter_progression` 缺失时自动补建计划记录。
---
## 6. 验证要求
本轮变更完成后，至少执行：
1. `npm run check:encoding`
2. `cargo test -p module-combat`
3. `cargo test -p module-progression`
4. `cargo test -p module-quest`
5. `cargo check -p spacetime-module`

156
docs/technical/M4_RPG_RUNTIME_INVENTORY_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,156 @@
# M4 RPG Runtime Inventory SpacetimeDB 基座记录（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只记录一件事：
**把 `module-inventory` 从“只有 README 占位”推进到“已有首版背包领域契约、SpacetimeDB `inventory_slot` 真相表与 `apply_inventory_mutation` reducer”的真实落地结果。**
本轮目标不是一次性迁完 Node 版所有背包玩法，而是先把后续 `story / quest / runtime-item / npc` 都能稳定复用的最小背包真相源立起来。
---
## 1. 本轮落地范围
本轮只落实下面 4 件事：
1. 新增 `server-rs/crates/module-inventory/` 真实 crate，而不是继续停留在 README 占位。
2. 在 `module-inventory` 中冻结 `inventory_slot`、`apply_inventory_mutation` 的首版领域类型、输入输出和字段校验 helper。
3. 在 `server-rs/crates/spacetime-module/` 中新增 `inventory_slot` 表。
4. 在 `spacetime-module` 中新增 `apply_inventory_mutation` reducer，形成最小可编译背包主链。
---
## 2. 当前冻结的数据口径
### 2.1 `inventory_slot`
当前首版字段冻结为：
1. `slot_id`
2. `runtime_session_id`
3. `story_session_id`
4. `actor_user_id`
5. `container_kind`
6. `slot_key`
7. `item_id`
8. `category`
9. `name`
10. `description`
11. `quantity`
12. `rarity`
13. `tags`
14. `stackable`
15. `stack_key`
16. `equipment_slot_id`
17. `source_kind`
18. `source_reference_id`
19. `created_at`
20. `updated_at`
当前策略：
1. `inventory_slot` 采用“单槽位即单真相行”的口径，不再把背包塞回 runtime snapshot 大 JSON。
2. `Backpack / Equipment` 统一进同一张表，通过 `container_kind + slot_key` 区分容器和装备位。
3. 首版堆叠不再依赖 Node 版的隐式 heuristic，统一冻结为 `stackable + stack_key` 显式口径。
### 2.2 `apply_inventory_mutation`
当前首版只支持 4 类 mutation：
1. `GrantItem`
2. `ConsumeItem`
3. `EquipItem`
4. `UnequipItem`
当前策略：
1. `GrantItem` 负责发放新物品，并在 `Backpack` 内按 `stack_key` 合并可堆叠物品。
2. `ConsumeItem` 负责安全扣减堆叠数量，数量归零时删除槽位。
3. `EquipItem` 负责把背包中的可装备物品移动到目标装备位，并自动把原装备挪回背包。
4. `UnequipItem` 负责把装备位物品退回背包。
---
## 3. 当前刻意未做
本轮明确没有扩到以下范围：
1. 还没有落 `UseItem / Craft / Dismantle / Reforge` 这类更高阶背包动作。
2. `quest_turn_in` 奖励物品链当前已进入聚合 reducer 接线，但 `npc_trade`、`npc_gift` 仍未落专属 reducer。
3. 当前已经补上最小同步查询切片 `GET /api/runtime/sessions/:runtimeSessionId/inventory`，
但还没有落背包 public view，也没有让前端直读 `inventory_slot`。
4. 还没有把 Node 版 `inventoryMutationService.ts` 整体迁到 Rust，只先冻结首版真相表和最小规则。
也就是说，本轮只是把 `module-inventory` 的基座立起来，不宣称已经完成完整背包玩法迁移。
---
## 4. 关键规则冻结
### 4.1 非堆叠物品固定单槽位单数量
当前规则：
1. `stackable = false` 的物品必须固定 `quantity = 1`。
2. 可装备物品固定 `equipment_slot_id != None` 且必须 `stackable = false`。
3. 后续如果要支持“同名但独立词缀装备”，继续沿用“一件装备一条 `inventory_slot`”。
### 4.2 装备切换不引入新真相副本
当前规则：
1. 装备和卸下都只是在同一条 `inventory_slot` 上切换 `container_kind + slot_key`。
2. 遇到同装备位冲突时，原装备直接回到 `Backpack`，不额外创建临时副本。
3. 这样后续做 Axum façade 或前端 view 时，可以稳定用 `slot_id` 追踪同一件物品。
### 4.3 背包真相优先，展示读模型后置
当前规则：
1. `module-inventory` 只负责状态真相与 mutation 规则。
2. 若后续需要“前端背包列表”“装备面板读模型”，优先通过 `view` 或 Axum façade 暴露。
3. 不新增第二份背包真相副本，也不回退到多个 service 各自改 JSON。
---
## 5. 本轮新增的真实工程落点
### 5.1 新增 crate
1. `server-rs/crates/module-inventory/Cargo.toml`
2. `server-rs/crates/module-inventory/src/lib.rs`
### 5.2 workspace 与主工程聚合
1. `server-rs/Cargo.toml`
- 已把 `crates/module-inventory` 纳入 workspace members
2. `server-rs/crates/spacetime-module/Cargo.toml`
- 已接入 `module-inventory` 依赖
3. `server-rs/crates/spacetime-module/src/lib.rs`
- 已接入 `module-inventory` 类型
- 已新增 `inventory_slot`
- 已新增 `apply_inventory_mutation`
---
## 6. 验证目标
本轮应至少验证：
1. `module-inventory` crate 可以独立 `cargo check / cargo test`
2. `spacetime-module` 能成功编译并接入新表与 reducer
3. 不会把现有中文内容写坏，编码检查继续通过
---
## 7. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 在 `module-inventory` 中继续补 `UseItem / Craft / Dismantle / Reforge` 对应的纯规则契约。
2. 继续把 `npc_trade / npc_gift / runtime-item` 发物链改成显式调用 `apply_inventory_mutation`，并补齐 quest / treasure 之外的奖励入口。
3. 在最小同步查询切片稳定后，再评估是否继续补 `inventory view`、旧前端背包读模型兼容或 public subscription。
4. 最后再把 Node 版 `inventoryMutationService.ts` 的玩法细节逐步迁走。

204
docs/technical/M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,204 @@
# 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 与前端任务主链。

171
docs/technical/M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,171 @@
# M4 RPG Runtime Story Session State Query 设计（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结当前 `M4` 的一个最小新增切片：
**新增 `GET /api/story/sessions/:storySessionId/state`，让 Axum 能从 `SpacetimeDB` 同步读取 `story session` 当前快照与事件流，不提前承诺旧 `runtime story state` 兼容。**
本轮目标不是实现旧 `GET /api/runtime/story/state/:sessionId` 的等价替换，也不是把 `resolve_story_action`、`currentStory`、`view model compiler` 一次性补齐。
---
## 1. 为什么先做这个切片
当前仓库里已经有三块能力先行落地：
1. `module-story` 已有 `StorySessionStateInput`、`StorySessionStateRecord` 与 builder / validator。
2. `spacetime-module` 已有 `get_story_session_state` procedure，可在单次事务内返回 `story_session + story_events`。
3. `spacetime-client`、`shared-contracts`、`api-server/story_sessions.rs` 已存在大部分适配代码。
真正缺的是：
1. 把这条查询链路正式挂到 Axum 路由树。
2. 用文档明确当前只开放“真相态查询”，不误导为旧 runtime story 状态恢复已完成。
因此本轮选择先把最小查询切片收口，而不是直接跳到更重的旧接口兼容。
---
## 2. 当前冻结范围
本轮只包含以下能力：
1. 新增公开接口：`GET /api/story/sessions/:storySessionId/state`
2. 认证方式：Bearer JWT
3. 数据来源：`SpacetimeDB procedure get_story_session_state`
4. 返回体只包含：
- `storySession`
- `storyEvents`
本轮明确不做：
1. 不兼容旧 `GET /api/runtime/story/state/:sessionId`
2. 不补 `POST /api/runtime/story/state/resolve`
3. 不返回旧 `RuntimeStoryViewModel`
4. 不回填旧 `currentStory`
5. 不拼装 `availableOptions / presentation / patch`
6. 不在查询链路里混入 `npc / quest / combat / inventory` 聚合快照
---
## 3. 接口 contract
### 3.1 请求
- 方法：`GET`
- 路径：`/api/story/sessions/:storySessionId/state`
- 认证：必须携带 Bearer JWT
- 路径参数：
- `storySessionId`：目标故事会话 ID
### 3.2 成功响应
成功响应延续当前 `api-server` 统一 envelope，`data` 字段结构为：
```json
{
"storySession": {
"storySessionId": "storysess_xxx",
"runtimeSessionId": "runtime_xxx",
"actorUserId": "user_xxx",
"worldProfileId": "profile_xxx",
"initialPrompt": "进入营地",
"openingSummary": "营地开场",
"latestNarrativeText": "你看见篝火边有人招手。",
"latestChoiceFunctionId": "talk_to_npc",
"status": "active",
"version": 2,
"createdAt": "2026-04-22T00:00:00.000000Z",
"updatedAt": "2026-04-22T00:01:00.000000Z"
},
"storyEvents": [
{
"eventId": "storyevt_xxx",
"storySessionId": "storysess_xxx",
"eventKind": "story_continued",
"narrativeText": "你看见篝火边有人招手。",
"choiceFunctionId": "talk_to_npc",
"createdAt": "2026-04-22T00:01:00.000000Z"
}
]
}
```
### 3.3 错误响应
当前延续 story session facade 已有策略：
1. `SpacetimeClientError::Runtime(_)` 映射为 `400`
2. 其他 `SpacetimeClientError` 映射为 `502`
3. 错误 `details.provider` 固定为 `spacetimedb`
---
## 4. 分层职责
### 4.1 `module-story`
职责：
1. 冻结 `StorySessionStateInput`
2. 冻结 `StorySessionStateRecord`
3. 负责 builder、validator 与 record 映射
不负责：
1. HTTP 参数解析
2. JWT 鉴权
3. 旧前端 view model 编译
### 4.2 `spacetime-module`
职责：
1. 读取 `story_session`
2. 读取同一 `story_session_id` 下的 `story_event`
3. 按时间与 `event_id` 排序
4. 返回最小 `StorySessionStateProcedureResult`
### 4.3 `spacetime-client`
职责：
1. 构造 `StorySessionStateInput`
2. 调用 `get_story_session_state`
3. 把 generated binding 结果映射为 `StorySessionStateRecord`
### 4.4 `api-server`
职责：
1. 暴露 `GET /api/story/sessions/:storySessionId/state`
2. 做 Bearer JWT 鉴权
3. 透传 `storySessionId`
4. 把 `StorySessionStateRecord` 映射到 `StorySessionStateResponse`
---
## 5. 验收口径
本轮验收只要求以下几点：
1. `api-server` 路由树已真实挂出该接口
2. 未登录访问返回 `401`
3. 在 `SpacetimeDB` 未发布或未连通时返回 `502`
4. `cargo test -p api-server get_story_session_state` 可通过
5. `npm run check:encoding` 通过，确保新增中文文档没有编码损坏
---
## 6. 后续边界
这条最小查询链路落地后，后续再继续拆下一层：
1. 评估是否需要把旧 `runtime story state` 查询兼容到新 facade
2. 设计 `resolve_story_action` 真正冻结后的输入/输出 contract
3. 再考虑 `currentStory`、`availableOptions`、`presentation`、`patch` 的旧 view model 兼容
在这些 contract 未冻结前，不应把当前接口误称为“旧 runtime story state 已迁移完成”。

250
docs/technical/M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,250 @@
# M4 RPG Runtime Story SpacetimeDB 基座记录（2026-04-21）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只记录一件事：
**把 `M4` 从“只有任务清单和 crate 占位”推进到“SpacetimeDB 侧已有最小可编译 story 会话基座”的真实落地结果。**
本轮只落最小骨架，不扩到完整 runtime story action 迁移，不改前端交互界面设计。
---
## 1. 本轮落地范围
本轮按 `M4` 与 `RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md` 的交叉口径，只落实下面 6 件事：
1. 新增 `server-rs/crates/module-story/` 真实 crate，而不是继续停留在 README 占位。
2. 在 `module-story` 中冻结 `story_session / story_event` 的首版领域类型、ID 前缀、状态枚举与字段校验 helper。
3. 在 `server-rs/crates/spacetime-module/` 中新增 `story_session`、`story_event` 两张表。
4. 在 `spacetime-module` 中新增 `begin_story_session`、`continue_story` 两个 reducer，形成最小可编译会话主链。
5. 在 `spacetime-module` 中新增 `begin_story_session_and_return`、`continue_story_and_return` 两个 procedure，让 Axum 可同步拿到结果快照。
6. 在 `spacetime-client` 与 `api-server` 中新增最小 story session facade，打通 `server-rs` 侧纵向调用链。
---
## 2. 本轮新增的真实工程落点
### 2.1 新增 crate
1. `server-rs/crates/module-story/Cargo.toml`
2. `server-rs/crates/module-story/src/lib.rs`
### 2.2 workspace 与主工程聚合
1. `server-rs/Cargo.toml`
- 已把 `crates/module-story` 纳入 workspace members
2. `server-rs/crates/spacetime-module/Cargo.toml`
- 已接入 `module-story` 依赖
3. `server-rs/crates/spacetime-module/src/lib.rs`
- 已接入 `module-story` 类型
- 已新增 `story_session`
- 已新增 `story_event`
- 已新增 `begin_story_session`
- 已新增 `continue_story`
- 已新增 `begin_story_session_and_return`
- 已新增 `continue_story_and_return`
4. `server-rs/crates/spacetime-client/src/lib.rs`
- 已新增 `begin_story_session(...)`
- 已新增 `continue_story(...)`
5. `server-rs/crates/api-server/src/story_sessions.rs`
- 已新增 `POST /api/story/sessions`
- 已新增 `POST /api/story/sessions/continue`
---
## 3. 当前冻结的数据口径
### 3.1 `story_session`
当前首版字段冻结为：
1. `story_session_id`
2. `runtime_session_id`
3. `actor_user_id`
4. `world_profile_id`
5. `initial_prompt`
6. `opening_summary`
7. `latest_narrative_text`
8. `latest_choice_function_id`
9. `status`
10. `version`
11. `created_at`
12. `updated_at`
当前策略：
1. `story_session` 保持 private 真相表口径。
2. 当前只解决“故事会话存在、版本递增、最新叙事状态可追踪”。
3. 不在本轮提前塞入 quest、combat、npc、inventory 混合字段。
### 3.2 `story_event`
当前首版字段冻结为：
1. `event_id`
2. `story_session_id`
3. `event_kind`
4. `narrative_text`
5. `choice_function_id`
6. `created_at`
当前策略：
1. 事件先只承接 `SessionStarted / StoryContinued` 两类最小事件。
2. 先证明事件追加模型能工作，再扩到 `resolve_story_action` 真实子域事件。
---
## 4. 当前 reducer 口径
### 4.1 `begin_story_session`
当前负责：
1. 校验 `StorySessionInput`
2. 拒绝重复 `story_session_id`
3. 写入 `story_session`
4. 追加一条 `SessionStarted` 事件
### 4.2 `continue_story`
当前负责：
1. 校验 `StoryContinueInput`
2. 校验目标 `story_session` 必须存在
3. 以事件追加方式写入 `story_event`
4. 递增 `story_session.version`
5. 更新 `latest_narrative_text / latest_choice_function_id / updated_at`
---
## 5. 当前 procedure / facade 口径
### 5.1 `begin_story_session_and_return`
当前负责：
1. 在单次 procedure 调用里执行 `begin_story_session_tx`
2. 直接返回 `storySession + storyEvent` 快照
3. 供 `spacetime-client` 与 `api-server` 直接同步消费
### 5.2 `continue_story_and_return`
当前负责：
1. 在单次 procedure 调用里执行 `continue_story_tx`
2. 直接返回推进后的 `storySession + storyEvent` 快照
3. 避免 Axum 再额外读取 private table
### 5.3 `spacetime-client` story facade
当前已新增：
1. `begin_story_session(...)`
2. `continue_story(...)`
当前策略：
1. `spacetime-client` 负责把 `module-story` 输入 builder 映射到 generated bindings。
2. procedure 错误统一折叠为 `SpacetimeClientError`，供 Axum 映射为 `400 / 502`。
### 5.4 `api-server` story session facade
当前已新增：
1. `POST /api/story/sessions`
2. `POST /api/story/sessions/continue`
当前 contract：
1. 两个接口都要求 Bearer JWT。
2. `actorUserId` 由 JWT claims 提供，不允许前端透传。
3. `storySessionId` / `eventId` 由 Rust 服务端使用 `module-story` 的 ID helper 生成。
4. 两个接口当前都返回：
- `storySession`
- `storyEvent`
---
## 6. 当前刻意未做
本轮明确没有扩到以下范围：
1. 还没有落 `resolve_story_action`
2. 还没有落 `sync_runtime_snapshot_projection`
3. 还没有接入 `npc_state / quest_record / battle_state / inventory_slot`
4. 还没有兼容旧 `POST /api/runtime/story/actions/resolve`
5. 还没有兼容旧 `GET /api/runtime/story/state/:sessionId`
6. 还没有兼容旧 `POST /api/runtime/story/state/resolve`
7. 还没有兼容旧 `POST /api/runtime/story/initial`
8. 还没有兼容旧 `POST /api/runtime/story/continue`
9. 还没有把 `server-node` 现有 `rpg-runtime-story` 主链切换到 `server-rs`
10. 还没有改任何前端交互界面设计
也就是说，本轮只是把 `M4` 的 SpacetimeDB 会话基座与最小 Axum facade 立起来，不宣称已经完成 runtime story 兼容迁移。
---
## 7. 验证结果
本轮已执行：
1. `cargo check -p module-story --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
2. `cargo check -p spacetime-module --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
3. `cargo check -p spacetime-module --target wasm32-unknown-unknown --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
4. `spacetime generate --no-config --lang rust --out-dir D:\\Genarrative\\server-rs\\crates\\spacetime-client\\src\\module_bindings --module-path D:\\Genarrative\\server-rs\\crates\\spacetime-module --include-private --yes`
5. `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
6. `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
7. `npm run check:encoding`
结果：
1. 全部通过。
---
## 8. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 先冻结 `story state` 查询 contract，明确是新 `/api/story/sessions/:storySessionId/state` 还是兼容旧 `/api/runtime/story/state/*`。
2. 再把 `story_session` 与 `runtime_snapshot` 的 projection / sync 边界补清。
3. 再把 `resolve_story_action` 的输入/输出与 `RuntimeStoryActionRequest` 对齐成下一个 reducer / procedure 设计。
4. 再逐步把 `npc / quest / treasure / combat` 子域动作接成显式事件与独立 reducer。
5. 最后再处理旧 Node `runtime story` 兼容接口与前端实际切换。
---
## 9. 后续增量状态（`2026-04-22`）
在本文件记录的首轮 story session 基座之上，当前仓库又继续补了两条与 `M4 story runtime` 直接相关的增量切片：
1. 已补 `GET /api/story/sessions/:storySessionId/state`
- 当前只返回 `storySession + storyEvents`
- 不兼容旧 `RuntimeStoryActionResponse`
2. 已补 `GET /api/story/battles/:battleStateId`
- 当前只返回单个 `battleState`
- 供 battle 刷新、重连和后续 story 编排复用
3. 已补 `POST /api/story/npc/battle`
- 当前只承接 `npc_fight / npc_spar`
- 同步返回 `npcInteraction + battleState`
同时，本轮还完成了以下工程收口：
1. 已重新执行 `spacetime generate --no-config --lang rust --out-dir D:\\Genarrative\\server-rs\\crates\\spacetime-client\\src\\module_bindings --module-path D:\\Genarrative\\server-rs\\crates\\spacetime-module --include-private --yes`。
2. 已把 `spacetime-client` 中 battle query 的占位实现替换为真实 procedure 调用。
3. 已再次执行 `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 与 `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 并通过。
当前仍需继续追的验证项：
1. `story_sessions` / `story_battles` 相关二进制测试在当前机器上编译时间较长，还没有在单次时窗内拿到最终断言结果。
2. `npm run check:encoding` 已启动，但尚未在单次时窗内跑完。
因此，当前准确口径应为：
1. `M4 story session / story state / battle state / NPC 开战` 的最小后端编译链已经打通。
2. 旧 `runtime story` 兼容接口与旧 view model 兼容仍未完成。
3. 长时回归测试与编码检查仍在继续推进，不应提前宣称整阶段验收完成。

232
docs/technical/M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,232 @@
# M4 Runtime Inventory State Query 设计（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结当前 `M4` 的一个最小新增切片：
**新增 `GET /api/runtime/sessions/:runtimeSessionId/inventory`，让 Axum 能从 `SpacetimeDB` 同步读取当前玩家在指定 `runtime_session` 下的 `inventory_slot` 真相态，不提前承诺旧 `GameState.playerInventory / playerEquipment` 全量兼容。**
本轮目标不是把旧前端背包 view model 一次性全迁到 Rust，也不是把 `inventory_use / craft / dismantle / reforge` 一次性补齐。
---
## 1. 为什么先做这个切片
当前 inventory 主链已经具备：
1. `module-inventory` 已冻结 `inventory_slot`、`apply_inventory_mutation` 的首版领域 contract。
2. `spacetime-module` 已有 `inventory_slot` 真相表与 `apply_inventory_mutation` reducer。
3. `treasure / quest / battle` 奖励物品已经能同步写入 `inventory_slot`。
真正缺的部分是：
1. 背包真相态还没有稳定查询入口。
2. `api-server` 还不能按 `runtime_session_id + 当前用户` 同步返回当前背包与装备状态。
3. 后续如果要把背包面板、装备面板或 runtime story projection 收口到 `SpacetimeDB`，需要先有一个最小 inventory query 切片可复用。
因此本轮先补“只读查询”能力，不提前跳到更重的旧前端状态兼容。
---
## 2. 当前冻结范围
本轮只包含以下能力：
1. 新增公开接口：`GET /api/runtime/sessions/:runtimeSessionId/inventory`
2. 认证方式：Bearer JWT
3. 查询 scope：`runtime_session_id + 当前登录用户`
4. 数据来源：`SpacetimeDB procedure get_runtime_inventory_state`
5. 返回体只包含：
- `runtimeSessionId`
- `actorUserId`
- `backpackItems`
- `equipmentItems`
本轮明确不做：
1. 不兼容旧 `GameState.playerInventory`
2. 不兼容旧 `GameState.playerEquipment`
3. 不补按 `story_session_id` 或全局用户维度的 inventory 查询
4. 不做 inventory public subscription / view
5. 不在查询链路里拼装 quest / npc / battle / story_event
6. 不提前做 `inventory_use / craft / dismantle / reforge`
---
## 3. 为什么按 `runtime_session_id + 当前用户` 查询
当前 `inventory_slot` 的主作用域字段是：
1. `runtime_session_id`
2. `actor_user_id`
3. `story_session_id`
本轮选择 `runtime_session_id + actor_user_id` 作为最小 query scope，原因如下：
1. `inventory_slot` 当前是运行态背包真相，不是单个 story session 的临时投影。
2. 同一 `runtime_session` 下的宝箱、任务、战斗奖励都已经按这个 scope 汇入同一张表。
3. 旧前端背包面板语义本质上也是“当前运行态玩家的背包”，不是“某个 story session 的局部背包”。
4. 若后续确实需要更细的 `story_session` 投影，应通过上层 façade 或专门 view 提供，而不是先把真相查询 scope 做窄。
---
## 4. 接口 contract
### 4.1 请求
- 方法：`GET`
- 路径：`/api/runtime/sessions/:runtimeSessionId/inventory`
- 认证：必须携带 Bearer JWT
- 路径参数：
- `runtimeSessionId`：目标运行时会话 ID
### 4.2 成功响应
成功响应延续当前 `api-server` 统一 envelope，`data` 字段结构为：
```json
{
"runtimeSessionId": "runtime_xxx",
"actorUserId": "user_xxx",
"backpackItems": [
{
"slotId": "invslot_xxx",
"containerKind": "backpack",
"slotKey": "invslot_xxx",
"itemId": "consumable_heal_potion",
"category": "消耗品",
"name": "疗伤药",
"description": "用于恢复少量气血。",
"quantity": 3,
"rarity": "common",
"tags": ["healing"],
"stackable": true,
"stackKey": "heal_potion",
"equipmentSlotId": null,
"sourceKind": "treasure_reward",
"sourceReferenceId": "treasure_xxx",
"createdAt": "2026-04-22T00:00:00.000000Z",
"updatedAt": "2026-04-22T00:01:00.000000Z"
}
],
"equipmentItems": [
{
"slotId": "invslot_weapon_xxx",
"containerKind": "equipment",
"slotKey": "weapon",
"itemId": "weapon_trial_blade",
"category": "武器",
"name": "试作短剑",
"description": "一柄适合入门者的短剑。",
"quantity": 1,
"rarity": "rare",
"tags": ["weapon"],
"stackable": false,
"stackKey": "weapon_trial_blade",
"equipmentSlotId": "weapon",
"sourceKind": "quest_reward",
"sourceReferenceId": "quest_xxx",
"createdAt": "2026-04-22T00:00:00.000000Z",
"updatedAt": "2026-04-22T00:05:00.000000Z"
}
]
}
```
### 4.3 错误响应
当前延续 runtime/profile/story 查询已有策略：
1. `SpacetimeClientError::Runtime(_)` 映射为 `400`
2. 其他 `SpacetimeClientError` 映射为 `502`
3. 错误 `details.provider`：
- 参数构建或本地语义错误：`runtime-inventory`
- 下游 `SpacetimeDB` 失败：`spacetimedb`
---
## 5. 分层职责
### 5.1 `module-inventory`
职责：
1. 冻结 `RuntimeInventoryStateQueryInput`
2. 冻结 `RuntimeInventoryStateSnapshot`
3. 冻结 `RuntimeInventorySlotRecord`
4. 负责 builder、validator 与 record 映射
不负责：
1. HTTP 路径解析
2. JWT 鉴权
3. 旧前端背包 view model 编译
### 5.2 `spacetime-module`
职责：
1. 读取指定 `runtime_session_id + actor_user_id` 下的 `inventory_slot`
2. 按 `container_kind` 拆成 `backpackItems / equipmentItems`
3. 复用 `module-inventory` 的 query input / snapshot 结构
4. 通过 `get_runtime_inventory_state` procedure 返回当前真相态
### 5.3 `spacetime-client`
职责：
1. 构造 `RuntimeInventoryStateQueryInput`
2. 调用 `get_runtime_inventory_state`
3. 把返回结果映射为稳定 Rust record
### 5.4 `api-server`
职责：
1. 暴露 `GET /api/runtime/sessions/:runtimeSessionId/inventory`
2. 做 Bearer JWT 鉴权
3. 从 token 中注入 `actorUserId`
4. 把 inventory record 映射到 JSON payload
---
## 6. 排序规则
为了保证前端和后续 façade 读到稳定顺序，本轮冻结以下排序口径：
1. `backpackItems`
- 先按 `slot_key`
- 再按 `slot_id`
2. `equipmentItems`
- 先按装备位固定顺序：`weapon -> armor -> relic`
- 再按 `slot_id`
当前不在 query 层额外做“按稀有度”“按分类”“按来源”的排序投影。
---
## 7. 验收口径
本轮验收只要求以下几点：
1. `module-inventory` 已补 inventory query contract 与最小测试
2. `spacetime-module` 已新增 `get_runtime_inventory_state` procedure
3. `spacetime-client` 已能同步读取 inventory 真相态
4. `api-server` 已真实挂出 `GET /api/runtime/sessions/:runtimeSessionId/inventory`
5. `cargo check -p module-inventory -p spacetime-module -p spacetime-client -p api-server` 可通过
6. `npm run check:encoding` 已执行，确保新增中文文档与接口文件没有编码损坏
---
## 8. 后续边界
这条最小 inventory query 落地后，后续再继续拆下一层：
1. 评估是否需要补 `story session` 局部 inventory projection
2. 评估是否需要把 inventory query 接成旧背包面板 view model
3. 再继续补 `inventory_use / craft / dismantle / reforge`
4. 最后再考虑 inventory subscription / public view
在这些 contract 未冻结前，不应把当前接口误称为“旧背包系统已完整迁移完成”。

142
docs/technical/M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md Normal file
View File

@@ -0,0 +1,142 @@
# M4 Runtime Item Treasure SpacetimeDB 基座记录（2026-04-21）
更新时间：`2026-04-21`
## 0. 文档目标
本文件只记录一件事：
**把 `module-runtime-item` 从“只有 README 占位”推进到“SpacetimeDB 侧已有 `treasure_record` 真相表、`resolve_treasure_interaction` reducer/procedure，以及可桥接 `inventory_slot` 的奖励 contract”的真实落地结果。**
本轮目标不是一次性迁完 Node 版所有 runtime item 玩法，而是先把宝藏奖励记录、奖励字段口径与后续背包接入边界固定下来。
---
## 1. 本轮落地范围
本轮只落实下面 5 件事：
1. 新增 `server-rs/crates/module-runtime-item/` 真实 crate，而不是继续停留在 README 占位。
2. 在 `module-runtime-item` 中冻结 `TreasureResolveInput / TreasureRecordSnapshot / RuntimeItemRewardItemSnapshot` 的首版领域类型与校验 helper。
3. 在 `server-rs/crates/spacetime-module/` 中新增 `treasure_record` 表。
4. 在 `spacetime-module` 中新增 `resolve_treasure_interaction` reducer 与 `resolve_treasure_interaction_and_return` procedure。
5. 把宝藏奖励物品字段扩到可无损映射 `inventory_slot` 的粒度，并在聚合层接通宝藏奖励到背包真相表的最小发物链。
---
## 2. 当前冻结的数据口径
### 2.1 `treasure_record`
当前首版字段冻结为：
1. `treasure_record_id`
2. `runtime_session_id`
3. `story_session_id`
4. `actor_user_id`
5. `encounter_id`
6. `encounter_name`
7. `scene_id`
8. `scene_name`
9. `action`
10. `reward_items`
11. `reward_hp`
12. `reward_mana`
13. `reward_currency`
14. `story_hint`
15. `created_at`
16. `updated_at`
当前策略：
1. `treasure_record` 保持 private 真相表口径。
2. `Inspect / Secure / Leave` 都会留下正式记录，避免宝藏交互继续散落在 runtime snapshot 大 JSON 或 story 文本里。
3. `Leave` 允许不发物；`Inspect / Secure` 的奖励字段当前已经通过聚合层同步写入 `inventory_slot`。
4. 同一 `treasure_record_id` 重放时直接返回既有记录，不重复执行发物，保证宝藏奖励幂等。
### 2.2 `RuntimeItemRewardItemSnapshot`
当前奖励物品字段冻结为：
1. `item_id`
2. `category`
3. `item_name`
4. `description`
5. `quantity`
6. `rarity`
7. `tags`
8. `stackable`
9. `stack_key`
10. `equipment_slot_id`
当前策略：
1. 奖励物品不再只保留 `item_id + item_name + quantity` 的轻量占位结构。
2. 当前字段已经与 `inventory_slot` 的首版真相字段对齐到可桥接程度，避免后续发物时再回头猜品类、堆叠策略和装备位。
3. `build_inventory_item_snapshot_from_reward_item(...)` 负责把宝藏奖励快照稳定映射为 `module-inventory::InventoryItemSnapshot`。
---
## 3. 当前 reducer / procedure 口径
### 3.1 `resolve_treasure_interaction`
当前负责：
1. 校验 `TreasureResolveInput`
2. 校验 `story_session_id / runtime_session_id / actor_user_id` 作用域一致
3. 同一 `treasure_record_id` 重放时直接返回已落库快照
4. 初次落库时写入 `treasure_record`
5. 初次落库后把 `reward_items` 同步发放到 `inventory_slot`
### 3.2 `resolve_treasure_interaction_and_return`
当前负责：
1. 复用同一套 `treasure_record` upsert 规则
2. 返回最终 `TreasureRecordSnapshot`
3. 避免 Axum facade 再额外读取 private table
---
## 4. 当前刻意未做
本轮明确没有扩到以下范围：
1. 还没有把 `reward_hp / reward_mana / reward_currency` 接到运行时资源真相表
2. 还没有把 runtime item director 的完整物品导演链迁到 Rust
3. 还没有新增 Axum 的 runtime treasure facade
4. 还没有把前端 `treasureInteractions.ts` 主链切到 `server-rs`
也就是说，本轮只是把宝藏结算真相表和奖励 contract 立起来，不宣称已经完成完整宝藏奖励迁移。
---
## 5. 本轮新增的真实工程落点
### 5.1 新增 crate
1. `server-rs/crates/module-runtime-item/Cargo.toml`
2. `server-rs/crates/module-runtime-item/src/lib.rs`
### 5.2 workspace 与主工程聚合
1. `server-rs/Cargo.toml`
- 已把 `crates/module-runtime-item` 纳入 workspace members
2. `server-rs/crates/spacetime-module/Cargo.toml`
- 已接入 `module-runtime-item` 依赖
3. `server-rs/crates/spacetime-module/src/lib.rs`
- 已接入 `module-runtime-item` 类型
- 已新增 `treasure_record`
- 已新增 `resolve_treasure_interaction`
- 已新增 `resolve_treasure_interaction_and_return`
---
## 6. 下一步建议
按当前节奏，后续应继续按下面顺序推进：
1. 先把 `treasure / quest / battle` 的奖励发物 helper 继续收敛，减少 `spacetime-module` 聚合层的重复映射代码。
2. 再补 runtime 资源恢复、货币与 story projection 的跨域聚合写入。
3. 最后再接 Axum facade 与前端真实 treasure 主链切换。

264
docs/technical/M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,264 @@
# M4 Runtime Story 兼容状态桥设计（2026-04-22）
更新时间：`2026-04-22`
## 0. 文档目标
本文件只冻结 `M4` 当前下一条最小可落地兼容桥：
**先把 Rust `api-server` 侧旧 `runtime story state` 兼容返回所需的 DTO 与状态桥边界冻结清楚，再进入 Axum handler 与状态编译迁移。**
当前仓库已经有两条并行现实：
1. `server-node` 侧旧兼容接口 `POST /api/runtime/story/state/resolve` 仍然在真实服务前端。
2. `server-rs` 侧已经有 `story_session / battle_state / npc battle / inventory state` 等真相态接口，但还没有编译成旧前端消费的 `RuntimeStoryActionResponse`。
因此，本轮不直接宣称“runtime story 已迁完”，而是先把兼容桥 contract 冻结为下一段可编码的工程基线。
---
## 1. 当前真实现状
### 1.1 前端真实调用入口
当前前端 `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts` 的真实行为是：
1. 加载 option catalog 时优先调用 `POST /api/runtime/story/state/resolve`
2. story 选项点击时调用 `POST /api/runtime/story/actions/resolve`
3. 请求体默认携带：
- `sessionId`
- `clientVersion`
- `snapshot`
其中 `snapshot` 当前来自前端内存态：
1. `gameState`
2. `bottomTab`
3. `currentStory`
这意味着兼容桥的第一优先级不是“把所有真相态一次性并回旧结构”，而是：
**先让 Rust 侧能吃下同样的 `snapshot + sessionId + clientVersion`，并返回旧前端已经稳定消费的 `RuntimeStoryActionResponse` 形状。**
### 1.2 Rust 侧当前已存在的真相态
当前 `server-rs` 已经真实挂出的接口包括：
1. `POST /api/story/sessions`
2. `POST /api/story/sessions/continue`
3. `GET /api/story/sessions/:storySessionId/state`
4. `POST /api/story/battles`
5. `POST /api/story/battles/resolve`
6. `GET /api/story/battles/:battleStateId`
7. `POST /api/story/npc/battle`
8. `GET /api/runtime/sessions/:runtimeSessionId/inventory`
但这些接口的返回仍是“真相态切片”，还没有拼成旧前端直接依赖的：
1. `viewModel`
2. `presentation`
3. `patches`
4. `snapshot`
### 1.3 Node 侧兼容链的真实落点
当前旧兼容链不再是任务清单里早期写法的 `server-node/src/modules/story/*`，而是已经迁到：
1. `server-node/src/routes/rpg-runtime/rpgRuntimeStoryRoutes.ts`
2. `server-node/src/modules/rpg-runtime-story/RpgRuntimeStoryActionDomain.ts`
3. `server-node/src/modules/rpg-runtime-story/RpgRuntimeSessionDomain.ts`
因此，后续对照迁移时必须以这些新域路径为准，不再以已删除或已降级的旧 `modules/story/*` 口径作为实施依据。
---
## 2. 本轮冻结范围
本轮只冻结以下兼容桥边界：
1. Rust `shared-contracts` 新增旧 `runtime story` 兼容响应 DTO
2. Rust `shared-contracts` 新增 `POST /api/runtime/story/state/resolve` 的最小请求 DTO
3. 明确 Rust 侧第一段只先承接“状态查询兼容桥”
4. 明确 `actions/resolve`、`initial`、`continue` 继续后置
本轮明确不做：
1. 不在 `server-rs` 里直接落完整 `resolve_story_action`
2. 不迁移 Node 侧全部 story 行为决策
3. 不把 `runtime snapshot` 正式持久化真相一次性迁到 Rust
4. 不在本轮让前端切到 Rust `api-server`
---
## 3. 为什么先做状态桥
当前如果直接做 `POST /api/runtime/story/actions/resolve`，会同时撞上 4 个未冻结边界：
1. `resolve_story_action` 本体 reducer / procedure 还没设计完成
2. `runtime snapshot projection` 还没有 Rust 侧正式真相模型
3. `battle / npc / quest / inventory` 旧 patch 结构还没完全映射
4. LLM story 文本生成口径还没决定是继续经 Node 还是挂到 Rust `platform-llm`
而 `POST /api/runtime/story/state/resolve` 的依赖更小：
1. 前端已经会把当前 `snapshot` 一并传上来
2. Node 侧现有状态读取逻辑本质上就是基于 `snapshot` 编译 `viewModel + availableOptions + currentStory`
3. Rust 侧可以先承接“兼容状态查询 + DTO 编译”这一条独立切片
因此当前正确顺序是：
```text
先冻结 shared-contracts DTO
-> 再做 Rust state bridge compiler
-> 再挂 POST /api/runtime/story/state/resolve
-> 最后再进入 actions/resolve
```
---
## 4. 兼容桥 contract 冻结
## 4.1 请求：`POST /api/runtime/story/state/resolve`
首版仍沿用前端现有字段名：
```json
{
"sessionId": "runtime-main",
"clientVersion": 7,
"snapshot": {
"savedAt": "2026-04-22T12:00:00.000Z",
"bottomTab": "adventure",
"gameState": {},
"currentStory": {}
}
}
```
字段要求：
1. `sessionId` 必填
2. `clientVersion` 可选
3. `snapshot` 可选
4. `snapshot.gameState` 当前保持 `serde_json::Value`，不在本轮提前强类型化
5. `snapshot.currentStory` 当前保持 `serde_json::Value | null`
### 4.1.1 `snapshot` 缺省策略
在 Rust 状态桥首版里：
1. 如果 `snapshot` 存在，则优先用它编译兼容状态
2. 如果 `snapshot` 缺失，则允许后续 bridge handler 退回：
- 新真相态聚合
- 或返回当前无法恢复状态的明确错误
本轮只冻结 DTO，不在文档里提前承诺缺省路径的最终实现方式。
## 4.2 成功响应：`RuntimeStoryActionResponse`
为了兼容当前前端 `rpgRuntimeStoryClient.ts`，Rust 侧成功响应字段必须与现有共享 TS contract 保持同形：
1. `sessionId`
2. `serverVersion`
3. `viewModel`
4. `presentation`
5. `patches`
6. `snapshot`
其中：
1. `viewModel.availableOptions` 必须继续使用旧 `RuntimeStoryOptionView`
2. `presentation.storyText` 必须保留
3. `snapshot` 必须继续包含：
- `savedAt`
- `bottomTab`
- `gameState`
- `currentStory`
### 4.2.1 `patches` 首版策略
状态查询接口本身不产生新的行为变更，因此 `state/resolve` 首版兼容桥返回：
1. `patches` 固定为空数组
这与当前 Node `getRuntimeStoryState(...)` 的行为一致，不需要在状态查询时伪造 patch。
---
## 5. DTO 分层
## 5.1 `shared-contracts::runtime_story`
新模块负责：
1. `RuntimeStorySnapshotPayload`
2. `RuntimeStoryStateResolveRequest`
3. `RuntimeStoryActionResponse`
4. `RuntimeStoryViewModel`
5. `RuntimeStoryPresentation`
6. `RuntimeStoryPatch`
7. `RuntimeStoryOptionView`
8. `RuntimeBattlePresentation`
9. `RuntimeStoryOptionInteraction`
当前策略：
1. 兼容层 DTO 独立成新模块，不继续塞进 `story.rs`
2. `runtime.rs` 继续保留 settings / browse history / profile / inventory / custom world 的公开 DTO
3. `story.rs` 继续只承接 `story session` 真相链 DTO
## 5.2 字段类型策略
为了先稳住兼容层：
1. `snapshot.game_state` 使用 `serde_json::Value`
2. `snapshot.current_story` 使用 `Option<serde_json::Value>`
3. `RuntimeStoryOptionView.payload` 使用 `Option<serde_json::Value>`
原因：
1. 这些字段当前本来就是旧前端快照结构
2. Rust 侧正式领域模型尚未冻结
3. 提前强类型化只会放大后续迁移返工面
---
## 6. 第一段工程落地顺序
建议直接按下面顺序编码：
1. `shared-contracts` 新增 `runtime_story.rs`
2. 为 `RuntimeStoryStateResolveRequest / RuntimeStoryActionResponse` 补 camelCase 序列化测试
3. `docs/technical/README.md` 与 `shared-contracts/README.md` 更新索引
4. `backend-rewrite-tasklist/03_M4_STORY_AND_GAMEPLAY.md` 追加当前冻结进展
5. 下一轮再进入 `api-server` 的 `state/resolve` handler 与兼容 compiler
---
## 7. 当前刻意不冻结的内容
以下内容继续明确后置：
1. `POST /api/runtime/story/actions/resolve` 的请求 DTO 是否直接复用旧 TS contract 全量字段
2. `resolve_story_action` 是否拆成：
- `resolve_story_action`
- `resolve_story_combat_action`
- `resolve_story_interaction_action`
3. `snapshot` 缺失时是否允许直接从 Rust 真相表完整恢复旧 `currentStory`
4. `LLM` 文本续写是在 Rust bridge 内继续调用，还是继续通过 Node 兼容层兜底
这些边界在状态桥稳定前都不应提前拍死。
---
## 8. 完成定义
这一轮“兼容状态桥基线完成”的定义是：
1. 已有独立技术文档冻结 `state/resolve` 兼容桥边界
2. `shared-contracts` 已拥有旧 `runtime story` 兼容 DTO
3. DTO 字段名与当前前端消费口径保持一致
4. `cargo test -p shared-contracts` 通过
5. `npm run check:encoding` 通过，确保新增中文文档与 Rust 源文件编码未损坏
达到以上条件后，下一轮即可直接进入 Rust `state bridge compiler` 与 Axum handler 落地。

218
docs/technical/PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,218 @@
# `platform-llm` 文本网关首版设计（2026-04-21）
## 1. 背景
`server-rs/crates/platform-llm/` 在 `2026-04-20` 只完成了目录占位，但当前仓库里已经存在一条稳定的 Node 侧文本模型主链：
1. `server-node/src/services/llmClient.ts`
2. `server-node/src/modules/ai/*`
3. `server-node/src/services/storyService.ts`
4. `server-node/src/services/questService.ts`
5. `server-node/src/services/runtimeItemService.ts`
这些调用点已经依赖一套隐含约束：
1. 使用 OpenAI 兼容的 `/chat/completions`
2. 统一 Bearer 鉴权
3. 同时支持非流式 JSON 响应与 SSE 流式增量
4. 要求有超时、连接失败、上游错误和空响应兜底
如果 Rust 侧继续只保留 README 占位，后续 `api-server`、`module-ai`、`module-story`、`module-npc` 在落地时又会各自复制一份私有上游 client，重新造成平台层分叉。
因此本次先把 `platform-llm` 收口成一个真实可编译、可测试、可复用的 Rust crate，冻结文本主链基础设施。
## 2. 本次落地范围
### 2.1 本次明确实现
1. `LlmProvider`：冻结 provider 来源标签，首版包含 `ark`、`dash_scope`、`openai_compatible`
2. `LlmConfig`：统一 base url、api key、model、timeout、retry 配置
3. `LlmMessageRole`、`LlmMessage`、`LlmTextRequest`：统一请求 DTO
4. `LlmClient::request_text(...)`：统一非流式文本调用
5. `LlmClient::stream_text(...)`：统一流式 SSE 文本调用
6. `LlmTextResponse`、`LlmStreamDelta`、`LlmTokenUsage`：统一响应 DTO
7. `LlmError`：统一配置错误、请求错误、超时、连接失败、上游错误、反序列化错误、空响应错误
8. 基础重试策略：对 `408`、`429`、`5xx`、超时、连接失败重试
### 2.2 本次明确不做
1. 不在 `platform-llm` 内承接业务 prompt 组织
2. 不在 `platform-llm` 内承接模块级状态写回
3. 不在 `platform-llm` 内做 HTTP Route/SSE façade
4. 不提前把图片、视频、异步任务轮询混进同一个 crate
5. 不声称已经打通 DashScope 图像 API；当前首版只做文本网关
## 3. 当前边界口径
### 3.1 文本协议边界
首版只冻结 **OpenAI 兼容 chat completion**：
1. 请求路径固定为 `base_url + /chat/completions`
2. Bearer Token 由 `Authorization: Bearer <api_key>` 注入
3. 非流式返回解析 `choices[0].message.content`
4. 流式返回解析 `choices[0].delta.content`
5. `content` 若返回数组文本片段，也统一拼成单字符串
### 3.2 Provider 边界
1. `Ark`：当前仓库已有真实默认 base url，可直接作为 Rust 首版默认值
2. `DashScope`：当前只保留 provider 标签，不在 crate 内硬编码其文本兼容入口
3. `OpenAiCompatible`：用于其他兼容网关
这里故意不把 DashScope 文本 base url 写死，是因为当前仓库的真实 Node 主链并没有用 DashScope 跑文本 `/chat/completions`，而是主要用于图像任务；Rust 首版不应在没有仓库事实对齐的前提下硬塞一个未经验证的默认路径。
## 4. 对外 API 设计
### 4.1 `LlmConfig`
字段：
1. `provider`
2. `base_url`
3. `api_key`
4. `model`
5. `request_timeout_ms`
6. `max_retries`
7. `retry_backoff_ms`
约束：
1. `base_url`、`api_key`、`model` 不允许为空
2. `request_timeout_ms` 必须大于 `0`
3. `max_retries` 表示“首轮之外还允许重试多少次”
### 4.2 `LlmTextRequest`
字段：
1. `model: Option<String>`
2. `messages: Vec<LlmMessage>`
3. `max_tokens: Option<u32>`
约束：
1. `messages` 不能为空
2. 每条 `message.content` 不能为空字符串
3. `model` 如果传入，则 trim 后不能为空
### 4.3 `LlmTextResponse`
字段：
1. `provider`
2. `model`
3. `content`
4. `finish_reason`
5. `response_id`
6. `usage`
设计目的：
1. 上层只拿统一文本结果，不再接触 `choices`、`delta`、`message` 等上游细节
2. 后续 `api-server` 可以直接把这些字段映射到自己的 HTTP / SSE contract
## 5. 错误与重试策略
### 5.1 错误分层
`LlmError` 首版固定为：
1. `InvalidConfig`
2. `InvalidRequest`
3. `Timeout`
4. `Connectivity`
5. `Upstream`
6. `StreamUnavailable`
7. `EmptyResponse`
8. `Transport`
9. `Deserialize`
### 5.2 重试规则
允许重试：
1. 请求超时
2. 连接失败
3. `408`
4. `429`
5. `5xx`
不重试：
1. 配置错误
2. 请求体无效
3. 上游返回 `4xx` 非限流类错误
4. 已成功开始返回流之后的解析错误
### 5.3 Backoff 规则
首版采用线性 backoff：
1. 第 1 次重试等待 `retry_backoff_ms`
2. 第 2 次重试等待 `retry_backoff_ms * 2`
3. 依此类推
原因：
1. 先保持实现简单
2. 足以覆盖当前仓库文本上游的偶发抖动
3. 真正需要指数退避时，再在平台层单点升级即可
## 6. 与 Node 现状对齐
Rust 首版有意对齐 `server-node/src/services/llmClient.ts` 的事实边界：
1. 同样走 `/chat/completions`
2. 同样区分非流式与流式
3. 同样在空文本时直接报错
4. 同样把上游 JSON 错误体里的 `error.message` / `message` 提取出来
5. 同样把重试、超时、连接失败收口在一个平台层里
但 Rust 版这次额外收紧两点：
1. 不混入 Express Request/Response 转发逻辑
2. 不把业务 prompt 参数与上游 client 绑定在一起
这样后续 `api-server` 和 `module-ai` 都只能依赖一套稳定基础设施，而不是复制旧 Node 的“传 HTTP 对象进去直接转发”的实现方式。
## 7. 当前测试覆盖
首版要求至少覆盖：
1. 配置校验
2. URL 归一化
3. SSE 事件解析
4. 非流式成功响应解析
5. `500 -> retry -> 200` 的重试闭环
6. 流式累计文本拼接
## 8. 后续衔接
### 8.1 `api-server`
后续 `api-server` 应该：
1. 在自身配置层解析环境变量
2. 组装 `LlmConfig`
3. 注入 `LlmClient`
4. 在 handler / application façade 中调用 `request_text` 或 `stream_text`
### 8.2 `module-ai`
后续 `module-ai` 应该：
1. 只负责 prompt 组织、阶段状态和结果引用
2. 不直接依赖 `reqwest`
3. 不再自己解析 SSE 增量
4. 统一通过 `platform-llm` 调模型
## 9. 本次验收标准
本次实现完成后，应满足：
1. `server-rs` workspace 能识别 `platform-llm` crate
2. `cargo test -p platform-llm` 通过
3. `cargo check -p platform-llm` 通过
4. `platform-llm` README 不再是“仅目录占位”
5. `docs/technical/README.md` 有正式文档索引

33
docs/technical/README.md
View File

@@ -4,6 +4,8 @@
## 文档列表
- [PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md](./PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md)：`platform-llm` 文本模型网关首版设计，冻结 OpenAI 兼容 `/chat/completions`、SSE 增量解析、错误模型与重试边界。
- [API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md](./API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md)：`api-server` 接入 `platform-llm` 的最小代理设计，冻结 `/api/llm/chat/completions` 的配置、状态注入与首版非流式兼容边界。
- [PHONE_SMS_LOGIN_STAGE_A_IMPLEMENTATION_2026-04-21.md](./PHONE_SMS_LOGIN_STAGE_A_IMPLEMENTATION_2026-04-21.md)：冻结手机号验证码登录第一阶段的真实落地边界，明确游客兜底默认关闭、公开请求不污染登录态，以及 smoke 必须覆盖短信登录主链。
- [AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md](./AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md)：`/api/auth/login-options` 首版设计，冻结登录方式列表 contract、配置开关来源与返回顺序。
- [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)：`/api/auth/me` 首版查询设计，冻结 Bearer JWT 衔接、`user + availableLoginMethods` 返回 contract，以及用户不存在时的 `401` 语义。
@@ -19,6 +21,13 @@
- [PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` 首版 JWT 适配设计，冻结 `JwtConfig`、claims 结构、`HS256` 签发/校验、`api-server` Bearer 中间件与内部验收路由边界。
- [OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](./OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)：面向 Axum、`platform-auth` 与 `SpacetimeDB` 身份透传的 OIDC 风格 JWT claims 设计，冻结 `iss/sub/sid/provider/roles` 等关键字段。
- [RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md](./RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md)：Rust 工作区统一日志模块 `shared-logging` 的职责边界、API、输出风格与 `api-server` 迁移规则。
- [RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md](./RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md)：把 `shared-contracts` 从占位目录推进成真实共享协议 crate，冻结统一 envelope、`auth/*`、`runtime/settings`、`assets/*` 与 `story-sessions/*` 首批公开 DTO 的迁移边界。
- [RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md](./RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md)：继续把 `assets/*` 与 `story-sessions/*` 的成功响应从 handler 内 `json!` 手拼收口到 `shared-contracts`，冻结显式响应 DTO 与适配边界。
- [RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md](./RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md)：把 `shared-kernel` 从目录占位推进到首批真实共享内核，冻结第一阶段只允许上提的基础字符串、ID 与时间处理能力，以及首批接入 crate 范围。
- [RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md](./RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md)：在不扩公共 API 的前提下，把 `shared-kernel` 第一阶段已冻结的字符串、UUID 与时间处理能力继续接入 `module-runtime`、`module-story`、`spacetime-client` 与 `api-server`。
- [RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md)：继续把 `shared-kernel` 扩到跨多个纯领域 crate 已稳定重复的字符串列表归一化与前缀种子 ID 拼接能力，明确第三阶段仍不进入 JSON、配置与平台语义处理。
- [RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md)：继续把 `shared-kernel::normalize_required_string(...)` 接入更多纯领域 crate，收口跨模块重复的“trim + 判空 + 映射字段错误”逻辑，同时明确不进入平台与 JSON 语义。
- [RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md](./RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md)：继续把 `shared-kernel::normalize_required_string(...)` 接入 `module-runtime` 与 `module-assets` 剩余的纯字段级归一化逻辑，保留 `object_key` 等模块局部语义不变。
- [SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md)：`M2` 第七张微信 OAuth 状态表 `wechat_auth_state` 的字段、过期/消费语义、`wechat/start` 与 `wechat/callback` 的单次消费规则，以及多实例下的清理策略。
- [SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md)：`M2` 第六张短信鉴权统计表 `sms_auth_event` 的事件范围、统计口径、索引与和风控/审计表的协作边界。
- [SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md)：`M2` 第五张风控状态表 `auth_risk_block` 的作用域、活跃态、刷新/解除规则与读取派生约束。
@@ -29,9 +38,16 @@
- [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于当前 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。
- [M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md](./M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md)：冻结 M6 剩余的 STS 与服务端上传 helper 落地口径，明确当前上传主链为服务器上传 OSS，Web 端只负责签名读下载。
- [AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md](./AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md)：冻结 `POST /api/assets/objects/confirm` 从 Axum 通过 Rust SDK 调用 `SpacetimeDB procedure` 的最小落地方案，明确本地 server、数据库名、procedure/reducer 分工与 `spacetime-client` 边界。
- [M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)：冻结 `M3` 首批 `runtime settings` 纵向切片的表字段、默认值、procedure、Axum facade、错误 contract 与测试策略。
- [SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)：冻结 `M5` Agent session create / snapshot 的最小 SpacetimeDB 与 Axum facade 闭环，明确本轮不迁移 LLM、SSE、卡片更新和完整 action registry。
- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md)：冻结 `M5` Agent `message submit / operation query` 的 deterministic 最小闭环，明确同步写入 user/assistant 消息、`process_message` operation 与 session 进度推进规则。
- [SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md)：冻结 `M5` Agent `/messages/stream` 的最小兼容 SSE facade，明确复用 Stage 7 的同步写表逻辑，只输出当前前端真实消费的 `reply_delta / session / done / error` 事件。
- [SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md)：补齐 `M5` Stage 5 遗漏的 owner-only `GET /api/runtime/custom-world-library/:profileId` 设计，冻结单条 profile detail 的 SpacetimeDB procedure、client facade、404 语义与 Axum 路由扩展方式。
- [M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)：冻结 `M3` 第二批 `browse history` 纵向切片的 `user_browse_history` 表、双路径 facade、宽松归一化、去重排序规则与测试策略。
- [ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](./ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)：冻结已确认 `asset_object` 绑定到业务实体槽位的首版 reducer/procedure、通用 `asset_entity_binding` 表与 Axum facade。
- [FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md](./FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md)：把鉴权、浏览历史、runtime story 快照、NPC 待接委托与正式生成编排继续后移到 Express 后端的实施方案与验收口径。
- [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
- [ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md](./ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md)：冻结编码检查不扫描临时 Cargo / verify 工作区、同时把 Rust 源文件纳入 UTF-8 校验的修复口径。
- [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。
- [CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md](./CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md)：世界草稿生成失败后等待页误显示为“卡在编译草稿卡”的根因拆解、主链与增强链路边界，以及本次修复策略。
- [CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md](./CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md)：世界草稿里“资产已生成但结果页看不到”的根因拆解，包含角色主形象展示、分幕背景露出和 fallback 资源格式修复。
@@ -51,6 +67,23 @@
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md)：记录工作包 E 已完成的前端 runtime story 主链真实迁移、NPC 交互与 gateway/client 收口、旧入口兼容降级，以及定向回归验证结果。
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md)：记录工作包 G 已完成的后端 runtime session / action service 物理迁移、新域原语导出、旧热点兼容降级，以及定向 runtime story 回归验证结果。
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md)：记录工作包 H 已完成的 RPG 运行时仓储拆分、shared runtime contract 分文件、旧 `story.ts` façade 兼容与定向回归结果。
- [M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `M4` 首轮已落地的 `story_session / story_event` SpacetimeDB 基座、`begin_story_session / continue_story` reducer、同步返回快照的 story procedure、`spacetime-client` facade 与新的 `/api/story/sessions*` Axum 接口，以及当前尚未兼容旧 `runtime story` 路由的边界。
- [M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md](./M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/story/sessions/:storySessionId/state` 这条最小 story state 查询切片，明确当前只返回 `storySession + storyEvents`，不等价于旧 `runtime story state` 兼容完成。
- [M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md](./M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md)：冻结旧 `POST /api/runtime/story/state/resolve` 兼容桥的首版边界，明确先补 `RuntimeStoryActionResponse` DTO 与状态桥，再继续进入 Rust `actions/resolve` 与正式 snapshot projection。
- [M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md](./M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md)：冻结 `module-ai` 首版的任务/阶段/流式片段/结果引用领域模型、最小内存服务与后续 `platform-llm` / `api-server` / `spacetime-module` 的边界。
- [M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-ai` 在 `spacetime-module` 中首轮已落地的 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 真相表、最小 reducer/procedure 与当前仍未扩到真实模型调用和 Axum facade 的边界。
- [M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md](./M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md)：冻结 `module-ai` 从 `shared-contracts`、`spacetime-client` 到 `api-server` 的最小 AI task mutation facade，明确 `start` 路由当前只返回 `202 Accepted`。
- [M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-quest` 首轮已落地的 `quest_record / quest_log` 字段模型、`accept_quest / apply_quest_signal / acknowledge_quest_completion / turn_in_quest` reducer 边界，以及当前刻意未扩到奖励结算和 Axum facade 的范围。
- [M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `module-runtime-item` 首轮已落地的 `treasure_record` 字段模型、奖励快照 contract、`resolve_treasure_interaction` reducer/procedure 边界，以及当前刻意未扩到 `inventory_slot` 和 Axum facade 的范围。
- [M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md)：冻结 `module-combat` 首版 `battle_state`、`resolve_combat_action`、`fight / spar` 收束规则与 `spacetime-module` 接线边界，明确当前暂不接入 `inventory_use` 与跨子域奖励联动。
- [M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md](./M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md)：冻结 `module-combat` 从 `spacetime-module procedure` 到 `spacetime-client` 再到 `api-server` 的最小同步返回链，明确当前只新增独立 battle facade，不直接兼容旧 runtime story 总入口。
- [M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md](./M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/story/battles/:battleStateId` 这条最小 battle state 查询切片，明确当前只返回单个 `battleState` 真相态，不等价于旧 runtime story state 兼容完成。
- [M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md](./M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md)：冻结 `GET /api/runtime/sessions/:runtimeSessionId/inventory` 这条最小 inventory 查询切片，明确当前只返回 `inventory_slot` 真相表拆分后的 `backpackItems + equipmentItems`。
- [M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `module-npc` 首轮已落地的 `npc_state / relation_state / stance_profile` 领域 contract、`resolve_npc_social_action` 规则原语，以及 `spacetime-module` 的最小 reducer / procedure 接线边界。
- [M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md](./M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md)：冻结 `npc_fight / npc_spar` 在 `spacetime-module` 聚合层初始化 `battle_state` 的最小联合 procedure 边界，明确仍不把战斗初始化字段回灌到 `module-npc` 纯领域 crate。
- [M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md](./M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md)：冻结 `resolve_npc_battle_interaction_and_return` 向上接入 `spacetime-client` 与 `api-server` 的最小同步返回链，明确当前只新增独立 `POST /api/story/npc/battle` facade。
- [M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md)：记录 `server-rs` 侧 `module-progression` 首轮已落地的 `player_progression / chapter_progression` 字段模型、成长曲线、章节预算与记账 reducer / procedure 边界，以及当前刻意未扩到完整章节蓝图迁移和 quest/combat 自动联动的范围。
- [M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md](./M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md)：冻结 `turn_in_quest` 与 `resolve_combat_action(Victory)` 到 `player_progression / chapter_progression` 的最小联动口径，明确 battle 奖励字段、章节账本静默跳过规则与本轮不扩到的范围。
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md)：对照执行计划逐项复核第一批与第二批并行工作的真实落地状态，记录本轮确认到的测试合流收口遗漏与文档索引补齐结果。
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md)：记录 RPG 执行计划第三批收口已完成的前端新域主链接回、后端新仓储接线、shared contract 直连收紧、旧兼容脚本物理删除，以及明确未扩到 UI 和无关历史文档的边界。
- [RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md](./RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md)：记录 RPG 主链旧 `GameShell`、`useGame*`、`hooks/story`、`runtimeRoutes`、`modules/story/*`、`contracts/story.ts` 脚本的物理删除范围、残留依赖扫描和定向验证结果。

207
docs/technical/RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,207 @@
# Rust `shared-contracts` Stage1/Stage3 落地设计
日期：`2026-04-21`
关联任务：
- [../../backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md](../../backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md)
- [../../backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](../../backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md)
关联现状：
- [EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md](./EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md)
- [AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md](./AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md)
- [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)
- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)
- [M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](./M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
- [ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md](./ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md)
- [ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](./ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)
- [M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md)
## 1. 文档目的
`server-rs/crates/shared-contracts` 当前只有 README 占位，没有真正落到可被 `api-server`、后续模块 crate 与前端兼容层复用的共享协议代码。
本文件先解决 Stage1 的最小可编码切片，并补充 Stage2 的鉴权 DTO 扩展，以及 Stage3 的资产 / 叙事请求 DTO 收口：
1. 把统一 response envelope / 头部常量落到真实 crate。
2. 把已经冻结的 `auth/login-options`、`auth/me`、`auth/sessions`、`runtime/settings` DTO 收进共享 crate。
3. 让 `api-server` 首次真实依赖 `shared-contracts`，而不是继续把协议类型散落在 handler 文件里。
4. 继续把 `auth/entry`、`auth/refresh`、`auth/logout`、`auth/logout-all`、`auth/phone/*`、`auth/wechat/*` 的对外 HTTP DTO 收进共享 crate。
5. 把 `assets/*` 与 `story-sessions/*` 已冻结的公开请求 DTO 收进共享 crate。
本文件不在本轮解决：
1. SSE 事件总线的统一事件模型。
2. 前端 TypeScript 与 Rust crate 自动生成同构协议。
3. handler 里用 `json!` 拼装的响应体进一步升级为显式共享响应 DTO。
## 2. 当前问题
当前 Rust 工作区虽然已经创建了 `crates/shared-contracts` 目录，但协议仍然散落在 `crates/api-server/src/*.rs`：
1. `api_response.rs` 自己维护 `API_VERSION`、`ApiResponseMeta`。
2. `http_error.rs` 自己维护 `ApiErrorPayload`。
3. `login_options.rs`、`auth_me.rs`、`auth_sessions.rs`、`runtime_settings.rs` 继续把 DTO 定义在 handler 文件顶部。
4. `password_entry.rs`、`phone_auth.rs`、`refresh_session.rs`、`logout.rs`、`logout_all.rs`、`wechat_auth.rs` 也继续各自维护请求/响应结构。
这会带来三个直接问题：
1. `api-server` 无法和后续模块 crate 共用同一份协议定义。
2. DTO 一旦增多，handler 会重新退化成“协议 + 业务 + 装配”混写。
3. `shared-contracts` 仍是空壳，无法作为多 crate 架构中的真实依赖节点。
## 3. Stage1 范围冻结
### 3.1 本轮允许进入 `shared-contracts` 的内容
1. HTTP response envelope 常量与结构：
- `API_VERSION`
- `x-genarrative-response-envelope`
- `x-request-id`
- `x-api-version`
- `x-route-version`
- `x-response-time-ms`
- `ApiResponseMeta`
- `ApiErrorPayload`
- success / error envelope 结构
2. 鉴权相关 DTO：
- `AuthLoginOptionsResponse`
- `AuthUserPayload`
- `AuthMeResponse`
- `AuthSessionSummaryPayload`
- `AuthSessionsResponse`
- `PasswordEntryRequest`
- `PasswordEntryResponse`
- `RefreshSessionResponse`
- `LogoutResponse`
- `LogoutAllResponse`
- `PhoneSendCodeRequest`
- `PhoneSendCodeResponse`
- `PhoneLoginRequest`
- `PhoneLoginResponse`
- `WechatStartQuery`
- `WechatStartResponse`
- `WechatCallbackQuery`
- `WechatBindPhoneRequest`
- `WechatBindPhoneResponse`
3. runtime settings DTO：
- `RuntimeSettingsResponse`
- `PutRuntimeSettingsRequest`
4. 资产与叙事边界 DTO：
- `CreateDirectUploadTicketRequest`
- `GetReadUrlQuery`
- `ConfirmAssetObjectRequest`
- `BindAssetObjectRequest`
- `ConfirmAssetObjectAccessPolicy`
- `BeginStorySessionRequest`
- `ContinueStoryRequest`
### 3.2 本轮明确不进入 `shared-contracts` 的内容
1. 业务规则、归一化逻辑、数据库字段验证。
2. `module-auth`、`module-runtime` 内部领域对象。
3. 供应商回包 DTO，例如微信 OAuth provider 响应、OSS SDK 内部结构。
4. `RequestContext` 这类框架运行时对象。
## 4. crate 设计
### 4.1 目录结构
```text
server-rs/crates/shared-contracts/
├─ Cargo.toml
└─ src/
├─ lib.rs
├─ api.rs
├─ auth.rs
├─ runtime.rs
├─ assets.rs
└─ story.rs
```
### 4.2 模块职责
1. `api.rs`
- 统一 API 版本常量、头部常量。
- 定义 success / error envelope 的共享序列化结构。
2. `auth.rs`
- 只放对外 HTTP DTO 与协议常量。
- 不承接账号仓储、session 轮换、手机号/微信规则。
3. `runtime.rs`
- 只放 `runtime/settings` 的请求响应 DTO。
- 不承接 `module-runtime` 的默认值、归一化与 SpacetimeDB 表结构。
4. `assets.rs`
- 只放资产上传、读签名、对象确认、实体绑定的公开 HTTP DTO。
- 允许依赖 `platform-oss::OssObjectAccess` 这类跨 crate 协议字段类型，但不承接 OSS client、provider 回包与上传流程实现。
5. `story.rs`
- 只放 `story-sessions` 的公开请求 DTO。
- 不承接 `module-story` 的会话状态机、事件生成与持久化细节。
## 5. 关键约束
### 5.1 只放协议，不放业务
`shared-contracts` 的判断标准是：
1. 这个类型是否直接出现在 HTTP / SSE 边界上。
2. 它是否不需要访问仓储、配置、时钟、网络或第三方 SDK。
如果答案不是这两项都满足，就不应该进入本 crate。
### 5.2 Stage1 先接受字符串字段
本轮共享 DTO 里的部分值域虽然已经在文档中冻结，例如：
1. `loginMethod`
2. `bindingStatus`
3. `platformTheme`
但为了避免第一轮就把 Rust 领域枚举与 HTTP 枚举强绑定，本轮仍以字符串字段为主，只提供协议常量，不在 `shared-contracts` 内复制业务枚举和归一化规则。
这样做的原因：
1. 当前 `api-server` 已有 `module-auth`、`module-runtime` 的真实值域来源。
2. 先把协议层抽出来，能更快形成稳定依赖。
3. 后续若要升级成显式枚举，可在 `shared-contracts` 单独做 breaking change，而不是把 Stage1 扩成大量语义迁移。
## 6. 首批接入策略
### 6.1 `api-server`
本轮直接接入以下共享定义：
1. `api_response.rs` 改为依赖 `shared-contracts::api::*`
2. `http_error.rs` 改为依赖 `shared-contracts::api::ApiErrorPayload`
3. `login_options.rs`、`auth_me.rs`、`auth_sessions.rs`、`runtime_settings.rs` 改为依赖 `shared-contracts` DTO
4. `password_entry.rs`、`phone_auth.rs`、`refresh_session.rs`、`logout.rs`、`logout_all.rs`、`wechat_auth.rs` 改为依赖 `shared-contracts::auth::*`
5. `assets.rs` 改为依赖 `shared-contracts::assets::*`
6. `story_sessions.rs` 改为依赖 `shared-contracts::story::*`
### 6.2 其他 crate
本轮暂不要求 `module-auth`、`module-runtime`、`module-story` 直接依赖 `shared-contracts`。
原因：
1. 这些 crate 当前主要暴露领域模型，而不是对外 HTTP DTO。
2. 先让 `api-server` 真实消费共享协议，才能验证 crate 边界是否稳定。
## 7. 验证要求
至少完成以下验证：
1. `cargo test -p shared-contracts`
2. `cargo test -p api-server`
3. 文档索引补齐，确保后续任务能直接找到这份设计。
## 8. 完成定义
满足以下条件时，`实现 shared-contracts` 的 Stage1 到 Stage3 视为完成：
1. `server-rs/crates/shared-contracts` 不再只有 README，占位 crate 变成真实可编译 crate。
2. `server-rs/Cargo.toml` 已把它纳入 workspace members。
3. `api-server` 已真实依赖并消费首批共享协议定义。
4. 统一 envelope、auth/runtime/assets/story 的公开 DTO 不再散落定义在 handler 文件顶部。
5. `api-server` 中剩余本地 `Request/Response/Query` 类型只保留框架运行时对象与第三方 provider 私有 DTO。
6. 文档与技术索引已同步更新。

126
docs/technical/RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,126 @@
# Rust `shared-contracts` Stage4 响应 DTO 落地设计
日期：`2026-04-21`
关联文档：
- [RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md](./RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md)
- [ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md](./ASSET_OBJECT_CONFIRM_FLOW_DESIGN_2026-04-21.md)
- [ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](./ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)
- [M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md](./M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md)
## 1. 文档目的
Stage1 到 Stage3 已经把 `auth/runtime/assets/story` 的公开请求 DTO 收进 `shared-contracts`，但 `api-server` 里仍有两组成功响应还在 handler 内用 `json!` 直接手拼：
1. `assets.rs`
2. `story_sessions.rs`
这会让 handler 继续承担协议字段名维护职责，也会让共享 crate 在“请求已收口、响应仍分散”的中间态停太久。
本文件冻结 Stage4 的最小追加范围：
1. 把 `assets/*` 的成功响应 DTO 显式落到 `shared-contracts::assets`
2. 把 `story-sessions/*` 的成功响应 DTO 显式落到 `shared-contracts::story`
3. 让 `api-server` 的这两组 handler 改为直接返回共享响应类型
## 2. 当前问题
当前 `api-server` 已经不再本地定义 `assets/story` 的请求 DTO，但成功响应仍然是字面量 JSON：
1. `create_direct_upload_ticket`
2. `get_asset_read_url`
3. `confirm_asset_object`
4. `bind_asset_object_to_entity`
5. `begin_story_session`
6. `continue_story`
风险有三点：
1. 字段名仍散落在 handler 内，后续字段调整容易漏改测试或文档。
2. `shared-contracts` 无法完整代表这几条公开接口的成功 contract。
3. handler 重新退化成“业务编排 + 协议拼装”混写。
## 3. Stage4 范围冻结
### 3.1 本轮新增进入 `shared-contracts` 的类型
`shared-contracts::assets`：
1. `CreateDirectUploadTicketResponse`
2. `DirectUploadTicketPayload`
3. `DirectUploadTicketFormFields`
4. `GetAssetReadUrlResponse`
5. `AssetReadUrlPayload`
6. `ConfirmAssetObjectResponse`
7. `AssetObjectPayload`
8. `BindAssetObjectResponse`
9. `AssetBindingPayload`
`shared-contracts::story`：
1. `StorySessionPayload`
2. `StoryEventPayload`
3. `StorySessionMutationResponse`
### 3.2 本轮明确不进入 `shared-contracts` 的内容
1. `AppError.details` 里的错误明细 JSON 结构。
2. `healthz`、内部调试路由或测试专用返回体。
3. `spacetime-client`、`module-assets`、`module-story` 的领域记录类型。
4. `platform-oss` 的上传客户端实现与原始返回对象直接对外暴露。
## 4. 设计约束
### 4.1 响应字段名必须完全兼容当前 JSON
本轮不是协议重设计，而是把现有稳定输出显式类型化，因此：
1. 字段名必须与当前测试断言一致。
2. `assets` 返回中的 `formFields` 结构必须保持现有 key 命名。
3. `story` 返回中的 `status`、`eventKind` 继续保持字符串，不升级成 Rust 枚举。
### 4.2 允许以适配层方式消费下游 crate
`shared-contracts` 可以为 `platform-oss` 的稳定协议返回对象提供转换适配，但不直接把这些类型当作最终 HTTP contract 暴露出去。
这样做的原因：
1. HTTP contract 仍由 `shared-contracts` 持有。
2. `platform-oss` 仍只负责 OSS 协议与签名实现。
3. 后续若 HTTP 返回要和底层实现解耦，可以只改适配层，不影响 handler 调用方式。
## 5. `api-server` 接入方式
### 5.1 `assets.rs`
改造后 handler 只负责：
1. 调用 `oss_client` / `spacetime_client`
2. 把结果映射成 `shared-contracts::assets::*`
3. 交给 `json_success_body` 输出 envelope 或裸数据
### 5.2 `story_sessions.rs`
改造后 handler 只负责：
1. 组装 `begin_story_session` / `continue_story` 调用参数
2. 把 `StorySessionResultRecord` 映射成 `StorySessionMutationResponse`
3. 复用现有错误 envelope 输出
## 6. 验证要求
至少完成以下验证：
1. `cargo fmt --all`
2. `cargo test -p shared-contracts`
3. `cargo test -p api-server`
## 7. 完成定义
满足以下条件时，Stage4 视为完成：
1. `shared-contracts::assets` 与 `shared-contracts::story` 已拥有这轮新增的成功响应 DTO。
2. `api-server/src/assets.rs` 与 `api-server/src/story_sessions.rs` 不再直接手拼成功响应字段。
3. 现有接口 JSON 输出对测试保持兼容。
4. 文档索引与 crate README 已同步更新。

106
docs/technical/RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,106 @@
# Rust `shared-kernel` crate 第一阶段设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于把 `server-rs/crates/shared-kernel` 从“目录占位”推进到“首批真实可复用能力”，并明确第一阶段只实现已经在多个 Rust crate 中重复出现的最小领域内核。
本阶段目标不是提前把所有业务模型都上提，而是先解决当前已经出现的共享基础能力重复：
1. 字符串归一化
2. 前缀 ID 生成
3. RFC3339 / 微秒时间戳格式化与解析
## 2. 当前问题
截至 `2026-04-21`，`shared-kernel` 已有目录与 README 占位，但仍存在以下工程问题：
1. `server-rs/Cargo.toml` 尚未把 `shared-kernel` 纳入 workspace member
2. `module-auth`、`module-assets`、`platform-auth` 已经各自重复实现字符串裁剪、UUID 生成、时间格式化等基础逻辑
3. 这些重复逻辑已经跨多个 crate 出现，继续分散会让后续 `SpacetimeDB` 表、reducer、Axum facade 和平台适配层继续复制
## 3. 第一阶段职责边界
### 3.1 `shared-kernel` 本阶段负责
1. 提供跨模块共享的基础字符串归一化函数
2. 提供跨模块共享的前缀 ID 生成函数
3. 提供跨模块共享的时间文本格式化与解析函数
4. 为后续 `SpacetimeDB` 表字段、模块输入输出和平台适配提供统一基础值处理
### 3.2 `shared-kernel` 本阶段不负责
1. 不上提 `AuthProvider`、`BindingStatus`、`AssetObjectAccessPolicy` 这类仍带模块语义的业务枚举
2. 不上提 `AuthUser`、`RefreshSessionRecord`、`AssetObjectRecord` 这类仍明显属于单模块的实体结构
3. 不承担 `Axum`、`JWT`、`Cookie`、`OSS`、`SpacetimeDB SDK` 等框架或平台适配职责
4. 不把 `shared-kernel` 做成新的“大公共工具箱”
## 4. 第一阶段落地范围
首批只允许进入 `shared-kernel` 的能力如下：
1. `normalize_required_string(...)`
2. `normalize_optional_string(...)`
3. `build_prefixed_seed_id(prefix, seed_micros)`
4. `build_prefixed_uuid_id(prefix)`
5. `new_uuid_simple_string()`
6. `format_timestamp_micros(...)`
7. `format_rfc3339(...)`
8. `parse_rfc3339(...)`
选择这些能力的原因：
1. 已经在 `module-auth`、`module-assets`、`platform-auth` 至少两处出现重复模式
2. 它们只表达基础值处理，不携带模块私有业务语义
3. 后续 `SpacetimeDB` 表、snapshot、procedure/reducer 输入输出会继续使用这些能力
## 5. 首批接入 crate
第一阶段要求至少完成以下真实接入，避免出现“crate 存在但没有复用”的假落地：
1. `module-assets`
- 接管 `normalize_optional_value`
- 接管 `generate_asset_object_id`
- 接管 `generate_asset_binding_id`
- 接管微秒时间戳格式化
2. `module-auth`
- 接管随机会话 / state ID 生成
- 接管可选字符串归一化
- 接管 RFC3339 格式化与解析
3. `platform-auth`
- 接管必填/可选字符串归一化
- 接管 refresh session token UUID simple 生成
## 6. 与 SpacetimeDB 的边界
根据 `spacetimedb-rust` 与 `spacetimedb-concepts` 约束，`shared-kernel` 本阶段保持以下边界：
1. 不在这里定义 `#[table]` 结构
2. 不在这里实现 reducer / procedure
3. 不在这里引入外部副作用
4. 只沉淀可以同时服务 `Axum` 模块、领域模块和后续 `SpacetimeDB` 类型的基础值对象处理
## 7. 完成定义
当以下条件满足时，本阶段 `shared-kernel` 落地视为完成：
1. `shared-kernel` 已有正式 `Cargo.toml` 与 `src/lib.rs`
2. `server-rs/Cargo.toml` 已纳入 workspace member
3. `module-assets`、`module-auth`、`platform-auth` 至少有一批重复基础逻辑已改为复用 `shared-kernel`
4. `shared-kernel` 自身带有最小单元测试
5. 文档索引已收录本设计文档
## 8. 后续阶段
第一阶段完成后，后续若要继续扩展 `shared-kernel`，必须满足以下前置条件：
1. 新上提类型已经在多个模块稳定复用
2. 已有文档能证明它不是单模块私有语义
3. 不会把模块边界重新压回共享层
优先候选方向包括：
1. 更稳定的核心 ID 新类型
2. 共享版本号 / 状态值对象
3. 更明确的时间或审计基础结构

112
docs/technical/RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md Normal file
View File

@@ -0,0 +1,112 @@
# Rust `shared-kernel` crate 第二阶段接入设计
日期：`2026-04-21`
## 1. 文档目的
第一阶段已经把 `shared-kernel` 从占位目录推进成真实 crate，并冻结了最小共享 API。
第二阶段不新增共享 API，只继续把已经确认稳定的第一阶段能力接入更多 Rust crate，避免重复 helper 在工作区继续扩散。
## 2. 本阶段问题
截至当前，工作区里仍有几类已经被第一阶段覆盖、但尚未切到 `shared-kernel` 的重复实现：
1. `module-runtime` 仍本地维护可选字符串归一化与 RFC3339 / 微秒时间戳格式化解析
2. `module-story` 仍本地维护可选字符串归一化与微秒时间戳格式化
3. `spacetime-client` 仍本地维护微秒时间戳格式化
4. `api-server` 的 `session_client` 与 `assets` 测试仍各自维护可选字符串归一化、UUID simple 生成
这些逻辑都属于第一阶段已经冻结的共享值处理能力，继续保留本地副本只会增加后续漂移风险。
## 3. 本阶段边界
### 3.1 本阶段允许做的事
1. 继续复用第一阶段已存在的 `shared-kernel` API
2. 删除业务 crate 内与这些 API 完全等价的本地 helper
3. 在文档中补充第二阶段接入范围与验证结果
### 3.2 本阶段明确不做的事
1. 不新增新的 `shared-kernel` 公共函数
2. 不上提 `module-runtime`、`module-story`、`api-server` 私有业务规则
3. 不修改 `SpacetimeDB` table、reducer、procedure 的领域边界
4. 不把 `shared-kernel` 扩成新的“通用工具箱”
## 4. 第二阶段接入范围
### 4.1 `module-runtime`
接入以下共享能力：
1. `normalize_optional_string(...)`
2. `format_rfc3339(...)`
3. `parse_rfc3339(...)`
保留本地 `format_utc_micros(...)` 作为 runtime 领域语义包装，但内部改为调用共享格式化/解析能力，统一异常兜底口径。
### 4.2 `module-story`
接入以下共享能力：
1. `normalize_optional_string(...)`
2. `format_timestamp_micros(...)`
### 4.3 `spacetime-client`
接入以下共享能力：
1. `format_timestamp_micros(...)`
### 4.4 `api-server`
接入以下共享能力：
1. `session_client` 使用 `normalize_optional_string(...)`
2. `assets` 测试使用 `new_uuid_simple_string(...)`
## 5. 完成定义
当以下条件满足时，`shared-kernel` 第二阶段接入视为完成：
1. 第二阶段设计文档已补齐并收录到技术索引
2. 上述四个 crate 不再保留完全等价的重复 helper
3. 相关 crate 编译通过
4. 关键测试与编码检查通过
## 6. 后续约束
后续若继续扩展 `shared-kernel`，仍必须满足：
1. 已在多个 crate 稳定复用
2. 已有文档证明它不是单模块私有语义
3. 能通过“共享值处理”边界审核，而不是把业务规则上提
## 7. 本轮落地结果
### 7.1 实际收口情况
1. `module-runtime` 改为直接使用 `shared-kernel::normalize_optional_string(...)`，并保留 `format_utc_micros(...)` 作为 runtime 领域语义包装
2. `module-story` 改为直接使用 `shared-kernel::format_timestamp_micros(...)`，并保留 `normalize_optional_value(...)` 作为现有公共 API 兼容入口
3. `spacetime-client` 改为直接使用 `shared-kernel::format_timestamp_micros(...)`，同时移除 battle state 查询遗留的未使用导入噪音
4. `api-server::session_client` 改为直接使用 `shared-kernel::normalize_optional_string(...)`
5. `module-auth` 第一阶段遗留的可选字符串归一化私有副本也一并收口到 `shared-kernel`
### 7.2 验证结果
本轮基于独立 `CARGO_TARGET_DIR` 进行最小验证，避免与工作区内其他并行 `cargo` 任务争抢默认构建目录。
已通过的命令：
1. `cargo check -p module-auth --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml --message-format short`
2. `cargo check -p module-runtime --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml --message-format short`
3. `cargo check -p module-story --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml --message-format short`
4. `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml --message-format short`
5. `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml --message-format short`
### 7.3 当前刻意保留的兼容说明
1. 第二阶段没有新增 `shared-kernel` 公共 API，只扩大既有共享能力的复用范围
2. `spacetime-client::get_battle_state(...)` 仍保持“明确报错”的临时兼容语义，因为当前生成的 SpacetimeDB binding 尚未带出对应可调用 procedure
3. 本轮没有修改自动生成的 `server-rs/crates/spacetime-client/src/module_bindings/*`

84
docs/technical/RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md Normal file
View File

@@ -0,0 +1,84 @@
# Rust `shared-kernel` crate 第三阶段值归一化扩展设计
日期：`2026-04-22`
## 1. 文档目的
第二阶段已经把第一阶段冻结的字符串、UUID 与时间处理能力继续接入到更多 crate，但 `server-rs` 里仍有一批完全等价、且已经跨多个纯领域 crate 重复出现的“字符串列表归一化”和“前缀种子 ID 拼接”逻辑。
第三阶段目标不是继续扩大共享边界到业务规则，而是只补一个已经被多个 crate 重复验证过的最小共享能力，并把现有 `build_prefixed_seed_id(...)` 继续接到更多领域 crate。
## 2. 本阶段问题
截至当前，以下重复模式已在多个 crate 中稳定出现：
1. `normalize_string_list(Vec<String>) -> Vec<String>`：逐项 `trim()`，过滤空白项
2. `format!("{}{:x}", PREFIX, seed_micros)`：前缀 + 十六进制微秒种子 ID 生成
这些逻辑已经出现在 `module-ai`、`module-inventory`、`module-runtime-item`、`module-npc`、`module-quest`、`module-combat`、`module-story` 等多个纯领域 crate 中，继续分散维护会增加漂移风险。
## 3. 本阶段边界
### 3.1 本阶段允许做的事
1. 在 `shared-kernel` 中新增 `normalize_string_list(...)`
2. 把更多纯领域 crate 的前缀种子 ID 生成切到 `build_prefixed_seed_id(...)`
3. 把更多纯领域 crate 的字符串列表归一化切到 `normalize_string_list(...)`
4. 保留对外已有的领域兼容函数名，只替换其内部实现或导出方式
### 3.2 本阶段明确不做的事
1. 不上提 JSON payload、配置、HTTP header、OSS object key 等带平台语义的归一化规则
2. 不上提 `task_id + stage_kind` 这种带模块专属结构的 ID 生成规则
3. 不把单个字段的业务校验错误语义挪进 `shared-kernel`
4. 不修改 `SpacetimeDB` table、reducer、procedure 的领域边界
## 4. 第三阶段接入范围
### 4.1 `shared-kernel`
新增：
1. `normalize_string_list(values: Vec<String>) -> Vec<String>`
函数职责只包含：
1. 逐项裁剪字符串首尾空白
2. 过滤归一化后为空的条目
3. 返回顺序保持不变
### 4.2 继续接入 `build_prefixed_seed_id(...)`
接入以下 crate：
1. `module-ai`
2. `module-inventory`
3. `module-combat`
4. `module-story`
### 4.3 继续接入 `normalize_string_list(...)`
接入以下 crate：
1. `module-ai`
2. `module-inventory`
3. `module-runtime-item`
4. `module-npc`
5. `module-quest`
## 5. 完成定义
当以下条件满足时，第三阶段视为完成：
1. 设计文档已收录到技术索引
2. `shared-kernel` 新增 `normalize_string_list(...)` 且带最小测试
3. 上述 crate 不再保留完全等价的重复列表归一化与前缀种子 ID 拼接实现
4. 相关 crate 编译通过
## 6. 后续约束
后续若继续扩展 `shared-kernel`，仍必须满足：
1. 已在多个 crate 稳定复用
2. 仍属于共享值处理，而不是业务规则
3. 必须先补文档再落代码

72
docs/technical/RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md Normal file
View File

@@ -0,0 +1,72 @@
# Rust `shared-kernel` crate 第四阶段必填字符串接入设计
日期：`2026-04-22`
## 1. 文档目的
第三阶段已经把前缀种子 ID 和字符串列表归一化继续接入到更多纯领域 crate，但工作区里仍有一批完全等价的“必填字符串裁剪后判空”逻辑分散在多个领域模块内。
第四阶段目标仍然不是新增业务规则，而是继续把已有的 `normalize_required_string(...)` 扩到更多纯领域 crate，减少重复实现。
## 2. 本阶段问题
截至当前，以下重复模式仍在多个领域 crate 中出现：
1. `value.trim().to_string()` 后判空并返回模块自己的字段错误
2. 构造输入 DTO 时先 `trim().to_string()`，再走统一校验函数
这些模式已经出现在 `module-progression`、`module-story`、`module-combat`、`module-ai`、`module-npc`、`module-runtime-item`、`module-inventory`、`module-quest` 中，且都只属于共享值处理能力。
## 3. 本阶段边界
### 3.1 本阶段允许做的事
1. 继续复用 `shared-kernel::normalize_required_string(...)`
2. 在各领域 crate 中保留原有错误枚举与错误语义
3. 把本地 `normalize_required_*` 改成调用共享实现
4. 把“构造时先 trim，再 validate”的输入构造改成共享归一化
### 3.2 本阶段明确不做的事
1. 不新增新的 `shared-kernel` 公共函数
2. 不修改 JSON、配置、HTTP、OSS 等平台语义归一化逻辑
3. 不改动 `SpacetimeDB` table、reducer、procedure 边界
4. 不改动模块对外错误文案
## 4. 第四阶段接入范围
### 4.1 继续接入 `normalize_required_string(...)`
接入以下 crate：
1. `module-progression`
2. `module-story`
3. `module-combat`
4. `module-ai`
5. `module-npc`
6. `module-runtime-item`
7. `module-inventory`
8. `module-quest`
### 4.2 接入策略
1. 若本地 helper 只是“trim + 判空 + 映射错误”，则改为调用 `normalize_required_string(...)`
2. 若本地构造函数只是先 `trim` 再调用 validate，则直接在构造阶段复用共享必填归一化
3. 若逻辑同时包含模块私有结构规则，则只替换其中的基础字符串归一化部分
## 5. 完成定义
当以下条件满足时，第四阶段视为完成：
1. 文档已收录到技术索引
2. 上述 crate 中完全等价的必填字符串归一化重复实现已继续减少
3. 相关 crate 编译通过
4. 编码检查通过
## 6. 后续约束
后续若继续扩展 `shared-kernel`，仍必须满足：
1. 已在多个 crate 稳定复用
2. 仍属于共享值处理，而不是业务规则
3. 先补文档再落代码

89
docs/technical/RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md Normal file
View File

@@ -0,0 +1,89 @@
# Rust `shared-kernel` crate 第五阶段纯领域字段接入设计
日期：`2026-04-22`
## 1. 文档目的
第四阶段已经把 `normalize_required_string(...)` 接入到更多纯领域 crate，但 `module-runtime` 与 `module-assets` 中仍保留一批完全等价的“必填字符串裁剪后判空”逻辑。
第五阶段目标仍然不是扩展新的共享 API，而是继续把已冻结的共享能力接入剩余纯领域字段，进一步减少重复实现，同时保持各模块既有错误语义与字段特有规则不变。
## 2. 本阶段问题
截至当前，以下重复模式仍然存在：
1. `user_id` 一类稳定必填字段在多个 runtime 输入构造函数里重复 `trim + 判空`
2. 浏览历史同步中 `owner_user_id / profile_id / world_name` 的字段级过滤仍然手写 `trim + is_empty`
3. 资产对象与绑定输入中的 `asset_object_id / bucket / asset_kind / binding_id / entity_kind / entity_id / slot` 等稳定字段仍然手写 `trim + 判空`
这些逻辑都属于共享值处理，不涉及业务流程、平台配置或外部服务语义。
## 3. 本阶段边界
### 3.1 本阶段允许做的事
1. 继续复用 `shared-kernel::normalize_required_string(...)`
2. 在模块内增加薄包装 helper，把共享归一化结果映射到模块自己的错误枚举
3. 对仍然需要字段特有语义的场景，仅替换其中的基础必填字符串归一化部分
### 3.2 本阶段明确不做的事
1. 不新增新的 `shared-kernel` 公共函数
2. 不把 `theme_mode`、`visited_at`、RFC3339 解析等 runtime 语义上提到共享层
3. 不把 OSS endpoint、metadata、HTTP request、JSON payload 归一化上提到共享层
4. 不改动 `SpacetimeDB` reducer / procedure / table 结构
5. 不改动模块对外错误文案
## 4. 第五阶段接入范围
### 4.1 `module-runtime`
接入以下稳定字段：
1. `RuntimeSettingGetInput.user_id`
2. `RuntimeSettingUpsertInput.user_id`
3. `RuntimeBrowseHistoryListInput.user_id`
4. `RuntimeBrowseHistoryClearInput.user_id`
5. `RuntimeBrowseHistorySyncInput.user_id`
6. `RuntimeProfileDashboardGetInput.user_id`
7. `RuntimeProfileWalletLedgerListInput.user_id`
8. `RuntimeProfilePlayStatsGetInput.user_id`
9. 浏览历史同步时单条记录过滤使用的 `owner_user_id / profile_id / world_name`
### 4.2 `module-assets`
接入以下稳定字段：
1. `asset_object_id`
2. `bucket`
3. `asset_kind`
4. `binding_id`
5. `asset_object_id`
6. `entity_kind`
7. `entity_id`
8. `slot`
其中 `object_key` 保持模块本地语义：先裁剪空白，再去掉前导 `/`，最后再做必填校验；该规则不抽到 `shared-kernel`。
## 5. 接入策略
1. 若字段只是“trim + 判空 + 返回模块错误”，则直接改为 `normalize_required_string(...)`
2. 若字段同时有局部规则，例如 `object_key` 需要去前导 `/`，则先在模块内保留局部处理，再复用共享必填归一化
3. 若字段缺失时需要“静默过滤单条记录而非整批失败”，则继续保留该行为，只替换字段归一化实现
## 6. 完成定义
当以下条件满足时，第五阶段视为完成：
1. 文档已收录到技术索引
2. `module-runtime` 与 `module-assets` 中上述纯字段级重复实现已继续减少
3. 相关 crate 编译通过
4. 编码检查通过
## 7. 后续约束
后续若继续扩展 `shared-kernel`，仍必须满足：
1. 已在多个 crate 中稳定重复出现
2. 只属于共享值处理，不属于模块私有语义
3. 先补文档，再落代码

190
docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,190 @@
# `M5` custom world Agent message / operation Stage 7 设计
日期：`2026-04-22`
## 1. 文档目的
这份文档冻结 `M5` 的下一段最小闭环：在 Stage 6 已具备 `session create / session snapshot` 的前提下，把 RPG 创作 Agent 的 `message submit / operation query` 接到 `SpacetimeDB` 真相表与 `Axum` facade。
本轮只做：
1. `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages`
2. `GET /api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId`
3. `custom_world_agent_message` 写入用户消息
4. `custom_world_agent_operation` 写入并返回 `process_message` 操作状态
5. 在 `custom_world_agent_session` 内同步更新最小会话进度与 assistant 回复
本轮不做：
1. LLM 编排
2. SSE `message stream`
3. 真正的异步后台任务
4. `card detail / card update`
5. `draft_foundation`
6. 真实 `pendingClarifications` 推导
## 2. 设计目标
Stage 6 已能创建和读取 session，但 `POST /messages` 与 `GET /operations/:operationId` 仍未迁移，导致旧前端无法继续沿 `session -> message -> operation -> session` 的基本主链工作。
本轮目标不是还原旧 Node 的完整单轮推理，而是先提供 deterministic、同步完成的最小消息处理链，确保：
1. 前端可以提交消息
2. 后端会记录 user / assistant 双消息
3. 前端可以轮询 operation
4. session snapshot 会体现最新 turn、progress、stage 与最后回复
## 3. SpacetimeDB contract
新增输入：
1. `CustomWorldAgentMessageSubmitInput`
2. `CustomWorldAgentOperationGetInput`
新增返回：
1. `CustomWorldAgentOperationProcedureResult`
新增 procedure：
1. `submit_custom_world_agent_message`
2. `get_custom_world_agent_operation`
## 4. 最小 deterministic 处理规则
### 4.1 message submit
输入字段：
1. `session_id`
2. `owner_user_id`
3. `user_message_id`
4. `user_message_text`
5. `operation_id`
6. `submitted_at_micros`
处理步骤固定如下：
1. 校验 session 存在且归属当前用户
2. 校验 `user_message_id` 与 `operation_id` 未重复
3. 写入一条 `role = user`、`kind = chat` 的消息
4. 写入一条 `operation_type = process_message` 的操作，状态直接落为 `completed`
5. 写入一条 `role = assistant`、`kind = chat` 的 deterministic 回复消息
6. 更新 `custom_world_agent_session`：
- `current_turn += 1`
- `last_assistant_reply = deterministic reply`
- `updated_at = submitted_at`
- `progress_percent` 按最小规则推进
- `stage` 按最小规则推进
### 4.2 deterministic 回复规则
本轮不用 LLM，固定返回规则：
1. 当消息为空白时直接报错，不写表
2. 普通消息统一返回：
- `已记录这条设定。我会先把它当作新的世界线索收进当前草稿，你可以继续补充玩家身份、主题氛围、核心冲突、关键关系或标志性元素。`
3. 如果文本包含 `__phase1_force_fail__`，直接返回 procedure 错误：
- `forced failure`
这个保留字只用于兼容旧 Node 测试中的失败路径，不代表正式产品行为。
### 4.3 最小 session 推进规则
1. 初次提交消息后，`progress_percent` 至少推进到 `20`
2. 当累计 user 消息数达到 `2` 条及以上时：
- `progress_percent = 100`
- `stage = foundation_review`
- `creator_intent_readiness_json` 改为 `{ "isReady": true, "completedKeys": ["seed_input"], "missingKeys": [] }`
3. 当累计 user 消息数只有 `1` 条时：
- `progress_percent = max(existing, 20)`
- `stage = clarifying`
- `creator_intent_readiness_json` 保持 `isReady = false`
- `pending_clarifications_json` 写入最小数组，至少包含一条问题
这样做的目的不是伪装完整意图抽取，而是提供一个能被旧前端继续驱动的最小状态机。
## 5. HTTP contract
### 5.1 `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages`
请求：
```json
{
"clientMessageId": "client-001",
"text": "一条新的世界设定",
"quickFillRequested": false,
"focusCardId": null,
"selectedCardIds": []
}
```
说明：
1. `quickFillRequested`、`focusCardId`、`selectedCardIds` 本轮先只做兼容解析，不进入 SpacetimeDB 真相表
2. `clientMessageId` 直接作为 user message 主键
3. operation id 由 Axum 生成，前缀固定 `operation-`
响应：
```json
{
"operation": {
"operationId": "operation-...",
"type": "process_message",
"status": "completed",
"phaseLabel": "消息已处理",
"phaseDetail": "...",
"progress": 100,
"error": null
}
}
```
### 5.2 `GET /api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId`
返回裸 `operation` JSON，不额外包 `{ operation }`，保持旧 Node contract。
## 6. Axum 与 client 边界
`api-server` 负责：
1. Bearer JWT 鉴权
2. 参数校验与错误 envelope
3. 生成 `operation-` 主键
4. 把请求映射到 `spacetime-client`
`spacetime-client` 负责：
1. 调用 `submit_custom_world_agent_message`
2. 调用 `get_custom_world_agent_operation`
3. 把 procedure 结果映射成领域 record
`spacetime-module` 负责：
1. 真相表写入与最小 deterministic 状态推进
2. 会话归属校验
3. 快照与 operation 单条读取
## 7. 完成定义
当以下条件满足时，本轮 Stage 7 视为完成：
1. `module-custom-world` 冻结 message submit / operation get 输入输出类型
2. `spacetime-module` 可提交消息并返回 operation
3. `spacetime-module` 可查询单条 operation
4. `spacetime-client` 封装 submit / get operation
5. `api-server` 挂载：
- `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages`
- `GET /api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId`
6. `cargo check -p module-custom-world`
7. `cargo check -p spacetime-module`
8. `cargo check -p spacetime-client`
9. `cargo check -p api-server`
## 8. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md)

188
docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,188 @@
# `M5` custom world Agent message stream Stage 8 设计
日期：`2026-04-22`
## 1. 文档目的
这份文档冻结 `M5` 在 Stage 7 之后的下一段最小闭环：补齐 RPG 创作 Agent 的 `message stream` 兼容接口，让当前前端默认使用的流式消息提交主链可以重新接上 `Axum` 后端。
本轮只做：
1. `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream`
2. 兼容前端当前消费的最小 SSE 事件集合
3. 复用 Stage 7 已落地的 deterministic `message submit`
4. 在流式结束前返回最新 session snapshot
本轮不做：
1. 真实 LLM token streaming
2. SpacetimeDB 内部异步 operation 编排
3. 持续多段增量推理
4. `card detail / card update`
5. `draft_foundation`
## 2. 现状与问题
当前 Rust 后端已经完成：
1. `POST /messages`
2. `GET /operations/:operationId`
3. session snapshot 读取
但前端 RPG 创作主链默认并不是调用 `POST /messages`，而是调用：
1. `POST /messages/stream`
并消费以下 SSE 事件：
1. `reply_delta`
2. `session`
3. `error`
4. `done`
如果这条流式路由缺失，当前前端提交共创消息时会直接失败，导致 `message submit` 虽然已落地，但主链仍不可用。
## 3. 设计目标
本轮目标不是恢复旧 Node 那套真实按回调逐字增量刷新的内部推理过程，而是先提供一个最小兼容 SSE facade，满足当前前端协议：
1. 前端仍然可以继续走 `/messages/stream`
2. 后端内部复用 Stage 7 的同步 deterministic 写表逻辑
3. SSE 至少发送一条 `reply_delta`
4. SSE 最终发送一条 `session`
5. SSE 发送 `done` 后结束连接
## 4. 最小兼容 SSE 规则
### 4.1 请求体
请求体沿用 Stage 7：
```json
{
"clientMessageId": "client-001",
"text": "一条新的世界设定",
"quickFillRequested": false,
"focusCardId": null,
"selectedCardIds": []
}
```
本轮继续保持：
1. `quickFillRequested`
2. `focusCardId`
3. `selectedCardIds`
只做兼容解析，不进入真相表。
### 4.2 处理顺序
`api-server` 收到 `/messages/stream` 后按以下顺序处理：
1. 校验 `sessionId`、`clientMessageId`、`text`
2. 调用 `spacetime-client.submit_custom_world_agent_message(...)`
3. 再调用 `spacetime-client.get_custom_world_agent_session(...)`
4. 从 session snapshot 中取最后一条 assistant 消息文本
5. 组装 SSE 文本并一次性返回
### 4.3 SSE 事件集合
返回事件严格控制为以下几类：
1. `reply_delta`
- 载荷：
```json
{ "text": "assistant 最终回复全文" }
```
2. `session`
- 载荷：
```json
{ "session": { ...最新 session snapshot... } }
```
3. `done`
- 载荷：
```json
{ "ok": true }
```
4. `error`
- 仅错误时返回：
```json
{ "message": "..." }
```
本轮不引入：
1. 多段 `reply_delta`
2. operation 事件
3. keepalive 心跳
4. token / chunk 级别 streaming
## 5. 与 Stage 7 的关系
本轮 `message stream` 不是重新发明一套消息处理逻辑，而是一个 facade：
1. 真相写入仍然完全走 Stage 7 的 `submit_custom_world_agent_message`
2. session 读取仍然走 Stage 6 的 `get_custom_world_agent_session`
3. SSE 只是把“同步完成后的最终结果”包装成旧前端可消费的流式文本
因此本轮不会新增：
1. `module-custom-world` 输入输出类型
2. `spacetime-module` reducer / procedure
3. `spacetime-client` 新的 message stream 方法
## 6. HTTP contract
### 6.1 成功响应
响应头：
1. `Content-Type: text/event-stream; charset=utf-8`
2. `Cache-Control: no-cache`
3. `X-Accel-Buffering: no`
响应体示例：
```text
event: reply_delta
data: {"text":"已记录这条设定。我会先把它当作新的世界线索收进当前草稿，你可以继续补充玩家身份、主题氛围、核心冲突、关键关系或标志性元素。"}
event: session
data: {"session":{"sessionId":"..."}}
event: done
data: {"ok":true}
```
### 6.2 错误响应
如果在真正开始返回 SSE 前就失败，仍按普通 JSON 错误 envelope 返回 HTTP 错误。
如果已经进入 SSE 写出阶段才失败，则返回：
```text
event: error
data: {"message":"..."}
```
然后结束连接。
## 7. 完成定义
当以下条件满足时，本轮 Stage 8 视为完成：
1. `api-server` 挂载 `POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream`
2. 当前前端 `streamRpgCreationMessage(...)` 可解析返回内容
3. `message stream` 内部复用 Stage 7 的 deterministic 消息写入
4. `backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md` 勾选 `message stream`
5. `docs/technical/README.md` 收录本设计文档
6. `cargo check -p api-server`
## 8. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md)

187
docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,187 @@
# `M5` custom world Agent session Stage 6 设计
日期：`2026-04-22`
## 1. 文档目的
这份文档冻结 `M5` 的下一段最小闭环：把 RPG 创作 Agent 的 `session create / session snapshot` 从旧 Node 单大 JSON 会话体，迁到 `SpacetimeDB` 真相表与 `Axum` facade。
本轮只做：
1. `custom_world_agent_session` 会话骨架创建
2. 初始 assistant 欢迎消息写入 `custom_world_agent_message`
3. `session snapshot` 聚合读取
4. `POST /api/runtime/custom-world/agent/sessions`
5. `GET /api/runtime/custom-world/agent/sessions/:sessionId`
本轮不做：
1. LLM 意图抽取与澄清问题生成
2. message submit / message stream
3. card detail / card update
4. operation query
5. 完整 action registry
6. result preview compiler
## 2. 当前问题
Stage 5 已接入 agent `publish_world` action，但调用方仍需要显式提供 `draftProfile` 与 `settingText`。根因是 Rust 侧还没有可读取的 Agent session snapshot。
现有 `custom_world_agent_session` 表已有大部分会话级字段，但缺少旧前端必填的 `pendingClarifications` 真相源。本轮必须补上 `pending_clarifications_json`，否则 Axum 只能用空数组猜测，后续 message turn 迁移会继续漂移。
## 3. 表结构调整
`custom_world_agent_session` 新增：
1. `pending_clarifications_json: String`
字段语义：
1. 存储旧 contract 的 `pendingClarifications` 数组 JSON
2. 初始创建时固定为 `[]`
3. 后续 message turn / clarification 迁移后由服务端派生写入
4. 读取 snapshot 时必须反序列化为 JSON 数组，非法 JSON 返回 procedure 错误
## 4. SpacetimeDB contract
新增输入：
1. `CustomWorldAgentSessionCreateInput`
2. `CustomWorldAgentSessionGetInput`
新增快照：
1. `CustomWorldAgentMessageSnapshot`
2. `CustomWorldAgentOperationSnapshot`
3. `CustomWorldDraftCardSnapshot`
4. `CustomWorldAgentSessionSnapshot`
新增返回：
1. `CustomWorldAgentSessionProcedureResult`
新增 procedure：
1. `create_custom_world_agent_session`
2. `get_custom_world_agent_session`
创建规则：
1. `session_id` 由 Axum 生成并传入，前缀保持 `custom-world-agent-session-`
2. `owner_user_id` 来自 Bearer JWT，不信任请求体
3. `seed_text` 可为空
4. `stage` 首版固定为 `collecting_intent`
5. `progress_percent` 首版固定为 `0`
6. `anchor_content_json` 固定写入八锚点空结构
7. `creator_intent_json`、`anchor_pack_json`、`lock_state_json`、`draft_profile_json` 写入 `{}` 或最小草稿
8. `creator_intent_readiness_json` 固定写入 `{ "isReady": false, "completedKeys": [], "missingKeys": [] }`
9. `pending_clarifications_json` 固定写入 `[]`
10. `asset_coverage_json` 固定写入空覆盖率结构
11. 初始 assistant 消息写入 `custom_world_agent_message`
## 5. Axum HTTP contract
### 5.1 `POST /api/runtime/custom-world/agent/sessions`
请求：
```json
{
"seedText": "可选的世界设定起点"
}
```
响应：
```json
{
"session": {
"sessionId": "custom-world-agent-session-...",
"currentTurn": 0,
"anchorContent": {},
"progressPercent": 0,
"lastAssistantReply": "...",
"stage": "collecting_intent",
"focusCardId": null,
"creatorIntent": {},
"creatorIntentReadiness": {
"isReady": false,
"completedKeys": [],
"missingKeys": []
},
"anchorPack": {},
"lockState": {},
"draftProfile": {},
"messages": [],
"draftCards": [],
"pendingClarifications": [],
"suggestedActions": [],
"recommendedReplies": [],
"qualityFindings": [],
"assetCoverage": {},
"checkpoints": [],
"supportedActions": [],
"resultPreview": null,
"updatedAt": "..."
}
}
```
说明：
1. 返回字段保持旧 `RpgAgentSessionSnapshot` / `CustomWorldAgentSessionSnapshot` camelCase shape
2. 初始欢迎语只做 deterministic 文本，不调用 LLM
3. `supportedActions` 首版只给出保守能力状态，不伪装完整 registry
### 5.2 `GET /api/runtime/custom-world/agent/sessions/:sessionId`
读取同一个 snapshot。
权限：
1. 必须 Bearer JWT
2. 只能读取 `owner_user_id = claims.user_id` 的 session
3. 不存在或不属于当前用户时返回 SpacetimeDB procedure 错误，由 Axum 映射到当前统一错误 envelope
## 6. 完成定义
当以下条件满足时，Stage 6 视为完成：
1. `module-custom-world` 冻结 session create/get/snapshot 领域类型
2. `spacetime-module` 可创建并读取 agent session snapshot
3. `spacetime-client` 封装 create/get procedure
4. `api-server` 挂载 `POST /sessions` 与 `GET /sessions/:sessionId`
5. `M5` 任务清单勾选 `session create / session snapshot`
6. `cargo check -p module-custom-world`
7. `cargo check -p spacetime-module`
8. `cargo check -p spacetime-client`
9. `cargo check -p api-server`
## 7. bindings 刷新约束
`spacetime-client/src/module_bindings` 必须视为生成产物，不允许手工补假类型来绕过 `spacetime-module` 与客户端之间的 schema 漂移。
本仓默认刷新命令：
```bash
spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --module-path server-rs/crates/spacetime-module --include-private --yes
```
如果当前工作树里存在其他并行 `cargo build/test/check` 导致 `spacetime generate` 内部构建长期卡在锁竞争，则先在独立目标目录编译 wasm，再使用 `--bin-path` 生成：
```bash
CARGO_TARGET_DIR=server-rs/target-spacetime-bindgen cargo build --manifest-path server-rs/crates/spacetime-module/Cargo.toml --target wasm32-unknown-unknown --release
spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --bin-path server-rs/target-spacetime-bindgen/wasm32-unknown-unknown/release/spacetime_module.wasm --include-private --yes
```
这样做的目的固定如下：
1. 避开根目录 `spacetime.json` 多 generate target 对单次 Rust 生成的参数冲突。
2. 避开共享 `target/` 目录被其他任务占锁时的构建阻塞。
3. 保证 `create_custom_world_agent_session` / `get_custom_world_agent_session` 这类新 procedure 与输入输出类型能同步进入 Rust bindings。
## 8. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md)

313
docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,313 @@
# `M5` 首批 `custom world / agent` 表设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于把 `M5` 从“任务清单”推进到可直接编码的级别。
本轮只冻结首批最小可落地表：
1. `custom_world_profile`
2. `custom_world_session`
3. `custom_world_agent_session`
4. `custom_world_agent_message`
5. `custom_world_agent_operation`
6. `custom_world_draft_card`
7. `custom_world_gallery_entry`
本轮不直接落 `custom_world_asset_link`。
## 2. 本轮为什么不落 `custom_world_asset_link`
`custom_world_asset_link` 的正式真相必须与：
1. `asset_object`
2. `asset_entity_binding`
3. `M6 assets / OSS`
三者的对象定位与业务槽位规则保持一致。
当前这些规则在 `custom world` 域还没有完全冻结：
1. 角色主图槽位
2. 动作集槽位
3. 场景图槽位
4. profile / preview / card 的引用回写规则
所以本轮先不硬落，避免在 `M6` 再拆主键和字段。
## 3. 设计原则
### 3.1 不允许回到单大 JSON 会话
当前允许存在边界清晰的 JSON 字符串列，例如：
1. `draft_profile_json`
2. `result_preview_json`
3. `quality_findings_json`
4. `asset_coverage_json`
但不允许再把 `message / operation / card` 混回一个整包 `session payload`。
### 3.2 发布态 profile 允许先存编译工件
`custom_world_profile` 当前承担：
1. library
2. works 的发布态
3. publish / unpublish
4. enter-world
因此允许先保留 `profile_payload_json` 作为正式发布态工件。
### 3.3 gallery 单独投影
`custom_world_gallery_entry` 作为公开读模型单独建表，不再从 profile 运行时拼装。
## 4. 表设计
## 4.1 `custom_world_profile`
### 职责
1. 存正式 profile 工件
2. 承接 library / publish / enter-world 的发布态真相
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `profile_id` | `String` | 是 | 主键 |
| `owner_user_id` | `String` | 是 | 归属用户 |
| `source_agent_session_id` | `Option<String>` | 否 | 来源 Agent 会话 |
| `publication_status` | `CustomWorldPublicationStatus` | 是 | `draft / published` |
| `world_name` | `String` | 是 | 世界名 |
| `subtitle` | `String` | 是 | 副标题 |
| `summary_text` | `String` | 是 | 摘要 |
| `theme_mode` | `CustomWorldThemeMode` | 是 | 主题模式 |
| `cover_image_src` | `Option<String>` | 否 | 封面 |
| `profile_payload_json` | `String` | 是 | 正式 profile JSON |
| `playable_npc_count` | `u32` | 是 | 角色数量摘要 |
| `landmark_count` | `u32` | 是 | 地标数量摘要 |
| `published_at` | `Option<Timestamp>` | 否 | 发布时间 |
| `created_at` | `Timestamp` | 是 | 创建时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `owner_user_id`
2. `publication_status`
## 4.2 `custom_world_session`
### 职责
1. 承接旧 `custom-world/sessions` 传统问答流历史兼容
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `session_id` | `String` | 是 | 主键 |
| `owner_user_id` | `String` | 是 | 归属用户 |
| `generation_mode` | `CustomWorldGenerationMode` | 是 | `fast / full` |
| `status` | `CustomWorldSessionStatus` | 是 | 传统问答流状态 |
| `setting_text` | `String` | 是 | 原始设定输入 |
| `creator_intent_json` | `Option<String>` | 否 | creator intent |
| `question_snapshot_json` | `String` | 是 | 问答快照 |
| `result_payload_json` | `Option<String>` | 否 | 编译结果 |
| `last_error_message` | `Option<String>` | 否 | 最近错误 |
| `created_at` | `Timestamp` | 是 | 创建时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `owner_user_id`
## 4.3 `custom_world_agent_session`
### 职责
1. 承接 RPG 创作 Agent 会话真相
2. 会话级元数据与 preview / readiness / quality / asset coverage
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `session_id` | `String` | 是 | 主键 |
| `owner_user_id` | `String` | 是 | 归属用户 |
| `seed_text` | `String` | 是 | 初始输入 |
| `current_turn` | `u32` | 是 | 当前轮次 |
| `progress_percent` | `u32` | 是 | 进度 0~100 |
| `stage` | `RpgAgentStage` | 是 | 当前阶段 |
| `focus_card_id` | `Option<String>` | 否 | 当前焦点卡 |
| `anchor_content_json` | `String` | 是 | 八锚点 |
| `creator_intent_json` | `Option<String>` | 否 | creator intent |
| `creator_intent_readiness_json` | `String` | 是 | readiness |
| `anchor_pack_json` | `Option<String>` | 否 | anchor pack |
| `lock_state_json` | `Option<String>` | 否 | lock state |
| `draft_profile_json` | `Option<String>` | 否 | foundation draft |
| `last_assistant_reply` | `Option<String>` | 否 | 最近回复 |
| `result_preview_json` | `Option<String>` | 否 | 结果页预览 |
| `quality_findings_json` | `String` | 是 | 质量结论 |
| `suggested_actions_json` | `String` | 是 | 建议动作 |
| `recommended_replies_json` | `String` | 是 | 推荐回复 |
| `asset_coverage_json` | `String` | 是 | 资产覆盖率 |
| `checkpoints_json` | `String` | 是 | checkpoint 摘要 |
| `created_at` | `Timestamp` | 是 | 创建时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `owner_user_id`
2. `stage`
## 4.4 `custom_world_agent_message`
### 职责
1. 存消息流
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message_id` | `String` | 是 | 主键 |
| `session_id` | `String` | 是 | 所属会话 |
| `role` | `RpgAgentMessageRole` | 是 | user / assistant / system |
| `kind` | `RpgAgentMessageKind` | 是 | chat / clarification / summary / checkpoint / warning / action_result |
| `text` | `String` | 是 | 正文 |
| `related_operation_id` | `Option<String>` | 否 | 关联操作 |
| `created_at` | `Timestamp` | 是 | 创建时间 |
### 索引
1. `session_id`
## 4.5 `custom_world_agent_operation`
### 职责
1. 存异步操作
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `operation_id` | `String` | 是 | 主键 |
| `session_id` | `String` | 是 | 所属会话 |
| `operation_type` | `RpgAgentOperationType` | 是 | 动作类型或 `process_message` |
| `status` | `RpgAgentOperationStatus` | 是 | queued / running / completed / failed |
| `phase_label` | `String` | 是 | 阶段标题 |
| `phase_detail` | `String` | 是 | 阶段说明 |
| `progress` | `u32` | 是 | 进度 0~100 |
| `error_message` | `Option<String>` | 否 | 失败原因 |
| `created_at` | `Timestamp` | 是 | 创建时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `session_id`
## 4.6 `custom_world_draft_card`
### 职责
1. 把 card 从会话主体拆出
2. 支撑 card detail / update
### 访问级别
`private`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `card_id` | `String` | 是 | 主键 |
| `session_id` | `String` | 是 | 所属会话 |
| `kind` | `RpgAgentDraftCardKind` | 是 | 卡片类型 |
| `status` | `RpgAgentDraftCardStatus` | 是 | suggested / confirmed / locked / warning |
| `title` | `String` | 是 | 标题 |
| `subtitle` | `String` | 是 | 副标题 |
| `summary` | `String` | 是 | 摘要 |
| `linked_ids_json` | `String` | 是 | 关联对象 ID 列表 |
| `warning_count` | `u32` | 是 | 警告数 |
| `asset_status` | `Option<CustomWorldRoleAssetStatus>` | 否 | 资产状态 |
| `asset_status_label` | `Option<String>` | 否 | 资产状态文案 |
| `detail_payload_json` | `Option<String>` | 否 | 详情与 section |
| `created_at` | `Timestamp` | 是 | 创建时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `session_id`
2. `kind`
## 4.7 `custom_world_gallery_entry`
### 职责
1. 作为公开画廊投影
### 访问级别
`public`
### 字段
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `profile_id` | `String` | 是 | 主键 |
| `owner_user_id` | `String` | 是 | 作者 |
| `author_display_name` | `String` | 是 | 作者展示名 |
| `world_name` | `String` | 是 | 世界名 |
| `subtitle` | `String` | 是 | 副标题 |
| `summary_text` | `String` | 是 | 摘要 |
| `cover_image_src` | `Option<String>` | 否 | 封面 |
| `theme_mode` | `CustomWorldThemeMode` | 是 | 主题模式 |
| `playable_npc_count` | `u32` | 是 | 角色数 |
| `landmark_count` | `u32` | 是 | 地标数 |
| `published_at` | `Timestamp` | 是 | 发布时间 |
| `updated_at` | `Timestamp` | 是 | 更新时间 |
### 索引
1. `owner_user_id`
2. `theme_mode`
## 5. 本轮完成定义
当以下条件满足时，本轮 `M5` 首批设计视为完成：
1. 上述 7 张表字段、索引、访问级别已具体到可直接编码
2. `module-custom-world` 已成为真实 crate
3. `spacetime-module` 已接入上述表骨架
## 6. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
3. [./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)

213
docs/technical/SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,213 @@
# `M5` custom world Axum facade Stage 5 设计
日期：`2026-04-22`
## 1. 文档目的
这份文档用于把 `M5` 已落地的 SpacetimeDB custom world 主链，接入 `server-rs/crates/api-server` 的 Axum 兼容接口首批 facade。
本轮只冻结：
1. `custom-world-library` 首批读写接口
2. `custom-world-gallery` 首批读接口
3. agent `publish_world` action 的最小 HTTP facade
4. `api-server -> spacetime-client -> spacetime-module procedure` 的调用边界
本轮不做：
1. `DELETE /api/runtime/custom-world-library/:profileId`
2. 完整 agent session create / snapshot / message / SSE
3. `publish gate` / `enter-world gate` blocker 规则迁移
4. works 聚合读模型
5. LLM、图片生成、OSS 副作用编排
## 2. 当前可复用能力
当前 SpacetimeDB module 已有：
1. `list_custom_world_profiles`
2. `upsert_custom_world_profile_and_return`
3. `publish_custom_world_profile_and_return`
4. `unpublish_custom_world_profile_and_return`
5. `list_custom_world_gallery_entries`
6. `get_custom_world_gallery_detail`
7. `publish_custom_world_world`
其中 `publish_custom_world_world` 已固定为：
1. compile published profile
2. upsert profile
3. publish profile
4. 推进 `custom_world_agent_session.stage = published`
## 3. 本轮冻结的 HTTP 兼容接口
### 3.1 library
本轮接入：
1. `GET /api/runtime/custom-world-library`
2. `PUT /api/runtime/custom-world-library/:profileId`
3. `POST /api/runtime/custom-world-library/:profileId/publish`
4. `POST /api/runtime/custom-world-library/:profileId/unpublish`
本轮暂不接：
1. `DELETE /api/runtime/custom-world-library/:profileId`
原因：
1. 当前 `spacetime-module` 还没有冻结 profile delete / soft delete contract
2. 不能在 Axum 层绕开 SpacetimeDB 直接制造第二套删除语义
### 3.2 gallery
本轮接入：
1. `GET /api/runtime/custom-world-gallery`
2. `GET /api/runtime/custom-world-gallery/:ownerUserId/:profileId`
### 3.3 agent publish action
本轮接入：
1. `POST /api/runtime/custom-world/agent/sessions/:sessionId/actions`
但只支持 payload：
```json
{ "action": "publish_world" }
```
其他 agent action 继续返回 `501 NOT_IMPLEMENTED`，等待 agent session / operation / card 主链冻结。
## 4. 请求与响应 contract
### 4.1 library entry 响应
继续兼容旧 Node 的 `CustomWorldLibraryEntry` camelCase shape：
1. `ownerUserId`
2. `profileId`
3. `profile`
4. `visibility`
5. `publishedAt`
6. `updatedAt`
7. `authorDisplayName`
8. `worldName`
9. `subtitle`
10. `summaryText`
11. `coverImageSrc`
12. `themeMode`
13. `playableNpcCount`
14. `landmarkCount`
### 4.2 `PUT /custom-world-library/:profileId`
请求 body：
```json
{
"profile": {}
}
```
字段映射：
1. `profile` 原样序列化为 `profile_payload_json`
2. 元数据首版由 `api-server` 从 profile JSON 提取：
- `name`
- `subtitle`
- `summary`
- `cover.imageSrc / camp.imageSrc / landmarks[0].imageSrc`
- `themeMode`
- `playableNpcs.length + storyNpcs.length`
- `landmarks.length`
说明：
1. 后续更完整的 metadata 推断可以迁回 `module-custom-world`
2. 本轮不把 Node 的全部 `customWorldLibraryMetadata.ts` 逻辑一次性强迁
### 4.3 `POST /custom-world-library/:profileId/publish`
普通 library profile：
1. 调用 `publish_custom_world_profile_and_return`
2. 返回 `CustomWorldLibraryMutationResponse`
agent draft profile：
1. 如果 profileId 形如 `agent-draft-${sessionId}`，但请求没有提供 draft payload，本轮不会在 library publish 里自动从 agent session 重建发布内容
2. agent 发布主链应优先走 agent action facade
原因：
1. Stage 4 的 `publish_custom_world_world` 需要显式传入 `draft_profile_json`
2. session snapshot 主链尚未冻结，library publish 不能私自从 session 大 JSON 读取未定义字段
### 4.4 `POST /custom-world/agent/sessions/:sessionId/actions`
请求 body：
```json
{
"action": "publish_world",
"profileId": "agent-draft-session-001",
"draftProfile": {},
"legacyResultProfile": {},
"settingText": "..."
}
```
说明：
1. 旧 Node 的 `{ "action": "publish_world" }` 仍是最终目标
2. 但当前 Rust 还没有完整 session snapshot/read model，所以本轮先要求 facade 调用方显式传入 `draftProfile`
3. 这不是最终产品 contract，后续在 agent session snapshot 迁移后再收口为旧 payload
响应 body 继续使用旧 action 形状：
```json
{
"operation": {
"operationId": "...",
"type": "publish_world",
"status": "completed",
"phaseLabel": "世界已发布",
"phaseDetail": "...",
"progress": 100,
"error": null
}
}
```
## 5. `spacetime-client` 边界
`api-server` 不直接引用 generated bindings。
本轮在 `spacetime-client` 中新增领域侧 record：
1. `CustomWorldLibraryEntryRecord`
2. `CustomWorldGalleryEntryRecord`
3. `CustomWorldLibraryMutationRecord`
4. `CustomWorldPublishWorldRecord`
`api-server` 只消费这些 record，再映射到 `shared-contracts` 的 HTTP response。
## 6. 完成定义
当以下条件满足时，本轮 Stage 5 视为完成：
1. `shared-contracts` 已补 custom world library/gallery/action 首批响应类型
2. `spacetime-client` 已封装 custom world procedures
3. `api-server` 已挂载首批 custom world routes
4. `cargo check -p spacetime-client` 通过
5. `cargo check -p api-server` 通过
6. `npm run check:encoding` 通过
## 7. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md)

198
docs/technical/SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md Normal file
View File

@@ -0,0 +1,198 @@
# `M5` custom world library detail Stage 5 扩展设计
日期：`2026-04-22`
## 1. 文档目的
这份文档用于补齐 `Stage 5` 首批 Axum facade 中遗漏的 owner-only library detail 查询接口：
1. `GET /api/runtime/custom-world-library/:profileId`
本轮目标不是扩新系统，而是在当前已经落地的 `custom_world_profile`、`spacetime-client`、`api-server` 基座上补完正式接口台账中的缺口。
## 2. 问题背景
当前仓库状态已经具备：
1. `GET /api/runtime/custom-world-library`
2. `PUT /api/runtime/custom-world-library/:profileId`
3. `POST /api/runtime/custom-world-library/:profileId/publish`
4. `POST /api/runtime/custom-world-library/:profileId/unpublish`
5. `GET /api/runtime/custom-world-gallery`
6. `GET /api/runtime/custom-world-gallery/:ownerUserId/:profileId`
但正式接口台账里仍缺：
1. `GET /api/runtime/custom-world-library/:profileId`
同时，当前 `spacetime-module` 只有：
1. `list_custom_world_profiles`
2. `get_custom_world_gallery_detail`
缺少 owner-only 的单条 profile detail procedure。
## 3. 兼容目标
### 3.1 查询语义
`GET /api/runtime/custom-world-library/:profileId` 只允许查询当前 Bearer 用户自己的 profile。
等价语义：
1. `ownerUserId = authenticated user id`
2. `profileId = path param`
3. 不要求 profile 已发布
4. 不从 gallery 投影取数，直接以 `custom_world_profile` 真相表为准
### 3.2 响应形状
响应继续复用 gallery detail 的稳定 shape：
```json
{
"entry": {
"ownerUserId": "user_xxx",
"profileId": "profile_xxx",
"profile": {},
"visibility": "draft",
"publishedAt": null,
"updatedAt": "2026-04-22T00:00:00Z",
"authorDisplayName": "玩家",
"worldName": "潮雾群岛",
"subtitle": "旧航道与失控灯塔",
"summaryText": "......",
"coverImageSrc": null,
"themeMode": "tide",
"playableNpcCount": 2,
"landmarkCount": 3
}
}
```
原因：
1. 旧前端 detail 消费点本来就只认单个 `entry`
2. 当前 `shared-contracts` 已有 `CustomWorldGalleryDetailResponse { entry }`
3. 没必要为了 owner-only detail 再新增一套重复 envelope
## 4. SpacetimeDB 设计
### 4.1 `module-custom-world`
新增一个独立输入：
1. `CustomWorldLibraryDetailInput`
字段：
1. `owner_user_id`
2. `profile_id`
并新增对应校验：
1. `validate_custom_world_library_detail_input(...)`
### 4.2 `spacetime-module`
新增 procedure：
1. `get_custom_world_library_detail`
返回继续复用：
1. `CustomWorldLibraryMutationResult`
原因：
1. 当前已有 `entry + gallery_entry + error_message` 组合
2. owner-only detail 只需要 `entry`
3. `gallery_entry` 在这个接口中固定允许为 `None`
内部查询规则：
1. 按 `profile_id` 命中单条 `custom_world_profile`
2. 再校验 `owner_user_id == input.owner_user_id`
3. 命中后返回 `Some(profile_snapshot)`
4. 不存在时返回 `Ok((None, None))`
这里刻意不在 SpacetimeDB procedure 内把“不存在”包装成失败字符串，避免把“记录缺失”和“procedure 运行失败”混成一个错误通道。
## 5. `spacetime-client` 设计
新增 facade：
1. `get_custom_world_library_detail(owner_user_id, profile_id)`
客户端返回值继续复用：
1. `CustomWorldLibraryMutationRecord`
但需要单独增加一个 detail result mapper，在进入 HTTP 层之前就完成：
1. `result.ok == false` 时返回 procedure error
2. `result.entry == None` 时返回 `SpacetimeClientError::Procedure("custom_world_profile 不存在")`
这样 `api-server` 可以统一通过已有错误映射把缺失记录转成 `404`。
## 6. `api-server` 设计
### 6.1 路由
把：
1. `/api/runtime/custom-world-library/{profile_id}`
从仅支持 `PUT` 扩展为：
1. `GET`
2. `PUT`
### 6.2 handler
新增：
1. `get_custom_world_library_detail`
流程：
1. 读取 Bearer 身份
2. 校验 `profile_id` 非空
3. 调 `spacetime_client.get_custom_world_library_detail(...)`
4. 映射为 `CustomWorldGalleryDetailResponse { entry }`
### 6.3 错误语义
本轮明确：
1. `profileId` 为空 -> `400`
2. 当前用户下找不到 profile -> `404`
3. SpacetimeDB transport / procedure 异常 -> 继续按现有 `502/400` 规则返回
## 7. 任务清单同步
这轮还需要同步 `backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md`：
1. 把已落地的 `message stream` 勾为完成
2. 把 `/agent/sessions/:sessionId/messages/stream` 勾为完成
3. 在本接口落地后，把 `/api/runtime/custom-world-library/:profileId` 勾为完成
## 8. 完成定义
当以下条件满足时，本轮扩展视为完成：
1. 新设计文档已落到 `docs/technical/`
2. `docs/technical/README.md` 已补索引
3. `module-custom-world` 已新增 library detail input 与校验
4. `spacetime-module` 已新增 owner-only detail procedure
5. `spacetime-client` 已新增 detail facade
6. `api-server` 已挂 `GET /api/runtime/custom-world-library/:profileId`
7. `cargo check -p api-server` 通过
8. `npm run check:encoding` 通过
## 9. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md)
4. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md)

275
docs/technical/SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,275 @@
# `M5` custom world library / publish / gallery Stage 2 设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于把 `M5` 的下一段从“已有表骨架”推进到“可以直接开始写 reducer / procedure”的级别。
本轮只冻结以下最小主链：
1. `custom_world_profile` upsert
2. `custom_world_profile` publish
3. `custom_world_profile` unpublish
4. `custom_world_gallery_entry` 与发布态的同步规则
5. library / gallery 的最小 procedure 返回口径
本轮仍不进入：
1. Agent session -> profile 的自动编译
2. works 聚合读模型
3. enter-world gate
4. Axum HTTP façade
## 2. Node 当前口径对齐结论
对照当前 Node 实现：
1. `RpgWorldProfileRepository.ts`
2. `RpgWorldLibraryRepository.ts`
3. `customWorldAgentPublishingService.ts`
4. `packages/shared/src/contracts/runtime.ts`
可以确认当前正式主链是：
1. 先 upsert profile
2. publish 时把 profile 元数据重算后写回
3. published profile 同时作为 gallery 公开读模型来源
4. unpublish 后从公开画廊移除
因此 Rust / SpacetimeDB 首版不需要额外发明一套“发布态缓存”。
当前更稳妥的落法是：
1. `custom_world_profile` 继续作为私有正式作品真相
2. `custom_world_gallery_entry` 继续作为公开投影
3. publish / unpublish 明确负责两张表的同步
## 3. 当前冻结的 procedure 契约
### 3.1 `CustomWorldProfileSnapshot`
用于承接 library detail / publish / unpublish 的返回对象。
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `source_agent_session_id`
4. `publication_status`
5. `world_name`
6. `subtitle`
7. `summary_text`
8. `theme_mode`
9. `cover_image_src`
10. `profile_payload_json`
11. `playable_npc_count`
12. `landmark_count`
13. `author_display_name`
14. `published_at_micros`
15. `created_at_micros`
16. `updated_at_micros`
说明：
1. 虽然 `author_display_name` 当前不在 `custom_world_profile` 表骨架里，但 publish / gallery 主链已经需要它。
2. 因此本轮允许给 `custom_world_profile` 补这一列，避免 publish procedure 只能从外部临时参数现拼。
### 3.2 `CustomWorldGalleryEntrySnapshot`
用于承接 gallery 列表项和 detail 返回项。
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `author_display_name`
4. `world_name`
5. `subtitle`
6. `summary_text`
7. `cover_image_src`
8. `theme_mode`
9. `playable_npc_count`
10. `landmark_count`
11. `published_at_micros`
12. `updated_at_micros`
### 3.3 `CustomWorldLibraryMutationResult`
用于 upsert / publish / unpublish 的最小 procedure 返回。
字段冻结为：
1. `ok`
2. `entry`
3. `gallery_entry`
4. `error_message`
说明：
1. 本轮不直接返回整包 `entries` 列表。
2. 列表读取交给单独 list procedure，避免每次写入都重复扫描全表。
### 3.4 `CustomWorldProfileListResult`
用于 list own library。
字段冻结为：
1. `ok`
2. `entries`
3. `error_message`
### 3.5 `CustomWorldGalleryListResult`
用于 list public gallery。
字段冻结为：
1. `ok`
2. `entries`
3. `error_message`
## 4. 当前冻结的输入契约
### 4.1 `CustomWorldProfileUpsertInput`
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `source_agent_session_id`
4. `world_name`
5. `subtitle`
6. `summary_text`
7. `theme_mode`
8. `cover_image_src`
9. `profile_payload_json`
10. `playable_npc_count`
11. `landmark_count`
12. `author_display_name`
13. `updated_at_micros`
规则：
1. upsert 默认把 `publication_status` 固定为当前行已有值；若不存在则为 `draft`
2. upsert 不直接负责 publish
3. 若 profile 已经处于 `published`，则需要同步刷新 gallery 投影
### 4.2 `CustomWorldProfilePublishInput`
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `author_display_name`
4. `published_at_micros`
规则：
1. 目标 profile 必须存在
2. publish 会把 `publication_status` 改为 `published`
3. publish 会把 `published_at` 与 `updated_at` 一并更新
4. publish 会 upsert `custom_world_gallery_entry`
### 4.3 `CustomWorldProfileUnpublishInput`
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `author_display_name`
4. `updated_at_micros`
规则：
1. 目标 profile 必须存在
2. unpublish 会把 `publication_status` 改为 `draft`
3. unpublish 会清空 `published_at`
4. unpublish 会删除 `custom_world_gallery_entry`
### 4.4 `CustomWorldProfileListInput`
字段冻结为：
1. `owner_user_id`
### 4.5 `CustomWorldGalleryDetailInput`
字段冻结为：
1. `owner_user_id`
2. `profile_id`
## 5. 表同步规则冻结
### 5.1 `custom_world_profile`
本轮允许补充：
1. `author_display_name: String`
原因：
1. 当前 library / publish / gallery 全链路都依赖作者展示名
2. 若不存回 profile 真相，publish / unpublish 过程会丢失元数据来源一致性
### 5.2 `custom_world_gallery_entry`
同步规则冻结为：
1. 仅 `published` profile 允许存在 gallery entry
2. `published_at` 必须与 profile 的正式发布时间一致
3. `updated_at` 跟随 profile 最新更新时间
4. `theme_mode / cover / title / subtitle / summary / counts` 全部以 profile 当前元数据为准
## 6. reducer / procedure 范围
本轮推荐直接落以下入口：
1. reducer: `upsert_custom_world_profile`
2. procedure: `upsert_custom_world_profile_and_return`
3. reducer: `publish_custom_world_profile`
4. procedure: `publish_custom_world_profile_and_return`
5. reducer: `unpublish_custom_world_profile`
6. procedure: `unpublish_custom_world_profile_and_return`
7. procedure: `list_custom_world_profiles`
8. procedure: `list_custom_world_gallery_entries`
9. procedure: `get_custom_world_gallery_detail`
说明：
1. list / detail 当前优先做 procedure，避免先引入 view 设计。
2. 这些入口足以支撑后续 Axum facade 接 `/runtime/custom-world-library` 和 `/runtime/custom-world-gallery`。
## 7. 当前刻意不做
本轮明确不做：
1. `soft delete`
2. `MAX_*` limit 常量与分页
3. `works` 聚合输出
4. publish gate blocker 校验
5. `custom_world_profile` 从 `agent session` 自动编译
6. `agent session` 发布后自动推进 `published` stage
这些内容后续会分别进入：
1. M5 works 主链
2. M5 agent publish 主链
3. Axum facade 兼容层
## 8. 本轮完成定义
当以下条件满足时，本轮 Stage 2 视为完成：
1. `module-custom-world` 已补齐上述输入 / 输出 snapshot 契约
2. `spacetime-module` 已补 profile/library/gallery 的 reducer / procedure
3. `cargo check -p spacetime-module` 通过
4. 文档与任务清单同步更新
## 9. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md)
3. [./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)

208
docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,208 @@
# `M5` published profile compile Stage 3 设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于把 `M5` 的 “published profile compile” 从 Node 兼容实现推进到 Rust / SpacetimeDB 可直接编码的级别。
本轮只冻结：
1. `agent draft -> published profile payload` 的最小编译边界
2. 输入输出 contract
3. 和 `custom_world_profile` / `publish` 主链的衔接方式
本轮不做：
1. publish gate blocker 规则迁移
2. Axum HTTP 接口兼容
3. works 聚合读模型
4. `resultPreview` 全量生成主链迁移
## 2. 当前 Node 主链结论
对照当前实现：
1. `rpgCreationPreviewProfileBuilder.ts`
2. `RpgWorldPreviewCompiler.ts`
3. `customWorldAgentPublishingService.ts`
4. `runtime-profile/buildCompiledProfile.ts` 及其 normalize 子模块
当前发布链不是“把 draft 原样存进去”，而是：
1. 先从 `draftProfile` 取 foundation draft
2. 如果存在 `legacyResultProfile`，把旧 runtime-rich 字段当作 base profile
3. 用最新草稿资产覆盖 base profile 中的角色 / 地点 / 场景幕资产字段
4. 再通过 runtime profile compiler 归一化为正式 `CustomWorldProfile`
因此 Rust 首版不能只做“字段透传”。
但当前仓库约束也要求：
1. 不做大爆炸重写
2. 优先先把最小可运行主链迁过去
所以本轮采用折中方案：
1. 先在 Rust 里落“编译输入 contract + profile payload 归一化 helper”
2. 首版继续允许 `compiled_profile_payload_json` 作为正式工件
3. 不在本轮把 Node runtime-profile 的所有细节一次性 1:1 重写为强类型结构
## 3. 本轮冻结的输入 contract
### 3.1 `CustomWorldPublishedProfileCompileInput`
字段冻结为：
1. `session_id`
2. `profile_id`
3. `owner_user_id`
4. `draft_profile_json`
5. `legacy_result_profile_json`
6. `setting_text`
7. `author_display_name`
8. `updated_at_micros`
说明：
1. `draft_profile_json` 是 foundation draft 的正式输入。
2. `legacy_result_profile_json` 允许为空，用于兼容 Node 当前 Phase 5 的 runtime-rich 字段回灌。
3. `setting_text` 单独传入，避免编译阶段再从松散 JSON 猜测。
## 4. 本轮冻结的输出 contract
### 4.1 `CustomWorldPublishedProfileCompileSnapshot`
字段冻结为：
1. `profile_id`
2. `owner_user_id`
3. `world_name`
4. `subtitle`
5. `summary_text`
6. `theme_mode`
7. `cover_image_src`
8. `playable_npc_count`
9. `landmark_count`
10. `author_display_name`
11. `compiled_profile_payload_json`
12. `updated_at_micros`
说明：
1. 这不是完整 `custom_world_profile` 行快照，而是“编译产物摘要”。
2. publish / upsert profile reducer 后续直接消费这里的结果写回 `custom_world_profile`。
### 4.2 `CustomWorldPublishedProfileCompileResult`
字段冻结为：
1. `ok`
2. `record`
3. `error_message`
## 5. 本轮编译规则冻结
### 5.1 最小字段来源规则
首版 Rust 编译先固定以下字段：
1. `world_name`
- 优先 `draft_profile.name`
- 否则 `legacy_result_profile.name`
2. `subtitle`
- 优先 `draft_profile.subtitle`
- 否则 `legacy_result_profile.subtitle`
3. `summary_text`
- 优先 `draft_profile.summary`
- 否则 `legacy_result_profile.summary`
4. `cover_image_src`
- 优先 `draft_profile.camp.imageSrc`
- 否则首个 `landmark.imageSrc`
- 否则 `legacy_result_profile.cover.imageSrc`
5. `playable_npc_count`
- `draft_profile.playableNpcs + draft_profile.storyNpcs` 去重后的总量
6. `landmark_count`
- `draft_profile.landmarks.length`
### 5.2 `theme_mode` 映射规则
首版 Rust 不强行完整复刻 Node 的主题推断器，而是采用稳定回退：
1. 如果 `legacy_result_profile` 中已有合法主题枚举，则沿用
2. 否则默认 `CustomWorldThemeMode::Mythic`
原因：
1. 当前 shared contract 中 `themeMode` 已经是摘要元数据，不影响 runtime profile 主体结构
2. 真正复杂的主题推断不应在没有专项文档的情况下直接硬迁
### 5.3 payload 输出规则
本轮 `compiled_profile_payload_json` 先采用：
1. 把 `legacy_result_profile_json` 解析为 base object
2. 把 `draft_profile_json` 中的关键字段覆盖到 base object
3. 至少保证以下键被同步：
- `id`
- `settingText`
- `name`
- `subtitle`
- `summary`
- `playableNpcs`
- `storyNpcs`
- `landmarks`
- `camp`
- `sceneChapterBlueprints`
- `updatedAt`
当前刻意不做：
1. 完整 runtime-profile normalize
2. attribute schema 重建
3. theme pack / story graph / knowledge facts 的智能合并
这些继续留待后续 Stage 4 单独迁移。
## 6. 与 `custom_world_profile` 的衔接方式
本轮推荐新增：
1. `module-custom-world`：
- `CustomWorldPublishedProfileCompileInput`
- `CustomWorldPublishedProfileCompileSnapshot`
- `CustomWorldPublishedProfileCompileResult`
2. `spacetime-module`：
- `compile_custom_world_published_profile`
- `compile_custom_world_published_profile_and_return`
当前策略：
1. compile procedure 只产出编译结果，不直接写表
2. publish 主链下一步可以显式执行：
- compile
- upsert profile
- publish profile
这样可以保持：
1. 编译
2. 持久化
3. 发布
三段职责清晰分离。
## 7. 本轮完成定义
当以下条件满足时，本轮 Stage 3 视为完成：
1. `module-custom-world` 已补编译输入输出 contract
2. `spacetime-module` 已新增 compile procedure
3. compile procedure 能基于最小字段规则返回合法 profile payload 与摘要
4. `cargo check -p spacetime-module` 通过
## 8. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md)
3. [./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)

177
docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,177 @@
# `M5` publish_world Stage 4 设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于把 `M5` 里的 `publish_world` 动作，从 Node 兼容实现推进到 Rust / SpacetimeDB 可直接编码的最小主链级别。
本轮只冻结：
1. `publish_world` 的输入输出 contract
2. `compile -> upsert profile -> publish profile` 的事务顺序
3. `custom_world_agent_session.stage` 推进到 `published` 的最小写法
本轮不做：
1. `publish gate` / `enter-world gate` blocker 规则迁移
2. `qualityFindings` 的 blocker 清洗与 warning 摘要回写
3. Axum HTTP 接口兼容
4. works 聚合读模型
5. 资产对象绑定、OSS、封面上传等 `M6` 相关能力
## 2. 当前 Node 主链结论
对照当前 Node 链路：
1. `customWorldAgentActionExecutors/publishWorldExecutor.ts`
2. `customWorldAgentPublishingService.ts`
当前 `publish_world` 的职责可拆成两段：
1. 发布门禁校验
2. 发布写入串联
其中发布写入串联又固定为：
1. 基于当前 session 草稿构建 publish readiness
2. 生成正式 published profile
3. 写入 repository / library
4. 推进 session stage 到 `published`
Rust / SpacetimeDB 这一轮只迁第 2 段，也就是“发布写入串联”。
原因：
1. `publish gate` 当前仍依赖 `qualityFindings`、角色资产覆盖率、场景图资产完整度等一系列未冻结的 blocker 口径
2. 如果这一轮把 gate 一起硬迁，会把后续 `M5/M6` 的资产和 blocker 设计提前锁死
3. 当前最需要的是先把 `published profile compile + library + publish + session stage` 串成一个可复用的后端真相主链
## 3. 本轮冻结的输入 contract
### 3.1 `CustomWorldPublishWorldInput`
字段冻结为：
1. `session_id`
2. `profile_id`
3. `owner_user_id`
4. `draft_profile_json`
5. `legacy_result_profile_json`
6. `setting_text`
7. `author_display_name`
8. `published_at_micros`
说明：
1. 当前仍延续 Stage 2 / Stage 3 的显式 `owner_user_id` 传参口径，后续等 OIDC claims 真正确认后再切到 `ctx.sender()` 授权真相。
2. `draft_profile_json` 与 `legacy_result_profile_json` 直接复用 Stage 3 compile 的输入来源，避免这一轮再新增 session 内部 JSON 解析耦合。
3. `published_at_micros` 同时作为：
- profile publish 的 `published_at`
- profile upsert 的 `updated_at`
- session stage 推进的 `updated_at`
当前不额外引入：
1. `quality_findings_json`
2. `publish_gate_summary`
3. `result_preview_json`
这些都留到后续 gate / works 迁移时再单独冻结。
## 4. 本轮冻结的输出 contract
### 4.1 `CustomWorldPublishWorldResult`
字段冻结为：
1. `ok`
2. `compiled_record`
3. `entry`
4. `gallery_entry`
5. `session_stage`
6. `error_message`
说明：
1. `compiled_record` 返回 Stage 3 编译产物，方便 Axum 或后续 facade 直接复用，不必再次 compile。
2. `entry` 返回最新 `custom_world_profile` 快照。
3. `gallery_entry` 返回同步后的公开 gallery 投影。
4. `session_stage` 当前只返回最终阶段枚举，最小闭环固定为 `published`。
## 5. 串联顺序冻结
本轮 `publish_world` procedure 固定按以下顺序执行：
1. 先基于 `CustomWorldPublishWorldInput` 构造 Stage 3 compile 输入
2. 调用 `build_custom_world_published_profile_compile_snapshot(...)`
3. 将 compile 结果映射成 `CustomWorldProfileUpsertInput`
4. 调用 `upsert_custom_world_profile_record(...)`
5. 调用 `publish_custom_world_profile_record(...)`
6. 根据 `session_id + owner_user_id` 查找 `custom_world_agent_session`
7. 将 session 的 `stage` 推进到 `RpgAgentStage::Published`
8. 返回 compile 结果、profile 快照、gallery 快照与最终 session stage
### 5.1 为什么先 upsert 再 publish
因为当前 Stage 2 已经冻结了两段职责：
1. `upsert_custom_world_profile_record(...)`
- 负责把 profile 最新内容写回正式表
2. `publish_custom_world_profile_record(...)`
- 负责把 profile 状态切到 `published`
- 同步 gallery 公开投影
Stage 4 不应绕开这两段既有入口重写一遍 publish 逻辑，否则会制造第二套 profile / gallery 写入口。
## 6. session stage 推进规则
本轮最小冻结规则：
1. 只推进 `custom_world_agent_session.stage = published`
2. 其余字段保持原样
3. `updated_at` 使用 `published_at_micros`
本轮刻意不做：
1. `quality_findings_json` 删除 blocker
2. `supportedActions` / `suggestedActions` 重算
3. `progress_percent` 二次推断
原因：
1. 当前 `custom_world_agent_session` 还没有冻结完整的 action registry / supportedActions 主链
2. 如果这轮顺手改太多 session 派生字段，后面 Axum / agent 主链接入时容易和旧 Node 行为再次漂移
## 7. 与 Node 当前语义的最小对齐边界
这一轮只要求对齐以下事实：
1. session draft 可以被编译成正式 published profile
2. 正式 profile 会写入 `custom_world_profile`
3. publish 后 gallery 有公开投影
4. session 最终会进入 `published` 阶段
这一轮不要求 1:1 对齐：
1. blocker message 文案
2. publish readiness 的细粒度缺失项列表
3. session 消息追加与 checkpoint 追加
4. warning 数量摘要
## 8. 本轮完成定义
当以下条件满足时，本轮 Stage 4 视为完成：
1. `module-custom-world` 已补 `CustomWorldPublishWorldInput / Result`
2. `spacetime-module` 已新增 `publish_world` procedure
3. procedure 能复用 Stage 2 / Stage 3 helper 串联 compile、upsert、publish
4. procedure 能把 `custom_world_agent_session.stage` 推进到 `published`
5. `cargo test -p module-custom-world` 通过
6. `cargo check -p spacetime-module` 通过
## 9. 相关文档
1. [../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
2. [./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md)
3. [./SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md](./SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md)