diff --git a/backend-rewrite-tasklist/00_MASTER_TASKLIST.md b/backend-rewrite-tasklist/00_MASTER_TASKLIST.md index 00d6380b..84c7133b 100644 --- a/backend-rewrite-tasklist/00_MASTER_TASKLIST.md +++ b/backend-rewrite-tasklist/00_MASTER_TASKLIST.md @@ -36,7 +36,7 @@ - [ ] `M3`:完成 runtime snapshot / settings / profile 迁移 - [ ] `M4`:完成 story action 主循环与核心 gameplay reducer 迁移 - [ ] `M5`:完成 custom world / agent 主链迁移 -- [ ] `M6`:完成 assets / OSS / editor 主链迁移 +- [ ] `M6`:完成 assets / OSS 主链迁移 - [ ] `M7`:完成联调、回归、部署与切流准备 ## 2. 阶段导航 @@ -96,8 +96,7 @@ 1. 迁移 assets 2. 接入阿里云 OSS -3. 迁移 editor 读写能力 -4. 做旧静态资源路径兼容 +3. 做旧静态资源路径兼容 详见: @@ -137,7 +136,7 @@ 3. 再做 `M3`,优先跑通快照、设置、profile。 4. 再做 `M4`,把 story action 主循环真正迁走。 5. 然后做 `M5`,迁 custom world 与 agent。 -6. 最后做 `M6 + M7`,收口 assets、editor、部署与切流。 +6. 最后做 `M6 + M7`,收口 assets、部署与切流。 ## 5. 最终验收清单 diff --git a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md index 0a17cfc0..26ac9b06 100644 --- a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md +++ b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md @@ -71,8 +71,6 @@ 交付物:[../server-rs/packages/module-custom-world/README.md](../server-rs/packages/module-custom-world/README.md) - [x] 创建 `packages/module-assets` 交付物:[../server-rs/packages/module-assets/README.md](../server-rs/packages/module-assets/README.md) -- [x] 创建 `packages/module-editor` - 交付物:[../server-rs/packages/module-editor/README.md](../server-rs/packages/module-editor/README.md) - [x] 创建 `packages/module-ai` 交付物:[../server-rs/packages/module-ai/README.md](../server-rs/packages/module-ai/README.md) - [x] 创建 `packages/shared-contracts` diff --git a/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md b/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md index 38112571..240923cc 100644 --- a/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md +++ b/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md @@ -1,4 +1,9 @@ -# M6:assets / 阿里云 OSS / editor 任务清单 +# M6:assets / 阿里云 OSS 任务清单 + +说明: + +1. `editor` 已于 `2026-04-21` 被确认为遗留无用模块,不再纳入本轮 Rust 后端重写范围。 +2. 本文件保留原文件名仅用于延续既有任务编号与链接,不再继续安排 editor 迁移项。 ## 1. OSS 基础设施 @@ -42,22 +47,14 @@ - [ ] 迁移场景图生成 - [ ] 迁移封面图上传 -## 5. 编辑器能力 - -- [ ] 迁移编辑器 JSON 读取 -- [ ] 迁移编辑器 JSON 保存 -- [ ] 迁移图标目录枚举 -- [ ] 开发态保留本地文件适配 -- [ ] 线上态评估对象化替代方案 - -## 6. 路径兼容 +## 5. 路径兼容 - [ ] 兼容 `/generated-character-drafts/*` - [ ] 兼容 `/generated-characters/*` - [ ] 兼容 `/generated-custom-world-scenes/*` - [ ] 兼容 `/generated-qwen-sprites/*` -## 7. 兼容接口 +## 6. 兼容接口 - [ ] 兼容 `/api/assets/character-visual/generate` - [ ] 兼容 `/api/assets/character-visual/jobs/:taskId` @@ -73,12 +70,8 @@ - [ ] 兼容 `/api/assets/qwen-sprite/sheet` - [ ] 兼容 `/api/assets/qwen-sprite/frame-repair` - [ ] 兼容 `/api/assets/qwen-sprite/save` -- [ ] 兼容 `/api/editor/catalog/items` -- [ ] 兼容 `/api/editor/json/:resourceId` - -## 8. 阶段验收 +## 7. 阶段验收 - [ ] 所有新生成资产都写入 OSS - [ ] 前端仍能通过旧路径习惯访问资源 - [ ] 资产任务状态可查询 -- [ ] 编辑器主链不依赖旧 Node 后端 diff --git a/backend-rewrite-tasklist/M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md b/backend-rewrite-tasklist/M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md index b4c964e9..daa8f874 100644 --- a/backend-rewrite-tasklist/M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md @@ -15,9 +15,10 @@ 这里的“冻结”不是要求新后端永远维持原实现,而是要求: -1. 新后端第一阶段必须完整覆盖这 `6` 个挂载面。 -2. 每个挂载面的入口职责、路径空间、权限模式、主要边界不能丢。 -3. 允许内部实现从 `Express + PostgreSQL + 本地 public/generated-*` 重写为 `Axum + SpacetimeDB + 阿里云 OSS`,但不允许把挂载面职责打散到无法对照验收。 +1. 当前 Node 后端历史基线仍固定为这 `6` 个挂载面。 +2. 本轮 Rust 后端的 active rewrite target 固定覆盖其中 `5` 个挂载面:`assets`、`auth`、`health`、`runtime-main`、`runtime-story-action`。 +3. `editor` 作为历史遗留挂载面继续保留对照记录,但自 `2026-04-21` 起不纳入 `server-rs` 本轮重写验收。 +4. 允许内部实现从 `Express + PostgreSQL + 本地 public/generated-*` 重写为 `Axum + SpacetimeDB + 阿里云 OSS`,但不允许把挂载面职责打散到无法对照验收。 ## 2. 冻结结论 @@ -34,12 +35,13 @@ 冻结总数: -1. 对外挂载面:`6` -2. 已登记路由:`96` -3. 公开接口:`10` -4. JWT 接口:`69` -5. 开关控制接口:`17` -6. 流式接口:`6` +1. 历史对外挂载面:`6` +2. 本轮 active rewrite target:`5` +3. 已登记路由:`96` +4. 公开接口:`10` +5. JWT 接口:`69` +6. 开关控制接口:`17` +7. 流式接口:`6` ## 3. 各挂载面冻结要求 @@ -88,9 +90,9 @@ 重写后的冻结要求: -1. 仍保留独立的 `/api/editor/*` 命名空间。 -2. 仍保留 `EDITOR_API_ENABLED` 开关门禁。 -3. 开发态允许继续对本地工作区做读写适配,生产态可重构为对象化资源方案,但接口职责不能消失。 +1. `server-node/src/app.ts -> /api/editor/*` 的历史存在事实继续保留在基线文档中。 +2. 自 `2026-04-21` 起,该挂载面不纳入 `server-rs` 本轮重写范围,不再作为 `M1 ~ M6` 主线交付目标。 +3. 若未来仍需清理或替代 editor,需要在遗留链路依赖核对完成后单独立项。 ### 3.4 `health` @@ -145,7 +147,7 @@ | --- | --- | --- | | `assets` | `Axum + OSS + SpacetimeDB asset metadata` | 外部副作用在 Axum,二进制在 OSS,任务与引用状态在 SpacetimeDB。 | | `auth` | `Axum auth-service + SpacetimeDB auth tables` | 登录副作用与 cookie/JWT 在 Axum,身份与会话状态在 SpacetimeDB。 | -| `editor` | `Axum editor facade` | 开发态保留本地文件适配,后续再逐步对象化。 | +| `editor` | `遗留保留于 server-node` | 历史挂载面对照,当前不进入 Rust 重写主链。 | | `health` | `Axum health route` | 维持最小化健康检查面。 | | `runtime-main` | `Axum runtime facade + SpacetimeDB runtime/custom-world tables` | Axum 维持兼容 REST/SSE,SpacetimeDB 负责状态真相。 | | `runtime-story-action` | `Axum story facade + SpacetimeDB gameplay reducers/views` | Story Action 入口继续独立存在,但结算内核迁到新状态层。 | @@ -154,22 +156,24 @@ 后续迁移中,不允许出现以下情况: -1. 把 `6` 个挂载面减少成更少但无法一一对照的“超级入口”。 -2. 把当前 `/api/auth/*`、`/api/assets/*`、`/api/editor/*`、`/api/runtime/story/*` 顶层命名空间直接改掉。 -3. 在未完成路径兼容前,直接移除 `/healthz` 或 `/generated-*` 的既有访问习惯。 -4. 在未完成契约回归前,把 `runtime-main` 和 `runtime-story-action` 的职责重新混成一个难以验收的大入口。 +1. 把历史 `6` 个挂载面减少成更少但无法一一对照的“超级入口”。 +2. 为了迎合本轮重写范围而把历史存在的 `/api/editor/*` 从基线文档中抹掉。 +3. 把当前 `/api/auth/*`、`/api/assets/*`、`/api/runtime/story/*` 顶层命名空间直接改掉。 +4. 在未完成路径兼容前,直接移除 `/healthz` 或 `/generated-*` 的既有访问习惯。 +5. 在未完成契约回归前,把 `runtime-main` 和 `runtime-story-action` 的职责重新混成一个难以验收的大入口。 ## 6. 本任务完成定义 当以下条件成立时,这条任务视为完成: -1. 当前 `6` 个挂载面已经有正式书面冻结清单。 +1. 当前历史 `6` 个挂载面已经有正式书面冻结清单。 2. 每个挂载面都有: - 当前入口 - 当前路由数 - 顶层路径空间 - 重写后必须保留的职责边界 -3. 后续任务可以直接以这份文档作为验收引用,不再靠聊天记录记忆。 +3. 本轮 active rewrite target 为 `5` 个,且 `editor` 的遗留/不迁移口径已经冻结。 +4. 后续任务可以直接以这份文档作为验收引用,不再靠聊天记录记忆。 ## 7. 后续直接依赖这份基线的任务 diff --git a/backend-rewrite-tasklist/M0_MODULE_MIGRATION_BASELINE_2026-04-20.md b/backend-rewrite-tasklist/M0_MODULE_MIGRATION_BASELINE_2026-04-20.md index 03fe7e6f..856cc73b 100644 --- a/backend-rewrite-tasklist/M0_MODULE_MIGRATION_BASELINE_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_MODULE_MIGRATION_BASELINE_2026-04-20.md @@ -35,13 +35,19 @@ 当前 Node 后端的正式内部模块固定为以下 `12` 个: +补充口径: + +1. 上表 `12` 个模块属于历史基线总量。 +2. 自 `2026-04-21` 起,本轮 Rust 后端重写的 active rewrite modules 固定为 `11` 个。 +3. `editor` 作为遗留无用模块,仅保留历史事实对照,不再进入 `server-rs` 主线迁移。 + | 模块 ID | 中文名称 | 当前目录 | 关联路由数 | 当前对外暴露面 | 重写后主归属 | 重写后次归属 | 目标迁移阶段 | | --- | --- | --- | --- | --- | --- | --- | --- | | `ai` | AI 编排模块 | `server-node/src/modules/ai` | `23` | `runtime-main` | `application + llm-service` | `contracts + api-server SSE facade` | `M4`、`M5`、`M6` | | `assets` | 资产工具模块 | `server-node/src/modules/assets` | `18` | `assets` | `application::assets + oss-service` | `spacetime-module::asset_metadata` | `M6` | | `combat` | 战斗结算模块 | `server-node/src/modules/combat` | `1` | `runtime-story-action` | `spacetime-module::gameplay::combat` | `domain::combat` | `M4` | | `custom-world` | 自定义世界运行时模块 | `server-node/src/modules/custom-world` | `26` | `runtime-main` | `spacetime-module::custom_world + application::custom_world` | `llm-service + oss-service` | `M5` | -| `editor` | 编辑器资源模块 | `server-node/src/modules/editor` | `3` | `editor` | `api-server::editor + application::editor` | `oss-service`、开发态本地文件适配 | `M6` | +| `editor` | 编辑器资源模块 | `server-node/src/modules/editor` | `3` | `editor` | `不迁移(遗留模块)` | 保留 `server-node/` 历史链路对照 | `不纳入本轮` | | `inventory` | 背包与物品变更模块 | `server-node/src/modules/inventory` | `1` | `runtime-story-action` | `spacetime-module::gameplay::inventory` | `domain::inventory` | `M4` | | `npc` | NPC 交互模块 | `server-node/src/modules/npc` | `6` | `runtime-story-action`、`runtime-main` | `spacetime-module::gameplay::npc` | `application::npc_dialogue + llm-service` | `M4`、`M5` | | `progression` | 成长与关卡进程模块 | `server-node/src/modules/progression` | `3` | `runtime-story-action`、`runtime-main` | `spacetime-module::gameplay::progression` | `domain::progression` | `M3`、`M4` | @@ -52,11 +58,13 @@ 冻结总数: -1. 内部模块目录:`12` -2. 关联路由数最多的模块:`runtime`,共 `32` 条 -3. 纯外部副作用导向模块:`ai`、`assets`、`editor` -4. 纯状态规则导向模块:`combat`、`inventory` -5. 需要“状态层 + 编排层”双落位的混合模块:`custom-world`、`npc`、`quest`、`runtime-item`、`story` +1. 历史内部模块目录:`12` +2. 本轮 active rewrite modules:`11` +3. 关联路由数最多的模块:`runtime`,共 `32` 条 +4. 本轮纯外部副作用导向模块:`ai`、`assets` +5. 已退出本轮重写范围的遗留模块:`editor` +6. 纯状态规则导向模块:`combat`、`inventory` +7. 需要“状态层 + 编排层”双落位的混合模块:`custom-world`、`npc`、`quest`、`runtime-item`、`story` ## 3. 锁定迁移归属规则 @@ -78,7 +86,7 @@ | `assets` | 生成、发布、缓存、Qwen 精灵表 | `asset_job`、`asset_object`、`asset_manifest` 等表 | `oss-service` + 外部媒体模型 | 二进制进 OSS,任务与引用进 SpacetimeDB。 | | `combat` | 战斗结算、数值变化 | `battle_state`、`story_event` | 无 | 作为纯 reducer 规则模块落到 gameplay。 | | `custom-world` | 世界资料、问答流、Agent 草稿与编译 | `custom_world_*` 系列表 | `llm-service`、`oss-service` | 世界状态在 SpacetimeDB,编译/生成在 Axum。 | -| `editor` | 编辑器 JSON 读写、图标枚举 | 开发态本地文件;线上对象元数据可入 SpacetimeDB | Axum 本地文件适配或 OSS | 第一阶段保留 Axum 工具面,不迁到前端。 | +| `editor` | 编辑器 JSON 读写、图标枚举 | 仍以遗留 Node 链路与开发态本地文件为历史对照 | 不迁移到 `server-rs` | 仅保留历史基线,不纳入本轮 Rust 重写。 | | `inventory` | 背包变更、物品副作用、NPC 背包交互 | `inventory_slot`、`story_event` | 无 | 归入 story action 对应 reducer。 | | `npc` | 互动规则、关系变化、招募/对话语义 | `npc_state`、`story_event` | `application::npc_dialogue + llm-service` | 状态归 SpacetimeDB,台词生成归 Axum。 | | `progression` | 等级、章节、敌对 scaling、benchmark | `player_progression`、`chapter_progression` | 无 | 作为 runtime / story 公共领域模块进入 SpacetimeDB。 | @@ -153,10 +161,10 @@ 重写后的冻结要求: -1. 第一阶段主归属固定为 `api-server::editor + application::editor`。 -2. 开发态允许继续读写本地文件,线上态再逐步对象化。 -3. 不允许把编辑器写盘逻辑迁到前端浏览器侧。 -4. 仍必须保留 `EDITOR_API_ENABLED` 开关门禁。 +1. 该模块在 `server-node/` 中的存在事实继续保留,用于历史基线与后续清理对照。 +2. 自 `2026-04-21` 起,不再为 `server-rs/` 创建 `module-editor` package,也不再把它纳入 `M1 ~ M6` 主线迁移。 +3. 若未来仍需清理或替代 editor,必须在遗留链路依赖确认后单独立项,不能夹带进当前 Rust 重写主链。 +4. 不允许为了简化本轮任务而篡改其历史存在事实。 ### 5.6 `inventory` @@ -253,17 +261,18 @@ 后续迁移中,不允许出现以下情况: -1. 把 `ai`、`assets`、`editor` 直接放进 SpacetimeDB reducer 执行三方网络或文件系统 IO。 -2. 把 `combat`、`inventory`、`progression` 重新做成只存在于 Axum handler 内部的计算 helper。 -3. 把 `custom-world`、`story`、`npc` 这类混合模块继续保留为“单大对象 JSON + 单大 service 写回”模式。 -4. 把 `runtime` 当成一个兜底垃圾桶,把其他领域模块重新并回去。 -5. 在没有对应 Axum facade 的前提下,让前端第一阶段直接依赖 SpacetimeDB 原生写接口。 +1. 把 `ai`、`assets` 直接放进 SpacetimeDB reducer 执行三方网络或文件系统 IO。 +2. 在未单独立项前,把已退出本轮范围的 `editor` 重新并回 `server-rs` 主链。 +3. 把 `combat`、`inventory`、`progression` 重新做成只存在于 Axum handler 内部的计算 helper。 +4. 把 `custom-world`、`story`、`npc` 这类混合模块继续保留为“单大对象 JSON + 单大 service 写回”模式。 +5. 把 `runtime` 当成一个兜底垃圾桶,把其他领域模块重新并回去。 +6. 在没有对应 Axum facade 的前提下,让前端第一阶段直接依赖 SpacetimeDB 原生写接口。 ## 7. 本任务完成定义 当以下条件成立时,这条任务视为完成: -1. 当前 `12` 个内部模块已经有正式书面冻结清单。 +1. 当前历史 `12` 个内部模块已经有正式书面冻结清单。 2. 每个模块都已明确: - 当前目录 - 关联路由数 @@ -271,11 +280,12 @@ - 重写后主归属 - 重写后次归属 - 目标迁移阶段 -3. 后续拆 `server-rs/` 多 package、建 SpacetimeDB bounded context、排 M3~M6 任务时,可以直接引用本文,不再靠口头记忆。 +3. 本轮 active rewrite modules 为 `11` 个,且 `editor` 的遗留/不迁移口径已经冻结。 +4. 后续拆 `server-rs/` 多 package、建 SpacetimeDB bounded context、排 M3~M6 任务时,可以直接引用本文,不再靠口头记忆。 ## 8. 后续直接依赖这份基线的任务 1. 设计 `server-rs/` workspace 与 package 边界 2. 设计 SpacetimeDB `runtime / gameplay / custom_world / asset_metadata` 表分层 3. 设计 story action reducer 的跨模块协作边界 -4. 设计 custom world / assets / editor 的 Axum facade +4. 设计 custom world / assets 的 Axum facade diff --git a/backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md b/backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md index 10a08a81..4ee5623b 100644 --- a/backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md @@ -25,7 +25,8 @@ 1. 未满足上一阶段退出条件前,不进入下一阶段主线编码。 2. 每一阶段至少保留一份可复查的证据,证据可以是文档、脚本、测试结果或回归记录。 3. 所有阶段都必须持续对齐当前冻结基线: - - `6` 个挂载面 + - 历史基线 `6` 个挂载面 + - 本轮 active rewrite target `5` 个挂载面 - `96` 条路由 - `12` 个模块 - `6` 条 SSE 接口 @@ -43,7 +44,7 @@ | `M3` runtime snapshot / settings / profile | `M2` 鉴权稳定;用户身份可透传到 SpacetimeDB | `runtime_snapshot`、`runtime_setting`、profile 相关主表与 facade;存档、设置、浏览历史、save archive 兼容接口 | 登录用户可正常保存、读取、删除存档;profile dashboard / browse history / save archive 行为一致;前端恢复流程可直接跑通 | 快照恢复准确性;兼容路径与主路径是否返回一致;历史记录排序与去重逻辑 | | `M4` story action 与 gameplay reducer | `M3` 快照与用户状态主链稳定 | story / combat / inventory / npc / quest / progression / runtime-item 表与 reducer;story 兼容接口与 view model | 前端 story 主循环可用;`story state` 恢复链可用;NPC / quest / treasure / combat 主循环行为不回退;旧 Node story route 回归平移完成 | `RuntimeStoryActionResponse` 结构;战斗与奖励联动;状态投影是否与旧前端恢复逻辑一致 | | `M5` custom world / gallery / agent | `M4` story 与 runtime 真相源已稳定;SSE facade 可持续输出 | custom world 主表、agent 会话拆表、传统问答流、library / gallery、agent 消息与操作、LLM/图片生成编排 | 传统 custom world 主链可用;library / gallery 主链可用;agent 主链可用;会话不再依赖单大 JSON 体 | SSE 事件格式;卡片、消息、操作状态一致性;世界草稿编译与发布链是否可回放 | -| `M6` assets / OSS / editor | `M5` 世界与角色主链稳定;Axum 应用层可承接外部副作用 | OSS 对象键规范、上传签名、对象确认、资产任务表、角色/场景/Qwen 资产迁移、编辑器读写适配、旧静态路径兼容 | 所有新生成资产写入 OSS;前端仍能通过旧路径习惯访问资源;资产任务状态可查询;编辑器主链不依赖旧 Node | `/generated-*` 路径兼容;OSS 元数据与对象绑定关系;编辑器开发态与线上态差异 | +| `M6` assets / OSS | `M5` 世界与角色主链稳定;Axum 应用层可承接外部副作用 | OSS 对象键规范、上传签名、对象确认、资产任务表、角色/场景/Qwen 资产迁移、旧静态路径兼容 | 所有新生成资产写入 OSS;前端仍能通过旧路径习惯访问资源;资产任务状态可查询 | `/generated-*` 路径兼容;OSS 元数据与对象绑定关系;资产任务链状态一致性 | | `M7` 联调、回归、部署与切流 | `M6` 已具备主链闭环;双栈对照条件具备 | 测试体系、部署方案、观测能力、灰度切流方案、回退方案、对比脚本与 smoke 清单 | 全链路 smoke 通过;主流程回归通过;关键 SSE 联调通过;可在灰度环境切流并可回退 | 双跑窗口稳定性;API 对比结果;切流开关、回退开关、观测告警是否齐备 | ## 4. M0 冻结项专用验收清单 @@ -71,6 +72,7 @@ - 前端 `M0 ~ M6` 期间只访问 Axum - 外部副作用统一收口在 Axum - `server-rs/` 内部采用 `apps/* + packages/*` 多 package 组织 + - `editor` 已于 `2026-04-21` 退出本轮 Rust 重写范围 4. `M1` 以后任何任务引用路由、模块、SSE、静态资源与响应契约时,都必须能追溯到本阶段产出的冻结文档。 ## 5. 跨阶段回归维度 diff --git a/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md b/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md index 06b59817..8793b695 100644 --- a/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md @@ -12,7 +12,7 @@ 这份文档用于持续冻结 `M0` 中与仓库边界直接相关的决策,避免进入 `M1` 后再反复改目录、改职责口径。 -当前已确认的事项只包含第一条;后续几条会继续在这份文档上追加。 +当前已确认的事项会持续在这份文档上追加维护,后续若再有新的边界冻结结论,也统一收口到这里。 ## 2. 边界决议状态 @@ -23,6 +23,7 @@ | 前端第一阶段仍然只访问 Axum,不直连 SpacetimeDB | 已确认 | `M0 ~ M6` 前端统一只访问 Axum 暴露的 `/api/*`、`/healthz`、SSE 与静态资源兼容层,不新增直连 SpacetimeDB 原生协议路径。 | | 外部副作用统一收口在 Axum,不放进 SpacetimeDB 模块 | 已确认 | OSS、LLM、短信、微信 OAuth、本地文件系统等外部副作用统一落在 Axum/application/infra,不进入 SpacetimeDB reducer/module。 | | `server-rs/` 内部采用多 package 组织,由主工程统一引用模块包 | 已确认 | `server-rs/` 采用 `apps/* + packages/*` 工作区结构,`apps/api-server` 与 `apps/spacetime-module` 作为主工程,独立模块以 `packages/module-*` 形式被主工程引用。 | +| `editor` 为遗留无用模块,不纳入 `server-rs` 本轮重写范围 | 已确认 | `server-node/src/modules/editor` 与 `/api/editor/*` 仅作为历史基线保留对照;自 `2026-04-21` 起退出本轮 Rust 后端重写范围。 | ## 3. 已确认决议一:`server-rs/` 固定落在仓库根目录 @@ -228,8 +229,7 @@ Genarrative/ 9. `packages/module-runtime-item` 10. `packages/module-custom-world` 11. `packages/module-assets` -12. `packages/module-editor` -13. `packages/module-ai` +12. `packages/module-ai` 跨模块共享 package 固定包含: @@ -254,3 +254,29 @@ Genarrative/ 1. `M1` 后续目录创建任务统一按 `apps/* + packages/*` 执行,不再新增 `crates/*` 目录规划。 2. 每个业务模块默认先有自己的 workspace package,再由主工程引用。 3. 只有共享 contract、共享领域内核、平台适配、SpacetimeDB client 这类跨模块能力,才允许使用共享 package,而不是业务模块混装。 + +## 9. 已确认决议六:`editor` 退出本轮 Rust 重写范围 + +### 9.1 决议内容 + +`editor` 在当前 Node 后端中确实存在真实模块与真实挂载面,但已于 `2026-04-21` 被确认为遗留无用模块,不再纳入本轮 `server-rs/` 重写主链。 + +当前固定口径为: + +1. 历史基线继续保留 `server-node/src/modules/editor` 与 `/api/editor/*` 的存在事实。 +2. `server-rs/` 不再保留 `packages/module-editor`。 +3. `M1 ~ M6` 的主线任务、阶段验收与 package 规划,不再把 `editor` 计入 active rewrite scope。 + +### 9.2 这样决议的原因 + +1. 用户已明确确认 `editor` 为遗留无用模块,应从本轮重写目标中剔除。 +2. 保留历史事实有助于后续对照清理,不会把“旧系统曾存在该模块”的信息抹掉。 +3. 从当前阶段开始继续为 `editor` 预留 Rust package,只会增加主线迁移噪音与工程负担。 + +### 9.3 对后续任务的直接约束 + +从这一条决议开始,后续任务必须遵守: + +1. 不再为 `editor` 创建或维护 `server-rs` 下的新 package、Axum 路由树与迁移验收项。 +2. 所有涉及挂载面、模块、路由总量的文档,都要区分“历史基线”与“本轮 active rewrite target”。 +3. 若未来仍要清理 `editor`,应在 `server-node/` 遗留链路依赖核对完成后单独立项。 diff --git a/backend-rewrite-tasklist/M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md b/backend-rewrite-tasklist/M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md index e8bd6ae6..a6db4a67 100644 --- a/backend-rewrite-tasklist/M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md @@ -29,7 +29,7 @@ | --- | --- | | `A-HEALTH` | `Axum health route` | | `A-AUTH` | `Axum auth routes + auth-service + SpacetimeDB auth tables` | -| `A-EDITOR` | `Axum editor routes + editor facade + 本地文件适配/对象化适配` | +| `A-EDITOR` | `历史 Node editor 路由(遗留保留,不迁移到 server-rs)` | | `A-OSS` | `Axum assets routes + application::assets + oss-service + SpacetimeDB asset metadata` | | `A-LLM` | `Axum llm proxy/service` | | `A-RUNTIME` | `Axum runtime facade + SpacetimeDB runtime reducers/views` | @@ -43,6 +43,7 @@ 1. 第一阶段默认保留旧路径,不主动改前端请求地址。 2. 兼容路径与主路径在新后端中应尽量共用同一 handler。 3. 所有 `stream` 接口第一阶段继续用 Axum SSE,不强推改成 WebSocket。 +4. 自 `2026-04-21` 起,`editor` 路由仅保留历史对照,不纳入本轮 Rust 重写范围。 ## 3. 总量校验 @@ -57,6 +58,11 @@ | `runtime-story-action` | `2` | | `health` | `1` | +补充说明: + +1. 上表总量仍然是当前 Node 后端历史基线。 +2. 其中 `editor` 的 `3` 条路由继续计入历史对照,但不计入本轮 `server-rs` active rewrite target。 + ## 4. `assets` 路由映射(14 条) | 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 | @@ -98,13 +104,13 @@ | `auth.wechatCallback` | `GET /api/auth/wechat/callback` | `A-AUTH` | 保留原路径与 redirect 语义;微信 code 交换由 Axum 处理。 | | `auth.wechatStart` | `GET /api/auth/wechat/start` | `A-AUTH` | 保留原路径;授权 URL 由 Axum 按设备场景生成。 | -## 6. `editor` 路由映射(3 条) +## 6. `editor` 路由映射(3 条,历史遗留) | 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 | | --- | --- | --- | --- | -| `editor.catalogItems` | `GET /api/editor/catalog/items` | `A-EDITOR` | 保留原路径;先继续由 Axum 枚举工作区图标目录。 | -| `editor.resourceRead` | `GET /api/editor/json/:resourceId` | `A-EDITOR` | 保留原路径;开发态继续读本地 JSON,后续再对象化。 | -| `editor.resourceWrite` | `POST /api/editor/json/:resourceId` | `A-EDITOR` | 保留原路径;开发态继续写本地 JSON,行为由 Axum 统一托管。 | +| `editor.catalogItems` | `GET /api/editor/catalog/items` | `A-EDITOR` | 保留在 `server-node/` 遗留链路,仅作为历史对照;不迁移到 `server-rs`。 | +| `editor.resourceRead` | `GET /api/editor/json/:resourceId` | `A-EDITOR` | 保留在 `server-node/` 遗留链路,仅作为历史对照;不迁移到 `server-rs`。 | +| `editor.resourceWrite` | `POST /api/editor/json/:resourceId` | `A-EDITOR` | 保留在 `server-node/` 遗留链路,仅作为历史对照;不迁移到 `server-rs`。 | ## 7. `runtime-main` 路由映射(59 条) @@ -229,6 +235,7 @@ 3. `stream` 接口第一阶段默认沿用 SSE。 4. `assets` 与 `custom-world` 里的生成类接口,外部副作用统一在 Axum,状态与任务统一进 SpacetimeDB。 5. `storyAction.resolve`、`runtime.snapshotPut`、`auth.refresh` 属于最优先回归接口,后续开发必须优先补完整测试。 +6. `editor` 相关旧路径只保留历史基线记录,不纳入 `server-rs` 路由树实施范围。 ## 11. 本任务完成定义 diff --git a/backend-rewrite-tasklist/README.md b/backend-rewrite-tasklist/README.md index 00ebe72c..3fbccb1c 100644 --- a/backend-rewrite-tasklist/README.md +++ b/backend-rewrite-tasklist/README.md @@ -11,7 +11,7 @@ - [02_M3_RUNTIME_PROFILE.md](./02_M3_RUNTIME_PROFILE.md):runtime snapshot / settings / profile 迁移任务。 - [03_M4_STORY_AND_GAMEPLAY.md](./03_M4_STORY_AND_GAMEPLAY.md):story action 主循环与 gameplay reducer 迁移任务。 - [04_M5_CUSTOM_WORLD_AND_AGENT.md](./04_M5_CUSTOM_WORLD_AND_AGENT.md):custom world / gallery / agent 主链迁移任务。 -- [05_M6_ASSETS_OSS_EDITOR.md](./05_M6_ASSETS_OSS_EDITOR.md):assets / 阿里云 OSS / editor 迁移任务。 +- [05_M6_ASSETS_OSS_EDITOR.md](./05_M6_ASSETS_OSS_EDITOR.md):assets / 阿里云 OSS 迁移任务;`editor` 已于 `2026-04-21` 退出本轮重写范围。 - [06_M7_TEST_DEPLOY_CUTOVER.md](./06_M7_TEST_DEPLOY_CUTOVER.md):联调、回归、部署、观测与切流任务。 - [07_CROSS_CUTTING_AND_ACCEPTANCE.md](./07_CROSS_CUTTING_AND_ACCEPTANCE.md):横向专项、执行顺序与最终验收清单。 - [M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md](./M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md):当前 Node 后端 `6` 个挂载面的冻结基线,用于后续接口映射、模块迁移与验收对照。 diff --git a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md index 09babe4e..40d96346 100644 --- a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md +++ b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md @@ -27,14 +27,18 @@ - 环境开关接口:`17` 条 - 流式接口:`6` 条 -重写后的 Rust 后端,第一阶段必须至少完整覆盖这 6 个挂载面: +当前 Node 后端的历史基线仍然是这 `6` 个挂载面,但自 `2026-04-21` 起,本轮 Rust 后端重写的 active rewrite target 固定为其中 `5` 个: 1. `health` 2. `auth` -3. `editor` -4. `assets` -5. `runtime-main` -6. `runtime-story-action` +3. `assets` +4. `runtime-main` +5. `runtime-story-action` + +补充说明: + +1. `editor` 挂载面在历史系统中真实存在,但已被确认为遗留无用能力。 +2. `editor` 仅保留为历史基线对照,不纳入本轮 `server-rs` 重写验收。 当前后端内部模块也不能“凭感觉重设计”,而要按现有职责做映射: @@ -51,6 +55,12 @@ 11. `runtime-item` 12. `story` +其中: + +1. 上述 `12` 个模块是历史基线总量。 +2. 本轮 active rewrite modules 固定为 `11` 个。 +3. `editor` 仅保留历史事实,不进入 `server-rs` 主线 package 与阶段验收。 + ## 3. 技术选型后的硬边界 ### 3.1 SpacetimeDB 的平台约束与本项目边界 @@ -119,7 +129,6 @@ Axum API Server ├─ runtime facade:兼容当前 REST / SSE contract ├─ asset gateway:OSS 直传签名、对象确认、媒体任务编排 ├─ ai gateway:DashScope / Ark / 其他模型调用 -├─ editor gateway:开发态文件读写或对象化编辑能力 ├─ background workers:异步作业执行与回写 └─ SpacetimeDB client:调用 reducer、查询 view / public table、订阅任务状态 @@ -139,7 +148,7 @@ Aliyun OSS ├─ generated-custom-world-scenes ├─ generated-custom-world-covers ├─ generated-qwen-sprites -└─ editor-exports / temp-uploads / workflow-cache +└─ temp-uploads / workflow-cache ``` ## 5. 重写后的核心原则 @@ -224,7 +233,6 @@ server-rs/ │ ├─ module-runtime-item/ # 运行时物品模块 package │ ├─ module-custom-world/ # 自定义世界与 agent 模块 package │ ├─ module-assets/ # 资产任务与对象绑定模块 package -│ ├─ module-editor/ # 编辑器读写模块 package │ ├─ module-ai/ # AI 编排模块 package │ ├─ shared-contracts/ # HTTP DTO / SSE event / 前后端兼容 contract │ ├─ shared-kernel/ # 跨模块共享领域类型、ID、枚举、值对象 @@ -243,7 +251,7 @@ server-rs/ 1. `apps/api-server/` 只做协议装配、鉴权、中间件、handler 与模块组合,不把业务模块重新堆回单包。 2. `apps/spacetime-module/` 只负责聚合各模块 package 的状态模型,不直接承接外部副作用。 -3. `packages/module-*` 保持与当前业务模块边界一一对应,必要时可在 package 内部再拆 `application`、`domain`、`spacetime` 子层次。 +3. `packages/module-*` 保持与当前业务模块边界一一对应,已明确退出本轮的 `editor` 遗留模块除外;必要时可在 package 内部再拆 `application`、`domain`、`spacetime` 子层次。 4. `packages/shared-contracts/` 负责与当前前端兼容的 JSON / SSE 协议。 5. `packages/shared-kernel/` 只放跨模块复用的数据结构和规则,不碰框架。 6. `packages/platform-*` 统一承接三方供应商与平台适配。 @@ -269,7 +277,11 @@ server-rs/ | `custom-world` | SpacetimeDB module + Axum orchestration | OSS | 会话、草稿、agent 状态放 SpacetimeDB;世界编译、资产生成、发布编排在 Axum。 | | `ai` | Axum `llm-service` | SpacetimeDB task tables | 外部模型调用全部放 Axum。 | | `assets` | Axum `oss-service` | SpacetimeDB asset metadata | 二进制进 OSS,元数据进 SpacetimeDB。 | -| `editor` | Axum `editor` namespace | OSS / local fs | 开发态保留本地文件适配,线上默认走对象化资源。 | + +补充说明: + +1. 历史 `editor` 模块不纳入 `server-rs` 本轮重写。 +2. 相关 `/api/editor/*` 与 `server-node/src/modules/editor` 仅保留为旧系统对照事实,后续若要清理再单独立项。 ## 8. 数据建模方案 @@ -448,7 +460,6 @@ Axum 进程建议拆成以下子系统: - `/api/runtime/*` - `/api/runtime/story/*` - `/api/assets/*` - - `/api/editor/*` 3. `application::services` - story facade - runtime snapshot facade @@ -505,7 +516,6 @@ generated-animations/{character_id}/{animation_set_id}/{action}/{file} generated-custom-world-scenes/{profile_id}/{landmark_id}/{asset_id}/{file} generated-qwen-sprites/{role_id}/{sheet_id}/{file} generated-custom-world-covers/{profile_id}/{asset_id}/{file} -editor-cache/{resource_type}/{resource_id}/{file} workflow-cache/{workflow_type}/{workflow_id}.json ``` @@ -697,22 +707,26 @@ workflow-cache/{workflow_type}/{workflow_id}.json 3. custom world agent 会话、卡片、操作 4. scene npc / entity generation -## Phase 5:迁移 assets / editor +## Phase 5:迁移 assets / OSS 交付: 1. OSS 直传 2. 生成任务 3. 对象元数据 -4. 编辑器读写开发态适配 -5. 旧 `/generated-*` 路径兼容 +4. 旧 `/generated-*` 路径兼容 + +补充说明: + +1. `editor` 已于 `2026-04-21` 被确认为遗留无用模块,退出本轮 Rust 后端重写范围。 +2. Phase 5 只覆盖资产与 OSS 主链,不再包含 editor 迁移。 ## 14. 验收标准 重写完成至少要满足: 1. 当前 `96` 条已登记路由全部有对应实现或明确兼容替代。 -2. 当前 6 个挂载面全部保留。 +2. 当前历史 `6` 个挂载面的迁移去向全部明确,且本轮 active rewrite target 的 `5` 个挂载面全部落地。 3. 浏览器无需直接知道 SpacetimeDB 原生接口即可跑通主流程。 4. story action、存档、custom world、agent、assets 都以后端为唯一真相。 5. 所有生成图片、动画、精灵表都不再依赖本地 `public/generated-*` 持久化。 diff --git a/server-rs/README.md b/server-rs/README.md index 0d53409f..26ba5c8c 100644 --- a/server-rs/README.md +++ b/server-rs/README.md @@ -14,7 +14,7 @@ ## 2. 当前阶段说明 -当前目录已经完成以下二十五项初始化: +当前目录已经完成以下二十四项初始化: 1. 为新后端预留正式目录并把路径固定到仓库结构中。 2. 创建虚拟 workspace `Cargo.toml`,后续 package 会逐项挂入。 @@ -32,15 +32,14 @@ 14. 创建 `packages/module-runtime-item/` 目录占位,固定运行时物品模块 package 落位。 15. 创建 `packages/module-custom-world/` 目录占位,固定自定义世界与 agent 模块 package 落位。 16. 创建 `packages/module-assets/` 目录占位,固定资产任务与对象绑定模块 package 落位。 -17. 创建 `packages/module-editor/` 目录占位,固定编辑器读写模块 package 落位。 -18. 创建 `packages/module-ai/` 目录占位,固定 AI 编排模块 package 落位。 -19. 创建 `packages/shared-contracts/` 目录占位,固定前后端兼容 contract 共享 package 落位。 -20. 创建 `packages/shared-kernel/` 目录占位,固定跨模块共享领域内核 package 落位。 -21. 创建 `packages/platform-auth/` 目录占位,固定鉴权平台适配 package 落位。 -22. 创建 `packages/platform-oss/` 目录占位,固定 OSS 平台适配 package 落位。 -23. 创建 `packages/platform-llm/` 目录占位,固定大模型平台适配 package 落位。 -24. 创建 `packages/spacetime-client/` 目录占位,固定 SpacetimeDB 客户端适配 package 落位。 -25. 创建 `packages/tests-support/` 目录占位,固定测试支撑共享 package 落位。 +17. 创建 `packages/module-ai/` 目录占位,固定 AI 编排模块 package 落位。 +18. 创建 `packages/shared-contracts/` 目录占位,固定前后端兼容 contract 共享 package 落位。 +19. 创建 `packages/shared-kernel/` 目录占位,固定跨模块共享领域内核 package 落位。 +20. 创建 `packages/platform-auth/` 目录占位,固定鉴权平台适配 package 落位。 +21. 创建 `packages/platform-oss/` 目录占位,固定 OSS 平台适配 package 落位。 +22. 创建 `packages/platform-llm/` 目录占位,固定大模型平台适配 package 落位。 +23. 创建 `packages/spacetime-client/` 目录占位,固定 SpacetimeDB 客户端适配 package 落位。 +24. 创建 `packages/tests-support/` 目录占位,固定测试支撑共享 package 落位。 后续任务会继续在本目录内按顺序补齐: diff --git a/server-rs/packages/module-editor/README.md b/server-rs/packages/module-editor/README.md deleted file mode 100644 index f1efb212..00000000 --- a/server-rs/packages/module-editor/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# module-editor 独立模块 package 占位说明 - -日期:`2026-04-20` - -## 1. package 职责 - -`module-editor` 是编辑器读写模块 package,后续负责: - -1. 编辑器资源 JSON 的读取、保存与校验 -2. 图标目录、资源目录等开发态枚举能力 -3. 开发态本地文件适配与线上对象化替代策略 -4. 与 `apps/api-server` 的 editor 兼容接口对接 - -## 2. 当前阶段说明 - -当前提交仅完成目录占位,不提前进入编辑器 API、文件适配与对象化迁移实现。 - -后续与本 package 直接相关的任务包括: - -1. 迁移编辑器 JSON 读取与保存 -2. 迁移图标目录枚举 -3. 评估线上态对象化资源替代方案 -4. 保持开发态本地文件能力与开关门禁 - -## 3. 边界约束 - -1. `module-editor` 负责编辑器资源读写与模块级编排,不把编辑器写盘逻辑迁到前端浏览器侧。 -2. 开发态允许通过本地文件适配工作,但线上态要为对象化资源保留演进空间。 -3. 前端兼容接口由 `apps/api-server` 暴露,编辑器能力必须继续遵守环境开关门禁。 diff --git a/server-rs/packages/platform-oss/README.md b/server-rs/packages/platform-oss/README.md index e12a2d15..d6d7c954 100644 --- a/server-rs/packages/platform-oss/README.md +++ b/server-rs/packages/platform-oss/README.md @@ -9,7 +9,7 @@ 1. OSS 直传签名、STS、上传策略适配 2. 对象上传、下载、签名 URL 与 `cdn_url` 解析适配 3. 对象元数据、标签与内容 hash 适配 -4. 供 `module-assets`、`module-custom-world`、`module-editor` 复用的对象存储基础设施能力 +4. 供 `module-assets`、`module-custom-world` 等模块复用的对象存储基础设施能力 ## 2. 当前阶段说明