OpenFlare/docs/frontend-revamp-plan.md

ATSFlare 前端改造计划（Next.js + Tailwind CSS）

1. 文档定位

本文档用于规划 ATSFlare 管理端 UI 改造方案，目标是在不破坏当前 Server/Agent 主链路的前提下，将现有基于 CRA + React + Semantic UI 的前端，升级为基于 Next.js + Tailwind CSS 的现代化管理端。

说明：

• 当前正式基线仍以 docs/design.md、docs/development-guidelines.md、docs/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
• 用户管理 /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 工程，采用如下结构：

atsf_server/web/
  app/
    (public)/
      login/
      register/
      reset/
      oauth/github/
    (dashboard)/
      layout.tsx
      page.tsx
      proxy-route/
      config-version/
      node/
      apply-log/
      managed-domain/
      tls-certificate/
      user/
      setting/
    not-found.tsx
  components/
    ui/
    layout/
    forms/
    tables/
    feedback/
  features/
    auth/
    proxy-route/
    config-version/
    node/
    apply-log/
    managed-domain/
    tls-certificate/
    user/
    setting/
  lib/
    api/
    auth/
    env/
    utils/
    constants/
  hooks/
  store/
  types/
  styles/
  public/
  tests/

分层原则：

• app/ 只负责路由与页面组装
• features/ 承载业务模块
• components/ui/ 承载可复用基础组件
• lib/api/ 统一管理请求封装、错误处理与接口定义
• store/ 只放少量跨页面客户端状态

---

7. 页面迁移映射

建议按“业务模块”而不是“旧文件结构”迁移：

现有路由	目标路由	改造重点
/	/	首页概览卡片、系统状态、公告区域重设计
/proxy-route	/proxy-route	表格、创建/编辑抽屉、发布动作、域名证书联动
/config-version	/config-version	版本列表、diff 预览、激活流程、只读预览体验
/node	/node	节点状态标签、心跳时间、部署命令、更新动作
/apply-log	/apply-log	过滤器、结果状态可视化、分页与详情展示
/managed-domain	/managed-domain	通配符匹配提示、证书绑定状态、启用状态切换
/tls-certificate	/tls-certificate	导入、上传、有效期展示、到期提醒样式
/user	/user	用户列表、角色管理、搜索与编辑体验
/setting	/setting	系统设置、运维设置、个人设置按信息架构重组
/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 组件骨架
5. 建立亮色 / 暗色主题 token 与主题切换基础设施

模式切换补充要求：

• 阶段 1 即完成全局主题模式基础设施，不将模式切换延后到业务页面迁移阶段
• 默认支持“跟随系统”与“用户手动切换”两种模式来源
• 至少支持 light、dark、system 三种主题状态
• 用户手动选择后必须持久化，并在刷新、重新进入页面、路由切换后保持一致
• 首屏渲染应尽量避免主题闪烁，不能出现明显的先亮后暗或先暗后亮跳变
• 布局层、导航层、页面容器、基础卡片、按钮、表单容器等基础骨架必须率先接入双主题 token
• 主题切换实现应基于统一主题上下文或全局主题状态，不允许页面各自维护一套切换逻辑
• 所有新增颜色变量应优先落在语义 token 层，不直接把亮暗配色散落在业务组件中

验收：

• 可本地启动开发环境
• 可生成静态构建产物
• Go Server 可正确托管构建结果
• 亮色 / 暗色主题可切换，且基础布局在两种主题下均可正常显示
• 首次进入页面时可正确应用默认主题策略
• 用户切换主题后刷新页面仍保持所选模式
• 首页、公共布局、后台主框架在 light / dark 下均无明显可读性问题
• 阶段 1 交付的基础组件不依赖单一暗色样式前提

阶段 2：认证与框架层迁移

目标：先完成入口与骨架迁移。

任务：

1. 迁移登录、注册、密码重置、OAuth 回调页面
2. 实现全局布局、侧边栏、顶部导航、面包屑、页面标题体系
3. 建立统一鉴权守卫与未登录跳转逻辑
4. 建立统一消息反馈、加载态、空态、错误态组件

验收：

• 用户可完成登录、退出、进入后台主框架
• 公共骨架稳定可复用

阶段 3：核心业务模块迁移

目标：优先覆盖主链路页面。

优先顺序：

1. proxy-route
2. config-version
3. node
4. managed-domain
5. tls-certificate
6. apply-log

验收：

• 核心主链路页面具备完整增删改查能力
• 关键动作存在明确确认、反馈与错误提示

阶段 4：设置与边缘模块迁移

目标：完成非主链路页面迁移。

任务：

• 迁移 setting、user、about 等模块
• 重构表单项、标签页、操作区布局
• 增加部署命令复制、时间友好显示、状态颜色体系

验收：

• 日常管理操作均可在新前端完成
• 旧前端仅剩兼容兜底价值

---

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 主链路。