diff --git a/docs/design.md b/docs/design.md index e19a06bf..3a47f160 100644 --- a/docs/design.md +++ b/docs/design.md @@ -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. 文档维护原则 + +后续只维护当前有效基线： + +* 产品范围或系统边界变化时更新本文档 +* 已完成阶段的步骤不再回填为长期计划 +* 新阶段开始前，先补设计，再进入实现 diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md index 59416a66..1b462e84 100644 --- a/docs/development-guidelines.md +++ b/docs/development-guidelines.md @@ -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` diff --git a/docs/development-plan.md b/docs/development-plan.md index c50afd1e..7e3da8d3 100644 --- a/docs/development-plan.md +++ b/docs/development-plan.md @@ -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. 新需求进入条件 + +满足以下任一情况时，才需要新增计划项： + +* 引入新的核心业务对象或系统边界 +* 引入新的基础设施依赖 +* 调整部署模式或运行方式 +* 大规模重构前后端主干结构 + +否则默认按常规开发任务处理，不再单独维护阶段计划。 diff --git a/docs/frontend-development-guidelines.md b/docs/frontend-development-guidelines.md index 0f52e04d..b0556a15 100644 --- a/docs/frontend-development-guidelines.md +++ b/docs/frontend-development-guidelines.md @@ -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 托管 +* 新页面与新组件默认同时通过亮色与暗色模式验收 diff --git a/docs/frontend-revamp-plan.md b/docs/frontend-revamp-plan.md index 7512b267..eb4f9eec 100644 --- a/docs/frontend-revamp-plan.md +++ b/docs/frontend-revamp-plan.md @@ -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) +* 若后续再次调整前端架构、部署模式或技术基线，再新增专项计划文档