Genarrative/server-rs/crates/spacetime-module/README.md

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 的最小经验联动

asset_object 的详细设计见：

1. ../../../docs/technical/SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md
2. ../../../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
2. ../../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md
3. ../../../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
5. ../../../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
2. ../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md
3. ../../../docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md

当前身份透传设计依据：

1. ../../../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 的对象槽位规则冻结后再补，不在本轮首批表骨架内提前硬落。