[优化] 环境分离

docs/app-config.md

@@ -168,19 +168,22 @@ volumes:
 * `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值
 * 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界
 
-### 1.3 前端构建环境变量
-
-新版管理端位于 `atsf_server/web`，构建时支持以下公开环境变量：
+### 1.3 前端构建环境变量
+
+新版管理端位于 `atsf_server/web`，构建时支持以下公开环境变量：
 
 | 环境变量 | 作用 | 默认值 | 示例 |
 | --- | --- | --- | --- |
-| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
-| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
-
-说明：
-
-* 以上变量在前端构建阶段读取，并会被打包进静态资源
-* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
+| `NEXT_PUBLIC_API_BASE_URL` | 前端请求后端 API 的基础路径；默认走同源 `/api` | `/api` | `NEXT_PUBLIC_API_BASE_URL=https://demo.example.com/api` |
+| `NEXT_PUBLIC_APP_VERSION` | 构建时注入前端展示版本号 | `dev` | `NEXT_PUBLIC_APP_VERSION=v0.4.0` |
+| `NEXT_DEV_BACKEND_URL` | 前端开发服务器通过反向代理转发 `/api/*` 时使用的后端地址；仅开发模式使用 | `http://127.0.0.1:3000` | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3300` |
+
+说明：
+
+* `NEXT_PUBLIC_*` 变量会在前端构建阶段读取，并打包进静态资源
+* `NEXT_DEV_BACKEND_URL` 仅在本地开发服务器模式下使用，不会进入静态导出产物
+* 推荐生产环境继续使用同源部署，优先保持 `NEXT_PUBLIC_API_BASE_URL=/api`
+* `pnpm start` 会以开发模式启动前端，默认监听 `3001`，并通过 `NEXT_DEV_BACKEND_URL` 将 `/api/*` 代理到后端
 
 ---
 

docs/deployment.md

@@ -24,22 +24,40 @@
 
 ## 2. Server 启动
 
-### 2.1 构建前端
-
-```bash
-cd atsf_server/web
-corepack enable
+### 2.1 构建前端
+
+```bash
+cd atsf_server/web
+corepack enable
 pnpm install
 pnpm build
 ```
 
 说明：
 
-* 前端使用 Next.js 静态导出模式构建
-* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
-* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
-
-### 2.2 启动服务
+* 前端使用 Next.js 静态导出模式构建
+* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
+* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
+
+### 2.1.1 本地前端热更新开发
+
+在本地联调时，可单独启动前端开发服务器：
+
+```bash
+cd atsf_server/web
+corepack enable
+pnpm install
+pnpm start
+```
+
+说明：
+
+* `pnpm start` 默认以 Next.js 开发模式启动，监听 `http://127.0.0.1:3001`
+* 开发服务器会把 `/api/*` 请求反向代理到 `http://127.0.0.1:3000`
+* 如需改后端地址，可在启动前设置 `NEXT_DEV_BACKEND_URL`
+* 这种模式用于本地热更新开发；正式运行和交付仍以 `pnpm build` 后由 Go Server 托管为准
+
+### 2.2 启动服务
 
 ```bash
 cd atsf_server

docs/frontend-development-guidelines.md

@@ -26,6 +26,13 @@
 * Vitest + Testing Library + Playwright
 * pnpm
 
+本地开发模式：
+
+* `pnpm start`：启动独立前端开发服务器，默认监听 `3001`，支持热更新
+* 开发服务器默认把 `/api/*` 反向代理到 `http://127.0.0.1:3000`
+* 如需改后端地址，可设置 `NEXT_DEV_BACKEND_URL`
+* `pnpm build`：继续用于静态导出，产物交给 Go Server 托管
+
 要求：
 
 * 默认使用 TypeScript，不新增 JS 页面模块