refactor: split large modules and normalize rust layout
This commit is contained in:
kdletters
@@ -16,10 +16,29 @@
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 2026-05-18 Rust 手写模块入口统一不用 mod.rs
|
||||
|
||||
- 背景：Rust 目录模块同时存在 `mod.rs` 与同名 `.rs` 两种入口形式，前次拆分已让 `spacetime-client/src/mapper.rs` 采用同名入口；继续新增 `mod.rs` 会让文件定位和评审口径不一致。
|
||||
- 决策：手写 Rust 模块统一使用同名入口文件，例如 `puzzle.rs`、`match3d.rs`、`gameplay.rs`，子模块继续放在同名目录下；不要再为手写模块新增 `mod.rs`。SpacetimeDB CLI 生成的 bindings 也由生成脚本同步为 `module_bindings.rs` 加 `module_bindings/` 子目录，避免仓库里继续出现 `mod.rs`。
|
||||
- 边界：本决策只规范文件布局，不改变 module path、HTTP route、DTO、SpacetimeDB schema、生成绑定内容或运行时行为。
|
||||
- 影响范围：`server-rs/crates/api-server/src/`、`server-rs/crates/spacetime-module/src/`、`server-rs/crates/spacetime-client/src/module_bindings.rs`、`scripts/generate-spacetime-bindings.mjs`。
|
||||
- 验证方式：执行 `Get-ChildItem server-rs -Recurse -Filter mod.rs` 应无结果；再执行对应 `cargo check` / 定向测试 / 编码检查。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-05-18 大文件拆分继续按聚合入口加领域子模块推进
|
||||
|
||||
- 背景：完成拼图 `api-server` 拆分后，`match3d.rs`、`spacetime-client/src/mapper.rs` 与 `PlatformEntryFlowShellImpl.tsx` 仍是后续迭代和评审的高噪音大文件。
|
||||
- 决策：抓大鹅 Match3D 的 `api-server` 单文件改为同名入口 `src/match3d.rs` 加 `src/match3d/` 子模块目录，`handlers.rs`、`draft.rs`、`works.rs`、`item_assets.rs`、`runtime.rs`、`vector_engine_gemini.rs`、`mappers.rs`、`tags.rs`、`tests.rs` 分担原实现；`spacetime-client/src/mapper.rs` 改为聚合入口，具体 mapper 按领域落到 `src/mapper/*.rs`；平台入口继续以 `PlatformEntryFlowShellImpl.tsx` 为编排壳，独立 UI 片段优先拆到 `PlatformEntryFlowShellImpl/` 子目录，本次已抽出 `PuzzleOnboardingView.tsx`。
|
||||
- 边界：这些拆分只改变文件组织，不改变 HTTP route、DTO、error envelope、SpacetimeDB schema、生成绑定、procedure result、入口配置事实源、前端行为、VectorEngine / OSS 副作用或计费语义。后续要下沉领域规则时另行讨论并更新设计。
|
||||
- 影响范围：`server-rs/crates/api-server/src/match3d/`、`server-rs/crates/spacetime-client/src/mapper/`、`src/components/platform-entry/PlatformEntryFlowShellImpl/`、后端架构文档和玩法链路文档。
|
||||
- 验证方式：执行 `cargo check -p api-server --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml --no-run`、`cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml`、前端 typecheck 或定向 tsc、`git diff --check` 与 `npm run check:encoding`。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-05-18 api-server 拼图能力按 HTTP/BFF 子模块拆分
|
||||
|
||||
- 背景：`server-rs/crates/api-server/src/puzzle.rs` 已膨胀为数千行大文件，混合 Axum handler、草稿编译、图片生成、VectorEngine / OSS 持久化、DTO mapper、标签生成和测试；继续在单文件内迭代会降低定位和评审效率。
|
||||
- 决策：删除单文件 `puzzle.rs`，改为 `server-rs/crates/api-server/src/puzzle/` 目录模块。`mod.rs` 只保留聚合入口和 handler re-export；`handlers.rs` 放 HTTP handler；`draft.rs` 放表单草稿 / 编译 / snapshot helper；`generation.rs` 放图片与 UI 背景生成编排；`vector_engine.rs` 放 VectorEngine、下载、OSS、asset object / binding 和错误归一；`mappers.rs` / `tags.rs` 保留映射和标签 / 错误 helper；`tests.rs` 承接原 puzzle 单测。
|
||||
- 决策：原超大 `puzzle.rs` 改为同名入口 `server-rs/crates/api-server/src/puzzle.rs` 加 `server-rs/crates/api-server/src/puzzle/` 子模块目录。`puzzle.rs` 只保留聚合入口和 handler re-export；`handlers.rs` 放 HTTP handler；`draft.rs` 放表单草稿 / 编译 / snapshot helper；`generation.rs` 放图片与 UI 背景生成编排；`vector_engine.rs` 放 VectorEngine、下载、OSS、asset object / binding 和错误归一；`mappers.rs` / `tags.rs` 保留映射和标签 / 错误 helper；`tests.rs` 承接原 puzzle 单测。
|
||||
- 边界：本次只改变 `api-server` 内部文件组织，不改变 `/api/runtime/puzzle/*` 路由、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义或计费语义。领域规则后续仍应逐步沉到 `module-puzzle`，SpacetimeDB 表、reducer、procedure 和 row shape 仍留在 `spacetime-module`。
|
||||
- 影响范围：`server-rs/crates/api-server/src/puzzle/`、`server-rs/crates/api-server/src/modules/puzzle.rs` 的 handler 引用、后端架构文档。
|
||||
- 验证方式：执行 `cargo check -p api-server --manifest-path server-rs\Cargo.toml`；后续若改动 puzzle API 行为，再按对应路由补充定向测试和 `npm run dev:api-server` `/healthz` smoke。
|
||||
|
||||
Reference in New Issue
Block a user