build: add spacetime local dev scripts

2026-04-21 01:58:46 +08:00
parent c9850c8caf
commit a1a02eee7d
7 changed files with 138 additions and 6 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ temp*build*/
 /server-node/data/*
 !/server-node/data/.gitkeep
 /server-rs/target/
+/server-rs/.spacetimedb/
 /public/generated-animations
 /public/generated-character-drafts
 /public/generated-characters
--- a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md
+++ b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md
@@ -123,7 +123,8 @@
  交付物：[../server-rs/scripts/check.ps1](../server-rs/scripts/check.ps1)、[../server-rs/scripts/check.sh](../server-rs/scripts/check.sh)
 - [x] 新增 smoke 脚本
  交付物：[../server-rs/scripts/smoke.ps1](../server-rs/scripts/smoke.ps1)、[../server-rs/scripts/smoke.sh](../server-rs/scripts/smoke.sh)
- [ ] 新增 SpacetimeDB 本地开发脚本
+- [x] 新增 SpacetimeDB 本地开发脚本
+  交付物：[../server-rs/scripts/spacetime-dev.ps1](../server-rs/scripts/spacetime-dev.ps1)、[../server-rs/scripts/spacetime-dev.sh](../server-rs/scripts/spacetime-dev.sh)

 ### 阶段验收

--- a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md
+++ b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md
@@ -244,7 +244,7 @@ server-rs/
 └─ scripts/
   ├─ dev.sh / dev.ps1
   ├─ check.sh / check.ps1
-   ├─ spacetime-publish.sh
+   ├─ spacetime-dev.sh / spacetime-dev.ps1
   └─ smoke.sh / smoke.ps1
 ```

--- a/server-rs/README.md
+++ b/server-rs/README.md
@@ -14,7 +14,7 @@

 ## 2. 当前阶段说明

-当前目录已经完成以下三十二项初始化：
+当前目录已经完成以下三十四项初始化：

 1. 为新后端预留正式目录并把路径固定到仓库结构中。
 2. 创建虚拟 workspace `Cargo.toml`，后续 package 会逐项挂入。
@@ -48,10 +48,13 @@
 30. 创建 `scripts/check.sh`，固定 Unix-like 本地统一检查入口。
 31. 创建 `scripts/smoke.ps1`，固定 Windows 本地冒烟验证入口。
 32. 创建 `scripts/smoke.sh`，固定 Unix-like 本地冒烟验证入口。
+33. 创建 `scripts/spacetime-dev.ps1`，固定 Windows 本地 SpacetimeDB 启动入口。
+34. 创建 `scripts/spacetime-dev.sh`，固定 Unix-like 本地 SpacetimeDB 启动入口。

 后续任务会继续在本目录内按顺序补齐：

-1. SpacetimeDB 本地开发脚本
+1. `apps/spacetime-module` 的表、reducer、view 聚合入口
+2. `module-auth` 的身份表、JWT 与 refresh cookie 主链

 ## 3. 已冻结边界

--- a/server-rs/apps/spacetime-module/README.md
+++ b/server-rs/apps/spacetime-module/README.md
@@ -10,17 +10,25 @@
 2. 聚合各独立模块 package 的 reducer
 3. 聚合各独立模块 package 的 view / 读模型
 4. 生成可发布的 SpacetimeDB wasm 模块
+5. 由 `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 驱动的本地 standalone 启动链路

 ## 2. 当前阶段说明

-当前提交仅完成目录占位，不提前进入具体 schema 与 reducer 实现。
+当前阶段仍未进入具体 schema 与 reducer 实现，但已经补齐本地 standalone 启动脚本，先把 SpacetimeDB 进程入口固定下来。

 后续与本 package 直接相关的任务包括：

 1. 建立模块聚合入口
 2. 设计表、reducer、view 的聚合方式
 3. 接入身份 claims 透传
-4. 接入本地开发与发布脚本
+4. 在实体 module scaffold 落地后接入 publish / dev 循环
+
+当前本地开发脚本约定：
+
+1. `../../scripts/spacetime-dev.ps1` 与 `../../scripts/spacetime-dev.sh` 当前固定执行 `spacetime start` 的 standalone 模式。
+2. 默认监听 `127.0.0.1:3001`，避免与 `api-server` 默认 `3000` 端口冲突。
+3. 本地数据目录固定到 `server-rs/.spacetimedb/local`，避免污染全局 SpacetimeDB 根目录。
+4. 当前阶段暂不自动 publish `apps/spacetime-module`，待 module 实体 scaffold 与聚合入口落地后再扩展。

 ## 3. 边界约束

--- a/server-rs/scripts/spacetime-dev.ps1
+++ b/server-rs/scripts/spacetime-dev.ps1
@@ -0,0 +1,67 @@
+[CmdletBinding()]
+param(
+    [Alias("h")]
+    [switch]$Help,
+    [string]$ListenHost = "127.0.0.1",
+    [int]$Port = 3001,
+    [string]$RootDir = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Usage {
+    @(
+        'Usage:'
+        '  ./server-rs/scripts/spacetime-dev.ps1'
+        '  ./server-rs/scripts/spacetime-dev.ps1 -ListenHost 127.0.0.1 -Port 3101'
+        ''
+        'Notes:'
+        '  1. Start local standalone SpacetimeDB for the Genarrative Rust backend'
+        '  2. Store local SpacetimeDB state in server-rs/.spacetimedb/local by default'
+        '  3. Current stage only boots the standalone server and does not publish a module yet'
+    ) -join [Environment]::NewLine
+}
+
+if ($Help) {
+    Write-Usage
+    exit 0
+}
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$serverRsDir = Split-Path -Parent $scriptDir
+
+if ([string]::IsNullOrWhiteSpace($RootDir)) {
+    $RootDir = Join-Path $serverRsDir ".spacetimedb\local"
+}
+
+if (-not (Test-Path (Join-Path $serverRsDir "apps\spacetime-module\README.md"))) {
+    throw "Missing server-rs/apps/spacetime-module/README.md, cannot start SpacetimeDB local dev script."
+}
+
+$spacetimeCommand = Get-Command spacetime -ErrorAction SilentlyContinue
+
+if ($null -eq $spacetimeCommand) {
+    throw @(
+        "Missing 'spacetime' CLI.",
+        "Install guide: https://spacetimedb.com/install",
+        "Windows PowerShell: iwr https://windows.spacetimedb.com -useb | iex"
+    ) -join " "
+}
+
+New-Item -ItemType Directory -Force -Path $RootDir | Out-Null
+
+$listenAddress = "$ListenHost`:$Port"
+
+Write-Host "[server-rs:spacetime-dev] working dir: $serverRsDir"
+Write-Host "[server-rs:spacetime-dev] root dir: $RootDir"
+Write-Host "[server-rs:spacetime-dev] listen addr: $listenAddress"
+Write-Host "[server-rs:spacetime-dev] mode: standalone"
+Write-Host "[server-rs:spacetime-dev] note: module publish is deferred until apps/spacetime-module scaffold lands"
+
+Push-Location $serverRsDir
+try {
+    & $spacetimeCommand.Source --root-dir $RootDir start --edition standalone --listen-addr $listenAddress
+}
+finally {
+    Pop-Location
+}
--- a/server-rs/scripts/spacetime-dev.sh
+++ b/server-rs/scripts/spacetime-dev.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# 当前阶段只负责启动本地 standalone SpacetimeDB，先把服务器进程和数据目录口径固定下来，不提前耦合 publish 流程。
+
+usage() {
+  cat <<'EOF'
+用法:
+  ./server-rs/scripts/spacetime-dev.sh
+  GENARRATIVE_SPACETIME_PORT=3101 ./server-rs/scripts/spacetime-dev.sh
+
+说明:
+  1. 启动 Genarrative Rust 后端使用的本地 standalone SpacetimeDB
+  2. 默认把本地数据目录放到 `server-rs/.spacetimedb/local`
+  3. 当前阶段只负责启动 standalone server，暂不自动 publish `apps/spacetime-module`
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+SERVER_RS_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
+LISTEN_HOST="${GENARRATIVE_SPACETIME_HOST:-127.0.0.1}"
+PORT="${GENARRATIVE_SPACETIME_PORT:-3001}"
+ROOT_DIR="${GENARRATIVE_SPACETIME_ROOT_DIR:-${SERVER_RS_DIR}/.spacetimedb/local}"
+
+if [[ ! -f "${SERVER_RS_DIR}/apps/spacetime-module/README.md" ]]; then
+  echo "[server-rs:spacetime-dev] 未找到 apps/spacetime-module/README.md，无法启动本地 SpacetimeDB 脚本。" >&2
+  exit 1
+fi
+
+if ! command -v spacetime >/dev/null 2>&1; then
+  echo "[server-rs:spacetime-dev] 缺少 spacetime CLI。" >&2
+  echo "[server-rs:spacetime-dev] 安装文档: https://spacetimedb.com/install" >&2
+  echo "[server-rs:spacetime-dev] Linux/macOS 安装命令: curl -sSf https://install.spacetimedb.com | sh" >&2
+  exit 1
+fi
+
+mkdir -p "${ROOT_DIR}"
+
+echo "[server-rs:spacetime-dev] 工作目录: ${SERVER_RS_DIR}"
+echo "[server-rs:spacetime-dev] 数据目录: ${ROOT_DIR}"
+echo "[server-rs:spacetime-dev] 监听地址: ${LISTEN_HOST}:${PORT}"
+echo "[server-rs:spacetime-dev] 模式: standalone"
+echo "[server-rs:spacetime-dev] 说明: 当前阶段暂不自动 publish apps/spacetime-module"
+
+cd "${SERVER_RS_DIR}"
+spacetime --root-dir "${ROOT_DIR}" start --edition standalone --listen-addr "${LISTEN_HOST}:${PORT}"