# 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`
* 用户管理 `/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-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 主链路。