kdletters
43b7aa809b
Project CI / AI game creator shell Rust crates (push) Successful in 1m6s
Project CI / AI game creator shell Rust smoke (push) Successful in 1m16s
Project CI / Backend tests (push) Successful in 4m49s
Project CI / AI game creator shell Rust lane 2/2 (push) Successful in 8m1s
Project CI / AI game creator shell Rust lane 1/2 (push) Successful in 8m50s
Project CI / Native shell tests (push) Successful in 6m5s
Project CI / Frontend tests (push) Successful in 2m6s
Project CI / AI game creator shell web tests (push) Successful in 1m19s
Project CI / Repository checks (push) Successful in 1m43s
- 删除一次性 schema guard 退役表白名单、isApprovedRetiredTableDeletion 导出与专属测试，compareTables 收回为内部函数 - 删除 shared-contracts 未挂载的旧玩法契约模块、api-server 旧 story 模块与旧压测资源 scripts/loadtest/ 及对应忽略/排除配置 - 清理 decision-log、pitfalls 中旧表退役、两阶段清表窗口与旧玩法过程记录，保留改写后的通用条目 - 移除权威文档、模块 README 与运维文档中的旧模板、历史表与旧压测叙述 Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/489 Co-authored-by: kdletters <kdletters@qq.com> Co-committed-by: kdletters <kdletters@qq.com>
148 lines
6.9 KiB
Markdown
148 lines
6.9 KiB
Markdown
# spacetime-module 主工程 crate 说明
|
||
|
||
日期：`2026-09-22`
|
||
|
||
## 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. 当前阶段说明
|
||
|
||
当前阶段以 `src/active.rs` 的现役聚合入口为准，已覆盖资产管理、认证、AI 任务、runtime / profile、编辑器工程与精选、外部生成、游戏分发、后台存储和数据库迁移能力。
|
||
|
||
后续与本 crate 直接相关的任务包括：
|
||
|
||
1. 继续扩充模块聚合入口
|
||
2. 保持 table / reducer / view / procedure、迁移白名单和生成 bindings 同步
|
||
3. 接入身份 claims 透传
|
||
4. 在当前 scaffold 基础上接入 publish / dev 循环
|
||
5. 新增业务域时按 `src/active.rs` 的现役声明落位，不得恢复不在现役声明中的业务域目录
|
||
|
||
当前已落地：
|
||
|
||
1. `spacetime-module` 真实 `cdylib` crate scaffold
|
||
2. `asset_object`、`asset_entity_binding` 与资产绑定 procedure
|
||
3. `runtime_setting`、`runtime_snapshot`、`user_browse_history`
|
||
4. `creation_entry_config`、`creation_entry_type_config`、`feature_gate_config`
|
||
5. 账号、身份、refresh session 与认证 procedure
|
||
6. profile / 钱包 / 充值 / 任务 / 邀请码 / 兑换码 / 埋点投影
|
||
7. `ai_task`、`ai_task_stage`、`ai_text_chunk`、`ai_result_reference` 与任务事件
|
||
8. 编辑器工程、画布、资源、素材、精选和编辑器 Agent 会话
|
||
9. 外部生成任务、游戏分发、LLM Router、AGC 模型、外部 API Key、后台与错误报告存储
|
||
10. 数据库导出 / 导入 / 分片导入 / operator 授权等通用迁移 procedure
|
||
|
||
### 2.0.1 `runtime` 域落位
|
||
|
||
`src/runtime.rs` 只承担聚合职责，现役入口如下：
|
||
|
||
1. 现役表定义：`src/runtime/legacy_schema/{settings,snapshots,browse_history}.rs`、`src/legacy_schema/creation_entry_config.rs`
|
||
2. 现役 procedure / helper：`src/runtime/active/{settings,profile}.rs`
|
||
3. 独立配置与投影：`src/runtime/feature_gate_config.rs`、`src/runtime/analytics_date_dimension.rs`
|
||
|
||
后续新增 runtime 相关 table / reducer / procedure / helper 时，必须直接落到对应二级文件，禁止回写到 `src/active.rs`；不得把未登记的根文件重新加入 `runtime.rs`。
|
||
|
||
### 2.0.2 `ai` 域拆分进度
|
||
|
||
截至 `2026-04-23`，`ai` 域也已完成第一轮真实内容拆分，根入口不再保留 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference / ai_task_event` 的业务实现。
|
||
|
||
当前 `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.rs` 当前只承担聚合职责：
|
||
|
||
1. 声明 `tasks / stages / snapshots / events`
|
||
2. 对外统一使用 `pub use xxx::*;`
|
||
3. 对内部共享的 row / snapshot helper 使用 `pub(crate) use snapshots::*;`
|
||
|
||
后续新增 AI 相关 table / reducer / procedure / helper 时，必须直接落到上述二级文件，禁止回写到 `src/active.rs`。
|
||
|
||
## 2.1 `src/active.rs` 聚合路由规则
|
||
|
||
从 `2026-04-23` 起，`src/active.rs` 不再承载具体业务域的 table / reducer / procedure / tx helper。
|
||
|
||
根入口只允许保留：
|
||
|
||
1. `use` 聚合
|
||
2. `mod` 声明
|
||
3. 少量跨域共享 helper
|
||
4. 迁移过渡期测试
|
||
|
||
根入口与子模块的导入导出规则同步冻结为：
|
||
|
||
1. `src/active.rs` 对外统一优先使用 `pub use xxx::*;` 重新导出模块内容
|
||
2. 已拆业务模块内部统一优先使用 `use crate::*;` 复用主入口已聚合的类型与函数
|
||
3. 只有 `use crate::*;` 无法覆盖或会引入明显歧义时，才补局部显式 `use`
|
||
4. 新增业务域内容禁止为了堆 `use` 列表再回写到 `src/active.rs`
|
||
|
||
当前业务内容按以下入口落位：
|
||
|
||
1. `src/asset_metadata/`
|
||
- 资产对象与资产绑定真相表
|
||
2. `src/auth/`
|
||
- 登录身份、账号、refresh session 和认证 procedure
|
||
3. `src/ai/`
|
||
- AI task / stage / chunk / result reference / event
|
||
4. `src/runtime/`
|
||
- runtime setting / snapshot / browse history / profile / 入口配置 / 功能灰度 / 日期维度
|
||
5. `src/editor_project_storage.rs`
|
||
- 编辑器工程、画布、资源、素材、精选和生成幂等
|
||
6. `src/editor_agent_storage.rs`
|
||
- 编辑器 Agent 会话存储
|
||
7. 其它单一领域存储入口
|
||
- `admin_account_storage.rs`、`admin_dashboard.rs`、`agc_models.rs`、`error_report.rs`、`external_api_key_storage.rs`、`external_generation.rs`、`game_distribution.rs`、`llm_router_account.rs`、`migration.rs`
|
||
|
||
### 已冻结的二级模块落位点
|
||
|
||
1. `src/asset_metadata/objects.rs`
|
||
2. `src/asset_metadata/bindings.rs`
|
||
3. `src/auth/tables.rs`
|
||
4. `src/auth/procedures.rs`
|
||
5. `src/ai/tasks.rs`
|
||
6. `src/ai/stages.rs`
|
||
7. `src/ai/snapshots.rs`
|
||
8. `src/ai/events.rs`
|
||
9. `src/runtime/active/settings.rs`
|
||
10. `src/runtime/active/profile.rs`
|
||
11. `src/runtime/legacy_schema/settings.rs`
|
||
12. `src/runtime/legacy_schema/snapshots.rs`
|
||
13. `src/runtime/legacy_schema/browse_history.rs`
|
||
14. `src/legacy_schema/creation_entry_config.rs`
|
||
15. `src/runtime/feature_gate_config.rs`
|
||
16. `src/runtime/analytics_date_dimension.rs`
|
||
|
||
后续如果新增 SpacetimeDB 表、reducer、procedure 或同域 helper，必须先判断属于哪个一级模块与二级落位点，再写入对应文件；禁止直接追加到 `src/active.rs`，也不得恢复不在现役声明中的业务域目录。
|
||
|
||
## 当前文档入口
|
||
|
||
当前长期工程口径已融合到：
|
||
|
||
1. [../../../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md](../../../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
|
||
2. [../../../docs/【玩法创作】平台入口与玩法链路-2026-05-15.md](../../../docs/【玩法创作】平台入口与玩法链路-2026-05-15.md)
|
||
3. [../../../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md](../../../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md)
|
||
|
||
旧阶段设计文档不再作为实现依据。
|
||
|
||
## 3. 边界约束
|
||
|
||
1. `spacetime-module` 只聚合状态模型，不直接承接 HTTP、Cookie、Header、OSS、短信、微信、LLM 等外部副作用。
|
||
2. 每个业务模块优先在自己的 `crates/module-*` 中定义状态与规则，再由主工程聚合。
|
||
3. 主工程不重新吞并各模块实现细节，避免回到单大包结构。
|
||
4. 新增跨域状态必须先在对应 `module-*` 定义领域规则，再由 `spacetime-module` 聚合；不得从未挂载源码复制未登记模块。
|