1

docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md

@@ -17,7 +17,8 @@
 5. 需要关闭 default features 的依赖，应优先在 workspace 根依赖中声明；成员 crate 不再重复覆盖同一项。
 6. `module-assets` 这类有默认服务端 feature 的领域 crate，在 workspace 根内按 `default-features = false` 维护；需要服务端 OSS/HTTP 能力的 adapter crate 显式启用 `features = ["server-service"]`。
 7. `shared-contracts` 只能承载前后端公开 DTO 和轻量枚举，禁止直接依赖 `platform-*` 服务实现 crate；需要把平台实现响应转换为公开 DTO 时，转换函数放在 `api-server` 等 adapter 层。
-8. `spacetime-module` 的传递依赖不能包含 `reqwest`、`web-sys`、`js-sys`、`wasm-bindgen` 等 Web/HTTP 客户端链路；发布前可用 `cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown` 排查。
+8. 面向 SpacetimeDB WASM 的依赖链不得隐式启用原生 HTTP / OSS / Web 平台依赖；例如 `shared-contracts` 的 `assets` 模块通过不依赖 `platform-oss` 的 `oss-contracts` feature 暴露给 `api-server`，`spacetime-module` 路径只消费关闭默认 feature 后的纯 DTO 子集。
+9. `spacetime-module` 的传递依赖不能包含 `reqwest`、`web-sys`、`js-sys`、`wasm-bindgen` 等 Web/HTTP 客户端链路；发布前可用 `cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown` 排查。
 
 ## 3. 本次收敛范围
 
@@ -56,7 +57,7 @@ npm.cmd run check:encoding -- docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDA
 
 若仅改 Cargo 依赖配置且未触碰 API smoke 相关代码，不强制启动 `npm run api-server`；若后续改动同时涉及 API 路由、SpacetimeDB facade 或运行时行为，仍按 `AGENTS.md` 和 DDD 文档执行后端 smoke。
 
-## 6. SpacetimeDB 模块依赖边界补充
+## 6. SpacetimeDB WASM 依赖边界
 
 2026-05-11 本地重置 SpacetimeDB 并重新发布 `xushi-p4wfr` 时，`spacetime publish` 在 Rust 编译成功后报 `wasm-bindgen detected`。排查命令显示链路为：
 
@@ -66,6 +67,8 @@ spacetime-module -> module-runtime -> shared-contracts -> platform-oss -> reqwes
 
 根因是 `shared-contracts` 为了复用 OSS 直传/读签名返回类型，直接依赖了 `platform-oss`。这违反 DDD 分层边界：契约 crate 不能依赖平台副作用实现，否则所有引用契约的纯领域和 SpacetimeDB 模块都会被迫拉入 HTTP client。
 
+`spacetime publish` 会构建 `spacetime-module` 的 `wasm32-unknown-unknown` 目标。这个目标不能包含 `wasm-bindgen`，也不应通过 DTO crate 间接拉入 `reqwest`、`web-sys` 或浏览器 WebAssembly 平台依赖。
+
 修正口径：
 
 1. `shared-contracts::assets` 定义独立的公开 DTO 和 `DirectUploadObjectAccess` 轻量枚举。
@@ -73,11 +76,16 @@ spacetime-module -> module-runtime -> shared-contracts -> platform-oss -> reqwes
 3. `api-server::assets` 负责把 `platform_oss::OssPostObjectResponse` / `OssSignedGetObjectUrlResponse` 转成 `shared-contracts` DTO。
 4. 后续新增外部平台能力时，重复使用这个边界：平台 crate 不得被 `shared-contracts`、`module-*` 或 `spacetime-module` 反向依赖。
 
-最小验证：
+已验证的排查命令：
 
 ```powershell
 cargo tree -i wasm-bindgen --manifest-path server-rs\Cargo.toml -p spacetime-module --target wasm32-unknown-unknown
+cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown
+cargo tree --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown | Select-String -Pattern 'wasm-bindgen|platform-oss|reqwest'
+cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown
 cargo check -p shared-contracts --manifest-path server-rs\Cargo.toml
 cargo check -p api-server --manifest-path server-rs\Cargo.toml
 spacetime publish xushi-p4wfr --server local --module-path server-rs\crates\spacetime-module --build-options="--debug" -c=on-conflict --yes
 ```
+
+若反向树显示 `reqwest -> platform-oss -> shared-contracts -> module-* -> spacetime-module`，优先检查新增的 `shared-contracts` 或领域 crate 依赖是否忘记关闭默认 feature，或 `shared-contracts` feature 是否错误依赖了平台实现 crate。原生 `api-server` 需要资产上传契约时，应在自身 `Cargo.toml` 显式启用 `shared-contracts` 的 `oss-contracts` feature，而不是让 workspace 根依赖默认启用。