OpenFlare/docs/development-plan.md

# ATSFlare 开发计划

## 1. 当前状态

当前结论：

* 第一版至第五版主线能力均已完成
* 已完成阶段的过程性任务不再继续展开维护
* 当前主线切换到第六版（0.6.x）

第六版主目标：

* 为节点增加请求数据采集、资源采集与 heartbeat 上报能力
* 在 Server 侧完成访问分析、趋势计算与聚合查询
* 改造管理端总览页与节点详情页，提升信息密度、数据层次和监控可读性
* 建立可持续扩展的观测数据分层，避免在旧节点模型和旧首页接口上继续补丁式堆功能

---

## 2. 已完成范围压缩归档

已完成能力统一归档为以下几类：

* 反代规则、配置版本、预览、发布、激活、回滚
* Agent 注册、心跳、同步、应用、失败回滚
* HTTPS/TLS、证书托管、域名管理
* 节点管理、令牌体系、部署与更新链路
* OpenResty 性能优化、缓存配置与主配置托管
* 新版管理端前端、主题与统一交互框架

归档原则：

* 第一版至第五版的实施细节以代码与 Git 历史为准
* 本文件只维护当前有效主线，不再保留已完成阶段的过程性拆分
* `docs/improve_plan.md` 继续作为并行整理清单存在，但不覆盖第六版主线优先级

---

## 3. 第六版范围

### 3.1 第六版要做

1. 节点数据采集与上报
   * Agent 在每次 heartbeat 时上报最近周期内的请求数据
   * Agent 同步上报节点系统画像、CPU/内存/存储快照、磁盘 IO、OpenResty 入站/出站流量
   * 新增在线时长、操作系统、内核、架构、CPU 型号、逻辑核数、总内存、磁盘布局等节点维度信息
   * 采集节点健康事件，覆盖离线、OpenResty 不健康、配置未追平、资源逼近阈值和错误率异常

2. 服务端访问分析
   * 基于请求数据计算当前节点 QPS、访问次数、访问人数
   * 统计访问来源分布、访问趋势、状态码分布等核心指标
   * 支持总览维度与节点维度两套查询视图
   * 生成系统整体健康摘要，回答“是否健康、是否有风险、问题集中在哪些节点”

3. 总览页改造
   * 首屏新增世界地图看板，用于展示全部节点分布与在线状态
   * 调整总览信息结构，不再以单一“四卡摘要”作为主布局
   * 增加趋势、分布、Top 榜单、容量风险和异常信号展示
   * 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 ATSFlare 当前系统健康与流量状态

4. 节点详情页改造
   * 第一行重构为三块核心卡片：系统信息、实时资源占用、网络流量监控
   * 第二行展示最近 24 小时历史趋势，至少覆盖 CPU、网络、磁盘 IO
   * 第三行接续当前目标版本与应用记录等运维信息
   * 清理低价值、重复、信息密度低的展示模块

5. 架构可扩展性治理
   * 将节点观测拆分为静态画像、动态快照、窗口聚合、健康事件四类数据
   * 为总览页和节点详情页建立专用聚合接口，不继续依赖旧列表接口临时拼装
   * 控制原始数据保留窗口和聚合粒度，避免后期查询、存储和维护成本失控

### 3.2 第六版不做

* 不引入 Prometheus、ClickHouse、Kafka、ElasticSearch 等新基础设施
* 不建设通用日志检索平台、APM 平台、调用链追踪平台
* 不扩展为 GeoDNS、全球流量调度、节点智能选路系统
* 不做任意自定义报表、任意维度 OLAP 查询或外部 BI 接入

---

## 4. 第六版实施顺序

建议按以下顺序推进：

1. 定义数据模型与 heartbeat 扩展协议
   * 明确系统画像结构、请求数据批次结构、资源快照结构、聚合结果结构与健康事件结构
   * 补齐保留策略、体积限制和失败回退规则

2. 完成 Agent 采集链路
   * 采集请求窗口聚合
   * 采集系统画像与运行时性能指标
   * 采集 OpenResty 入站/出站流量
   * 归并节点健康事件并挂入 heartbeat 上报

3. 完成 Server 入库与分析链路
   * 接收并校验 heartbeat 扩展数据
   * 入库存储系统画像、原始批次、资源快照和健康事件
   * 生成总览页与节点详情页所需聚合统计与系统健康摘要

4. 完成总览页改造
   * 世界地图看板
   * 系统健康摘要区
   * 核心访问指标区
   * 访问趋势与来源分布区
   * 节点状态、配置追平与异常摘要区

5. 完成节点详情页改造
   * 系统信息卡片
   * 实时仪表盘与网络流量卡片
   * 24 小时趋势图
   * 下移并重组当前目标版本、健康事件与应用记录

6. 补齐回归验证
   * Agent 心跳主链路
   * 聚合统计正确性
   * 健康事件触发/恢复正确性
   * 总览页与节点详情页的亮暗主题和空态/错误态

---

## 5. 第六版分阶段计划

### 5.1 阶段一：采集协议与存储落地

目标：

* 打通“节点采集 -> heartbeat 上报 -> Server 接收 -> 入库”主链路

任务：

* 扩展 Agent heartbeat payload
* 新增系统画像、请求数据批次、资源快照和健康事件模型
* 为请求明细、性能快照和聚合统计建立查询入口
* 控制单次 heartbeat 体积，避免影响现有同步稳定性

验收标准：

* 节点可随 heartbeat 成功上报系统画像、请求数据与性能快照
* heartbeat 扩展失败不影响配置同步主链路
* Server 能按节点和时间窗口查询到原始上报数据与健康事件

### 5.2 阶段二：服务端分析与指标计算

目标：

* 形成总览页和节点详情页可直接消费的数据接口

任务：

* 计算当前节点 QPS、访问次数、访问人数
* 计算访问来源分布、访问趋势、状态码分布
* 生成最近 24 小时 CPU、网络、磁盘 IO 趋势数据
* 统一总览级与节点级查询口径
* 生成整体健康摘要与异常节点清单

验收标准：

* 同一时间窗口下总览与节点详情的数据口径一致
* 核心统计字段可被测试覆盖，避免明显统计偏差
* 24 小时趋势查询在现有基线上可接受，不出现明显不可用卡顿
* 首页可直接定位离线、异常、配置落后和容量风险节点

### 5.3 阶段三：总览页改造

目标：

* 让总览页从“摘要入口页”升级为“运营与状态看板页”

任务：

* 实现世界地图节点看板
* 重构首屏布局，减少对称摘要卡片堆叠
* 增加系统健康摘要、趋势图、来源分布、状态码分布、节点异常摘要
* 为地图、趋势和分布图补齐加载态、空态和错误态

验收标准：

* 总览首屏可直接看到全部节点分布
* 总览页能展示比旧版更多的实时、趋势与健康信息
* 页面在桌面和移动端都能稳定显示

### 5.4 阶段四：节点详情页改造

目标：

* 让节点详情页回到运维排障视角，提升信息密度和首屏价值

任务：

* 第一行实现系统信息、实时资源占用、网络流量三块核心卡片
* 系统信息新增操作系统、内核、架构、CPU 型号、在线时长
* 网络流量卡片展示 OpenResty 入站/出站流量，自适应单位
* 第二行实现最近 24 小时 CPU、网络、磁盘 IO 趋势图
* 第三行承接当前目标版本、OpenResty 健康、健康事件与应用记录等现有高价值模块
* 移除低价值重复信息

验收标准：

* 节点详情首屏信息密度明显高于旧版
* 第一屏即可完成系统识别、资源判断和流量判断
* 趋势图可用于观察节点最近 24 小时性能变化

---

## 6. 第六版执行原则

第六版执行时遵循：

* 先遵守 `docs/design.md` 的系统边界
* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md`
* 数据采集优先走 heartbeat 批量上报，不新增独立常驻推流通道
* 前端优先消费服务端聚合结果，不在浏览器做重型统计
* 优先建设新的观测聚合链路，不继续在旧 `nodes` 列表接口与旧首页卡片上补丁式叠加字段
* 总览页与节点详情页都必须同时覆盖加载态、空态、错误态和亮暗主题
* 若第六版实现过程中需要新增基础设施或改变保留策略，必须先更新设计文档

---

## 7. 第六版总体验收标准

完成第六版时至少满足：

* Agent 能在 heartbeat 中稳定上报请求数据、系统信息和性能快照
* Server 能基于上报数据计算 QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码统计
* Server 能稳定生成系统健康摘要、异常节点清单和配置追平状态
* 总览页包含世界地图看板，并替换旧版以摘要卡片为主的单调结构
* 节点详情页包含系统信息卡、实时资源占用卡、网络流量卡、健康事件区与最近 24 小时趋势图
* 节点详情页保留当前目标版本等关键运维信息，但整体层级比旧版更清晰
* 第六版不破坏现有 Agent 心跳、同步、发布、回滚主链路