fix: align rust workspace build scope

docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md

@@ -0,0 +1,39 @@
+# Rust Workspace 默认构建范围修复（2026-04-25）
+
+## 背景
+
+`server-rs` 同时包含原生运行的 `api-server` 与只应由 SpacetimeDB CLI 按 wasm 模块方式构建的 `spacetime-module`。
+
+直接在 `server-rs` 下执行无参数 `cargo build` 时，Cargo 会尝试构建 workspace 的全部成员，其中 `spacetime-module` 是 `cdylib`，并依赖 `spacetimedb` 模块运行时导入函数。该 crate 不能作为 Windows 原生 DLL 链接，链接阶段会报 `LNK2019 unresolved external symbol`，例如 `datastore_insert_bsatn`、`console_log`、`table_id_from_name`。
+
+## 决策
+
+1. `cargo build` 默认只构建原生服务入口 `api-server`。
+2. `spacetime-module` 保留为 workspace member，便于 `cargo check --workspace --all-targets` 做类型检查。
+3. `spacetime-module` 的可发布产物必须继续通过 SpacetimeDB CLI 构建，不走无参数 `cargo build` 的原生链接路径。
+
+## 落地
+
+在 `server-rs/Cargo.toml` 增加：
+
+```toml
+[workspace]
+default-members = [
+    "crates/api-server",
+]
+```
+
+## 验证命令
+
+```powershell
+cd D:\Genarrative\server-rs
+cargo build
+cargo check --workspace --all-targets
+spacetime build --module-path crates/spacetime-module
+```
+
+## 后续约束
+
+- 日常本地编译原生后端用 `cargo build` 或 `cargo build -p api-server`。
+- 验证全部 Rust 目标用 `cargo check --workspace --all-targets`。
+- 构建 / 发布 SpacetimeDB 模块用 `spacetime build --module-path crates/spacetime-module` 或发布脚本，不要用原生 `cargo build -p spacetime-module`。