# spacetime-client 共享 package 说明

日期：`2026-04-20`

## 1. package 职责

`spacetime-client` 是 SpacetimeDB 客户端适配 package，后续负责：

1. 生成 bindings 后的客户端访问封装
2. Axum 与各模块对 reducer、view、订阅的调用适配
3. 身份透传、连接配置与基础错误处理适配

在 DDD 重构中，本 package 只承接 `WP-SC Spacetime Client`：

1. 把 SpacetimeDB 生成绑定转换成 `api-server` 可消费的 typed facade。
2. 把 row snapshot / procedure result 转换成 BFF record。
3. 统一 SDK 调用错误、业务 procedure 错误、缺失快照错误和超时错误。
4. 不承载领域规则，不直接定义 table / reducer / procedure，不替代 `spacetime-module`。

本轮方案见 [`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. 当前阶段说明

当前目录已不再只是占位，当前阶段已经落下：

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` 绑定返回值转换

`confirm_asset_object_and_return` 与 `bind_asset_object_to_entity_and_return` 的调用必须等到 SDK `on_connect` 回调后再发起。`DbConnection::build()` 只代表 WebSocket 已经初始化，不代表 SpacetimeDB 身份握手完成；如果过早调用 procedure，本地联调会表现为连接建立但请求长期没有回调，最终等到 idle timeout。

后续与本 package 直接相关的任务包括：

1. 固化 bindings 生成与更新脚本
2. 设计 reducer、procedure、view、订阅的统一调用接口
3. 设计身份透传与连接配置策略
4. 设计 Axum / worker / 测试环境下的客户端复用方式

## 2.1 `module_bindings` 生成物约束

`src/module_bindings` 目录下的 Rust 文件统一视为 SpacetimeDB CLI 生成产物，后续维护必须遵守：

1. 只允许通过仓库根目录 `npm run spacetime:generate -- --rust-only` 刷新，不允许手工修改。
2. 不生成私有表绑定，不追加 `--include-private`；如后端需要读取私有表，应先在 `api-server` 或模块层补明确 contract，而不是让客户端 crate 直接依赖私有表结构。
3. 不允许对该目录额外执行 `rustfmt`，生成物格式只接受 SpacetimeDB CLI 生成阶段自身输出。
4. `src/lib.rs` 已通过 `#[rustfmt::skip] pub mod module_bindings;` 显式阻止 workspace 级 `cargo fmt` 继续递归格式化该目录。
5. Windows 下直接把 Rust bindings 输出到本目录时，SpacetimeDB CLI `2.1.0` 的生成后 formatter 可能因为路径参数总长触发 `文件名或扩展名太长`；仓库脚本会先输出到短临时目录，再同步回本目录。

### 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
```

这里必须带 `--no-config`：仓库根目录的 `spacetime.json` 同时配置了 TypeScript 与 Rust 两个生成目标，直接追加 `--lang` / `--out-dir` 会触发 SpacetimeDB CLI 的多目标参数冲突。

生成后用以下命令确认 `mod.rs` 声明的模块都有落盘文件：

```powershell
$modFile = 'server-rs\crates\spacetime-client\src\module_bindings\mod.rs'
$dir = 'server-rs\crates\spacetime-client\src\module_bindings'
$mods = Select-String -Path $modFile -Pattern '^pub mod ([a-zA-Z0-9_]+);' |
  ForEach-Object { $_.Matches[0].Groups[1].Value }
$missing = @()
foreach ($m in $mods) {
  if (-not (Test-Path (Join-Path $dir ($m + '.rs')))) {
    $missing += $m
  }
}
if ($missing.Count -eq 0) { 'missing module files: 0' } else { $missing }
```

最后至少执行：

```powershell
cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml
```

## 3. 边界约束

1. `spacetime-client` 只承接 SpacetimeDB 客户端访问适配，不承接具体业务模块的规则实现。
2. 业务状态真相仍由 `apps/spacetime-module` 管理，业务编排由各模块 package 与 `apps/api-server` 承担。
3. 不允许把 reducer、view、订阅调用细节重新散落到多个业务模块里各自实现。
4. 新增 facade 必须等待对应 `spacetime-module` facade 稳定后再接，不提前假设 row shape。
5. `src/module_bindings/**` 是生成产物，只能通过 SpacetimeDB CLI 生成流程刷新。