拆分大文件
This commit is contained in:
@@ -0,0 +1,241 @@
|
||||
# spacetime-module `lib.rs` 拆分执行方案
|
||||
|
||||
日期：`2026-04-23`
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `server-rs/crates/spacetime-module/src/lib.rs` 已经超过 `9000` 行，同时混合了承载：
|
||||
|
||||
1. SpacetimeDB 主工程入口
|
||||
2. 跨域共享类型
|
||||
3. Big Fish
|
||||
4. Asset Metadata
|
||||
5. Runtime
|
||||
6. Gameplay
|
||||
7. Custom World
|
||||
8. AI
|
||||
9. Puzzle
|
||||
10. 测试
|
||||
|
||||
这会直接导致：
|
||||
|
||||
1. 任意一个领域改动都要在同一个超大文件里定位
|
||||
2. 不同玩法与领域的 reducer / procedure / helper 互相缠绕
|
||||
3. 结构上已经与 `M7` 冻结的“按业务与 SpacetimeDB 聚合层次拆分目录”目标不一致
|
||||
|
||||
## 2. 本轮约束
|
||||
|
||||
本轮拆分严格遵守以下规则：
|
||||
|
||||
1. 只做物理结构收口，不改 table 名、reducer 名、procedure 名。
|
||||
2. 不改现有 schema 字段名、字段顺序语义与已有对外 contract。
|
||||
3. 不把外部副作用搬进 SpacetimeDB reducer / procedure。
|
||||
4. 允许在过渡期继续保留少量跨域 helper 在 `lib.rs`，但新增内容禁止继续直接堆回 `lib.rs`。
|
||||
|
||||
## 3. 模块地图
|
||||
|
||||
### 3.1 根入口
|
||||
|
||||
`server-rs/crates/spacetime-module/src/lib.rs`
|
||||
|
||||
后续只允许保留：
|
||||
|
||||
1. `use` 聚合
|
||||
2. `mod` 声明
|
||||
3. 少量跨域共享 helper
|
||||
4. 迁移过渡期测试
|
||||
|
||||
禁止继续新增某个具体业务域的 table / reducer / procedure / tx helper。
|
||||
|
||||
导入导出风格同步冻结为：
|
||||
|
||||
1. `src/lib.rs` 对外统一优先使用 `pub use xxx::*;` 重新导出主工程模块与外部模块 crate 内容。
|
||||
2. 已拆出的业务模块内部统一优先使用 `use crate::*;`，避免每个文件重复维护大段显式 `use` 列表。
|
||||
3. 子模块只有遇到命名冲突、宏限制或无法从 crate 根重导出的外部符号时，才允许补局部显式 `use`。
|
||||
4. 后续拆分时不再因为导入列表变长而把业务实现留在 `lib.rs`。
|
||||
|
||||
### 3.2 已冻结的一级模块
|
||||
|
||||
1. `src/entry.rs`
|
||||
- 模块初始化入口
|
||||
- `#[spacetimedb::reducer(init)]`
|
||||
2. `src/domain_types.rs`
|
||||
- 跨域共享的 SpacetimeDB 类型
|
||||
- 目前主要承载 NPC 开战桥接输入输出
|
||||
3. `src/asset_metadata/mod.rs`
|
||||
- `asset_object`
|
||||
- `asset_entity_binding`
|
||||
- 资产确认与绑定 reducer / procedure
|
||||
4. `src/big_fish/mod.rs`
|
||||
- Big Fish session / message / asset slot / runtime run
|
||||
- Big Fish procedure 与 tx helper
|
||||
5. `src/runtime/mod.rs`
|
||||
- Runtime settings / snapshots / browse history / dashboard / wallet / save archive
|
||||
6. `src/gameplay/mod.rs`
|
||||
- `story / combat / inventory / npc / quest / runtime_item / progression`
|
||||
7. `src/custom_world/mod.rs`
|
||||
- profile / session / agent / publish / gallery / works
|
||||
8. `src/ai/mod.rs`
|
||||
- ai task / stage / chunk / reference
|
||||
9. `src/puzzle.rs`
|
||||
- 拼图玩法当前仍为单文件域模块，后续再决定是否继续拆目录
|
||||
|
||||
### 3.3 本轮先创建的二级落位点
|
||||
|
||||
#### `asset_metadata/`
|
||||
|
||||
1. `objects.rs`
|
||||
2. `bindings.rs`
|
||||
|
||||
#### `big_fish/`
|
||||
|
||||
1. `tables.rs`
|
||||
2. `session.rs`
|
||||
3. `assets.rs`
|
||||
4. `runtime.rs`
|
||||
|
||||
#### `runtime/`
|
||||
|
||||
1. `settings.rs`
|
||||
2. `snapshots.rs`
|
||||
3. `browse_history.rs`
|
||||
4. `profile.rs`
|
||||
|
||||
#### `gameplay/`
|
||||
|
||||
1. `combat.rs`
|
||||
2. `inventory.rs`
|
||||
3. `npc.rs`
|
||||
4. `progression.rs`
|
||||
5. `quest.rs`
|
||||
6. `runtime_item.rs`
|
||||
7. `story.rs`
|
||||
|
||||
#### `custom_world/`
|
||||
|
||||
1. `profile.rs`
|
||||
2. `session.rs`
|
||||
3. `agent.rs`
|
||||
4. `publishing.rs`
|
||||
5. `gallery.rs`
|
||||
6. `works.rs`
|
||||
|
||||
#### `ai/`
|
||||
|
||||
1. `tasks.rs`
|
||||
2. `stages.rs`
|
||||
3. `snapshots.rs`
|
||||
|
||||
## 4. 迁移顺序
|
||||
|
||||
为了降低脏工作区下的冲突风险，本轮按下面顺序推进：
|
||||
|
||||
1. 先冻结文档与 README 路由规则。
|
||||
2. 先创建二级空模块文件，作为后续内容落位点。
|
||||
3. 第一批先迁：
|
||||
- `entry.rs`
|
||||
- `domain_types.rs`
|
||||
- `asset_metadata/mod.rs`
|
||||
- `big_fish/mod.rs`
|
||||
4. 第二批再迁：
|
||||
- `runtime/mod.rs`
|
||||
- `gameplay/mod.rs`
|
||||
5. 第三批再迁：
|
||||
- `custom_world/mod.rs`
|
||||
- `ai/mod.rs`
|
||||
6. `puzzle.rs` 暂时保持单文件，不在本轮强拆。
|
||||
|
||||
## 5. 本轮完成标准
|
||||
|
||||
1. `README.md` 明确声明后续新增逻辑的落位规则。
|
||||
2. 一级模块与二级空模块文件创建完成。
|
||||
3. `lib.rs` 不再承载 `init`、共享 domain types、asset metadata、big fish 的实现细节。
|
||||
4. `cargo check -p spacetime-module --lib` 继续通过。
|
||||
5. 中文文档与 Rust 文件经过编码检查，没有写坏。
|
||||
|
||||
## 6. `runtime` 域实拆记录
|
||||
|
||||
`2026-04-23` 追加执行 `runtime` 域真实内容拆分，目标是把根入口中的 runtime 表、procedure 与同域 tx helper 收口到 `src/runtime/`，同时保持对外 API 名称不变。
|
||||
|
||||
### 6.1 已落位文件
|
||||
|
||||
1. `server-rs/crates/spacetime-module/src/runtime/mod.rs`
|
||||
- 仅保留二级模块声明与 `pub use xxx::*;` 聚合导出。
|
||||
2. `server-rs/crates/spacetime-module/src/runtime/settings.rs`
|
||||
- 承载 `RuntimeSetting`
|
||||
- 承载 runtime setting 的读取、upsert procedure 与快照构建 helper。
|
||||
3. `server-rs/crates/spacetime-module/src/runtime/snapshots.rs`
|
||||
- 承载 `RuntimeSnapshotRow`
|
||||
- 承载 runtime snapshot 的读取、upsert、delete 与 JSON 解析 helper。
|
||||
4. `server-rs/crates/spacetime-module/src/runtime/browse_history.rs`
|
||||
- 承载 `UserBrowseHistory`
|
||||
- 承载平台浏览历史 list、upsert、clear procedure 与行转换 helper。
|
||||
5. `server-rs/crates/spacetime-module/src/runtime/profile.rs`
|
||||
- 承载 `ProfileDashboardState`
|
||||
- 承载 `ProfileWalletLedger`
|
||||
- 承载 `ProfilePlayedWorld`
|
||||
- 承载 `ProfileSaveArchive`
|
||||
- 承载 profile dashboard、wallet ledger、play stats、save archive 投影与 snapshot 同步 helper。
|
||||
|
||||
### 6.2 根入口调整
|
||||
|
||||
`server-rs/crates/spacetime-module/src/lib.rs` 当前只通过下面方式接入 runtime 域：
|
||||
|
||||
1. `mod runtime;`
|
||||
2. `pub use runtime::*;`
|
||||
|
||||
原先留在 `lib.rs` 的 runtime setting、snapshot、profile、browse history 旧 helper 已删除，避免同名实现重复存在，也避免后续继续在根入口堆叠 runtime 业务逻辑。
|
||||
|
||||
### 6.3 后续维护规则
|
||||
|
||||
1. 对外导出继续通过 `pub use runtime::*;` 以及 `src/runtime/mod.rs` 中的 `pub use xxx::*;` 透出。
|
||||
2. `runtime` 子文件内部优先使用 `use crate::*;`，只有 SpacetimeDB table accessor trait、命名冲突或宏限制需要时才补最小显式导入。
|
||||
3. 新增 runtime 相关表、procedure、reducer 或 tx helper 时，必须先按 `settings / snapshots / browse_history / profile` 判断二级落位点；不匹配时先更新本文件与 README，再新增二级模块。
|
||||
4. `lib.rs` 只保留跨域共享 helper 和尚未迁出的过渡代码，不再接收 runtime 域新增实现。
|
||||
|
||||
## 7. `ai` 域实拆记录
|
||||
|
||||
`2026-04-23` 追加执行 `ai` 域真实内容拆分，目标是把根入口中的 AI 表、procedure 与同域 tx helper 收口到 `src/ai/`，同时保持 `module-ai` 对外输入输出 contract 与 SpacetimeDB reducer / procedure 名称不变。
|
||||
|
||||
### 7.1 已落位文件
|
||||
|
||||
1. `server-rs/crates/spacetime-module/src/ai/mod.rs`
|
||||
- 仅保留二级模块声明与聚合导出。
|
||||
- public API 通过 `pub use stages::*;` 和 `pub use tasks::*;` 透出。
|
||||
- 内部转换 helper 通过 `pub(crate) use snapshots::*;` 供 AI 子模块共享。
|
||||
2. `server-rs/crates/spacetime-module/src/ai/tasks.rs`
|
||||
- 承载 `AiTask`
|
||||
- 承载 `create_ai_task`
|
||||
- 承载 `create_ai_task_and_return`
|
||||
- 承载 `start_ai_task`
|
||||
- 承载 `complete_ai_task_and_return`
|
||||
- 承载 `fail_ai_task_and_return`
|
||||
- 承载 `cancel_ai_task_and_return`
|
||||
- 承载 task 状态迁移、读取与持久化 helper。
|
||||
3. `server-rs/crates/spacetime-module/src/ai/stages.rs`
|
||||
- 承载 `AiTaskStage`
|
||||
- 承载 `AiTextChunk`
|
||||
- 承载 `AiResultReference`
|
||||
- 承载 `start_ai_task_stage`
|
||||
- 承载 `append_ai_text_chunk_and_return`
|
||||
- 承载 `complete_ai_stage_and_return`
|
||||
- 承载 `attach_ai_result_reference_and_return`
|
||||
- 承载阶段流式文本聚合、阶段替换与 result reference 写入 helper。
|
||||
4. `server-rs/crates/spacetime-module/src/ai/snapshots.rs`
|
||||
- 承载 `AiTask / AiTaskStage / AiTextChunk / AiResultReference` 的 row 与 snapshot 转换 helper。
|
||||
|
||||
### 7.2 根入口调整
|
||||
|
||||
`server-rs/crates/spacetime-module/src/lib.rs` 当前只通过下面方式接入 AI 域：
|
||||
|
||||
1. `mod ai;`
|
||||
2. `pub use ai::*;`
|
||||
|
||||
原先留在 `lib.rs` 的 AI 表、procedure 与 helper 已删除，避免根入口继续堆叠 AI 业务实现。
|
||||
|
||||
### 7.3 后续维护规则
|
||||
|
||||
1. 对外导出继续通过 `pub use ai::*;` 以及 `src/ai/mod.rs` 中的 `pub use xxx::*;` 透出。
|
||||
2. `ai` 子文件内部优先使用 `use crate::*;`，只有 `module_ai` 中的归一化函数、校验函数、ID 前缀常量等需要避免 glob 歧义的符号才补最小显式导入。
|
||||
3. 新增 AI 相关表、procedure、reducer 或 tx helper 时，必须先按 `tasks / stages / snapshots` 判断二级落位点；不匹配时先更新本文件与 README，再新增二级模块。
|
||||
4. `lib.rs` 不再接收 AI 域新增实现。
|
||||
Reference in New Issue
Block a user