DiAL/openspec/specs/target-detail-drawer/spec.md

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 状态