mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-05 07:26:36 +08:00
[文档] 文档更新
This commit is contained in:
ryan
+66
-441
@@ -1,443 +1,68 @@
|
||||
# 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` 等 | 统一认证页视觉与表单规范 |
|
||||
# ATSFlare 前端改造说明
|
||||
|
||||
说明：
|
||||
## 1. 当前状态
|
||||
|
||||
* 路由命名统一使用单数英文资源名。
|
||||
|
||||
---
|
||||
|
||||
## 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 主链路。
|
||||
前端改造已完成，`atsf_server/web` 的 Next.js 新版工程已经成为正式管理端基线。
|
||||
|
||||
当前结论：
|
||||
|
||||
* 旧版 CRA + Semantic UI 方案已退出基线
|
||||
* 新版前端继续由 Go Server 以静态资源方式托管
|
||||
* 前端改造过程中的阶段计划、迁移顺序与风险清单不再继续维护
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前前端基线
|
||||
|
||||
新版管理端位于 `atsf_server/web`，当前基线为：
|
||||
|
||||
* Next.js 15 App Router
|
||||
* React 19
|
||||
* TypeScript
|
||||
* Tailwind CSS 4
|
||||
* TanStack Query
|
||||
* React Hook Form + Zod
|
||||
* Zustand（仅限轻量客户端状态）
|
||||
* Vitest + Playwright
|
||||
|
||||
工程与运行方式：
|
||||
|
||||
* `next build` 后生成静态导出产物
|
||||
* 构建后通过现有流程交由 `atsf_server` 托管
|
||||
* 登录态继续兼容现有 Session/Cookie 体系
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前结构约束
|
||||
|
||||
新版前端保持以下结构：
|
||||
|
||||
* `app/`：路由与布局
|
||||
* `features/`：业务模块
|
||||
* `components/`：复用组件
|
||||
* `lib/`：请求、环境、工具、常量
|
||||
* `store/`：少量跨页面 UI 状态
|
||||
* `tests/`：前端测试
|
||||
|
||||
当前已覆盖的主要页面包括：
|
||||
|
||||
* 首页
|
||||
* 反代规则
|
||||
* 配置版本
|
||||
* 节点管理
|
||||
* 应用记录
|
||||
* 域名管理
|
||||
* TLS 证书
|
||||
* 用户管理
|
||||
* 设置
|
||||
* 登录、注册、重置密码、GitHub OAuth、关于页
|
||||
|
||||
---
|
||||
|
||||
## 4. 后续维护原则
|
||||
|
||||
后续不再按“前端改造专项”推进，而按正式前端工程进行维护：
|
||||
|
||||
* 新前端开发统一遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)
|
||||
* 涉及项目级约束时，同时遵循 [docs/development-guidelines.md](./development-guidelines.md)
|
||||
* 若后续再次调整前端架构、部署模式或技术基线，再新增专项计划文档
|
||||
|
||||
Reference in New Issue
Block a user