feat: 添加前端改造计划和开发规范文档，规划 Next.js + Tailwind CSS 的迁移方案

2026-09-29 14:06:36 +08:00 · 2026-03-11 12:24:07 +08:00
parent 16ea572183
commit 052e3e98f8
3 changed files with 1042 additions and 2 deletions
@@ -11,10 +11,16 @@
 3. [docs/development-plan.md](./docs/development-plan.md)
   作用：理解当前开发阶段、实施顺序、阶段目标和验收标准。

-3. [docs/deployment.md](./docs/deployment.md)
+4. [docs/frontend-revamp-plan.md](./docs/frontend-revamp-plan.md)
+   作用：理解当前前端从 CRA + Semantic UI 迁移到 Next.js + Tailwind CSS + NextUI 的专项改造目标、实施阶段和风险边界。
+
+5. [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md)
+   作用：理解新版前端的技术选型、目录分层、组件规范、请求层、状态管理、样式和测试约束。
+
+6. [docs/deployment.md](./docs/deployment.md)
   作用：理解当前的部署方式和联调步骤，确保开发过程中产出的功能能够成功部署和验证。

-4. [docs/app-config.md](./docs/app-config.md)
+7. [docs/app-config.md](./docs/app-config.md)
   作用：系统启动时支持的环境变量和配置项说明，确保开发过程中新增的配置项能够正确使用和文档化。


@@ -23,6 +29,7 @@
 * 如果实现内容超出 `docs/design.md` 的范围，先修改设计文档，再继续编码。
 * 如果实现方式违反 `docs/development-guidelines.md`，应优先调整方案，而不是绕过规范。
 * 如果需求与当前开发阶段冲突，优先遵守 `docs/development-plan.md` 的阶段顺序。
+* 如果任务涉及前端改造或管理端 UI，必须同时阅读 `docs/frontend-revamp-plan.md` 与 `docs/frontend-development-guidelines.md`。


 ## 文档维护要求
@@ -33,4 +40,6 @@
 * 产品范围或系统边界变化：更新 `docs/design.md`
 * 开发约束、代码规范、接口约定变化：更新 `docs/development-guidelines.md`
 * 阶段目标、顺序、验收标准变化：更新 `docs/development-plan.md`
+* 前端技术栈、迁移阶段、页面范围变化：更新 `docs/frontend-revamp-plan.md`
+* 前端目录分层、组件规范、样式体系、测试基线变化：更新 `docs/frontend-development-guidelines.md`
 * 环境变量或配置项变化：更新 `docs/app-config.md`
@@ -0,0 +1,584 @@
+# ATSFlare 前端开发规范（Next.js + Tailwind CSS）
+
+## 1. 文档定位
+
+本文档用于约束 ATSFlare 新前端的工程结构、编码方式、组件设计、请求层、样式体系与交付标准。
+
+适用范围：
+
+* `atsf_server/web` 新版前端工程
+* 基于 Next.js + Tailwind CSS 的管理端页面、组件、状态、测试与构建代码
+
+说明：
+
+* 本文档为前端专项规范。
+* 当改造方案正式落地后，应将其中稳定约束同步回写到 [docs/development-guidelines.md](./development-guidelines.md)。
+
+---
+
+## 2. 技术栈规范
+
+前端默认技术基线如下：
+
+* Next.js 15（App Router）
+* React 19
+* TypeScript 5.x
+* Tailwind CSS 4.x
+* NextUI
+* pnpm
+* ESLint + Prettier
+* TanStack Query
+* React Hook Form + Zod
+* Zustand（仅限轻量客户端状态）
+* Vitest + Testing Library + Playwright
+
+要求：
+
+* 默认使用 TypeScript，不再新增 JS 页面模块
+* 默认使用函数组件，不新增 class 组件
+* 默认使用 App Router，不新建 Pages Router 结构
+* 默认使用 Tailwind CSS，不再引入新的大型样式框架
+* 默认使用 NextUI 作为统一视觉组件基础
+
+禁止：
+
+* 新增 Semantic UI 依赖
+* 混用多套大型组件库造成视觉与交互割裂
+* 在新模块中继续使用 jQuery 风格 DOM 操作
+* 将页面逻辑继续堆积为单个超大组件
+
+---
+
+## 3. 目录与分层规范
+
+推荐目录：
+
+```text
+app/
+components/
+features/
+lib/
+hooks/
+store/
+types/
+styles/
+tests/
+```
+
+### 3.1 `app/`
+
+职责：
+
+* 定义路由
+* 组织页面级布局
+* 组合业务模块
+
+禁止：
+
+* 在 `app/` 中堆积复杂请求逻辑
+* 在 `app/` 页面文件内直接写大段业务处理代码
+
+### 3.2 `features/`
+
+职责：
+
+* 按业务域组织模块
+* 管理该模块的视图、表单、schema、query、action、类型定义
+
+建议：
+
+* 一个核心业务对象对应一个 feature
+* feature 内部可包含 `components`、`api`、`hooks`、`schema`、`types`
+
+### 3.3 `components/`
+
+职责：
+
+* 放置跨 feature 复用组件
+
+分层建议：
+
+* `components/ui/`：基于 NextUI 封装的按钮、表格、对话框、标签、输入框等基础组件
+* `components/layout/`：侧边栏、导航栏、页面容器、内容区
+* `components/feedback/`：加载、空态、错误态、确认框、消息提示
+* `components/forms/`：复用型表单片段
+
+### 3.4 `lib/`
+
+职责：
+
+* 公共能力沉淀
+
+建议子目录：
+
+* `lib/api/`：请求客户端、资源接口、错误映射
+* `lib/auth/`：登录态工具、鉴权辅助
+* `lib/env/`：环境变量读取与校验
+* `lib/utils/`：纯工具函数
+* `lib/constants/`：常量定义
+
+### 3.5 `store/`
+
+职责：
+
+* 存储少量需要跨页面共享的客户端 UI 状态
+
+禁止：
+
+* 把服务端资源数据塞进 Zustand 作为主数据源
+* 用全局 store 代替正常的 props 或 query 缓存
+
+---
+
+## 4. 路由与页面规范
+
+### 4.1 路由命名
+
+要求：
+
+* 使用英文小写复数资源名
+* 使用语义清晰的层级结构
+
+示例：
+
+* `/nodes`
+* `/proxy-routes`
+* `/config-versions`
+* `/tls-certificates`
+* `/managed-domains`
+
+### 4.2 页面职责
+
+页面文件应只负责：
+
+* 获取路由参数
+* 组织页面结构
+* 调用 feature 组件
+
+页面不应负责：
+
+* 编写复杂表单校验逻辑
+* 手写 API 细节
+* 维护大量局部状态机
+
+### 4.3 页面结构建议
+
+后台页面优先采用统一结构：
+
+1. 页面标题区
+2. 页面说明区（可选）
+3. 操作区
+4. 筛选区
+5. 内容区（表格 / 卡片 / 表单）
+6. 详情区或侧栏（可选）
+
+---
+
+## 5. Server Component / Client Component 规范
+
+### 5.1 默认原则
+
+在当前 ATSFlare 管理端场景下，优先使用以下原则：
+
+* 路由层、布局层可优先使用 Server Component
+* 表单、交互、列表操作类组件使用 Client Component
+* 涉及浏览器 API、事件处理、弹窗状态的模块必须显式声明 `'use client'`
+
+### 5.2 使用约束
+
+禁止：
+
+* 为了省事，将整个应用顶层都改成 Client Component
+* 将仅用于展示的静态内容一律写成客户端组件
+
+建议：
+
+* 以“最小客户端边界”为目标组织组件
+* 明确区分展示组件与交互组件
+
+---
+
+## 6. TypeScript 与类型规范
+
+### 6.1 总体要求
+
+* 开启严格模式
+* 禁止滥用 `any`
+* 接口响应、表单输入、业务实体必须有明确类型
+
+### 6.2 命名建议
+
+* 接口返回：`ProxyRoute`, `NodeItem`, `ConfigVersionItem`
+* 表单值：`ProxyRouteFormValues`
+* 查询参数：`NodeListQuery`
+* Schema：`proxyRouteSchema`
+
+### 6.3 类型边界
+
+要求：
+
+* API 响应类型定义在资源模块或 `types/` 中
+* 组件 props 明确声明，不使用隐式结构
+* 日期、状态、枚举类字段应在前端建立明确字面量或枚举类型
+
+---
+
+## 7. 数据请求规范
+
+### 7.1 请求入口
+
+所有 API 请求必须统一经过 `lib/api/`。
+
+禁止：
+
+* 在页面组件中直接调用 `fetch('/api/...')`
+* 在多个组件中重复拼接相同接口路径
+
+### 7.2 请求封装
+
+要求：
+
+* 提供统一请求客户端
+* 统一处理：
+  * `success/message/data` 响应结构
+  * 鉴权失效
+  * 通用错误提示
+  * 网络异常
+
+### 7.3 Query 使用规范
+
+适用场景：
+
+* 列表查询
+* 详情查询
+* 配置读取
+* 依赖后端的分页、筛选、刷新操作
+
+要求：
+
+* 使用稳定的 query key
+* 变更操作完成后按资源粒度失效缓存
+* 列表刷新不要依赖手工多处 setState
+
+---
+
+## 8. 表单规范
+
+### 8.1 表单栈
+
+统一使用：
+
+* React Hook Form
+* Zod
+
+### 8.2 校验原则
+
+* 输入校验尽量前置
+* 与后端约束一致
+* 错误信息清晰可读
+
+### 8.3 交互要求
+
+* 必填项明确标识
+* 提交中状态不可重复点击
+* 保存成功要有明确反馈
+* 服务端错误要映射到表单或全局提示
+
+### 8.4 高风险表单
+
+适用场景：
+
+* 发布配置
+* 激活版本
+* 删除节点
+* 删除证书
+* 重置 Token
+
+要求：
+
+* 必须有二次确认
+* 必须展示操作对象名称
+* 必须明确成功与失败反馈
+
+---
+
+## 9. 样式与 UI 规范
+
+### 9.1 样式原则
+
+* NextUI 为统一视觉组件基线
+* Tailwind CSS 为布局、间距、响应式与业务样式扩展的基础方案
+* 样式通过设计 token、NextUI 主题能力与语义类组合实现
+* 页面视觉风格统一、留白一致、层级清晰
+
+### 9.2 设计 token
+
+至少抽象以下语义：
+
+* 主色、成功色、警告色、危险色
+* 边框色、背景色、弱文本色、强文本色
+* 圆角、阴影、间距、层级
+
+### 9.3 组件外观要求
+
+* 按钮尺寸、输入框高度、表格密度、弹窗圆角保持统一
+* 状态标签颜色语义固定，不允许每页自定义一套颜色
+* 表格、卡片、表单容器使用统一布局间距
+
+### 9.4 禁止项
+
+* 大量硬编码颜色值
+* 在 JSX 中堆砌不可读的超长类名且不抽组件
+* 同一个状态在不同页面使用不同颜色语义
+
+---
+
+## 10. 组件设计规范
+
+### 10.1 组件分类
+
+组件分为三类：
+
+1. 基础组件：基于 NextUI 二次封装的按钮、输入框、表格、对话框、标签
+2. 业务组件：节点状态卡、版本激活按钮、证书上传表单
+3. 页面组合组件：页面头部、筛选面板、详情抽屉
+
+### 10.2 复用原则
+
+* 先抽象稳定结构，再抽象复杂行为
+* 不为单次使用过度设计通用组件
+* 业务组件优先放在 feature 内，确认跨域复用后再上移
+
+### 10.3 Props 规范
+
+* props 命名语义化
+* 布尔值 props 使用肯定式命名
+* 事件 props 使用 `onXxx`
+
+示例：
+
+* `isLoading`
+* `isDanger`
+* `onSubmit`
+* `onConfirm`
+
+---
+
+## 11. 状态管理规范
+
+### 11.1 状态分类
+
+* 服务端状态：放 Query
+* 页面临时交互状态：放组件内部 `useState`
+* 跨页面 UI 状态：放 Zustand
+
+### 11.2 不推荐做法
+
+* 用 Zustand 保存服务端列表数据
+* 用 Context 替代完整的数据层方案
+* 页面里堆叠过多彼此耦合的本地状态
+
+### 11.3 推荐做法
+
+* 将筛选条件、对话框开关、当前编辑对象保持最小化
+* 复杂交互优先拆成自定义 hook 或 feature action
+
+---
+
+## 12. 反馈与异常处理规范
+
+### 12.1 基础反馈
+
+每个页面必须具备：
+
+* 加载态
+* 空态
+* 错误态
+* 成功反馈
+
+### 12.2 错误处理
+
+要求：
+
+* 请求失败时给出用户可理解的信息
+* 后端返回 `message` 时优先展示可读消息
+* 非预期错误需要统一兜底文案
+
+### 12.3 长耗时操作
+
+适用场景：
+
+* 发布配置
+* 激活版本
+* 上传证书
+* 节点触发更新
+
+要求：
+
+* 需要展示明确 loading 状态
+* 完成后要主动刷新相关资源
+
+---
+
+## 13. 可访问性与国际化规范
+
+### 13.1 可访问性
+
+要求：
+
+* 表单控件必须有关联标签
+* 按钮文案清晰，不只依赖图标表达语义
+* 弹窗支持键盘关闭与焦点管理
+* 状态颜色不能作为唯一信息来源
+
+### 13.2 国际化
+
+当前管理端以中文为主，但要求：
+
+* 文案集中管理，避免散落硬编码
+* 状态、按钮、提示信息尽量收敛到常量或文案文件
+
+---
+
+## 14. 测试规范
+
+### 14.1 单元与组件测试
+
+适用内容：
+
+* 工具函数
+* schema 校验
+* 基础组件
+* 关键业务组件
+
+### 14.2 集成测试
+
+适用内容：
+
+* 列表加载与筛选
+* 表单提交与错误反馈
+* 对话框确认流程
+
+### 14.3 E2E 测试
+
+至少覆盖以下主链路：
+
+* 登录
+* 新增反代规则
+* 发布并查看配置版本
+* 节点列表查看
+* 证书导入
+* 运维设置修改
+
+---
+
+## 15. 性能规范
+
+要求：
+
+* 避免不必要的大型客户端依赖
+* 避免页面级重复请求
+* 大表格页面优先考虑分页而非一次性全量加载
+* 图标、日期格式化、富文本等能力优先按需引入
+
+建议：
+
+* 公共重型组件按需加载
+* 详情弹窗、复杂编辑器、Diff 预览支持懒加载
+
+---
+
+## 16. 安全规范
+
+要求：
+
+* 不在前端持久化敏感 Token
+* 不在日志中输出敏感配置、证书私钥、完整凭证
+* 富文本或 Markdown 渲染必须经过安全处理
+* 上传、下载、外链跳转必须有明确来源控制
+
+禁止：
+
+* 在本地存储中缓存高敏感服务端数据
+* 为图方便绕过后端鉴权逻辑
+
+---
+
+## 17. 命名与代码风格规范
+
+### 17.1 文件命名
+
+* 组件：`PascalCase.tsx`
+* hook：`useXxx.ts`
+* 工具：`camelCase.ts` 或按职责命名
+* schema：`xxx.schema.ts`
+* 类型：`xxx.types.ts`
+
+### 17.2 符号命名
+
+* 组件名使用名词或名词短语
+* hook 使用 `use` 前缀
+* 布尔值使用 `is`、`has`、`can` 前缀
+* 事件处理使用 `handle` 前缀
+
+### 17.3 代码风格
+
+* 保持单文件职责清晰
+* 优先早返回减少嵌套
+* 删除废弃代码与无意义注释
+* 不在 JSX 中堆积复杂表达式，提取到变量或 hook
+
+---
+
+## 18. 提交与评审要求
+
+### 18.1 提交粒度
+
+要求：
+
+* 一次提交聚焦一个明确目标
+* 不把样式重构、功能新增、目录调整混在同一提交中
+
+### 18.2 代码评审关注点
+
+评审时重点检查：
+
+1. 是否符合目录分层
+2. 是否复用了统一请求层
+3. 是否破坏现有 API 兼容性
+4. 是否存在过度客户端化问题
+5. 是否符合 UI 一致性与状态反馈规范
+6. 是否补充必要测试
+
+---
+
+## 19. 文档维护要求
+
+以下内容变化时，必须同步更新本文档：
+
+* 技术栈调整
+* 目录结构调整
+* 请求层约定变化
+* 状态管理方案变化
+* 测试基线变化
+* 样式体系变化
+
+当专项方案正式实施后，还应同步更新：
+
+* [docs/design.md](./design.md)
+* [docs/development-guidelines.md](./development-guidelines.md)
+* [docs/deployment.md](./deployment.md)
+
+---
+
+## 20. 最低执行标准
+
+新前端代码提交前，至少满足：
+
+1. 通过类型检查
+2. 通过 lint
+3. 核心路径具备基础测试
+4. 页面具备加载态、空态、错误态
+5. API 请求不散落在页面 JSX 中
+6. 未新增 Semantic UI 依赖
+7. 未破坏当前后端主链路和部署约束
@@ -0,0 +1,447 @@
+# ATSFlare 前端改造计划（Next.js + Tailwind CSS）
+
+## 1. 文档定位
+
+本文档用于规划 ATSFlare 管理端 UI 改造方案，目标是在不破坏当前 Server/Agent 主链路的前提下，将现有基于 CRA + React + Semantic UI 的前端，升级为基于 Next.js + Tailwind CSS 的现代化管理端。
+
+说明：
+
+* 当前正式基线仍以 [docs/design.md](./design.md)、[docs/development-guidelines.md](./development-guidelines.md)、[docs/development-plan.md](./development-plan.md) 为准。
+* 本文档作为前端专项改造规划输入，用于后续确认技术路线、实施顺序与落地边界。
+* 在正式开工前，应将确认后的结论回写到基线文档中，避免与现有 V3 规范冲突。
+
+---
+
+## 2. 改造背景
+
+当前管理端位于 `atsf_server/web`，主要特征如下：
+
+* 技术栈为 CRA + React 18 + React Router + Semantic UI
+* 页面与业务逻辑耦合较高，请求、状态、展示常集中在单文件中
+* 样式体系依赖 Semantic UI，主题定制能力有限
+* 缺少面向长期演进的前端目录分层与组件规范
+* 当前构建产物为静态资源，由 Go Server 嵌入并直接托管
+
+当前主要页面包括：
+
+* 首页 `/`
+* 反代规则 `/proxy-route`
+* 配置版本 `/config-version`
+* 节点管理 `/node`
+* 应用记录 `/apply-log`
+* 域名管理 `/managed-domain`
+* TLS 证书 `/tls-certificate`
+* 文件管理 `/file`
+* 用户管理 `/user`
+* 设置 `/setting`
+* 登录、注册、重置密码、GitHub OAuth 等认证页面
+
+现状判断：
+
+* 后端 API 已形成相对稳定的控制面能力，适合先做前端层重构
+* 目前最需要优化的是信息层级、交互一致性、组件复用与可维护性
+* 由于现有 Go Server 直接嵌入静态前端资源，前端改造必须优先考虑部署兼容性
+
+---
+
+## 3. 改造目标
+
+### 3.1 业务目标
+
+* 提升管理端整体视觉质量与交互一致性
+* 优化节点、配置版本、证书、域名等核心页面的操作效率
+* 为后续运维设置、Agent 部署、状态展示等能力扩展提供稳定前端基础
+
+### 3.2 技术目标
+
+* 使用 Next.js 作为新的前端应用框架
+* 使用 Tailwind CSS 作为统一样式基础设施
+* 使用 TypeScript 建立明确类型边界
+* 建立可维护的目录结构、组件分层与请求层规范
+* 提升首屏体验、构建质量、代码可测试性与长期可演进性
+
+### 3.3 约束目标
+
+* 不改变现有 Server/Agent 的核心业务边界
+* 不以引入 Redis、BFF、消息队列等新基础设施为前提
+* 首期改造优先复用现有 HTTP API，不推动后端接口大规模重写
+* 首期部署尽量兼容当前 Go Server 嵌入静态资源的模式
+
+---
+
+## 4. 推荐目标技术栈
+
+推荐采用“稳定优先”的现代前端栈：
+
+* 框架：Next.js 15（App Router）
+* 运行时：React 19
+* 语言：TypeScript 5.x
+* 样式：Tailwind CSS 4.x
+* 组件库：NextUI
+* 组件方案：以 NextUI 作为统一视觉基础，结合 Tailwind CSS 做布局、间距与少量业务样式扩展
+* 状态管理：
+  * 服务端数据：TanStack Query
+  * 轻量客户端状态：Zustand
+* 表单：React Hook Form + Zod
+* HTTP：优先 `fetch` 封装；如需兼容现有拦截器逻辑，可局部保留 Axios
+* 质量工具：ESLint + Prettier + TypeScript strict mode
+* 测试：Vitest + Testing Library + Playwright
+* 包管理：pnpm
+
+说明：
+
+* 不建议继续沿用 Semantic UI。
+* 不建议同时混用多套大型组件库，统一以 NextUI 作为后台视觉主基线。
+* 不建议在首期同时引入过重的全局状态方案。
+* 不建议在首期追求过多服务端渲染能力，以免破坏当前部署模式。
+
+---
+
+## 5. 部署与运行策略
+
+这是本次改造的关键前置决策。
+
+### 5.1 当前约束
+
+当前 Go Server 通过嵌入静态资源目录对外提供管理端页面，因此现有模式更接近“静态管理后台”，而不是“独立 Node SSR 应用”。
+
+### 5.2 推荐方案
+
+首期采用：
+
+**Next.js App Router + 静态导出优先策略**
+
+即：
+
+* 使用 Next.js 进行前端工程化与路由组织
+* 管理端页面以客户端渲染和 API 拉取为主
+* 构建产物保持为静态资源，继续由 `atsf_server` 托管
+
+这样做的优点：
+
+* 对现有 Go 单体部署影响最小
+* 不需要为管理端新增 Node.js 常驻服务
+* 不需要修改当前用户访问入口
+* 可先完成 UI 和工程体系升级，再决定是否引入 SSR/BFF
+
+### 5.3 二期可选演进
+
+若后续确认需要更强的服务端能力，可再评估：
+
+* 独立部署 Next.js Node 服务
+* 引入中间层处理鉴权与聚合接口
+* 在部署文档中增加新的运行模式
+
+当前不建议首期直接采用该模式。
+
+---
+
+## 6. 目标目录结构
+
+建议新前端在 `atsf_server/web` 内重建为 Next.js 工程，采用如下结构：
+
+```text
+atsf_server/web/
+  app/
+    (public)/
+      login/
+      register/
+      reset/
+      oauth/github/
+    (dashboard)/
+      layout.tsx
+      page.tsx
+      proxy-routes/
+      config-versions/
+      nodes/
+      apply-logs/
+      managed-domains/
+      tls-certificates/
+      files/
+      users/
+      settings/
+    not-found.tsx
+  components/
+    ui/
+    layout/
+    forms/
+    tables/
+    feedback/
+  features/
+    auth/
+    proxy-routes/
+    config-versions/
+    nodes/
+    apply-logs/
+    managed-domains/
+    tls-certificates/
+    files/
+    users/
+    settings/
+  lib/
+    api/
+    auth/
+    env/
+    utils/
+    constants/
+  hooks/
+  store/
+  types/
+  styles/
+  public/
+  tests/
+```
+
+分层原则：
+
+* `app/` 只负责路由与页面组装
+* `features/` 承载业务模块
+* `components/ui/` 承载可复用基础组件
+* `lib/api/` 统一管理请求封装、错误处理与接口定义
+* `store/` 只放少量跨页面客户端状态
+
+---
+
+## 7. 页面迁移映射
+
+建议按“业务模块”而不是“旧文件结构”迁移：
+
+| 现有路由 | 目标路由 | 改造重点 |
+| --- | --- | --- |
+| `/` | `/` | 首页概览卡片、系统状态、公告区域重设计 |
+| `/proxy-route` | `/proxy-routes` | 表格、创建/编辑抽屉、发布动作、域名证书联动 |
+| `/config-version` | `/config-versions` | 版本列表、diff 预览、激活流程、只读预览体验 |
+| `/node` | `/nodes` | 节点状态标签、心跳时间、部署命令、更新动作 |
+| `/apply-log` | `/apply-logs` | 过滤器、结果状态可视化、分页与详情展示 |
+| `/managed-domain` | `/managed-domains` | 通配符匹配提示、证书绑定状态、启用状态切换 |
+| `/tls-certificate` | `/tls-certificates` | 导入、上传、有效期展示、到期提醒样式 |
+| `/file` | `/files` | 文件列表与下载交互优化 |
+| `/user` | `/users` | 用户列表、角色管理、搜索与编辑体验 |
+| `/setting` | `/settings` | 系统设置、运维设置、个人设置按信息架构重组 |
+| `/login` 等 | `/login` 等 | 统一认证页视觉与表单规范 |
+
+说明：
+
+* 路由命名建议统一改为复数英文资源名。
+* 为兼容旧链接，可在切换期保留旧路由跳转。
+
+---
+
+## 8. 实施阶段规划
+
+### 阶段 0：技术方案确认
+
+目标：确认不影响现有部署的前端升级路径。
+
+任务：
+
+1. 确认 Next.js 静态导出模式可满足当前管理端需求
+2. 确认构建产物与 Go Server 嵌入目录的衔接方式
+3. 确认登录态传递方式、Cookie/Session 兼容方式
+4. 确认 API Base URL、构建变量与开发代理方案
+
+验收：
+
+* 输出最终工程初始化方案
+* 输出环境变量与部署变更清单
+
+### 阶段 1：工程初始化
+
+目标：建立新的前端基础工程。
+
+任务：
+
+1. 将 `atsf_server/web` 初始化为 Next.js + TypeScript + Tailwind CSS 项目
+2. 接入 ESLint、Prettier、基础测试框架
+3. 建立 `app/`、`features/`、`components/`、`lib/` 基础结构
+4. 完成全局布局、主题变量、基础 UI 组件骨架
+
+验收：
+
+* 可本地启动开发环境
+* 可生成静态构建产物
+* Go Server 可正确托管构建结果
+
+### 阶段 2：认证与框架层迁移
+
+目标：先完成入口与骨架迁移。
+
+任务：
+
+1. 迁移登录、注册、密码重置、OAuth 回调页面
+2. 实现全局布局、侧边栏、顶部导航、面包屑、页面标题体系
+3. 建立统一鉴权守卫与未登录跳转逻辑
+4. 建立统一消息反馈、加载态、空态、错误态组件
+
+验收：
+
+* 用户可完成登录、退出、进入后台主框架
+* 公共骨架稳定可复用
+
+### 阶段 3：核心业务模块迁移
+
+目标：优先覆盖主链路页面。
+
+优先顺序：
+
+1. `proxy-routes`
+2. `config-versions`
+3. `nodes`
+4. `managed-domains`
+5. `tls-certificates`
+6. `apply-logs`
+
+验收：
+
+* 核心主链路页面具备完整增删改查能力
+* 关键动作存在明确确认、反馈与错误提示
+
+### 阶段 4：设置与边缘模块迁移
+
+目标：完成非主链路页面迁移。
+
+任务：
+
+* 迁移 `settings`、`users`、`files`、`about` 等模块
+* 重构表单项、标签页、操作区布局
+* 增加部署命令复制、时间友好显示、状态颜色体系
+
+验收：
+
+* 日常管理操作均可在新前端完成
+* 旧前端仅剩兼容兜底价值
+
+### 阶段 5：联调、回归与切换
+
+目标：完成替换上线准备。
+
+任务：
+
+1. 对照现有页面与接口完成功能回归
+2. 补齐前端测试与关键页面 E2E
+3. 验证静态资源构建、嵌入、发布流程
+4. 切换默认前端入口并保留回滚预案
+
+验收：
+
+* 所有核心页面通过冒烟测试
+* 构建与部署文档可复现
+* 可在必要时快速回退到旧前端版本
+
+---
+
+## 9. 页面与交互设计原则
+
+### 9.1 信息架构
+
+* 首层导航按业务对象组织，而不是按实现技术组织
+* 同类页面保持一致的操作区、筛选区、表格区、详情区结构
+* 删除“一个页面多种风格并存”的情况
+
+### 9.2 操作体验
+
+* 列表页优先支持搜索、筛选、排序、分页
+* 创建/编辑优先使用弹窗或抽屉，避免频繁整页跳转
+* 高风险操作必须二次确认
+* 发布、激活、删除、更新等动作必须可见反馈结果
+
+### 9.3 可视化规范
+
+* 节点状态、证书有效期、配置版本激活状态等统一颜色语义
+* 时间统一支持绝对时间 + 相对时间
+* 空数据、加载中、请求失败使用统一视觉语言
+
+---
+
+## 10. API 与数据层策略
+
+### 10.1 API 原则
+
+* 首期复用现有 `/api/*` 接口
+* 不为前端改造而大规模重写 Server API
+* 若现有字段命名不理想，可在前端适配层完成映射
+
+### 10.2 请求层规范
+
+* 所有接口调用统一收敛到 `lib/api/`
+* 统一处理鉴权失效、错误消息、超时与重试策略
+* 页面组件中不直接拼接复杂请求逻辑
+
+### 10.3 缓存策略
+
+* 列表、详情等读请求使用 Query 缓存
+* 变更成功后按资源粒度失效缓存
+* 不在组件中手写大量重复刷新逻辑
+
+---
+
+## 11. 风险与注意事项
+
+### 11.1 部署风险
+
+风险：Next.js 默认模式倾向 Node 运行，与当前 Go 嵌入式静态托管模式存在差异。
+
+控制措施：
+
+* 首期坚持静态导出优先
+* 在工程初始化阶段先验证构建产物与当前发布链路
+
+### 11.2 鉴权风险
+
+风险：现有登录态依赖后端体系，新前端若误用纯前端 Token 模式，可能破坏当前登录逻辑。
+
+控制措施：
+
+* 保持与现有 Session/Cookie 机制兼容
+* 不单独引入新的认证中心
+
+### 11.3 范围膨胀风险
+
+风险：UI 改造过程中顺带重写接口、模型或业务流程，导致项目失控。
+
+控制措施：
+
+* 首期只做前端体验、结构与规范升级
+* 后端只做前端接入所需的最小兼容调整
+
+### 11.4 双系统并行风险
+
+风险：旧前端与新前端长期并存，导致维护成本升高。
+
+控制措施：
+
+* 采用模块迁移清单和阶段性切换策略
+* 明确切换节点和旧代码下线窗口
+
+---
+
+## 12. 交付物清单
+
+本次专项规划建议至少产出以下交付物：
+
+1. 前端改造计划（本文档）
+2. 前端开发规范文档
+3. 新前端目录结构与脚手架
+4. UI 组件清单与页面设计稿
+5. 构建/部署切换说明
+6. 回归测试清单
+
+---
+
+## 13. 建议的近期执行顺序
+
+建议按以下顺序推进：
+
+1. 先确认 Next.js 静态导出与 Go 托管的兼容方案
+2. 再初始化新前端工程与基础规范
+3. 然后优先迁移核心主链路页面
+4. 最后完成设置、用户、文件等边缘模块与切换上线
+
+建议首批优先落地页面：
+
+* 节点管理
+* 反代规则
+* 配置版本
+* 运维设置
+
+这些页面最能直接体现新 UI 改造价值，也最贴近当前 V3 主链路。