fix(dev): use local spacetime data dir

.hermes/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md

@@ -1,34 +1,34 @@
 # `npm run dev` / `scripts/dev-rust-stack.sh` 启动修复记录
 
 ## 症状
-- `npm run dev` 在 WSL/Linux 下直接失败：
-  - `It seems like the spacetime version set as current may not exist`
-  - `exec failed for .../.spacetimedb/local/bin/current/spacetimedb-cli`
-- 失败位置通常在 `sync_local_spacetime_install` 后、等待 SpacetimeDB 就绪阶段。
-
-## 根因
-- `server-rs/.spacetimedb/local` 是空 root-dir 时，`spacetime start` 仍会尝试回调 `bin/current/spacetimedb-cli`。
-- 旧脚本只按 Windows/Git Bash 思路同步 `spacetimedb-cli.exe`，WSL/Linux 下没有把用户级安装同步到项目 root-dir。
+- `npm run dev` 的 SpacetimeDB standalone 启动需要把数据留在项目本地，避免污染用户级 SpacetimeDB 数据目录。
+- 早期脚本曾通过把用户级 SpacetimeDB 可执行文件目录同步到 `server-rs/.spacetimedb/local/bin/current` 来满足 standalone 回调需求，但这会把整套可执行文件复制进项目本地目录，维护成本高，也容易和用户级 CLI 版本漂移。
 - `api-server` 首次冷编译时，默认 300 秒超时不够，容易在就绪前被回收。
 
-## 修复要点
-1. 同步本机 SpacetimeDB 安装到项目 root-dir
-   - 从 `spacetime --version` 解析真实 CLI 路径。
-   - 将对应版本目录复制到 `server-rs/.spacetimedb/local/bin/`。
-   - 重新建立 `bin/current` 指向版本目录。
-2. 兼容 WSL/Linux 与 Windows
-   - 不再只判断 `OSTYPE=msys*|cygwin*`。
-   - 同时检查 `spacetimedb-cli` 与 `spacetimedb-cli.exe`。
-3. 提高 api-server 就绪等待时间
-   - `API_SERVER_TIMEOUT_SECONDS` 从 300 提升到 600。
+## 当前方案
+1. SpacetimeDB 可执行文件继续使用用户环境里的 `spacetime` 命令
+   - 启动 standalone 时不再复制 `spacetimedb-cli`、版本目录或 `bin/current`。
+   - `spacetime start` 不再通过工程内 `--root-dir` 寻找可执行文件。
+2. 数据目录显式指定到项目本地
+   - 默认 `SPACETIME_DATA_DIR=${SERVER_RS_DIR}/.spacetimedb/local/data`。
+   - 启动命令使用 `spacetime start --data-dir "${SPACETIME_DATA_DIR}" --non-interactive --listen-addr ...`。
+   - 如需临时切换数据目录，可传 `--spacetime-data-dir <path>`。
+3. CLI 身份/登录状态仍保留在 root-dir
+   - 发布模块和 CLI 管理命令继续使用 `spacetime --root-dir="${SPACETIME_ROOT_DIR}" publish ...`。
+   - 这样可以保留项目级 CLI 登录/token 隔离，同时不再把可执行文件复制到 root-dir。
+4. 提高 api-server 就绪等待时间
+   - `API_SERVER_TIMEOUT_SECONDS` 保持 600，降低首次冷编译误判失败概率。
 
 ## 复现 / 验证
-- 运行 `npm run dev`。
-- 观察日志：
-  - SpacetimeDB 能正常启动到 `Listening on 127.0.0.1:3101`
-  - 模块发布成功
-  - api-server 进入健康检查等待并最终可访问 `/healthz`
+- 运行脚本语法检查：`bash -n scripts/dev-rust-stack.sh`。
+- 运行帮助检查：`bash scripts/dev-rust-stack.sh --help`，确认有 `--spacetime-data-dir`。
+- 运行 `npm run dev` 后观察日志：
+  - 输出 `spacetime data: .../server-rs/.spacetimedb/local/data`。
+  - 不再出现同步/复制本机 SpacetimeDB 安装到项目 root-dir 的日志。
+  - SpacetimeDB 能正常监听 `127.0.0.1:3101`。
+  - 模块发布成功。
+  - api-server 进入健康检查等待并最终可访问 `/healthz`。
 
 ## 相关文件
 - `scripts/dev-rust-stack.sh`
-- `server-rs/.spacetimedb/local/`
+- `server-rs/.spacetimedb/local/data/`