Genarrative/docs/technical/BACKEND_REWRITE_CROSS_CUTTING_GOVERNANCE_2026-04-22.md

后端重写横向治理规则（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。
3. 仍存在旧能力差异时，同步更新 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. 灰度环境双跑对比。