lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity
Files
1c5cfafda639f0e9ca254732687e3fee2a69b660
DiAL/openspec/specs/target-detail-drawer/spec.md
lanyuanxiaoyao 1c5cfafda6 feat: 前端指标体系增强 — Dashboard/Metrics API、2×4 统计区、趋势图面积+异常标记、连续状态列 
- 新增 GET /api/dashboard 合并原 summary+targets 首屏接口
- 新增 GET /api/targets/:id/metrics 合并原 stats+trend 概览接口
- 后端指标纯函数：可用率、百分位、故障段分析、连续状态、UTC 小时分桶
- ProbeStore 窗口取数方法替代全量历史查询
- SummaryCards 扩展为 4 卡片（新增异常事件数）+ 数据新鲜度展示
- 表格新增「连续」列（Tag 渲染 capped 状态）
- OverviewTab 重构为 2×4 Statistic 多维度布局
- TrendChart 改为延迟范围面积图 + 红色异常标记点
- 删除旧路由（summary/targets/trend）和 computeTrendStats
- 同步 delta specs 到主 specs 并归档变更
2026-05-14 12:32:41 +08:00

255 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Purpose
定义目标详情 Drawer：时间范围筛选（TDesign RadioGroup + DateRangePicker，含快捷按钮联动概览和记录面板）、Tabs 组织概览/记录两个面板、Metrics 数据查询 Hook、多维度统计图表（2×4 布局）和分页检查结果列表。
## Requirements
### Requirement: 目标详情 Drawer
Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。Drawer 内容 SHALL 拆分为独立的 Tab 组件。
#### Scenario: 打开 Drawer
- **WHEN** 用户点击某个目标表格行
- **THEN** 系统 SHALL 从右侧滑出 Drawer（placement="right"），宽度为视口 60%
#### Scenario: Drawer 标题栏
- **WHEN** Drawer 渲染
- **THEN** 标题栏 SHALL 使用 TDesign Space 组件（align="center"）布局，包含 StatusDot、目标名称（TDesign Typography.Text strong）和类型标签（TDesign Tag，直接显示 target.type 原始文本），以及内建关闭按钮。不使用内联 style 的 flex 布局
#### Scenario: 关闭 Drawer
- **WHEN** 用户点击关闭按钮、ESC 键或遮罩层
- **THEN** Drawer SHALL 关闭
#### Scenario: Drawer 无底部按钮
- **WHEN** Drawer 渲染
- **THEN** Drawer SHALL 不显示底部操作栏（footer={false}）
#### Scenario: Drawer 数据同步
- **WHEN** Drawer 打开期间后台轮询刷新了 targets 数据
- **THEN** Drawer 中 selectedTarget 的状态 SHALL 随之同步更新
#### Scenario: 切换目标重置 Tab
- **WHEN** 用户从目标 A 切换到目标 B（点击不同的表格行）
- **THEN** Drawer SHALL 重置为概览 Tab，使用 key={target.id} 确保组件状态不残留
#### Scenario: Drawer 内容区间距
- **WHEN** Drawer 内容渲染
- **THEN** 时间选择器、Tabs 等区块之间的间距 SHALL 通过 TDesign Space 组件（direction="vertical", size={16}）统一管理，不使用内联 style 的 marginBottom
### Requirement: 概览面板组件化
概览 Tab SHALL 作为独立组件 `OverviewTab` 实现，展示多维度统计、趋势图、状态分布和基本信息。
#### Scenario: OverviewTab 组件职责
- **WHEN** 概览 Tab 渲染
- **THEN** `OverviewTab` 组件 SHALL 负责多维度统计卡片（2×4 布局）、趋势图（延迟范围面积图+异常标记点）、状态分布环形图和基本信息的渲染
#### Scenario: 统计计算不再使用 computeTrendStats
- **WHEN** OverviewTab 需要 totalChecks、upChecks、downChecks
- **THEN** SHALL 直接使用 metricsData.stats 中的 totalChecks、upChecks、downChecks 字段，`computeTrendStats` 工具函数 SHALL 被删除
#### Scenario: OverviewTab props
- **WHEN** OverviewTab 渲染
- **THEN** 组件 SHALL 接收 `target: TargetStatus`、`metricsData: TargetMetricsResponse | null`、`metricsLoading: boolean` 作为 props
### Requirement: 记录面板组件化
记录 Tab SHALL 作为独立组件 `HistoryTab` 实现。
#### Scenario: HistoryTab 组件职责
- **WHEN** 记录 Tab 渲染
- **THEN** `HistoryTab` 组件 SHALL 负责检查结果表格和分页的渲染
#### Scenario: HistoryTab props
- **WHEN** HistoryTab 渲染
- **THEN** 组件 SHALL 接收 `historyData: HistoryResponse`、`historyLoading: boolean`、`onPageChange: (page: number) => void` 作为 props
#### Scenario: 历史记录列定义外置
- **WHEN** HistoryTab 渲染表格
- **THEN** 列定义 SHALL 从 `constants/history-table-columns.tsx` 导入，不在组件内部定义
### Requirement: TrendChart 简化
TrendChart 组件 SHALL 仅接收数据 props，不处理 loading 状态。
#### Scenario: TrendChart 无 loading prop
- **WHEN** TrendChart 渲染
- **THEN** 组件 SHALL 仅接收 `data: TrendPoint[]` prop，不接收 `loading` prop
#### Scenario: TrendChart 空数据
- **WHEN** TrendChart 接收空数组
- **THEN** 组件 SHALL 显示"暂无趋势数据"占位文本
### Requirement: StatusDonut key 修复
StatusDonut 组件 SHALL 使用语义化的 key。
#### Scenario: Pie Cell key
- **WHEN** StatusDonut 渲染 Pie Cell 列表
- **THEN** 每个 Cell 的 key SHALL 使用 data item 的 `name` 字段，不使用数组索引
### Requirement: StatusBar 参数化
StatusBar 组件 SHALL 支持可配置的格数。
#### Scenario: maxSlots prop
- **WHEN** StatusBar 渲染
- **THEN** 组件 SHALL 接收可选的 `maxSlots` prop（默认 30），根据该值渲染对应数量的格子
#### Scenario: 格子渲染逻辑
- **WHEN** StatusBar 渲染且 samples 数量少于 maxSlots
- **THEN** 多余的格子 SHALL 显示为 empty 状态
### Requirement: Metrics 数据查询 Hook
系统 SHALL 提供 `useTargetMetrics` hook 查询单目标指标数据。
#### Scenario: metrics queryKey
- **WHEN** 查询某目标的指标数据
- **THEN** queryKey SHALL 为 ["metrics", targetId, from, to, bucket]
#### Scenario: metrics 条件查询
- **WHEN** 用户未选中任何目标
- **THEN** metrics 的 useQuery SHALL enabled=false，不发起请求
#### Scenario: metrics 数据返回
- **WHEN** metrics 查询成功
- **THEN** hook SHALL 返回 `TargetMetricsResponse` 类型数据
#### Scenario: 时间范围变化时重新请求
- **WHEN** 用户更改时间范围
- **THEN** metrics 的 useQuery SHALL 因 queryKey 变化自动重新请求
#### Scenario: Drawer 关闭清理查询缓存
- **WHEN** 用户关闭 Drawer
- **THEN** 系统 MAY 清理 metrics 和 history 查询缓存，避免旧目标数据残留
### Requirement: 时间范围选择器
Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录两个面板的数据。时间选择器 SHALL 分两行显示：第一行为快捷按钮，第二行为日期时间范围选择器。
#### Scenario: 快捷时间按钮
- **WHEN** Drawer 渲染
- **THEN** 时间选择区第一行 SHALL 显示 TDesign RadioGroup（variant=default-filled）快捷按钮：1小时、6小时、24小时、7天
#### Scenario: 点击快捷按钮
- **WHEN** 用户点击快捷按钮（如 "24小时"）
- **THEN** 系统 SHALL 自动设置对应的起止时间，DateRangePicker 显示对应的时间范围，该按钮高亮
#### Scenario: 快捷按钮联动统计区
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 概览面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/metrics` 数据
#### Scenario: 快捷按钮联动历史记录
- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 记录面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/history` 数据，并重置页码为 1
#### Scenario: 自定义日期时间范围
- **WHEN** 用户通过 TDesign DateRangePicker（mode=date, enableTimePicker, format="YYYY-MM-DD HH:mm"）修改时间范围
- **THEN** 快捷按钮 SHALL 取消高亮，系统重新请求对应时间范围的数据
#### Scenario: 时间精度为分钟级
- **WHEN** 用户通过 DateRangePicker 选择时间
- **THEN** 选择器 SHALL 仅精确到分钟（format="YYYY-MM-DD HH:mm"），秒列固定为 00
#### Scenario: DateRangePicker 全宽显示
- **WHEN** Drawer 渲染
- **THEN** DateRangePicker SHALL 通过 CSS 类 `.full-width` 占满时间选择区第二行的宽度，不使用内联 style 的 width: 100%
#### Scenario: 默认时间范围
- **WHEN** Drawer 打开
- **THEN** 时间选择器 SHALL 默认选中 "24小时" 快捷按钮
#### Scenario: 筛选触发数据刷新
- **WHEN** 时间范围发生变化
- **THEN** 系统 SHALL 重新请求趋势数据和历史记录
### Requirement: Tabs 内容组织
Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。TabPanel 内边距通过 className prop 控制。
#### Scenario: Tab 标签
- **WHEN** Drawer 渲染
- **THEN** Tabs SHALL 显示两个标签：概览、记录
#### Scenario: Tab 面板内边距
- **WHEN** TabPanel 渲染
- **THEN** TabPanel SHALL 通过 `className` prop 传入自定义类名（`tab-panel-padded`）控制内边距，不通过入侵 TDesign 内部类名（`.t-tab-panel`）覆盖
### Requirement: 概览面板
概览 Tab SHALL 按区域展示多维度统计、趋势图、状态分布和基本信息。
#### Scenario: 区域排列顺序
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示 TDesign Divider（align="left"）作为小标题
#### Scenario: 统计区多维度布局
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"统计"区域使用 2 行 × 4 列的 TDesign Row/Col + Statistic 布局：第一行为可用率（suffix="%"）、平均延迟（suffix="ms"）、P95 延迟（suffix="ms"）、检查总数；第二行为 MTTR（动态单位）、最长故障（动态单位）、故障次数（suffix="次"）、连续正常（suffix="次"，固定标题"连续正常"，当目标当前处于异常状态时值为 0）
#### Scenario: P99 暂不展示
- **WHEN** metricsData.stats 包含 p99DurationMs
- **THEN** 当前 2×4 统计区 SHALL 不展示 P99 延迟
#### Scenario: MTTR 和最长故障动态单位
- **WHEN** MTTR 或最长故障值小于 60000ms
- **THEN** SHALL 以秒为单位展示（suffix="秒"）
- **WHEN** 值大于等于 60000ms 且小于 3600000ms
- **THEN** SHALL 以分钟为单位展示（suffix="分钟"）
- **WHEN** 值大于等于 3600000ms
- **THEN** SHALL 以小时为单位展示（suffix="小时"）
#### Scenario: 统计区数据来源
- **WHEN** 统计区渲染
- **THEN** 第一行和第二行数据 SHALL 来自 metricsData.stats
#### Scenario: 统计区加载状态
- **WHEN** metricsData 正在加载
- **THEN** 统计区 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 统计区无数据
- **WHEN** metricsData 为 null 且未处于加载状态
- **THEN** 统计区 SHALL 展示占位状态，不从其他数据源反推统计值
#### Scenario: 延迟类指标无数据
- **WHEN** metricsData.stats 中 avgDurationMs 或 p95DurationMs 为 null
- **THEN** 对应 Statistic SHALL 展示值为 0 且不带单位后缀（TDesign Statistic value 仅接受 number，无数据时通过缺省 suffix 区分）
#### Scenario: 趋势图延迟范围面积
- **WHEN** 概览面板渲染且 metricsData.trend 可用
- **THEN** 趋势图 SHALL 使用 recharts Area 组件渲染 minDurationMs 到 maxDurationMs 的延迟范围（半透明品牌色填充），叠加 avgDurationMs 实线
#### Scenario: 趋势图时间轴标签本地化
- **WHEN** 趋势图渲染 X 轴标签
- **THEN** 前端 SHALL 使用 `toLocaleTimeString` 或等价方法将 UTC `bucketStart` 转换为本地时间标签（如 "08:00"），不直接展示 UTC 时间字符串
#### Scenario: 趋势图异常标记点
- **WHEN** metricsData.trend 中某小时的 availability < 100
- **THEN** 趋势图 SHALL 在 avgDurationMs 线上该时间点渲染红色圆点（fill: var(--td-error-color)），使用 recharts Line 的 dot 回调函数实现；图表 SHALL 仅保留左侧 Y 轴（ms），移除右侧 Y 轴（%）和 availability 折线
#### Scenario: 趋势数据加载中
- **WHEN** metricsData 正在加载
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 状态分布环形图
- **WHEN** 概览面板渲染且 metricsData 可用
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图（StatusDonut），使用 metricsData.stats.upChecks 和 metricsData.stats.downChecks 作为数据源，外圈显示 UP/DOWN 比例，中间显示可用率百分比
#### Scenario: 状态分布加载状态
- **WHEN** metricsData 正在加载
- **THEN** 状态分布区域 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 元信息展示
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"基本信息"区域使用 TDesign Descriptions 组件展示目标元信息：目标地址、检查间隔、最新检查时间、状态详情
### Requirement: 记录面板
记录 Tab SHALL 展示分页检查结果列表，使用 TDesign PrimaryTable。
#### Scenario: 检查结果表格
- **WHEN** 记录面板渲染且数据可用
- **THEN** 面板 SHALL 使用 TDesign PrimaryTable 展示检查结果，列包含：状态（StatusDot 圆点）、时间（YYYY-MM-DD HH:mm:ss 格式）、耗时（标题含 ms 单位，单元格仅显示数值，居中对齐）、详情（statusDetail 和 failure.message 用冒号拼接）
#### Scenario: 服务端分页
- **WHEN** 检查结果总数超过一页
- **THEN** 表格 SHALL 使用内建 pagination（disableDataPage=true），分页器显示在表格底部
#### Scenario: 翻页触发请求
- **WHEN** 用户切换分页页码
- **THEN** 系统 SHALL 请求对应页码的服务端数据，表格更新
#### Scenario: 记录数据加载中
- **WHEN** 历史记录正在加载
- **THEN** 表格 SHALL 显示 loading 状态
View Git Blame Copy Permalink