[重构] 前端改造v1

docs/app-config.md

@@ -94,6 +94,20 @@ volumes:
 * `REDIS_CONN_STRING` 未配置时，相关能力将回退为进程内实现
 * `UPLOAD_PATH` 目录在启动时若不存在会自动创建
 
+### 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`
+
 ---
 
 ## 2. Agent 配置

docs/deployment.md

@@ -27,10 +27,17 @@
 
 ```bash
 cd atsf_server/web
-npm install
-npm run build
+corepack enable
+pnpm install
+pnpm build
 ```
 
+说明：
+
+* 前端使用 Next.js 静态导出模式构建
+* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
+* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
+
 ### 2.2 启动服务
 
 ```bash
@@ -226,7 +233,7 @@ GOCACHE=/tmp/atsflare-go-cache go test ./...
 
 ```bash
 cd atsf_server/web
-npm run build
+pnpm build
 ```
 
 ### 6.4 发布工作流

docs/development-guidelines.md

@@ -43,11 +43,11 @@
 
 ### 2.3 前端
 
-前端继续基于现有 React 管理端：
+前端改造专项以 `atsf_server/web` 新版工程为基线：
 
-* 保持现有目录结构
-* 继续复用现有 UI 与 helper 组织方式
-* 不为第三版提前引入新的大型框架或状态管理方案
+* 使用 Next.js App Router + TypeScript + Tailwind CSS
+* 按 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) 执行目录分层与组件规范
+* 首期仍以静态导出产物交由 Go Server 托管为前提
 
 ---
 
@@ -216,15 +216,15 @@ V3 新增行为：
 
 要求：
 
-* 只为当前版本主链路增加页面与交互
-* API 请求统一放在已有 helper 体系
-* 页面状态优先保持简单
-* 沿用现有组件与样式体系，不大规模重构后台 UI
+* 新前端页面、组件与请求层统一遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)
+* API 请求统一收敛到 `atsf_server/web/lib/api/`
+* 页面路由与布局放在 `app/`，业务逻辑放在 `features/`
+* 构建产物必须保持可被 Go Server 静态托管
 
 如果第三版要新增页面，优先原则：
 
-* 能复用现有页面结构就不新增一套页面框架
-* 能复用已有表单模式就不自造 DSL 编辑器
+* 能复用现有 feature 结构就不平行再造一套页面逻辑
+* 能复用统一表单、反馈与布局组件就不在页面中重复实现
 
 ---
 

docs/development-plan.md

@@ -145,10 +145,27 @@
 * 节点状态有颜色区分：在线（绿色）、离线（红色）、待接入（黄色）
 * curl 部署命令支持一键复制
 
+### 3.6 并行专项：管理端前端工程改造
+
+目标：按 [docs/frontend-revamp-plan.md](./frontend-revamp-plan.md) 推进新版管理端重建，不阻塞 Server/Agent 主链路。
+
+实施约束：
+
+1. 前端专项按独立阶段推进，当前从“阶段 1：工程初始化”开始执行
+2. 首期产物必须保持静态导出，并继续由 `atsf_server` 托管
+3. 认证迁移、业务模块迁移与最终切换按 `docs/frontend-revamp-plan.md` 的阶段顺序执行
+
+验收标准：
+
+* 新前端可本地开发、可静态构建
+* Go Server 可继续托管新版构建产物
+* 前端专项与现有第三版主链路互不破坏
+
 ---
 
 ## 4. 阶段执行原则
 
 * 每个阶段完成后验证验收标准，再进入下一阶段
 * 阶段间的代码不相互依赖时可并行
-* 每个阶段完成后运行全量测试
+* 每个阶段完成后运行全量测试
+* 管理端前端改造按 [docs/frontend-revamp-plan.md](./frontend-revamp-plan.md) 单独跟踪阶段状态