完善 server-rs DDD 重构计划与骨架
This commit is contained in:
Codex
393
docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md
Normal file
393
docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# server-rs DDD 一次性重构落地方案
|
||||
|
||||
日期：`2026-04-28`
|
||||
|
||||
## 1. 背景与当前结论
|
||||
|
||||
当前仓库已经进入 `server-rs + Axum + SpacetimeDB` 单一后端路线，旧 `server-node` 已不存在，后续不再围绕 Express / PostgreSQL 做兼容设计。本轮重构目标不是新增玩法，而是把已有 Rust 后端统一成可长期演进的 DDD 边界：
|
||||
|
||||
1. 领域规则沉到 `module-*`。
|
||||
2. SpacetimeDB 事务、表、reducer、procedure 留在 `spacetime-module`。
|
||||
3. HTTP / SSE / BFF 留在 `api-server`。
|
||||
4. 外部副作用留在 `platform-*` 或 `api-server` 应用编排层。
|
||||
5. 前后端 DTO 留在 `shared-contracts`，跨领域纯值处理留在 `shared-kernel`。
|
||||
|
||||
本文件是后续编码前的总纲。若局部历史文档与本文冲突，以本文和对应 SpacetimeDB skill 为准；若本文仍无法精准指导某一处编码，必须先补本文或新增更细技术文档，再继续改工程。
|
||||
|
||||
## 2. 依赖方向
|
||||
|
||||
允许方向：
|
||||
|
||||
```text
|
||||
api-server
|
||||
-> shared-contracts
|
||||
-> module-*
|
||||
-> spacetime-client
|
||||
-> platform-*
|
||||
|
||||
spacetime-module
|
||||
-> module-*
|
||||
-> shared-kernel
|
||||
|
||||
module-*
|
||||
-> shared-kernel
|
||||
-> 其他 module-* 的纯领域类型（仅在确有跨域规则复用时）
|
||||
|
||||
platform-*
|
||||
-> shared-kernel
|
||||
|
||||
shared-contracts
|
||||
-> shared-kernel
|
||||
```
|
||||
|
||||
禁止方向：
|
||||
|
||||
1. `module-*` 直接依赖 Axum、HTTP client、OSS、LLM、文件系统、SpacetimeDB table/reducer/procedure API。
|
||||
2. `module-*` 新增 `mapper.rs`，映射只能落在 adapter crate。
|
||||
3. `spacetime-module` 反向依赖 `api-server`、`spacetime-client` 或 `platform-*`。
|
||||
4. `shared-kernel` / `shared-contracts` 依赖业务 crate。
|
||||
5. 前端绕过 Axum 直接承接后端业务规则或数据真相。
|
||||
|
||||
阶段性例外必须满足三个条件：
|
||||
|
||||
1. 在本文“阶段性债务表”登记。
|
||||
2. 有明确迁出目标 crate。
|
||||
3. 不允许继续扩大例外范围。
|
||||
|
||||
## 3. crate 职责矩阵
|
||||
|
||||
| crate | 职责 | 禁止内容 |
|
||||
| --- | --- | --- |
|
||||
| `module-ai` | AI 任务、阶段、流式片段、结果引用的纯领域模型和状态机 | 真实 LLM 调用、HTTP、SSE |
|
||||
| `module-assets` | 资产对象、资产绑定、历史查询输入输出和纯校验规则 | OSS head、reqwest、进程内 fallback store 扩散到领域核心 |
|
||||
| `module-auth` | 用户、会话、验证码、微信绑定、密码规则、领域错误 | 文件持久化、真实短信副作用、HTTP cookie 写入 |
|
||||
| `module-big-fish` | 大鱼创作会话、素材槽、运行态规则 | 图片生成、OSS 上传、HTTP handler |
|
||||
| `module-combat` | 战斗聚合、行动结算、奖励结果 | 直接写背包表、直接发放成长账本 |
|
||||
| `module-custom-world` | 世界 profile、Agent 会话、草稿卡、发布门禁规则 | LLM 推理、OSS、Axum response shape |
|
||||
| `module-inventory` | 背包、装备槽、堆叠与消耗规则 | SpacetimeDB table 操作 |
|
||||
| `module-npc` | NPC 关系、好感、互动、招募规则 | 战斗表初始化事务 |
|
||||
| `module-progression` | 玩家等级、章节预算、经验记账规则 | 查询前端视图拼装 |
|
||||
| `module-puzzle` | 拼图创作与运行态纯规则 | 图片生成、排行榜 HTTP shape |
|
||||
| `module-quest` | 任务领取、推进、完成、交付规则 | 奖励跨域副作用直接写表 |
|
||||
| `module-runtime` | 运行时设置、快照、个人页状态、存档领域模型 | 直接读写 SpacetimeDB |
|
||||
| `module-runtime-item` | 宝箱、奖励物品、运行时物品快照 | 背包持久化事务 |
|
||||
| `module-runtime-story` | RPG runtime story 新接口下的纯应用编排、剧情投影、场景旅行、战后收束、prompt context 投影 | Axum、LLM、SpacetimeDB |
|
||||
| `module-story` | story session、story event 与推进输入输出 | 直接调用 LLM 或 HTTP |
|
||||
| `spacetime-module` | 表、reducer、procedure、事务内查询写回、row/snapshot mapper、event table | 领域规则大段堆叠 |
|
||||
| `spacetime-client` | api-server 调用 SpacetimeDB 的客户端 facade 与绑定 mapper | 领域规则 |
|
||||
| `api-server` | 路由、鉴权上下文、请求响应映射、SSE、平台服务编排 | 表结构定义、领域规则主逻辑 |
|
||||
| `platform-*` | JWT/SMS/微信/OSS/LLM/HTTP client 等外部能力 | 玩法领域规则 |
|
||||
| `shared-kernel` | 字符串、时间、ID、纯值归一化 | 业务流程 |
|
||||
| `shared-contracts` | HTTP/前端 DTO、兼容 response shape | 领域状态机 |
|
||||
|
||||
## 4. 统一目录结构
|
||||
|
||||
所有 `module-*` 必须具备以下文件。第一阶段允许旧实现仍在 `lib.rs` 或历史子模块中，但新增和迁移代码必须进入对应落点。
|
||||
|
||||
```text
|
||||
src/
|
||||
├─ lib.rs
|
||||
├─ domain.rs 或 domain/
|
||||
├─ commands.rs
|
||||
├─ application.rs
|
||||
├─ events.rs
|
||||
└─ errors.rs
|
||||
```
|
||||
|
||||
落位规则：
|
||||
|
||||
1. `domain.rs` / `domain/*`：聚合、值对象、领域方法、纯校验、状态迁移。
|
||||
2. `commands.rs`：写入用例输入，只表达意图和必要参数，不含 adapter 类型。
|
||||
3. `application.rs`：纯应用编排函数，输出领域事件或应用结果，不执行外部副作用。
|
||||
4. `events.rs`：领域事件和跨上下文事件，例如奖励待入账、画廊投影待刷新。
|
||||
5. `errors.rs`：领域错误，优先可测试、可映射，不直接绑定 HTTP status。
|
||||
6. `mapper.rs`：只允许在 `api-server`、`spacetime-module`、`spacetime-client` 等 adapter crate 中出现。
|
||||
|
||||
## 5. 上下文设计清单
|
||||
|
||||
### 5.1 认证 `module-auth`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `AuthUser`：账号、公开叙世号、登录方式、绑定状态、token version。
|
||||
2. `RefreshSession`：refresh token hash、客户端信息、过期、吊销、last seen。
|
||||
3. `SmsVerification`：手机号、场景、验证码状态、冷却、失败次数。
|
||||
4. `WechatBinding`：微信 provider 身份、union id、绑定状态。
|
||||
|
||||
命令：
|
||||
|
||||
1. `PasswordEntryInput`
|
||||
2. `SendPhoneCodeInput`
|
||||
3. `PhoneLoginInput`
|
||||
4. `CreateRefreshSessionInput`
|
||||
5. `RevokeRefreshSessionInput`
|
||||
6. `ResolveWechatLoginInput`
|
||||
|
||||
事件：
|
||||
|
||||
1. `AuthUserCreated`
|
||||
2. `RefreshSessionIssued`
|
||||
3. `RefreshSessionRevoked`
|
||||
4. `PhoneCodeAccepted`
|
||||
5. `WechatIdentityLinked`
|
||||
|
||||
读模型：
|
||||
|
||||
1. `AuthMeResult`
|
||||
2. `PublicUserSearchResult`
|
||||
3. `AuthSessionListResult`
|
||||
|
||||
迁移要求：文件持久化和内存 store 从领域核心剥离到 adapter 或临时测试支撑；短信真实发送继续在 `platform-auth`。
|
||||
|
||||
### 5.2 资产 `module-assets`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `AssetObject`：bucket、object key、访问策略、hash、版本、业务归属。
|
||||
2. `AssetEntityBinding`：实体类型、实体 id、slot、资产对象 id。
|
||||
|
||||
命令：
|
||||
|
||||
1. `ConfirmAssetObjectInput`
|
||||
2. `AssetObjectUpsertInput`
|
||||
3. `AssetEntityBindingInput`
|
||||
4. `AssetHistoryListInput`
|
||||
|
||||
事件：
|
||||
|
||||
1. `AssetObjectConfirmed`
|
||||
2. `AssetEntityBindingChanged`
|
||||
|
||||
读模型：
|
||||
|
||||
1. `AssetObjectUpsertSnapshot`
|
||||
2. `AssetEntityBindingSnapshot`
|
||||
3. `AssetHistoryEntrySnapshot`
|
||||
|
||||
迁移要求：OSS `head_object`、reqwest client 和 fallback store 不再放入领域核心；SpacetimeDB 持久化由 `spacetime-module` 完成。
|
||||
|
||||
### 5.3 RPG 运行时
|
||||
|
||||
覆盖 `module-story`、`module-combat`、`module-inventory`、`module-npc`、`module-progression`、`module-quest`、`module-runtime-item`。
|
||||
|
||||
聚合：
|
||||
|
||||
1. `StorySession`、`StoryEvent`
|
||||
2. `BattleState`
|
||||
3. `InventorySlot`
|
||||
4. `NpcState`
|
||||
5. `PlayerProgression`、`ChapterProgression`
|
||||
6. `QuestRecord`、`QuestLog`
|
||||
7. `TreasureRecord`
|
||||
|
||||
跨上下文事件：
|
||||
|
||||
1. `CombatVictoryResolved`
|
||||
2. `QuestTurnedIn`
|
||||
3. `InventoryItemsGranted`
|
||||
4. `ProgressionXpGranted`
|
||||
5. `NpcRelationChanged`
|
||||
6. `RuntimeStoryProjectionChanged`
|
||||
|
||||
事务边界：
|
||||
|
||||
1. 单聚合变更在对应 `module-*` 纯函数中完成。
|
||||
2. 战斗奖励、任务奖励、背包写入、成长记账由 `spacetime-module` 或应用服务显式编排。
|
||||
3. reducer/procedure 不允许复制领域规则，只负责取 row、调用领域函数、写回 row 和事件表。
|
||||
|
||||
### 5.4 世界创作 `module-custom-world`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `CustomWorldProfile`
|
||||
2. `CustomWorldSession`
|
||||
3. `CustomWorldAgentSession`
|
||||
4. `CustomWorldAgentMessage`
|
||||
5. `CustomWorldAgentOperation`
|
||||
6. `CustomWorldDraftCard`
|
||||
7. `CustomWorldGalleryEntry`
|
||||
|
||||
命令：
|
||||
|
||||
1. 创建/恢复 Agent 会话。
|
||||
2. 写入用户消息。
|
||||
3. 写入 LLM 最终回复。
|
||||
4. 更新草稿卡。
|
||||
5. 发布/下架 profile。
|
||||
|
||||
事件：
|
||||
|
||||
1. `CustomWorldDraftChanged`
|
||||
2. `CustomWorldProfilePublished`
|
||||
3. `CustomWorldGalleryProjectionChanged`
|
||||
4. `CustomWorldAgentOperationProgressed`
|
||||
|
||||
迁移要求：LLM 提示词和推理在 `api-server + platform-llm`，SpacetimeDB 只落真相表和投影。
|
||||
|
||||
### 5.5 拼图 `module-puzzle`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `PuzzleAgentSession`
|
||||
2. `PuzzleAgentMessage`
|
||||
3. `PuzzleWorkProfile`
|
||||
4. `PuzzleRuntimeRun`
|
||||
|
||||
事件：
|
||||
|
||||
1. `PuzzleDraftChanged`
|
||||
2. `PuzzleWorkPublished`
|
||||
3. `PuzzleRunAdvanced`
|
||||
|
||||
读模型：
|
||||
|
||||
1. 作品卡片。
|
||||
2. 运行态快照。
|
||||
3. 排行榜结果。
|
||||
|
||||
### 5.6 大鱼吃小鱼 `module-big-fish`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `BigFishCreationSession`
|
||||
2. `BigFishAgentMessage`
|
||||
3. `BigFishAssetSlot`
|
||||
4. `BigFishRuntimeRun`
|
||||
|
||||
事件：
|
||||
|
||||
1. `BigFishDraftChanged`
|
||||
2. `BigFishAssetSlotChanged`
|
||||
3. `BigFishRunTicked`
|
||||
|
||||
### 5.7 AI `module-ai`
|
||||
|
||||
聚合：
|
||||
|
||||
1. `AiTask`
|
||||
2. `AiTaskStage`
|
||||
3. `AiTextChunk`
|
||||
4. `AiResultReference`
|
||||
|
||||
事件：
|
||||
|
||||
1. `AiTaskStarted`
|
||||
2. `AiTaskStageCompleted`
|
||||
3. `AiTaskFailed`
|
||||
4. `AiResultAttached`
|
||||
|
||||
边界：真实模型调用只在 `platform-llm`，`module-ai` 只表达状态机。
|
||||
|
||||
## 6. SpacetimeDB adapter 映射
|
||||
|
||||
`spacetime-module` 中每个上下文遵循：
|
||||
|
||||
```text
|
||||
src/<context>/
|
||||
├─ mod.rs
|
||||
├─ tables.rs # table 和 public/event 标记
|
||||
├─ reducers.rs # 客户端可调用写入口
|
||||
├─ procedures.rs # 需要同步返回或外部 procedure 语义的入口
|
||||
├─ mapper.rs # row <-> module-* snapshot/input
|
||||
└─ queries.rs # 事务内查询辅助，只返回 adapter DTO
|
||||
```
|
||||
|
||||
当前已有历史拆分与本文不同名时，先按现有文档继续维护；新增或迁移时逐步对齐上面结构。
|
||||
|
||||
Reducer / procedure 规则：
|
||||
|
||||
1. reducer 使用 `&ReducerContext`，返回 `Result<(), String>` 处理预期错误。
|
||||
2. reducer 内授权必须基于 `ctx.sender()`，禁止信任参数中的身份。
|
||||
3. reducer 禁止网络、文件系统、外部随机数和全局状态。
|
||||
4. procedure 使用 SpacetimeDB 2.0 正确 API；涉及事务必须显式 `with_tx` / `try_with_tx`。
|
||||
5. 表访问必须使用 `ctx.db.table()`，更新只通过主键。
|
||||
6. 复杂查询不复用写模型；需要前端订阅时新增明确读模型或 public 投影表。
|
||||
|
||||
## 7. 表结构约束
|
||||
|
||||
默认不改现有 SpacetimeDB 主表。确需改表时按以下优先级：
|
||||
|
||||
1. 新增 optional 字段。
|
||||
2. 新增投影表或 event table。
|
||||
3. 新增索引。
|
||||
4. 最后才考虑 rename/delete/type change，且必须单独写迁移方案。
|
||||
|
||||
任何 table 变更必须同步：
|
||||
|
||||
1. `server-rs/crates/spacetime-module/src/migration.rs`
|
||||
2. `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
|
||||
3. 对应 reducer/procedure 测试或最小 smoke
|
||||
4. 绑定生成和前端/`spacetime-client` 映射
|
||||
|
||||
本阶段只做目录、文档和边界检查，不变更表结构，因此不需要改 `migration.rs`。
|
||||
|
||||
## 8. 查询策略
|
||||
|
||||
1. 写模型不直接服务复杂前端页面。
|
||||
2. 每个前端场景必须有独立 query/result DTO。
|
||||
3. private table 默认不暴露给前端。
|
||||
4. public table 只服务明确订阅场景。
|
||||
5. event table 用于 reducer 后广播一次性事件，客户端必须显式订阅。
|
||||
|
||||
## 9. 第一阶段落地范围
|
||||
|
||||
第一阶段只做低风险基础设施：
|
||||
|
||||
1. 新增本文作为 DDD 总纲。
|
||||
2. 所有 `module-*` 补齐 `domain / commands / application / events / errors` 过渡落位文件。
|
||||
3. 新增 `scripts/check-server-rs-ddd-boundaries.mjs`，检查 DDD 骨架、禁用 mapper 落位和 SpacetimeDB/Axum 绝对边界。
|
||||
4. 更新文档索引和后端 README。
|
||||
5. 不改表、不改 reducer/procedure 名、不改 HTTP contract。
|
||||
|
||||
### 9.1 首个样板切片
|
||||
|
||||
`module-assets` 先作为 DDD 分层导出样板：
|
||||
|
||||
1. `domain.rs` 对外导出资产对象、实体绑定、访问策略、快照和纯校验函数。
|
||||
2. `commands.rs` 对外导出确认资产、绑定实体、资产历史查询等输入。
|
||||
3. `application.rs` 对外导出应用结果和纯构建函数。
|
||||
4. `errors.rs` 对外导出资产领域错误。
|
||||
5. `asset_object_core.rs` 暂作为内部历史实现文件保留，不再由 `lib.rs` 直接对外导出；后续触碰资产规则时继续把实现逐段迁到 DDD 文件。
|
||||
|
||||
## 10. 阶段性债务表
|
||||
|
||||
| 债务 | 当前位置 | 迁出目标 | 约束 |
|
||||
| --- | --- | --- | --- |
|
||||
| 资产 OSS head 与 reqwest 服务仍在 `module-assets` server-service feature | `module-assets/src/asset_object_service.rs` | `api-server` 应用服务或独立 adapter crate | 不得被 `domain.rs` 引用，不得新增更多 OSS 领域规则 |
|
||||
| 认证内存 store / 文件持久化仍在 `module-auth` | `module-auth/src/lib.rs` | adapter / repository 目录或 `api-server` 启动恢复层 | 新业务规则不得继续依赖文件路径 |
|
||||
| `spacetime-module/src/lib.rs` 仍有大量 gameplay 入口 | `spacetime-module/src/lib.rs` | `src/gameplay/*`、`src/custom_world/*`、`src/puzzle/*` | 新增实现禁止继续堆回根入口 |
|
||||
| 部分 `module-*` 仍是单文件领域实现 | 多个 `module-*` 的 `src/lib.rs` | 对应 DDD 文件 | 每次触碰模块时顺手迁移相关片段 |
|
||||
| runtime story 兼容层仍存在 | `module-runtime-story-compat`、`api-server/src/runtime_story/compat*`、前端旧 runtime story client | `module-runtime-story`、session scoped 新接口、前端新 client | 本轮允许 breaking change，不再为旧 HTTP shape 保留双接口 |
|
||||
|
||||
## 11. 全局并行执行清单
|
||||
|
||||
`2026-04-29` 起，`server-rs` DDD 全局重构按 `SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md` 执行。该清单覆盖：
|
||||
|
||||
1. 文档、契约、DDD 骨架和边界检查。
|
||||
2. `module-auth`、`module-assets`、`module-ai`、`module-custom-world`、`module-big-fish`、`module-puzzle`、`module-runtime`、RPG gameplay 域和 runtime story 域。
|
||||
3. `spacetime-module`、`spacetime-client`、`api-server`、`platform-*` 和前端接入。
|
||||
4. 旧层删除、命名收口、全链验证和 Maincloud smoke。
|
||||
|
||||
## 12. 去兼容层任务
|
||||
|
||||
`2026-04-29` 起，runtime story / chat 改造按 `SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md` 中的 `WP-RS Runtime Story 去兼容层` 工作包执行。该工作包明确：
|
||||
|
||||
1. 当前 `compat` 层可以物理删除。
|
||||
2. 新接口采用 `POST /api/runtime/story/sessions/:sessionId/...` 的 session scoped 口径。
|
||||
3. 前端允许同步修改以匹配新 contract。
|
||||
4. `api-server` 不再为旧 `worldType / character / monsters / history / context` 请求体保留正式主链分支。
|
||||
|
||||
## 13. 验收命令
|
||||
|
||||
阶段验收至少执行：
|
||||
|
||||
```powershell
|
||||
node scripts/check-server-rs-ddd-boundaries.mjs
|
||||
cargo fmt --all --check --manifest-path server-rs/Cargo.toml
|
||||
cargo test --workspace --manifest-path server-rs/Cargo.toml
|
||||
cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
|
||||
npm run api-server:maincloud
|
||||
npm run check:encoding
|
||||
```
|
||||
|
||||
若 `npm run api-server:maincloud` 因本机未配置 Maincloud 数据库或令牌失败，必须记录具体错误；不能改用旧后端重启命令。
|
||||
Reference in New Issue
Block a user