[优化] 更新开发计划文档，明确第六版目标与实施步骤，增加节点数据采集与访问分析能力

docs/development-guidelines.md

@@ -9,7 +9,8 @@
 * 第一版、第二版、第三版已完成
 * `docs/design.md` 是当前系统边界的唯一设计基线
 * `atsf_server/web` 新版前端已完成迁移并成为正式基线
-* 第五版（0.5.x）将以 OpenResty 性能优化与主配置接管为主线
+* 第五版（0.5.x）已完成
+* 第六版（0.6.x）以节点流量数据采集、访问分析与看板升级为主线
 
 超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。
 
@@ -125,9 +126,14 @@
 * `proxy_routes`
 * `config_versions`
 * `nodes`
+* `node_system_profiles`
 * `apply_logs`
 * `tls_certificates`
 * `managed_domains`
+* `node_request_reports`
+* `node_metric_snapshots`
+* `traffic_analytics_rollups`
+* `node_health_events`
 * `options`（运行时参数与 OpenResty 调优参数继续复用现有配置表，不扩展为独立新实体）
 
 通用约束：
@@ -140,6 +146,14 @@
 * 第五版新增的 OpenResty 性能参数必须由 Server 统一保存与校验，并参与版本渲染
 * 域名证书匹配必须同时支持精确匹配与通配符匹配
 * 节点专属 `agent_token` 必须可立即失效
+* `nodes` 只保留控制面与摘要状态，不直接承接第六版新增的高频资源字段、完整系统画像和大块统计结果
+* `node_system_profiles` 负责存储低频变化的节点事实信息；只有需要列表摘要展示的极少数字段可以回写到 `nodes`
+* 第六版新增的请求明细、资源快照和聚合统计必须按节点与时间窗口关联
+* `node_metric_snapshots` 必须是追加式时间序列快照，不通过覆盖 `nodes` 当前值替代历史
+* `traffic_analytics_rollups` 必须区分时间粒度与统计范围，优先存储窗口聚合而不是无限制保留原始逐请求明细
+* `node_health_events` 必须具备事件类型、严重级别、首次触发时间、最近触发时间和恢复时间，便于首页总览做异常归并
+* 访问分析优先复用现有 Server/SQLite 基线，不为第六版引入新的时序数据库或消息队列
+* 聚合统计与原始明细的保留策略必须明确，避免无限制累积
 
 ---
 
@@ -151,6 +165,7 @@
 * 成功与失败都必须返回清晰 `message`
 * 列表接口返回稳定字段
 * Agent API 固定放在 `/api/agent/*`
+* 第六版总览页与节点详情页优先新增专用聚合接口，不继续依赖多个旧列表接口在前端拼装
 
 统一响应结构保持现有风格：
 
@@ -223,6 +238,7 @@ Agent 必须满足：
 * 未显式配置 `node_ip` 时自动探测本机 IP
 * 周期性心跳与同步
 * 常规同步判定优先通过 heartbeat 响应中的激活版本 `version` / `checksum` 摘要完成；仅在 Agent 本地状态与摘要不一致时，再请求完整激活配置
+* heartbeat 请求体允许携带最近周期内的系统画像变更、资源快照、磁盘 IO 快照、入站/出站流量快照、访问聚合批次和健康事件
 * 发现新版本时先备份旧文件
 * 写入新的主配置、路由配置与必要证书文件
 * 先执行 `openresty -t`
@@ -234,6 +250,32 @@ Agent 必须满足：
 * 支持接收 Server 下发的受限运行指令，当前仅允许 OpenResty 重启
 * 支持自我更新，但失败不影响心跳与同步
 * 主配置接管模式下，必须保证主配置与受管 include 一起回滚，不能只回滚其中一部分
+* 请求明细采集失败、聚合失败或单次 heartbeat 上报失败时，不得阻断后续心跳与配置同步主链路
+* 节点侧指标采集必须优先读取 OpenResty 与本机运行时状态，不允许引入任意 shell 采集脚本拼接执行
+* 大批量请求上报必须具备批次边界和体积控制，避免单次 heartbeat 无限制膨胀
+* 节点侧应优先做窗口聚合后再上报，避免把逐请求原始日志持续搬运到 Server
+* 低频系统画像应支持变更检测，避免每次 heartbeat 重复上报大块静态信息
+* UV、来源分布、状态码分布等统计应在节点侧或服务端按窗口聚合，禁止前端再对原始明细做重型计算
+
+第六版新增规范：
+
+* 总览页默认展示世界地图节点分布、核心访问指标、趋势图和关键异常，不再以多个对称摘要卡片作为唯一主结构
+* 总览页必须能直接展示系统整体运行状况，至少覆盖节点在线率、OpenResty 健康、配置追平状态、容量风险与流量异常
+* 总览页异常区优先展示可行动的问题，如离线节点、配置落后节点、资源逼近阈值节点、错误率异常节点
+* 节点详情页第一屏至少覆盖系统信息、实时资源占用、网络流量与 24 小时历史趋势
+* 系统信息卡片除现有 Agent 版本、Nginx 版本、当前配置外，新增操作系统、CPU 型号、在线时长
+* 实时资源卡片展示 CPU、内存、存储占用，优先以仪表盘或等效高密度可视化呈现
+* 网络流量卡片展示经过 OpenResty 的入站和出站流量，并按 KB/MB/GB 自动换算
+* 节点详情页保留“当前目标版本”等高价值运维信息，但应下移到趋势区之后，避免抢占首屏
+* 节点详情页需要区分“静态画像”和“实时状态”，禁止把二者混在一组无层次字段列表中
+
+第六版实现约束补充：
+
+* 优先新增 `dashboard` / `node detail` 聚合 service，避免在旧 `node` service 上不断打补丁叠加查询逻辑
+* SQLite 查询应优先围绕“节点 + 时间窗口 + 粒度”建立索引与查询入口，避免首页每次全表扫描历史快照
+* TopN 榜单、来源分布、状态码分布等复杂结果允许以受控 JSON 结构写入聚合表，但必须保证字段稳定可测试
+* 异常阈值判断必须收敛在服务端统一实现，前端只负责展示，不复制阈值逻辑
+* 测试至少覆盖 heartbeat 扩展兼容性、聚合正确性、异常恢复状态切换和关键 dashboard 查询口径
 
 ---