From 37be3034ecb5d84a4a4c83e0465c8e8a0576db18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=B9=98=E9=A3=8E?= <fsmecx@gmail.com>
Date: Mon, 20 Apr 2026 11:20:47 +0800
Subject: [PATCH] =?UTF-8?q?fix(devdoc):=20Windows=20=E5=90=88=E6=B3=95?=
 =?UTF-8?q?=E8=B5=84=E6=BA=90=E8=B7=AF=E5=BE=84=20+=20=E6=9C=AC=E5=9C=B0?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8=20bat=20=E4=B8=8E=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 将误用 Markdown 语法的截图路径重命名为 截图1-占位说明图.png

- 新增 scripts/本地启动.bat；测试 README 补充 Windows 启动方式

- 新增 开发文档/Windows-资源命名与拉取.md

Made-with: Cursor
---
 scripts/test/README.md                        |   5 ++-
 scripts/本地启动.bat                          |  30 ++++++++++++++++++
 .../images/截图1.png)`.png => 截图1-占位说明图.png} | Bin
 开发文档/Windows-资源命名与拉取.md            |  25 +++++++++++++++
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 scripts/本地启动.bat
 rename 开发文档/1、需求/修改/images/{![描述](./images/截图1.png)`.png => 截图1-占位说明图.png} (100%)
 create mode 100644 开发文档/Windows-资源命名与拉取.md

diff --git a/scripts/test/README.md b/scripts/test/README.md
index a54d1653..119a118e 100644
--- a/scripts/test/README.md
+++ b/scripts/test/README.md
@@ -22,7 +22,10 @@ pip install -r requirements-test.txt
 pytest -v
 ```
 
-联调前请先执行 `scripts/本地启动.sh` 启动 soul-api 与 soul-admin。
+联调前请先启动 soul-api 与 soul-admin：
+
+- **macOS / Linux**：`bash scripts/本地启动.sh` 或 `./scripts/本地启动.sh`
+- **Windows**：双击或在仓库根目录执行 `scripts\本地启动.bat`（需已安装 Go、pnpm，且 Windows 10+ 自带 `curl` 用于健康检查）
 
 ---
 
diff --git a/scripts/本地启动.bat b/scripts/本地启动.bat
new file mode 100644
index 00000000..28f0f4db
--- /dev/null
+++ b/scripts/本地启动.bat
@@ -0,0 +1,30 @@
+@echo off
+setlocal EnableExtensions
+cd /d "%~dp0.."
+set "ROOT=%CD%"
+
+echo ===== 1. 启动 soul-api（端口 8080）=====
+if not exist "%ROOT%\soul-api\soul-api.exe" (
+  echo 未找到 soul-api.exe，正在编译...
+  pushd "%ROOT%\soul-api" || exit /b 1
+  go build -o soul-api.exe .\cmd\server
+  if errorlevel 1 popd & exit /b 1
+  popd
+)
+
+start "soul-api" /B cmd /c "set APP_ENV=development&& set PORT=8080&& cd /d ""%ROOT%\soul-api""&& soul-api.exe"
+echo soul-api 已以后台窗口启动，本脚本继续检查健康状态…
+timeout /t 3 /nobreak >nul
+
+curl -sf http://localhost:8080/health >nul
+if errorlevel 1 (
+  echo soul-api 启动失败，请检查数据库连接与本机是否已安装 Go
+  exit /b 1
+)
+echo soul-api 健康检查通过
+
+echo.
+echo ===== 2. 启动 soul-admin（端口 5174）=====
+echo 访问 http://localhost:5174  默认账号 admin / admin123
+cd /d "%ROOT%\soul-admin" || exit /b 1
+pnpm dev
diff --git a/开发文档/1、需求/修改/images/![描述](./images/截图1.png)`.png b/开发文档/1、需求/修改/images/截图1-占位说明图.png
similarity index 100%
rename from 开发文档/1、需求/修改/images/![描述](./images/截图1.png)`.png
rename to 开发文档/1、需求/修改/images/截图1-占位说明图.png
diff --git a/开发文档/Windows-资源命名与拉取.md b/开发文档/Windows-资源命名与拉取.md
new file mode 100644
index 00000000..2927a9db
--- /dev/null
+++ b/开发文档/Windows-资源命名与拉取.md
@@ -0,0 +1,25 @@
+# Windows 下开发文档与资源路径说明
+
+## 不要在仓库里用「Markdown 图片语法」当真实文件名
+
+曾出现将截图保存为类似 `…/images/![描述](./images/截图1.png`.png` 的路径：其中含 `/`、反引号等，在 Windows 上会导致 **无法克隆/拉取** 或与索引不一致。
+
+现已在 `开发文档/1、需求/修改/images/` 下改为规范文件名：**`截图1-占位说明图.png`**。
+
+## 若仍遇到 `invalid path` 拉取失败
+
+可临时放宽 NTFS 校验后拉取（本仓库已修正资源名后一般不再需要）：
+
+```bash
+git -c core.protectNTFS=false pull
+```
+
+或在当前仓库执行一次：
+
+```bash
+git config core.protectNTFS false
+```
+
+## 本地联调（Windows）
+
+除 `scripts/本地启动.sh` 外，可使用 **`scripts/本地启动.bat`** 启动 soul-api + soul-admin，详见 `scripts/test/README.md`。