tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 14:06:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

[文档] 文档更新

Browse Source
This commit is contained in:
ryan
2026-03-11 22:31:12 +08:00
parent ad59ea31fc
commit ca1c147dfe
5 changed files with 904 additions and 1981 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design.md
+234 -470
View File
@@ -1,474 +1,238 @@
# ATSFlare 设计基线（V3）
## 1. 文档目的
本文档保留当前系统边界、稳定约束与第三版的设计输入。
当前结论：
* 第一版、第二版已完成并进入归档状态
* 第三版进入实施阶段
* 当前代码库的可运行能力，以本文档为唯一设计基线
---
## 2. 当前产品定位
ATSFlare 当前仍定位为**内部自用的反向代理控制面**，不是面向外部租户的 CDN SaaS。
当前已经具备的核心能力：
* 反代规则管理
* 配置渲染、发布、激活与回滚
* Agent 心跳、同步、应用结果上报
# ATSFlare 设计基线
## 1. 文档目的
本文档只保留 ATSFlare 当前有效的产品边界、系统结构与稳定约束。
当前状态：
* 第一版、第二版、第三版均已完成
* 前端改造已完成，`atsf_server/web` 新版工程已成为正式基线
* 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计
---
## 2. 产品定位
ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
当前核心能力：
* 反代规则管理
* 配置预览、发布、激活与回滚
* Agent 注册、心跳、同步、应用结果上报
* Nginx 配置写入、校验、reload 与失败回滚
* HTTPS/TLS 路由支持
* 证书托管与域名管理
* 节点预创建、节点专属 `agent_token`、全局 `discovery_token`
* 配置预览与变更摘要
* 节点管理、节点专属 `agent_token`、全局 `discovery_token`
* 配置变更摘要
* Agent 运行参数下发
* Agent 自我更新与一键部署
* Server 版本检查与自升级
当前默认工作方式：
* 所有节点消费同一份全局激活版本
* 控制面保存状态与配置，不直接 SSH 管理机器
* Agent 是节点侧唯一落地入口
---
## 3. 明确保持不做的范围
在第三版目标明确前，以下内容仍视为范围外：
* 多租户
* WAF、限流、Bot、防刷
* 节点分组、差异化下发、灰度百分比发布
* Redis、消息队列、对象存储、Prometheus
* 复杂缓存策略、分层缓存、mid-tier
* 证书自动签发与自动续期
* 审批流、审计中台、Purge 平台化能力
* 抽象 `zone`、`origin_pool`、`policy`、`deployment` 等平台对象
如果第三版需要引入以上任一能力，必须先补设计，再进入实现。
---
## 4. 技术基线
### 4.1 Server
基于 `atsf_server` 单体应用继续演进：
* Web 框架：Gin
* ORM：GORM
* 数据库：SQLite
* 管理端前端：`atsf_server/web`
* 用户鉴权：沿用现有 ATSFlare 登录体系
默认不以新基础设施为前提：
* 不依赖 Redis
* 不依赖 MQ
* 不依赖外部对象存储
### 4.2 Agent
基于 `atsf_agent` Go 单体程序继续演进：
* 单二进制
* 节点本地执行
* 优先使用独立 Nginx
* 显式配置 `nginx_path` 时直接调用该路径
* 未配置 `nginx_path` 时默认使用 Docker Nginx 容器
* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
### 4.3 Nginx 管理边界
控制面当前只管理以下内容：
* 反向代理路由配置
* 控制面托管证书对应的本地证书文件
仍不管理以下内容：
* `nginx.conf`
* upstream 高级编排
* 复杂缓存策略
* 节点级系统运维逻辑
---
## 5. 当前总体架构
```text
ATSFlare Server (Gin + SQLite + Web UI)
|
| HTTP API / Config Pull
v
ATSFlare Agent (heartbeat / sync / apply / report)
|
v
Local Nginx or Docker Nginx
|
v
Origin
```
设计原则保持不变：
* Server 负责配置、版本、节点状态
* Agent 负责本地落盘、校验、reload、回滚
* 发布通过“生成新版本并激活”完成
* 历史版本不可变
---
## 6. 核心对象
### 6.1 `proxy_routes`
表示一条 `domain -> origin_url` 的反向代理规则。
关键字段：
* `domain`
* `origin_url`
* `enabled`
* `enable_https`
* `cert_id`
* `redirect_http`
* `custom_headers`
* `remark`
约束：
* 一个域名只对应一个源站
* `domain` 必须唯一
* `origin_url` 必须是合法的 `http://` 或 `https://`
### 6.2 `config_versions`
表示一次完整发布快照。
关键字段：
* `version`
* `snapshot_json`
* `rendered_config`
* `checksum`
* `is_active`
* `created_by`
约束：
* 每个版本保存完整快照与渲染结果
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
### 6.3 `nodes`
表示节点运行状态与接入凭证。
关键字段：
* `node_id`
* `name`
* `ip`
* `status`
* `current_version`
* `last_seen_at`
* `last_error`
* `agent_token`
约束：
* 节点专属 `agent_token` 由 Server 生成并持久化
* 删除节点后，其凭证必须立即失效
* 全局 `discovery_token` 不存放在 `nodes` 表中
### 6.4 `apply_logs`
记录节点应用版本的结果。
关键字段：
* `node_id`
* `version`
* `result`
* `message`
* `created_at`
### 6.5 `tls_certificates`
表示控制面托管的证书与私钥。
关键字段：
* `name`
* `cert_pem`
* `key_pem`
* `not_before`
* `not_after`
* `remark`
### 6.6 `managed_domains`
表示域名资产及其默认证书关系。
关键字段：
* `domain`
* `cert_id`
* `enabled`
* `remark`
约束：
* 支持精确域名与 `*.example.com` 通配符域名
* 证书匹配同时支持精确匹配与通配符匹配
---
## 7. 当前发布模型
标准链路：
```text
修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
```
发布规则：
1. 读取全部启用的 `proxy_routes`
2. 渲染完整 Nginx 配置
3. 计算 `checksum`
4. 写入 `config_versions`
5. 切换激活版本
6. Agent 在下一轮同步中发现并应用
版本规则：
* 版本号格式：`YYYYMMDD-NNN`
* 版本不可变
* 节点只拉取当前激活版本
---
## 8. 当前模块边界
### 8.1 `atsf_server`
负责：
* 管理端 UI 与 API
* Agent API
* 数据存储
* 配置渲染
* 发布与激活
* 节点状态展示
### 8.2 `atsf_agent`
负责：
* 首次注册与凭证置换
* 周期性心跳
* 拉取激活版本
* 写入本地路由与证书文件
* 执行 `nginx -t` / `nginx -s reload`
* 失败回滚
* 上报应用结果
### 8.3 `atsf_server/web`
负责：
* 规则、版本、节点、应用记录页面
* 证书与域名管理页面
* 发布前预览与变更摘要展示
---
## 9. 当前接口域
为控制文档长度，仅保留接口域，不再逐条展开历史接口清单。
管理端接口当前覆盖：
* `proxy-routes`
* `config-versions`
* `nodes`
* `apply-logs`
* `tls-certificates`
* `managed-domains`
Agent 接口当前覆盖：
* 注册
* 心跳
* 获取激活版本
* 上报应用结果
统一约束：
* 管理端与 Agent API 均使用 JSON
* Agent API 固定放在 `/api/agent/*`
* Agent 鉴权使用 `X-Agent-Token`
## 10. 文档策略
第一版、第二版的详细实施过程不再在本文档中长期保留。
后续原则：
* 设计文档只保留当前有效基线
* 已完成阶段的细节以 Git 历史为准
* 新阶段开始前，先把设计输入写清楚，再进入实现
---
## 11. 第三版设计输入
### 11.1 目标定位
第三版聚焦**运维体验优化**，不扩展系统功能边界，只提升已有能力的可操作性与可维护性。
### 11.2 启动设置热更新
当前状态：
* `SESSION_SECRET`、`SQLITE_PATH`、`PORT` 等启动参数通过环境变量注入
* 变更需要重启 Server 进程
第三版变更：
* 将可热更新的运行时设置迁入 Option 表，通过设置页面管理
* 以下设置在前端运维设置面板中可配置：
* `AgentHeartbeatInterval`：Agent 心跳上报间隔（毫秒），默认 30000
* `AgentSyncInterval`：Agent 配置同步间隔（毫秒），默认 30000
* `NodeOfflineThreshold`：节点离线判定阈值（毫秒），默认 120000
* `AgentUpdateRepo`：Agent 自动更新 GitHub 仓库地址，默认 `Rain-kl/ATSFlare`
* `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration`：全局 API 限流次数与窗口（秒）
* `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration`：全局 Web 限流次数与窗口（秒）
* `UploadRateLimitNum` / `UploadRateLimitDuration`：上传接口限流次数与窗口（秒）
* `DownloadRateLimitNum` / `DownloadRateLimitDuration`：下载接口限流次数与窗口（秒）
* `CriticalRateLimitNum` / `CriticalRateLimitDuration`：登录、注册、验证码等敏感接口限流次数与窗口（秒）
* 环境变量类设置（`SESSION_SECRET`、`SQLITE_PATH`、`PORT`）不迁移，保留原有方式
* 前端在设置页面新增「运维设置」Tab
### 11.3 Server 下发 Agent 设置
当前状态：
* Agent 心跳请求只是单向上报，Server 不返回业务数据
* Agent 的心跳间隔、同步间隔只在本地 `agent.json` 配置
第三版变更：
* 心跳响应新增 `agent_settings` 字段，包含 Server 端可控的运行时参数：
* `heartbeat_interval`（毫秒）
* `sync_interval`（毫秒）
* `auto_update`（节点级布尔值）
* `update_repo`（GitHub 仓库名）
* `update_now`（一次性手动更新指令）
* Agent 收到心跳响应后，动态调整本地定时器间隔
* 当 Server 未返回 `agent_settings` 或字段为空时，Agent 保持本地值不变
* Agent 不持久化 Server 下发的间隔值，重启后以本地 `agent.json` 为准，再由下次心跳覆盖
### 11.4 Agent 自我更新
当前状态：
* Agent 版本固定，更新需要运维手动替换二进制文件
第三版变更：
* Agent 在收到 `auto_update=true` 或 `update_now=true` 时：
* 通过 GitHub Releases API 查询 `update_repo` 的最新 Release
* 比较本地 `agent_version` 与远端 tag
* 若存在更新，下载对应平台的二进制文件
* 替换自身二进制并重启
* 更新检查频率：每轮心跳周期结束后检查一次，不独立起定时器
* 更新过程中不中断当前同步任务
* 更新失败不影响正常心跳与同步
* Agent 二进制文件命名约定：`atsflare-agent-{os}-{arch}`
* `auto_update` 默认关闭，由节点管理页逐节点开启
* `update_now` 由节点管理页手动触发，一次心跳消费一次
### 11.5 Agent 一键部署
当前状态：
* Agent 需要手动编译或复制二进制并创建配置文件
第三版变更：
* 提供 `install-agent.sh` 脚本，支持以下方式部署：
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--discovery-token your-token
```
* 脚本行为：
* 检测平台架构（linux/amd64、linux/arm64）
* 从 GitHub Releases 下载最新 Agent 二进制
* 创建安装目录（默认 `/opt/atsflare-agent`）
* 生成基础 `agent.json` 配置
* 创建 systemd service 文件（可选）
* 启动 Agent
### 11.6 GitHub Actions 内测发布
当前状态：
* 现有工作流只构建 Server 二进制和 Docker 镜像
* Agent 二进制不在 CI 中构建
* Alpha 标签在部分工作流中被排除
第三版变更：
* 新增 `agent-release.yml` 工作流：
* 触发条件：推送任意 tag（包括 alpha）
* 构建 Agent 二进制：`linux/amd64`、`linux/arm64`、`darwin/arm64`
* 产物命名：`atsflare-agent-{os}-{arch}`
* 上传至 GitHub Release
* 修改现有工作流：
* 统一 `linux-release.yml` 为同时构建 Server + Agent 二进制
* Alpha 标签的发布标记为 prerelease
* 安装脚本与自我更新共用同一 Release 产物
### 11.7 前端运维体验优化
当前状态：
* 时间字段使用纳秒整数，不够友好
* 设置页面未包含运维类设置
第三版变更：
* 设置页面新增「运维设置」Tab，包含：
* Agent 心跳间隔
* Agent 同步间隔
* 节点离线阈值
* Agent 更新仓库
* 全局 Discovery Token 展示与重新生成
* Agent 一键部署命令展示（根据当前 ServerAddress 和 DiscoveryToken 动态生成 curl 命令）
* 节点列表页优化：
* 时间显示改为友好的相对时间格式
* 节点状态使用颜色标识
* 支持逐节点开启自动更新
* 支持逐节点手动触发一次 Agent 更新
---
## 12. 第三版不做的范围
以下内容不在第三版范围内：
* 多租户
* WAF、限流、Bot
* 节点分组、差异化下发
* 证书自动签发与续期
* Agent 配置文件加密
* Server 远程执行 Agent 命令
* 新版管理端 UI、主题切换与统一交互框架
默认工作方式：
* 所有节点消费同一份全局激活版本
* 控制面保存配置与状态，不直接 SSH 管理机器
* Agent 是节点侧唯一落地入口
---
## 3. 范围边界
当前明确不做：
* 多租户
* WAF、限流防护平台化、Bot 管理
* 节点分组、灰度百分比发布、按节点差异化下发
* Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖
* 复杂缓存策略、分层缓存、mid-tier
* 证书自动签发与自动续期
* 审批流、审计中台、Purge 平台化能力
* 平台化抽象对象，如 `zone`、`origin_pool`、`policy`、`deployment`
新增能力超出上述边界时，必须先更新本文档，再进入实现。
---
## 4. 技术基线
### 4.1 Server
`atsf_server` 继续作为单体控制面：
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
* 托管 `atsf_server/web` 静态构建产物
### 4.2 Agent
`atsf_agent` 继续作为 Go 单体程序：
* 单二进制
* 节点本地执行
* `nginx_path` 优先
* 未配置 `nginx_path` 时默认使用 Docker Nginx
* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
### 4.3 Frontend
`atsf_server/web` 作为正式管理端前端基线：
* Next.js App Router
* React 19
* TypeScript
* Tailwind CSS
* 静态导出，继续由 Go Server 托管
---
## 5. 总体架构
```text
ATSFlare Server (Gin + SQLite + Web UI)
|
| HTTP API / Config Pull
v
ATSFlare Agent (register / heartbeat / sync / apply / update)
|
v
Local Nginx or Docker Nginx
|
v
Origin
```
职责分工：
* Server 负责配置、版本、节点、设置与管理端 UI
* Agent 负责本地落盘、校验、reload、回滚、自更新
* 发布通过“生成完整版本并激活”完成
* 历史版本不可变
---
## 6. 核心对象
当前有效实体：
* `proxy_routes`：域名到源站的反向代理规则
* `config_versions`：完整发布快照与渲染结果
* `nodes`：节点状态、版本、凭证与 Agent 设置相关状态
* `apply_logs`：节点应用版本结果
* `tls_certificates`：托管证书与私钥
* `managed_domains`：域名资产及默认证书关系
稳定约束：
* 一个域名只对应一个 `origin_url`
* `proxy_routes.domain` 必须唯一
* `origin_url` 必须为合法 `http://` 或 `https://`
* `config_versions` 必须保存完整快照、渲染结果与 `checksum`
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
* 域名与证书匹配同时支持精确匹配与通配符匹配
* 节点专属 `agent_token` 必须可立即失效
---
## 7. 发布模型
标准链路：
```text
修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
```
发布规则：
1. 读取全部启用的 `proxy_routes`
2. 渲染完整 Nginx 配置
3. 计算 `checksum`
4. 写入 `config_versions`
5. 切换激活版本
6. Agent 在后续同步中发现并应用
版本规则：
* 版本号格式：`YYYYMMDD-NNN`
* 版本不可变
* 节点只拉取当前激活版本
---
## 8. 模块边界
### 8.1 `atsf_server`
负责：
* 管理端 UI 与 API
* Agent API
* 数据存储
* 配置渲染
* 发布与激活
* 节点状态与设置管理
### 8.2 `atsf_agent`
负责：
* 首次注册与凭证置换
* 周期性心跳与同步
* 运行参数接收
* 本地路由与证书文件写入
* `nginx -t` / `nginx -s reload`
* 失败回滚
* 自我更新
* 应用结果上报
### 8.3 `atsf_server/web`
负责：
* 管理端页面、布局、交互与主题
* 规则、版本、节点、证书、域名、用户、设置等页面
* 统一请求层与前端状态管理
---
## 9. 接口域
管理端接口当前覆盖：
* `proxy-routes`
* `config-versions`
* `nodes`
* `apply-logs`
* `tls-certificates`
* `managed-domains`
* `users`
* `settings`
* `update`
Agent 接口当前覆盖：
* 注册
* 心跳
* 获取激活版本
* 上报应用结果
统一约束：
* 管理端与 Agent API 均使用 JSON
* Agent API 固定放在 `/api/agent/*`
* Agent 鉴权统一使用 `X-Agent-Token`
---
## 10. 文档维护原则
后续只维护当前有效基线：
* 产品范围或系统边界变化时更新本文档
* 已完成阶段的步骤不再回填为长期计划
* 新阶段开始前，先补设计，再进入实现
docs/development-guidelines.md
+298 -308
View File
@@ -1,308 +1,298 @@
# ATSFlare 开发规范（V3）
## 1. 适用范围
本规范适用于当前代码基线以及第三版的所有开发工作。
当前系统状态：
* 第一版、第二版功能已完成
* 第三版聚焦运维体验优化
* 超出 `docs/design.md` 当前边界的需求，必须先补设计，再编码
---
## 2. 技术基线
### 2.1 Server
`atsf_server` 继续作为单体控制面：
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
* 现有 `atsf_server/web` 前端
约束：
* 默认不依赖 Redis
* 默认不依赖 MQ
* 默认不依赖对象存储
* 不为第三版预埋平台化基础设施
### 2.2 Agent
`atsf_agent` 继续作为 Go 单体程序：
* 单二进制
* 本地执行
* `nginx_path` 优先
* 无 `nginx_path` 时默认 Docker Nginx
* 生成资源默认放在 `./data`，由 `data_dir` 统一覆盖
### 2.3 前端
前端改造专项以 `atsf_server/web` 新版工程为基线：
* 使用 Next.js App Router + TypeScript + Tailwind CSS
* 按 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) 执行目录分层与组件规范
* 首期仍以静态导出产物交由 Go Server 托管为前提
---
## 3. 分层与目录约束
### 3.1 Server 分层
* `controller/`：参数解析、调用 service、返回响应
* `service/`：业务逻辑、校验、渲染、事务编排
* `model/`：模型定义与持久化
* `router/`：路由注册
* `middleware/`：认证、鉴权、限流等横切逻辑
* `common/`：通用配置与工具
禁止：
* 在 `controller/` 堆积业务逻辑
* 在 `middleware/` 中写业务流程
* 为简单需求新增平台层抽象
### 3.2 Agent 分层
保持现有模块边界：
* `config`
* `heartbeat`
* `sync`
* `nginx`
* `state`
* `httpclient`
* `protocol`
要求：
* 每个模块职责单一
* 外部命令调用集中封装
* 状态落盘与配置落盘保持分离
---
## 4. 数据模型规范
当前有效实体：
* `proxy_routes`
* `config_versions`
* `nodes`
* `apply_logs`
* `tls_certificates`
* `managed_domains`
通用约束：
* 不新增平台化对象，除非第三版设计明确要求
* `proxy_routes` 仍保持一条域名对应一个 `origin_url`
* `config_versions` 必须保存完整快照与渲染结果
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
* 域名证书匹配必须同时支持精确匹配与通配符匹配
* 节点专属 `agent_token` 必须可立即失效
新增表或关键字段前，必须先回答两个问题：
1. 是否服务于第三版主链路？
2. 是否能在现有模型上扩展而不是平行造新模型？
---
## 5. API 与鉴权规范
### 5.1 API 约定
* 管理端与 Agent API 统一使用 JSON
* 成功与失败都必须返回清晰 `message`
* 列表接口返回稳定字段
* Agent API 固定放在 `/api/agent/*`
统一响应结构保持现有风格：
```json
{
"success": true,
"message": "",
"data": {}
}
```
### 5.2 鉴权约定
管理端：
* 继续复用 ATSFlare 登录、角色与 session
Agent：
* 正式请求统一使用节点专属 `agent_token`
* 首次接入可使用全局 `discovery_token`
* 请求头统一使用 `X-Agent-Token`
* Agent 认证逻辑不得与用户登录态混用
禁止：
* 将本地 Nginx 操作暴露为远程执行接口
* 在日志中打印完整 Token
---
## 6. 发布与渲染规范
发布逻辑必须保持以下事实：
* 发布时读取全部启用的 `proxy_routes`
* 生成完整 Nginx 配置
* 计算 `checksum`
* 写入 `config_versions`
* 通过切换 `is_active` 激活版本
版本号格式保持：
```text
YYYYMMDD-NNN
```
限制：
* 不做在线改历史版本
* 不做按节点分组的差异化版本
* 预览与 diff 是只读能力，不产生发布记录
---
## 7. Agent 行为规范
Agent 必须满足：
* 启动后读取或生成本地 `node_id`
* 未显式配置 `node_name` 时自动获取主机名
* 未显式配置 `node_ip` 时自动探测本机 IP
* 周期性心跳
* 周期性检查激活版本
* 发现新版本时先备份旧文件
* 写入新路由与必要证书文件
* 先执行 `nginx -t`
* 成功后执行 `nginx -s reload`
* 失败时自动回滚并上报最终结果
* 本地 `agent_token` 为空且存在 `discovery_token` 时，自动注册并完成 Token 置换
容错要求：
* Server 不可用时继续使用旧配置
* 下载失败时不修改本地配置
* 本地状态文件损坏时允许重建，但不能破坏当前生效配置
* Docker 容器异常时，启动阶段应自动重建
V3 新增行为：
* 心跳响应包含 `agent_settings` 时，动态调整定时器间隔
* `auto_update=true` 或 `update_now=true` 时在每次心跳后检查 GitHub Releases 更新
* 自我更新失败不影响心跳与同步
* Server 下发的间隔值不持久化到 `agent.json`，重启后以本地为准
* Agent 新增 `internal/updater` 模块处理自我更新逻辑
---
## 8. 前端开发规范
要求：
* 新前端页面、组件与请求层统一遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)
* API 请求统一收敛到 `atsf_server/web/lib/api/`
* 页面路由与布局放在 `app/`，业务逻辑放在 `features/`
* 构建产物必须保持可被 Go Server 静态托管
* 新前端必须支持亮色 / 暗色模式切换，且主题能力不得只停留在局部页面或单个组件
如果第三版要新增页面，优先原则：
* 能复用现有 feature 结构就不平行再造一套页面逻辑
* 能复用统一表单、反馈与布局组件就不在页面中重复实现
---
## 9. 代码风格与日志规范
### 9.1 Go
* 错误必须显式处理
* 函数尽量单一职责
* 输入校验放在边界层
* 业务枚举使用明确常量
* 不写无意义注释
### 9.2 命名
* 统一使用 `route`、`version`、`node`、`agent`
* 不混用 `client`、`edge`、`worker` 指代 Agent
### 9.3 日志
必须覆盖关键事件：
* 发布成功/失败
* Agent 注册
* 心跳异常
* 配置下载失败
* Nginx 校验或 reload 成功/失败
* 回滚触发
要求：
* 日志要足够定位问题
* 不打印敏感凭证完整值
---
## 10. 测试与验收规范
当前基线至少要持续覆盖：
* 路由校验与渲染
* 激活版本切换
* 节点在线状态判定
* 证书导入与匹配
* 自定义请求头渲染
* Agent 同步、回滚、本地状态读写
* 自动注册与 Token 置换
* 预览与 diff 的只读行为
第三版新增需求时：
* 先补单元测试或服务层测试
* 再补联调验证步骤
* 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试
---
## 11. 文档维护规范
出现以下情况必须同步更新文档：
* 第三版范围确定或变更
* API 出现破坏性变更
* 数据模型新增、删除或关键语义变化
* Agent 本地文件结构变化
* 部署方式变化
* 新增基础设施依赖
更新顺序：
1. `docs/design.md`
2. `docs/development-guidelines.md`
3. `docs/development-plan.md`
4. `docs/deployment.md`
## 12. Swagger 文档约束
* Server 提供 Swagger UI 入口：`/swagger/index.html`
* Swagger UI 仅对已登录的管理端用户开放，不向匿名用户公开
* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `atsf_server/docs`
# ATSFlare 开发规范
## 1. 适用范围
本规范适用于当前代码基线下的所有 Server、Agent 与管理端前端开发工作。
当前状态：
* 第一版、第二版、第三版已完成
* `docs/design.md` 是当前系统边界的唯一设计基线
* `atsf_server/web` 新版前端已完成迁移并成为正式基线
超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。
---
## 2. 技术基线
### 2.1 Server
`atsf_server` 继续作为单体控制面：
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
约束：
* 默认不引入 Redis、MQ、对象存储等新基础设施
* 不为未确认的平台化能力预埋复杂抽象
### 2.2 Agent
`atsf_agent` 继续作为 Go 单体程序：
* 单二进制
* 节点本地执行
* `nginx_path` 优先
* 无 `nginx_path` 时默认 Docker Nginx
* 生成资源默认写入 `./data`，由 `data_dir` 统一覆盖
### 2.3 Frontend
新版前端基线以当前 `atsf_server/web` 实现为准：
* Next.js 15 App Router
* React 19
* TypeScript
* Tailwind CSS 4
* TanStack Query
* React Hook Form + Zod
* Zustand（仅限轻量客户端状态）
* 静态导出并由 Go Server 托管
前端详细约束统一以 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md) 为准；本文件只保留跨项目层面的强约束。
---
## 3. 分层与目录约束
### 3.1 Server
* `controller/`：参数解析、调用 service、返回响应
* `service/`：业务逻辑、校验、渲染、事务编排
* `model/`：模型定义与持久化
* `router/`：路由注册
* `middleware/`：认证、鉴权、限流等横切逻辑
* `common/`：配置与通用工具
禁止：
* 在 `controller/` 堆积业务逻辑
* 在 `middleware/` 中实现业务流程
* 为简单需求新增平台层抽象
### 3.2 Agent
保持现有模块边界：
* `config`
* `heartbeat`
* `sync`
* `nginx`
* `state`
* `httpclient`
* `protocol`
* `internal/updater`
要求：
* 每个模块职责单一
* 外部命令调用集中封装
* 状态落盘与配置落盘分离
### 3.3 Frontend
前端分层与目录必须与当前工程保持一致：
* `app/`：路由、布局、页面组装
* `features/`：业务模块
* `components/`：跨模块复用组件
* `lib/`：请求、环境、工具、常量
* `store/`：少量跨页面 UI 状态
* `types/`：共享类型
要求：
* 页面路由与布局放在 `app/`
* API 请求统一收敛到 `lib/api/`
* 业务逻辑优先放在 `features/`
* 不重新引入旧版 CRA / Semantic UI 结构
---
## 4. 数据模型规范
当前有效实体：
* `proxy_routes`
* `config_versions`
* `nodes`
* `apply_logs`
* `tls_certificates`
* `managed_domains`
通用约束：
* 不新增平台化对象，除非设计文档明确要求
* `proxy_routes` 仍保持一条域名对应一个 `origin_url`
* `config_versions` 必须保存完整快照与渲染结果
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
* 域名证书匹配必须同时支持精确匹配与通配符匹配
* 节点专属 `agent_token` 必须可立即失效
---
## 5. API 与鉴权规范
### 5.1 API
* 管理端与 Agent API 统一使用 JSON
* 成功与失败都必须返回清晰 `message`
* 列表接口返回稳定字段
* Agent API 固定放在 `/api/agent/*`
统一响应结构保持现有风格：
```json
{
"success": true,
"message": "",
"data": {}
}
```
### 5.2 鉴权
管理端：
* 继续复用 ATSFlare 登录、角色与 session
Agent：
* 正式请求统一使用节点专属 `agent_token`
* 首次接入可使用全局 `discovery_token`
* 请求头统一使用 `X-Agent-Token`
* Agent 认证逻辑不得与用户登录态混用
禁止：
* 将本地 Nginx 操作暴露为远程执行接口
* 在日志中打印完整 Token
---
## 6. 发布与运行规范
发布逻辑必须保持以下事实：
* 发布时读取全部启用的 `proxy_routes`
* 生成完整 Nginx 配置
* 计算 `checksum`
* 写入 `config_versions`
* 通过切换 `is_active` 激活版本
版本号格式保持：
```text
YYYYMMDD-NNN
```
限制：
* 不在线修改历史版本
* 不做按节点分组的差异化版本
* 预览与 diff 是只读能力，不产生发布记录
Agent 必须满足：
* 启动后读取或生成本地 `node_id`
* 未显式配置 `node_name` 时自动获取主机名
* 未显式配置 `node_ip` 时自动探测本机 IP
* 周期性心跳与同步
* 发现新版本时先备份旧文件
* 写入新路由与必要证书文件
* 先执行 `nginx -t`
* 成功后执行 `nginx -s reload`
* 失败时自动回滚并上报最终结果
* 支持自动注册与 Token 置换
* 支持接收 Server 下发运行参数
* 支持自我更新，但失败不影响心跳与同步
---
## 7. 前端约束
前端新增开发必须遵循 [docs/frontend-development-guidelines.md](./frontend-development-guidelines.md)，其中以下要求属于项目级强约束：
* 页面与布局放在 `app/`，业务逻辑放在 `features/`
* 请求统一通过 `lib/api/`
* 构建产物必须保持可被 Go Server 静态托管
* 主题能力必须覆盖布局、基础组件与业务页面
* 不引入新的大型 UI 框架与旧式页面结构
---
## 8. 代码风格与日志
### 8.1 Go
* 错误必须显式处理
* 函数尽量单一职责
* 输入校验放在边界层
* 业务枚举使用明确常量
* 不写无意义注释
### 8.2 命名
* 统一使用 `route`、`version`、`node`、`agent`
* 不混用 `client`、`edge`、`worker` 指代 Agent
### 8.3 日志
必须覆盖关键事件：
* 发布成功/失败
* Agent 注册
* 心跳异常
* 配置下载失败
* Nginx 校验或 reload 成功/失败
* 回滚触发
要求：
* 日志足够定位问题
* 不打印敏感凭证完整值
---
## 9. 测试与验收
基线回归至少覆盖：
* 路由校验与渲染
* 激活版本切换
* 节点在线状态判定
* 证书导入与匹配
* 自定义请求头渲染
* Agent 同步、回滚、本地状态读写
* 自动注册与 Token 置换
* Agent 设置下发与更新链路
* 预览与 diff 的只读行为
新增需求时：
* 先补单元测试或服务层测试
* 再补联调验证步骤
* 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试
---
## 10. 文档维护
出现以下情况必须同步更新文档：
* 产品范围或系统边界变化：更新 `docs/design.md`
* 开发约束、接口约定、前后端分层变化：更新本文件
* 前端目录分层、请求层、主题体系变化：更新 `docs/frontend-development-guidelines.md`
* 部署方式变化：更新 `docs/deployment.md` 和 `README.md`
* 环境变量或配置项变化：更新 `docs/app-config.md`
## 11. Swagger 约束
* Server 提供 Swagger UI 入口：`/swagger/index.html`
* Swagger UI 仅对已登录的管理端用户开放
* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `atsf_server/docs`
docs/development-plan.md
+57 -177
View File
@@ -1,179 +1,59 @@
# ATSFlare 开发计划（V3）
## 1. 当前状态
当前结论：
* 第一版已完成并稳定闭环
* 第二版已完成并补齐 HTTPS、证书、域名、节点管理与预览能力
* 第三版进入实施阶段，聚焦运维体验优化
本文件不再展开第一版、第二版的详细实施步骤，只保留第三版实施计划与验收标准。
---
## 2. 已完成能力归档
### 2.1 第一版归档
已完成：
* 规则管理
* 配置发布与激活
* Agent 心跳、同步、应用、回滚
* 节点状态与应用记录展示
### 2.2 第二版归档
已完成：
* HTTPS/TLS 路由支持
* 证书托管与导入
* 域名管理与证书自动匹配
* 节点管理、专属 `agent_token`、全局 `discovery_token`
* 路由自定义请求头
* 配置预览与变更摘要
归档原则：
* 已完成阶段的实现细节以代码和 Git 历史为准
* 后续计划文档只维护当前阶段与下一阶段
---
## 3. 第三版实施计划
### 3.1 阶段一：Server 运维设置热更新
目标：将可热更新的运维相关设置迁入 Option 表，前端提供设置面板。
实施步骤：
1. 在 `common/constants.go` 新增运维设置变量：
* `AgentHeartbeatInterval`（默认 30000ms）
* `AgentSyncInterval`（默认 30000ms）
* `NodeOfflineThreshold`（默认 120000ms）
* `AgentUpdateRepo`（默认 `Rain-kl/ATSFlare`）
* `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration`
* `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration`
* `UploadRateLimitNum` / `UploadRateLimitDuration`
* `DownloadRateLimitNum` / `DownloadRateLimitDuration`
* `CriticalRateLimitNum` / `CriticalRateLimitDuration`
2. 在 `model/option.go` 的 `InitOptionMap()` 注册新选项
3. 在 `model/option.go` 的 `updateOptionMap()` 增加对新选项的同步
4. 修改 `service/agent.go` 中 `computeNodeStatus()` 使用动态 `NodeOfflineThreshold`
5. 前端设置页新增「运维设置」Tab
验收标准：
* 运维设置在设置页面可查看和修改
* 修改后立即生效，无需重启 Server
* `NodeOfflineThreshold` 变更后节点状态判定使用新阈值
* 限流阈值与时间窗口可在设置页调整，并即时影响对应中间件
### 3.2 阶段二：Server 下发 Agent 设置 + Agent 接收
目标：心跳响应携带 `agent_settings`，Agent 动态调整运行参数。
实施步骤：
1. Server 端：
* 修改 `service/agent.go` 的 `HeartbeatNode()` 返回 `AgentSettings`
* 新增 `AgentSettings` 结构体
* 修改 `controller/agent.go` 心跳接口返回 `agent_settings`
2. Agent 端：
* 修改 `protocol/agent_api.go` 新增 `HeartbeatResponse` 和 `AgentSettings`
* 修改 `httpclient/client.go` 解析心跳响应
* 修改 `heartbeat/service.go` 返回 `HeartbeatResponse`
* 修改 `agent/runner.go` 根据响应动态调整 `heartbeatTicker` 和 `syncTicker`
验收标准：
* Server 心跳响应 JSON 中包含 `agent_settings`
* Agent 收到新间隔后在下一个周期生效
* Agent 重启后恢复 `agent.json` 配置，再由心跳覆盖
* Server 未配置时 Agent 保持本地值不变
### 3.3 阶段三：Agent 自我更新
目标：Agent 支持从 GitHub Releases 自动更新。
实施步骤：
1. Agent 新增 `internal/updater` 模块：
* GitHub Releases API 查询最新版本
* 版本比较（语义化版本）
* 下载对应平台二进制
* 替换自身并重启（exec syscall）
2. 在 `runner.go` 心跳循环中集成更新检查
3. 更新触发条件：节点 `auto_update=true` 或收到一次性 `update_now=true` 且存在新版本
验收标准：
* Agent 能正确检测新版本
* 能下载并替换自身二进制
* 更新后自动重启并恢复心跳
* 默认不自动更新，需由控制面板逐节点开启或手动触发
* 更新失败不影响正常运行
### 3.4 阶段四：GitHub Actions 完善与 Agent 一键部署
目标：CI 支持 Agent 构建发布，提供 curl 一键安装。
实施步骤：
1. 新增 `.github/workflows/agent-release.yml`
2. 修改现有工作流支持 alpha/prerelease
3. 创建 `scripts/install-agent.sh` 安装脚本
4. 前端运维设置面板展示动态 curl 部署命令
验收标准：
* 推送 tag 后 Agent 二进制出现在 GitHub Release
* Alpha tag 标记为 prerelease
* curl 命令可在干净 Linux 机器上完成 Agent 部署
* 前端正确展示拼接后的 curl 命令
### 3.5 阶段五：前端体验优化
目标：优化管理端操作体验。
实施步骤：
1. 节点列表时间显示改为友好格式
2. 节点状态颜色标识
3. 节点专属 Agent 部署命令改为节点列表弹窗展示
4. 版本检查入口迁移到顶栏“版本”，支持可升级提示与 Server 自升级
# ATSFlare 开发计划
验收标准：
## 1. 当前阶段
* 时间显示为友好的相对时间（如「2 分钟前」）
* 节点状态有颜色区分：在线（绿色）、离线（红色）、待接入（黄色）
* 节点列表可弹窗查看并复制节点专属部署命令
* 顶栏版本入口可检查 GitHub 最新 Release，并在存在新版本时显示可升级提示
* Root 用户可从顶栏版本弹窗触发 Server 自升级
### 3.6 并行专项：管理端前端工程改造
目标：按 [docs/frontend-revamp-plan.md](./frontend-revamp-plan.md) 推进新版管理端重建，不阻塞 Server/Agent 主链路。
实施约束：
1. 前端专项按独立阶段推进，当前从“阶段 1：工程初始化”开始执行
2. 首期产物必须保持静态导出，并继续由 `atsf_server` 托管
3. 认证迁移、业务模块迁移与最终切换按 `docs/frontend-revamp-plan.md` 的阶段顺序执行
验收标准：
* 新前端可本地开发、可静态构建
* Go Server 可继续托管新版构建产物
* 前端专项与现有第三版主链路互不破坏
---
## 4. 阶段执行原则
* 每个阶段完成后验证验收标准，再进入下一阶段
* 阶段间的代码不相互依赖时可并行
* 每个阶段完成后运行全量测试
* 管理端前端改造按 [docs/frontend-revamp-plan.md](./frontend-revamp-plan.md) 单独跟踪阶段状态
当前结论：
* 第一版已完成并稳定运行
* 第二版已完成并补齐 HTTPS、证书、域名、节点与预览能力
* 第三版已完成，运维体验优化相关能力已经落地
* 前端改造已完成，新版管理端已经切换为正式基线
本文件不再维护已完成版本的阶段拆解，只保留当前状态与后续执行原则。
---
## 2. 已完成范围归档
### 2.1 已完成能力
* 规则管理、配置发布、激活、回滚
* Agent 注册、心跳、同步、应用、回滚
* HTTPS/TLS 路由、证书托管、域名管理
* 节点管理、专属 `agent_token`、全局 `discovery_token`
* 配置预览、变更摘要、自定义请求头
* 运维设置热更新
* Server 下发 Agent 运行参数
* Agent 自我更新与一键部署
* Server 版本检查与自升级
* 新版前端工程、主题切换与统一页面框架
### 2.2 归档原则
* 已完成阶段的实现细节以代码与 Git 历史为准
* 不再为已完成工作维护过程性计划、迁移步骤或分阶段验收清单
* 新的大功能阶段启动前，再补充新的计划文档
---
## 3. 当前执行原则
后续开发以维护和增量优化为主，执行时遵循：
* 先遵守 `docs/design.md` 的系统边界
* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md`
* 需求不改变边界时，直接按现有模型与结构增量实现
* 需求改变边界时，先补设计，再补计划，再编码
---
## 4. 新需求进入条件
满足以下任一情况时，才需要新增计划项：
* 引入新的核心业务对象或系统边界
* 引入新的基础设施依赖
* 调整部署模式或运行方式
* 大规模重构前后端主干结构
否则默认按常规开发任务处理，不再单独维护阶段计划。
docs/frontend-development-guidelines.md
+249 -585
View File
@@ -1,589 +1,253 @@
# 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
要求：
* 默认使用 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 路由命名
# ATSFlare 前端开发规范
## 1. 适用范围
本文档约束 `atsf_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
当前状态：
* 前端改造已完成
* 本文档描述的是现行正式基线，不再维护迁移期约束
---
## 2. 技术基线
前端默认技术栈：
* Next.js 15（App Router）
* React 19
* TypeScript 5
* Tailwind CSS 4
* TanStack Query
* React Hook Form + Zod
* Zustand（仅限轻量客户端状态）
* ESLint + Prettier
* Vitest + Testing Library + Playwright
* pnpm
要求：
* 使用英文小写单数资源名
* 使用语义清晰的层级结构
* 默认使用 TypeScript，不新增 JS 页面模块
* 默认使用函数组件，不新增 class 组件
* 默认使用 App Router，不新建 Pages Router 结构
* 默认使用 Tailwind CSS 与现有设计 token 体系
* 前端必须支持 `light`、`dark`、`system` 三种主题模式
示例：
禁止：
* `/node`
* `/proxy-route`
* `/config-version`
* `/tls-certificate`
* `/managed-domain`
### 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
至少抽象以下语义：
* 主色、成功色、警告色、危险色
* 边框色、背景色、弱文本色、强文本色
* 圆角、阴影、间距、层级
* 亮色 / 暗色两套语义 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. 未破坏当前后端主链路和部署约束
* 新增 Semantic UI 依赖
* 新增大型 UI 框架，破坏当前组件基线
* 在新模块中继续使用 jQuery 风格 DOM 操作
* 将页面逻辑堆积为单个超大组件
---
## 3. 目录与分层
推荐目录：
```text
app/
components/
features/
lib/
hooks/
store/
types/
styles/
tests/
```
职责约束：
* `app/`：定义路由、组织布局、组装页面
* `features/`：按业务域组织模块
* `components/`：跨 feature 复用组件
* `lib/`：请求客户端、环境变量、工具函数、常量
* `store/`：少量跨页面 UI 状态
* `types/`：共享类型定义
禁止：
* 在 `app/` 页面文件里堆积复杂请求逻辑
* 把服务端主数据放进 Zustand
* 将同一业务拆出多套平行结构
---
## 4. 路由与页面
路由命名要求：
* 使用英文小写
* 资源页保持现有单数命名
* 保持与当前路径结构一致
页面文件只负责：
* 获取路由参数
* 组织页面结构
* 调用 feature 组件
页面不应负责：
* 手写复杂 API 细节
* 编写复杂表单校验逻辑
* 维护大量彼此耦合的局部状态
后台页面优先采用统一结构：
1. 标题区
2. 操作区
3. 筛选区
4. 内容区
5. 详情区或弹层
---
## 5. 数据请求与类型
### 5.1 请求层
所有 API 请求必须统一经过 `lib/api/`。
要求：
* 统一处理 `success/message/data` 响应结构
* 统一处理鉴权失效、网络异常、通用错误消息
* 统一维护资源接口与请求路径
禁止：
* 在页面组件中直接调用 `fetch('/api/...')`
* 在多个组件中重复拼接同一接口路径
### 5.2 Query
适用场景：
* 列表查询
* 详情查询
* 配置读取
* 依赖后端的分页、筛选、刷新操作
要求：
* 使用稳定的 query key
* 变更成功后按资源粒度失效缓存
* 列表刷新不要依赖分散的手工 `setState`
### 5.3 类型
要求：
* 开启 TypeScript 严格模式
* 禁止滥用 `any`
* API 响应、表单输入、业务实体必须有明确类型
* 枚举、状态、日期字段建立明确类型边界
---
## 6. 表单与交互
统一使用：
* React Hook Form
* Zod
交互要求：
* 必填项明确标识
* 提交中不可重复点击
* 保存成功有明确反馈
* 服务端错误映射到表单或全局提示
高风险操作适用场景：
* 发布配置
* 激活版本
* 删除节点
* 删除证书
* 重置 Token
* 触发更新
要求：
* 必须有二次确认
* 必须展示操作对象名称
* 必须明确成功与失败反馈
---
## 7. 样式与主题
样式原则：
* 统一使用 Tailwind CSS 与现有 token 体系
* 优先复用已有基础组件与布局组件
* 页面视觉风格统一、层级清晰、留白一致
主题要求：
* 同时支持 `light`、`dark`、`system`
* 用户手动选择后必须持久化
* 刷新、重新进入页面、路由切换后保持一致
* 首屏尽量避免主题闪烁
* 布局层、导航层、基础卡片、表单容器必须先满足双主题
禁止：
* 大量硬编码颜色值
* 同一状态在不同页面使用不同颜色语义
* 仅验证单一主题后直接交付
---
## 8. 组件与状态管理
组件分层：
* 基础组件：按钮、输入框、表格、对话框、标签、卡片
* 业务组件：节点状态卡、版本激活按钮、证书上传表单
* 页面组合组件：页面头部、筛选面板、详情弹层
复用原则：
* 先抽象稳定结构，再抽象复杂行为
* 业务组件优先放在 feature 内，确认跨域复用后再上移
状态分类：
* 服务端状态：TanStack Query
* 页面临时状态：组件内部 `useState`
* 跨页面 UI 状态：Zustand
不推荐：
* 用 Zustand 保存服务端列表数据
* 用 Context 代替完整数据层方案
* 页面里堆叠过多耦合本地状态
---
## 9. 反馈、测试与交付
每个页面至少具备：
* 加载态
* 空态
* 错误态
* 成功反馈
测试要求：
* 公共工具、类型转换、主题逻辑补单元测试
* 关键页面交互补组件测试
* 核心主链路补 Playwright 或等效联调验证
交付要求：
* 构建产物保持可静态导出
* 构建结果保持可被 Go Server 托管
* 新页面与新组件默认同时通过亮色与暗色模式验收
docs/frontend-revamp-plan.md
+66 -441
View File
@@ -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)
* 若后续再次调整前端架构、部署模式或技术基线，再新增专项计划文档