# 后端重写横向治理规则（2026-04-22）

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

## 1. 文档目标

本文件冻结 `SpacetimeDB + Axum + OSS` 后端重写收口阶段的横向规则，覆盖：

1. 前端 TypeScript contract 与 Rust DTO 的映射策略。
2. SpacetimeDB table / reducer / procedure 的演进规则。
3. 大对象、manifest、workflow cache 的存储边界。
4. 阶段文档与 API 索引的维护规则。

这些规则用于减少 M4/M5/M6/M7 后续并行推进时的 contract 漂移。

## 2. Contract 与前端兼容

### 2.1 映射原则

1. `packages/shared/src/contracts/*` 是前端消费 contract 的现有事实来源。
2. `server-rs/crates/shared-contracts/src/*.rs` 是 Rust `api-server` 返回 DTO 的事实来源。
3. 两侧字段名必须继续使用当前前端已消费的 JSON 命名，不因 Rust 字段命名风格改变外部 shape。
4. Rust DTO 必须通过 `serde(rename_all = "camelCase")`、显式 `rename` 或兼容枚举值保持旧 contract。
5. 临时兼容字段只能标记为 optional，不能在没有迁移说明和测试前直接删除。

### 2.2 当前映射面

| 前端 contract | Rust DTO 模块 | 当前用途 |
| --- | --- | --- |
| `packages/shared/src/contracts/auth.ts` | `shared-contracts::auth` | 登录方式、用户信息、会话、审计、验证码与微信登录 |
| `packages/shared/src/contracts/runtime.ts` | `shared-contracts::runtime` | profile dashboard、play stats、wallet ledger、browse history、settings、inventory |
| `packages/shared/src/contracts/rpgRuntimeStoryAction.ts` | `shared-contracts::runtime_story` | runtime story action request / response、state resolve、view model |
| `packages/shared/src/contracts/rpgRuntimeStoryState.ts` | `shared-contracts::runtime_story` | runtime story state / presentation 兼容 |
| `packages/shared/src/contracts/rpgAgent*.ts` | `shared-contracts::runtime` 与 `custom_world` 相关 DTO | custom world agent session、message、operation、action |
| `packages/shared/src/contracts/rpgCreation*.ts` | `shared-contracts::runtime` 与 `custom_world` 相关 DTO | result preview、works、library、published profile |
| `packages/shared/src/contracts/common.ts` | `shared-contracts::api` | 统一 success / error envelope |

### 2.3 变更流程

1. 扩字段：先加 Rust optional 字段和 contract test，再接前端消费。
2. 改字段语义：必须新增技术方案说明旧语义、新语义、迁移期兼容逻辑和回退方式。
3. 删字段或删枚举：必须先证明前端调用、Node 兼容层、历史 fixture 和测试都不再消费。
4. breaking change 必须在任务清单和设计文档中显式标注，不允许只靠 PR diff 表达。
5. 所有 shared contract 变更至少运行 `cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`。

## 3. SpacetimeDB Schema 演进治理

本节按 SpacetimeDB 约束执行：

1. reducer 是事务性写入口，不依赖 reducer 返回值读取数据。
2. reducer 必须确定性执行，不做网络、文件系统、外部随机数或时间副作用。
3. 客户端读取依赖 table / subscription / procedure 返回的显式 DTO，不把 Axum 进程内缓存当真相。
4. 用户身份以后续接入 SpacetimeDB 直连时的 `ctx.sender()` 为准，不信任客户端传入 owner 字段。

### 3.1 命名规则

1. table 使用稳定单数 snake_case 名称，例如 `story_session`、`asset_object`、`custom_world_agent_session`。
2. reducer 使用动作动词 + 领域对象，例如 `upsert_runtime_snapshot`、`confirm_asset_object`、`turn_in_quest`。
3. 需要同步返回 DTO 的 procedure 统一使用 `_and_return` 或 `get_ / list_ / compile_` 语义。
4. public table 只暴露客户端确实需要订阅或查询的状态；内部审计、token、风控等默认不 public。
5. event table 只用于事件广播，不替代持久状态表。

### 3.2 列演进规则

1. 优先追加 optional 字段，不直接改名、改类型或删除列。
2. 必须删除语义时，先软废弃字段并让读模型停止依赖，再在独立迁移窗口清理。
3. 状态类枚举新增值时，前端必须有 unknown / fallback 处理。
4. 需要唯一约束或索引时，先补设计文档说明查询路径，再改 schema。
5. 大规模重排表结构必须拆成新表 + 双写 / 读模型迁移，不在原表上做破坏性变更。

### 3.3 软删除规则

1. 用户可见业务实体优先使用 `status`、`deleted_at`、`archived_at` 表达生命周期。
2. 会话、作品、资产绑定、审计和任务记录默认不物理删除。
3. 物理删除只用于临时草稿、过期验证码、过期 OAuth state 等明确可丢弃数据。
4. 删除 reducer 必须写清是否幂等，重复调用不能造成不可恢复错误。

## 4. 大对象与缓存治理

### 4.1 OSS 存储边界

必须进入 OSS：

1. 图片、视频、动作帧、封面图、场景图。
2. 大型 JSON manifest。
3. 角色工作流缓存 JSON。
4. 导入视频和生成过程草稿资源。

只进入 SpacetimeDB 元数据：

1. `bucket`、`object_key`、`asset_kind`、`content_type`、`content_length`、`content_hash`、`version`。
2. `asset_entity_binding` 的业务实体、槽位、owner 和 profile 绑定关系。
3. AI task、asset task、publish gate 等状态字段。
4. 可用于列表和权限判断的轻量 summary。

### 4.2 本地缓存边界

1. 生产主链不得把仓库 `public/generated-*` 作为资产真相。
2. 旧 `/generated-*` 仅作为同源代理兼容路径，读取私有 OSS 对象。
3. 测试环境允许使用 `#[cfg(test)]` 内存兜底，但必须在文档中注明不进入生产链。
4. workflow cache 当前真相是 OSS JSON 草稿对象，不落本地文件。
5. 临时生成文件如需存在，必须限制在进程临时目录，并在任务完成后清理。

### 4.3 Manifest 与版本

1. 多文件资产集合使用 OSS manifest 表达，不重复新增结构化表，除非已证明查询需求需要。
2. `asset_object.version` 当前默认 `1`，版本升级必须说明兼容读取规则。
3. `content_hash` 可为空，但一旦用于去重，必须先补冲突处理和重算策略。
4. 强业务资产表只有在需要领域查询、审核、回滚或权限策略时再新增。

## 5. 文档维护规则

1. 工程修改必须同步对应阶段任务清单。
2. 新增或改变接口时，同步更新 [RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md](./RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md)。
3. 仍存在旧能力差异时，同步更新 [CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md](./CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md) 或新增 Rust 侧补充索引。
4. M4 结构变更同步维护 RPG runtime 链路文档。
5. M5 结构变更同步维护 creation flow 链路文档。
6. M6 资产链路变更同步维护 OSS / asset_object / generated path 文档。
7. M7 切流相关变更同步维护部署、预检、smoke 与回滚文档。

## 6. 验收门禁

横向治理完成不等价于真实切流完成。当前可本地验收的门禁是：

1. `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
2. `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`
3. `cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`
4. `cargo test -p api-server --manifest-path server-rs/Cargo.toml --no-run`
5. `node scripts/check-encoding.mjs ...`

真实切流前仍必须单独完成：

1. OSS 真实读写 smoke。
2. LLM / DashScope 真实生成 smoke。
3. 关键 SSE 接口联调。
4. SpacetimeDB publish / rollback 演练。
5. 灰度环境双跑对比。