tcjlj/OpenFlare

Fork 0

mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 22:06:38 +08:00

Files

T

ryan ad090c9c04 feat: 更新嵌入式文件系统逻辑，支持路径清理和静态资源请求处理，增强前端主题切换能力

2026-03-11 13:32:11 +08:00

14 KiB

Raw Blame History

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
文件管理 /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 工程，采用如下结构：

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：技术方案确认

目标：确认不影响现有部署的前端升级路径。

任务：

确认 Next.js 静态导出模式可满足当前管理端需求
确认构建产物与 Go Server 嵌入目录的衔接方式
确认登录态传递方式、Cookie/Session 兼容方式
确认 API Base URL、构建变量与开发代理方案

验收：

输出最终工程初始化方案
输出环境变量与部署变更清单

阶段 1：工程初始化

目标：建立新的前端基础工程。

任务：

将 atsf_server/web 初始化为 Next.js + TypeScript + Tailwind CSS 项目
接入 ESLint、Prettier、基础测试框架
建立 app/、features/、components/、lib/ 基础结构
完成全局布局、主题变量、基础 UI 组件骨架
建立亮色 / 暗色主题 token 与主题切换基础设施

模式切换补充要求：

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

验收：

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

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

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

任务：

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

验收：

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

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

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

优先顺序：

proxy-routes
config-versions
nodes
managed-domains
tls-certificates
apply-logs

验收：

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

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

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

任务：

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

验收：

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

阶段 5：联调、回归与切换

目标：完成替换上线准备。

任务：

对照现有页面与接口完成功能回归
补齐前端测试与关键页面 E2E
验证静态资源构建、嵌入、发布流程
切换默认前端入口并保留回滚预案

验收：

所有核心页面通过冒烟测试
构建与部署文档可复现
可在必要时快速回退到旧前端版本

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. 交付物清单

本次专项规划建议至少产出以下交付物：

前端改造计划（本文档）
前端开发规范文档
新前端目录结构与脚手架
UI 组件清单与页面设计稿
构建/部署切换说明
回归测试清单

13. 建议的近期执行顺序

建议按以下顺序推进：

先确认 Next.js 静态导出与 Go 托管的兼容方案
再初始化新前端工程与基础规范
然后优先迁移核心主链路页面
最后完成设置、用户、文件等边缘模块与切换上线

建议首批优先落地页面：

节点管理
反代规则
配置版本
运维设置

这些页面最能直接体现新 UI 改造价值，也最贴近当前 V3 主链路。

14 KiB Raw Blame History Unescape Escape

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

1. 文档定位

2. 改造背景

3. 改造目标

3.1 业务目标

3.2 技术目标

3.3 约束目标

4. 推荐目标技术栈

5. 部署与运行策略

5.1 当前约束

5.2 推荐方案

5.3 二期可选演进

6. 目标目录结构

7. 页面迁移映射

8. 实施阶段规划

阶段 0：技术方案确认

阶段 1：工程初始化

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

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

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

阶段 5：联调、回归与切换

9. 页面与交互设计原则

9.1 信息架构

9.2 操作体验

9.3 可视化规范

10. API 与数据层策略

10.1 API 原则

10.2 请求层规范

10.3 缓存策略

11. 风险与注意事项

11.1 部署风险

11.2 鉴权风险

11.3 范围膨胀风险

11.4 双系统并行风险

12. 交付物清单

13. 建议的近期执行顺序

14 KiB

Raw Blame History