GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
3b0dd2ebeb0b0e82832e3b2f02f7b9f563e4c2c1
Genarrative/server-rs/crates/spacetime-module
History
kdletters df80876f60
Some checks failed
CI / verify (push) Has been cancelled
Details
Consolidate workspace deps and migrate sha1 to sha2
2026-05-07 21:11:14 +08:00
..
src
Consolidate workspace deps and migrate sha1 to sha2
2026-05-07 21:11:14 +08:00
Cargo.toml
Consolidate workspace deps and migrate sha1 to sha2
2026-05-07 21:11:14 +08:00
README.md
init with react+axum+spacetimedb
2026-04-26 18:06:23 +08:00

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
  1. 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
  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 的对象槽位规则冻结后再补，不在本轮首批表骨架内提前硬落。
Reference in New Issue View Git Blame Copy Permalink