Close DDD refactor and remove generated asset proxy
This commit is contained in:
kdletters
@@ -1,6 +1,6 @@
|
||||
# spacetime-client 共享 package 说明
|
||||
|
||||
日期：`2026-04-20`
|
||||
日期：`2026-05-01`
|
||||
|
||||
## 1. package 职责
|
||||
|
||||
@@ -19,24 +19,26 @@
|
||||
|
||||
本轮方案见 [`SERVER_RS_DDD_WP_SC_SPACETIME_CLIENT_REFACTOR_2026-04-29.md`](../../../docs/technical/SERVER_RS_DDD_WP_SC_SPACETIME_CLIENT_REFACTOR_2026-04-29.md)。
|
||||
|
||||
## 2. 当前阶段说明
|
||||
## 2. 当前完成口径
|
||||
|
||||
当前目录已不再只是占位，当前阶段已经落下：
|
||||
当前目录已不再只是占位。`WP-SC Spacetime Client` 在当前稳定 SpacetimeDB facade 范围内已经完成收尾：
|
||||
|
||||
1. 通过 `npm run spacetime:generate -- --rust-only` 生成的公开 Rust bindings
|
||||
2. `DbConnection` 连接封装
|
||||
3. `confirm_asset_object_and_return` procedure 的最小调用适配
|
||||
4. `bind_asset_object_to_entity_and_return` procedure 的最小调用适配
|
||||
5. `api-server` 所需的 `asset_object` 确认与 `asset_entity_binding` 绑定返回值转换
|
||||
1. 通过 `npm run spacetime:generate -- --rust-only` 生成并纳管公开 Rust bindings。
|
||||
2. `DbConnection` 连接池、握手等待、超时和断线清理已封装在 `SpacetimeClient` 内部。
|
||||
3. 已稳定的 assets、auth、AI task、Big Fish、Custom World、Puzzle、Runtime/Profile/Save、Story session、combat、inventory、NPC facade 均通过 typed 方法对外暴露。
|
||||
4. 生成绑定到 BFF record / module record 的 row snapshot mapper 已集中在 `mapper.rs`。
|
||||
5. SDK 调用错误、reducer 业务错误、procedure 业务错误、缺快照错误和本地输入校验错误已统一收口到 `SpacetimeClientError` helper。
|
||||
6. Story runtime projection source 已复用 runtime inventory typed facade，读取投影不再只依赖 runtime snapshot 中的历史背包 JSON 副本。
|
||||
|
||||
`confirm_asset_object_and_return` 与 `bind_asset_object_to_entity_and_return` 的调用必须等到 SDK `on_connect` 回调后再发起。`DbConnection::build()` 只代表 WebSocket 已经初始化，不代表 SpacetimeDB 身份握手完成；如果过早调用 procedure，本地联调会表现为连接建立但请求长期没有回调，最终等到 idle timeout。
|
||||
|
||||
后续与本 package 直接相关的任务包括：
|
||||
后续新增工作只随 `WP-ST` 新 table / reducer / procedure 或 row shape 稳定后按领域增量接入，不再把整个 `WP-SC` 包保持为进行中状态。新增 facade 时必须继续满足：
|
||||
|
||||
1. 固化 bindings 生成与更新脚本
|
||||
2. 设计 reducer、procedure、view、订阅的统一调用接口
|
||||
3. 设计身份透传与连接配置策略
|
||||
4. 设计 Axum / worker / 测试环境下的客户端复用方式
|
||||
1. 不手写 `module_bindings` 生成物。
|
||||
2. 不在 `spacetime-client` 内新增领域规则。
|
||||
3. procedure / reducer shape 稳定后再接 typed facade。
|
||||
4. 错误映射继续使用 `SpacetimeClientError` helper。
|
||||
5. mapper 测试或 facade 定向测试随新增场景补齐。
|
||||
|
||||
## 2.1 `module_bindings` 生成物约束
|
||||
|
||||
@@ -44,19 +46,19 @@
|
||||
|
||||
1. 只允许通过仓库根目录 `npm run spacetime:generate -- --rust-only` 刷新，不允许手工修改。
|
||||
2. 不生成私有表绑定，不追加 `--include-private`；如后端需要读取私有表，应先在 `api-server` 或模块层补明确 contract，而不是让客户端 crate 直接依赖私有表结构。
|
||||
3. 不允许对该目录额外执行 `rustfmt`，生成物格式只接受 SpacetimeDB CLI 生成阶段自身输出。
|
||||
3. 不允许手工对该目录执行散装 `rustfmt`；若 SpacetimeDB CLI 已生成文件但自身 formatter 在 Windows 下失败，只能由 `scripts/generate-spacetime-bindings.mjs` 在短临时目录中分批 `rustfmt` 后同步。
|
||||
4. `src/lib.rs` 已通过 `#[rustfmt::skip] pub mod module_bindings;` 显式阻止 workspace 级 `cargo fmt` 继续递归格式化该目录。
|
||||
5. Windows 下直接把 Rust bindings 输出到本目录时，SpacetimeDB CLI `2.1.0` 的生成后 formatter 可能因为路径参数总长触发 `文件名或扩展名太长`；仓库脚本会先输出到短临时目录，再同步回本目录。
|
||||
5. Windows 下 SpacetimeDB CLI `2.1.0` 的生成后 formatter 可能因为一次性传入过多 Rust 文件路径而失败；仓库脚本会先输出到短临时目录，必要时接管分批格式化，再同步回本目录。
|
||||
|
||||
### 2.1.1 绑定缺文件恢复流程
|
||||
|
||||
若 `mod.rs` 已声明 `*_table` 模块，但目录内缺少对应 `*_table.rs` 文件，说明 Rust bindings 刷新不完整。不要手工补 generated code，统一在仓库根目录执行：
|
||||
|
||||
```powershell
|
||||
spacetime generate --no-config --lang rust --include-private --out-dir .\server-rs\crates\spacetime-client\src\module_bindings --module-path .\server-rs\crates\spacetime-module --yes
|
||||
npm.cmd run spacetime:generate -- --rust-only
|
||||
```
|
||||
|
||||
这里必须带 `--no-config`：仓库根目录的 `spacetime.json` 同时配置了 TypeScript 与 Rust 两个生成目标，直接追加 `--lang` / `--out-dir` 会触发 SpacetimeDB CLI 的多目标参数冲突。
|
||||
脚本内部会使用 `--no-config`：仓库根目录的 `spacetime.json` 同时配置了 TypeScript 与 Rust 两个生成目标，直接追加 `--lang` / `--out-dir` 会触发 SpacetimeDB CLI 的多目标参数冲突。
|
||||
|
||||
生成后用以下命令确认 `mod.rs` 声明的模块都有落盘文件：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user