Genarrative/docs/technical/SPACETIME_MODULE_LIB_RS_SPLIT_EXECUTION_2026-04-23.md

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 域新增实现。