219 lines
9.8 KiB
Markdown
219 lines
9.8 KiB
Markdown
# spacetime-module 主工程 crate 说明
|
||
|
||
日期：`2026-04-21`
|
||
|
||
## 1. crate 职责
|
||
|
||
`spacetime-module` 是新后端的 SpacetimeDB 主工程 crate，后续负责：
|
||
|
||
1. 聚合各独立模块 crate 的表定义
|
||
2. 聚合各独立模块 crate 的 reducer
|
||
3. 聚合各独立模块 crate 的 view / 读模型
|
||
4. 生成可发布的 SpacetimeDB wasm 模块
|
||
5. 由 `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 驱动的本地 standalone 启动链路
|
||
|
||
## 2. 当前阶段说明
|
||
|
||
当前阶段已落下第一批真实 schema 骨架，并已补齐本地 standalone 启动脚本，先把 SpacetimeDB 进程入口、M3/M4 基础表以及 `M5 custom world / agent` 首批表骨架固定下来。
|
||
|
||
后续与本 crate 直接相关的任务包括：
|
||
|
||
1. 继续扩充模块聚合入口
|
||
2. 继续设计表、reducer、view 的聚合方式
|
||
3. 接入身份 claims 透传
|
||
4. 在当前 scaffold 基础上接入 publish / dev 循环
|
||
5. 在 `M7` 收口阶段拆分过大的 `src/lib.rs`，按 `runtime`、`gameplay/*`、`custom_world`、`asset_metadata`、`ai` 等业务与 SpacetimeDB 聚合层次重组目录，避免主工程 crate 回退成单大包
|
||
|
||
当前已落地：
|
||
|
||
1. `spacetime-module` 真实 `cdylib` crate scaffold
|
||
2. `asset_object` 首版表骨架
|
||
3. `bucket + object_key` 双列对象定位索引
|
||
4. `module-assets` 的访问策略与字段校验类型接入
|
||
5. 面向 Axum 的 `asset_object` 确认持久化入口
|
||
6. `asset_entity_binding` 通用绑定表
|
||
7. 面向 Axum 的 `bind_asset_object_to_entity_and_return` 绑定 procedure
|
||
8. `runtime_setting` 表与 procedure
|
||
9. `npc_state`、`story_session`、`story_event`
|
||
10. `battle_state`、`treasure_record`
|
||
11. `quest_record`、`quest_log`
|
||
12. `M5` 首批 `custom_world_profile / session / agent / gallery` 表骨架
|
||
13. `custom world library / publish / gallery` Stage 2 procedures
|
||
14. `published profile compile` Stage 3 procedure
|
||
15. `publish_world` Stage 4 串联 procedure
|
||
16. `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 首版 AI 真相表
|
||
17. AI 任务最小 procedure / reducer：
|
||
- `create_ai_task`
|
||
- `create_ai_task_and_return`
|
||
- `start_ai_task`
|
||
- `start_ai_task_stage`
|
||
- `append_ai_text_chunk_and_return`
|
||
- `complete_ai_stage_and_return`
|
||
- `attach_ai_result_reference_and_return`
|
||
- `complete_ai_task_and_return`
|
||
- `fail_ai_task_and_return`
|
||
- `cancel_ai_task_and_return`
|
||
18. `turn_in_quest` 与 `resolve_combat_action(Victory)` 到 `player_progression / chapter_progression` 的最小经验联动
|
||
|
||
### 2.0.1 `runtime` 域拆分进度
|
||
|
||
截至 `2026-04-23`，`runtime` 域已完成第一轮真实内容拆分，根入口不再保留该域的业务 helper 实现。
|
||
|
||
当前 `src/runtime/` 的实际落位如下：
|
||
|
||
1. `src/runtime/settings.rs`
|
||
- `runtime_setting` 表
|
||
- setting 读取 / upsert procedure 与快照 helper
|
||
2. `src/runtime/snapshots.rs`
|
||
- `runtime_snapshot` 表
|
||
- snapshot 读取 / upsert / delete helper
|
||
3. `src/runtime/browse_history.rs`
|
||
- `user_browse_history` 表
|
||
- 浏览历史 list / upsert / clear procedure 与行转换 helper
|
||
4. `src/runtime/profile.rs`
|
||
- `profile_dashboard_state`
|
||
- `profile_wallet_ledger`
|
||
- `profile_played_world`
|
||
- `profile_save_archive`
|
||
- profile dashboard / ledger / play stats / save archive 投影与同步 helper
|
||
|
||
`src/runtime/mod.rs` 当前只承担聚合职责：
|
||
|
||
1. 声明 `settings / snapshots / browse_history / profile`
|
||
2. 对外统一使用 `pub use xxx::*;` 重新导出
|
||
|
||
后续新增 runtime 相关 table / reducer / procedure / helper 时，必须直接落到上述二级文件，禁止回写到 `src/lib.rs`。
|
||
|
||
### 2.0.2 `ai` 域拆分进度
|
||
|
||
截至 `2026-04-23`，`ai` 域也已完成第一轮真实内容拆分，根入口不再保留 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 的业务实现。
|
||
|
||
当前 `src/ai/` 的实际落位如下：
|
||
|
||
1. `src/ai/tasks.rs`
|
||
- `ai_task` 表
|
||
- task 创建、启动、完成、失败、取消的 reducer / procedure
|
||
- task 状态迁移与持久化 helper
|
||
2. `src/ai/stages.rs`
|
||
- `ai_task_stage`
|
||
- `ai_text_chunk`
|
||
- `ai_result_reference`
|
||
- stage 启动、chunk 追加、stage 完成、result reference 绑定的 procedure / helper
|
||
3. `src/ai/snapshots.rs`
|
||
- AI 任务、阶段、chunk、reference 的 row / snapshot 转换 helper
|
||
|
||
`src/ai/mod.rs` 当前只承担聚合职责：
|
||
|
||
1. 声明 `tasks / stages / snapshots`
|
||
2. 对外统一使用 `pub use xxx::*;`
|
||
3. 对内部共享的 row / snapshot helper 使用 `pub(crate) use snapshots::*;`
|
||
|
||
后续新增 AI 相关 table / reducer / procedure / helper 时，必须直接落到上述二级文件，禁止回写到 `src/lib.rs`。
|
||
|
||
## 2.1 `src/lib.rs` 拆分路由规则
|
||
|
||
从 `2026-04-23` 起，`src/lib.rs` 不再允许继续承载具体业务域的 table / reducer / procedure / tx helper。
|
||
|
||
根入口后续只允许保留：
|
||
|
||
1. `use` 聚合
|
||
2. `mod` 声明
|
||
3. 少量跨域共享 helper
|
||
4. 迁移过渡期测试
|
||
|
||
根入口与子模块的导入导出规则同步冻结为：
|
||
|
||
1. `src/lib.rs` 对外统一优先使用 `pub use xxx::*;` 重新导出模块内容
|
||
2. 已拆业务模块内部统一优先使用 `use crate::*;` 复用主入口已聚合的类型与函数
|
||
3. 只有当 `use crate::*;` 无法覆盖或会引入明显歧义时，才补局部显式 `use`
|
||
4. 新增业务域内容禁止为了堆 `use` 列表再回写到 `src/lib.rs`
|
||
|
||
具体内容必须落到下面的模块：
|
||
|
||
1. `src/entry.rs`
|
||
- SpacetimeDB `init` 入口
|
||
2. `src/domain_types.rs`
|
||
- 跨域共享的 SpacetimeDB 类型
|
||
3. `src/asset_metadata/`
|
||
- 资产对象与资产绑定真相表
|
||
4. `src/big_fish/`
|
||
- Big Fish 创作与运行态
|
||
5. `src/runtime/`
|
||
- runtime setting / snapshot / browse history / profile 投影
|
||
6. `src/gameplay/`
|
||
- `story / combat / inventory / npc / quest / runtime_item / progression`
|
||
7. `src/custom_world/`
|
||
- custom world profile / session / agent / publishing / gallery / works
|
||
8. `src/ai/`
|
||
- ai task / stage / chunk / result reference
|
||
9. `src/puzzle.rs`
|
||
- 拼图玩法当前仍为单文件域模块
|
||
|
||
### 已冻结的二级模块落位点
|
||
|
||
1. `src/asset_metadata/objects.rs`
|
||
2. `src/asset_metadata/bindings.rs`
|
||
3. `src/big_fish/tables.rs`
|
||
4. `src/big_fish/session.rs`
|
||
5. `src/big_fish/assets.rs`
|
||
6. `src/big_fish/runtime.rs`
|
||
7. `src/runtime/settings.rs`
|
||
8. `src/runtime/snapshots.rs`
|
||
9. `src/runtime/browse_history.rs`
|
||
10. `src/runtime/profile.rs`
|
||
11. `src/gameplay/combat.rs`
|
||
12. `src/gameplay/inventory.rs`
|
||
13. `src/gameplay/npc.rs`
|
||
14. `src/gameplay/progression.rs`
|
||
15. `src/gameplay/quest.rs`
|
||
16. `src/gameplay/runtime_item.rs`
|
||
17. `src/gameplay/story.rs`
|
||
18. `src/custom_world/profile.rs`
|
||
19. `src/custom_world/session.rs`
|
||
20. `src/custom_world/agent.rs`
|
||
21. `src/custom_world/publishing.rs`
|
||
22. `src/custom_world/gallery.rs`
|
||
23. `src/custom_world/works.rs`
|
||
24. `src/ai/tasks.rs`
|
||
25. `src/ai/stages.rs`
|
||
26. `src/ai/snapshots.rs`
|
||
|
||
后续如果新增 SpacetimeDB 表、reducer、procedure 或同域 helper，必须先判断属于哪个一级模块与二级落位点，再写入对应文件；禁止直接追加到 `src/lib.rs`。
|
||
|
||
`asset_object` 的详细设计见：
|
||
|
||
1. [../../../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md)
|
||
2. [../../../docs/technical/ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md](../../../docs/technical/ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md)
|
||
|
||
`M5 custom world / agent` 首批表设计见：
|
||
|
||
1. [../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md)
|
||
2. [../../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md](../../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md)
|
||
3. [../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_LIBRARY_GALLERY_STAGE2_DESIGN_2026-04-21.md)
|
||
4. [../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md)
|
||
5. [../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md)
|
||
|
||
`module-ai` 的当前基座设计见：
|
||
|
||
1. [../../../docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md](../../../docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md)
|
||
2. [../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md](../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md)
|
||
3. [../../../docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md](../../../docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md)
|
||
|
||
当前身份透传设计依据：
|
||
|
||
1. [../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)
|
||
|
||
当前本地开发脚本约定：
|
||
|
||
1. `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 当前固定执行 `spacetime start` 的 standalone 模式。
|
||
2. 默认监听 `127.0.0.1:3000`，与 `spacetime` CLI 的 `local` server 默认口径保持一致。
|
||
3. 本地数据目录固定到 `server-rs/.spacetimedb/local`，避免污染全局 SpacetimeDB 根目录。
|
||
4. 当前阶段暂不自动 publish `crates/spacetime-module`，待 module 实体 scaffold 与聚合入口落地后再扩展。
|
||
|
||
## 3. 边界约束
|
||
|
||
1. `spacetime-module` 只聚合状态模型，不直接承接 HTTP、Cookie、Header、OSS、短信、微信、LLM 等外部副作用。
|
||
2. 每个业务模块优先在自己的 `crates/module-*` 中定义状态与规则，再由主工程聚合。
|
||
3. 主工程不重新吞并各模块实现细节，避免回到单大包结构。
|
||
4. `custom_world_asset_link` 仍等待 `M6 assets / OSS` 的对象槽位规则冻结后再补，不在本轮首批表骨架内提前硬落。
|