From 440d60d56317bf1ea3d9fd12675dc4a9d3c7717c Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Tue, 21 Apr 2026 01:41:31 +0800
Subject: [PATCH] build: add server-rs local dev scripts

---
 .../01_M0_M2_FOUNDATION_AND_AUTH.md           |  3 +-
 server-rs/README.md                           |  6 ++-
 server-rs/apps/api-server/README.md           |  1 +
 server-rs/scripts/dev.ps1                     | 52 +++++++++++++++++++
 server-rs/scripts/dev.sh                      | 41 +++++++++++++++
 5 files changed, 100 insertions(+), 3 deletions(-)
 create mode 100644 server-rs/scripts/dev.ps1
 create mode 100644 server-rs/scripts/dev.sh

diff --git a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md
index 8a5de406..1db85ee0 100644
--- a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md
+++ b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md
@@ -115,7 +115,8 @@
 
 ### 基础工程脚本
 
-- [ ] 新增本地开发脚本
+- [x] 新增本地开发脚本
+  交付物：[../server-rs/scripts/dev.ps1](../server-rs/scripts/dev.ps1)、[../server-rs/scripts/dev.sh](../server-rs/scripts/dev.sh)
 - [ ] 新增测试脚本
 - [ ] 新增 lint / fmt / clippy / check 脚本
 - [ ] 新增 smoke 脚本
diff --git a/server-rs/README.md b/server-rs/README.md
index 26ba5c8c..0ad76926 100644
--- a/server-rs/README.md
+++ b/server-rs/README.md
@@ -14,7 +14,7 @@
 
 ## 2. 当前阶段说明
 
-当前目录已经完成以下二十四项初始化：
+当前目录已经完成以下二十六项初始化：
 
 1. 为新后端预留正式目录并把路径固定到仓库结构中。
 2. 创建虚拟 workspace `Cargo.toml`，后续 package 会逐项挂入。
@@ -40,10 +40,12 @@
 22. 创建 `packages/platform-llm/` 目录占位，固定大模型平台适配 package 落位。
 23. 创建 `packages/spacetime-client/` 目录占位，固定 SpacetimeDB 客户端适配 package 落位。
 24. 创建 `packages/tests-support/` 目录占位，固定测试支撑共享 package 落位。
+25. 创建 `scripts/dev.ps1`，固定 Windows 本地开发入口。
+26. 创建 `scripts/dev.sh`，固定 Unix-like 本地开发入口。
 
 后续任务会继续在本目录内按顺序补齐：
 
-1. `scripts/*`
+1. 测试、lint、smoke 与 SpacetimeDB 本地脚本
 
 ## 3. 已冻结边界
 
diff --git a/server-rs/apps/api-server/README.md b/server-rs/apps/api-server/README.md
index d5ab79d6..4a419d29 100644
--- a/server-rs/apps/api-server/README.md
+++ b/server-rs/apps/api-server/README.md
@@ -11,6 +11,7 @@
 3. `with_state` 共享状态注入
 4. 中间件挂载
 5. `/healthz`、`/api/*`、SSE 与静态资源兼容层装配
+6. 由 `../../scripts/dev.ps1` 与 `../../scripts/dev.sh` 驱动的本地开发启动链路
 
 ## 2. 当前阶段说明
 
diff --git a/server-rs/scripts/dev.ps1 b/server-rs/scripts/dev.ps1
new file mode 100644
index 00000000..a8c7e5ae
--- /dev/null
+++ b/server-rs/scripts/dev.ps1
@@ -0,0 +1,52 @@
+[CmdletBinding()]
+param(
+    [Alias("h")]
+    [switch]$Help,
+    [string]$ApiHost = "127.0.0.1",
+    [int]$Port = 3000,
+    [string]$Log = "info,tower_http=info"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Usage {
+    @(
+        'Usage:'
+        '  ./server-rs/scripts/dev.ps1'
+        '  ./server-rs/scripts/dev.ps1 -ApiHost 0.0.0.0 -Port 3100 -Log "debug,tower_http=debug"'
+        ''
+        'Notes:'
+        '  1. Set default local env vars for the Rust api-server'
+        '  2. Start Axum with cargo run -p api-server'
+        '  3. This script only covers the api-server local dev loop'
+    ) -join [Environment]::NewLine
+}
+
+if ($Help) {
+    Write-Usage
+    exit 0
+}
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$serverRsDir = Split-Path -Parent $scriptDir
+
+if (-not (Test-Path (Join-Path $serverRsDir "Cargo.toml"))) {
+    throw "Missing server-rs/Cargo.toml, cannot start local dev script."
+}
+
+$env:GENARRATIVE_API_HOST = $ApiHost
+$env:GENARRATIVE_API_PORT = "$Port"
+$env:GENARRATIVE_API_LOG = $Log
+
+Write-Host "[server-rs:dev] working dir: $serverRsDir"
+Write-Host "[server-rs:dev] GENARRATIVE_API_HOST=$($env:GENARRATIVE_API_HOST)"
+Write-Host "[server-rs:dev] GENARRATIVE_API_PORT=$($env:GENARRATIVE_API_PORT)"
+Write-Host "[server-rs:dev] GENARRATIVE_API_LOG=$($env:GENARRATIVE_API_LOG)"
+
+Push-Location $serverRsDir
+try {
+    cargo run -p api-server --manifest-path (Join-Path $serverRsDir "Cargo.toml")
+}
+finally {
+    Pop-Location
+}
diff --git a/server-rs/scripts/dev.sh b/server-rs/scripts/dev.sh
new file mode 100644
index 00000000..d9a66f2a
--- /dev/null
+++ b/server-rs/scripts/dev.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+用法:
+  ./server-rs/scripts/dev.sh
+  GENARRATIVE_API_HOST=0.0.0.0 GENARRATIVE_API_PORT=3100 ./server-rs/scripts/dev.sh
+
+说明:
+  1. 为 Rust `api-server` 注入本地开发默认环境变量
+  2. 使用 `cargo run -p api-server` 启动 Axum 服务
+  3. 当前只覆盖 `api-server` 本地开发链路，不包含 SpacetimeDB
+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)"
+
+if [[ ! -f "${SERVER_RS_DIR}/Cargo.toml" ]]; then
+  echo "[server-rs:dev] 未找到 ${SERVER_RS_DIR}/Cargo.toml，无法启动本地开发脚本。" >&2
+  exit 1
+fi
+
+export GENARRATIVE_API_HOST="${GENARRATIVE_API_HOST:-127.0.0.1}"
+export GENARRATIVE_API_PORT="${GENARRATIVE_API_PORT:-3000}"
+export GENARRATIVE_API_LOG="${GENARRATIVE_API_LOG:-info,tower_http=info}"
+
+echo "[server-rs:dev] 工作目录: ${SERVER_RS_DIR}"
+echo "[server-rs:dev] GENARRATIVE_API_HOST=${GENARRATIVE_API_HOST}"
+echo "[server-rs:dev] GENARRATIVE_API_PORT=${GENARRATIVE_API_PORT}"
+echo "[server-rs:dev] GENARRATIVE_API_LOG=${GENARRATIVE_API_LOG}"
+
+cd "${SERVER_RS_DIR}"
+cargo run -p api-server --manifest-path "${SERVER_RS_DIR}/Cargo.toml"