fix(dev): accept spacetime port fallback

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

@@ -1,8 +1,10 @@
 # `npm run dev` / `scripts/dev-rust-stack.sh` 启动修复记录
 
 ## 症状
-- `npm run dev` 的 SpacetimeDB standalone 启动需要把数据留在项目本地，避免污染用户级 SpacetimeDB 数据目录。
+- 多个 worktree 同时本地开发时，SpacetimeDB 数据库名可能相同，早期用项目级 `--root-dir` 隔离 CLI 状态来规避冲突。
+- 实测后确认：真正需要隔离的是 standalone 的 `data-dir`，不需要把 publish 也绑到项目级 root-dir。
 - 早期脚本曾通过把用户级 SpacetimeDB 可执行文件目录同步到 `server-rs/.spacetimedb/local/bin/current` 来满足 standalone 回调需求，但这会把整套可执行文件复制进项目本地目录，维护成本高，也容易和用户级 CLI 版本漂移。
+- 多个 worktree 同时启动时，SpacetimeDB 端口可能冲突；CLI 会询问是否使用最近的可用端口。
 - `api-server` 首次冷编译时，默认 300 秒超时不够，容易在就绪前被回收。
 
 ## 当前方案
@@ -11,12 +13,17 @@
    - `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 start --data-dir "${SPACETIME_DATA_DIR}" --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 就绪等待时间
+3. 端口冲突时自动接受 SpacetimeDB 建议端口
+   - 启动时不传 `--non-interactive`。
+   - 脚本向 `spacetime start` 发送回车，接受“最近可用端口”的默认建议。
+   - 随后从启动日志中的 `Starting SpacetimeDB listening on ...` 解析实际端口。
+   - 解析出的实际端口会覆盖 `SPACETIME_SERVER`，后续 publish、api-server、前端代理统一使用这个端口。
+4. publish 不再使用项目级 root-dir
+   - 发布模块改为 `spacetime publish ... --server "${SPACETIME_SERVER}" ...`。
+   - 这样 publish 使用用户级 CLI 默认身份/配置，不再依赖 worktree 内 root-dir。
+5. 提高 api-server 就绪等待时间
    - `API_SERVER_TIMEOUT_SECONDS` 保持 600，降低首次冷编译误判失败概率。
 
 ## 复现 / 验证
@@ -25,7 +32,8 @@
 - 运行 `npm run dev` 后观察日志：
   - 输出 `spacetime data: .../server-rs/.spacetimedb/local/data`。
   - 不再出现同步/复制本机 SpacetimeDB 安装到项目 root-dir 的日志。
-  - SpacetimeDB 能正常监听 `127.0.0.1:3101`。
+  - SpacetimeDB 能正常监听，并输出 `spacetime actual: http://127.0.0.1:<实际端口>`。
+  - 若默认端口被占用，脚本应自动接受 SpacetimeDB 建议端口，并用实际端口发布模块、启动 api-server 和前端代理。
   - 模块发布成功。
   - api-server 进入健康检查等待并最终可访问 `/healthz`。