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

spacetime-client 共享 package 占位说明

日期：2026-04-20

1. package 职责

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

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

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 可能因为路径参数总长触发 文件名或扩展名太长；仓库脚本会先输出到短临时目录，再同步回本目录。

3. 边界约束

1. spacetime-client 只承接 SpacetimeDB 客户端访问适配，不承接具体业务模块的规则实现。
2. 业务状态真相仍由 apps/spacetime-module 管理，业务编排由各模块 package 与 apps/api-server 承担。
3. 不允许把 reducer、view、订阅调用细节重新散落到多个业务模块里各自实现。