lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity
Files
8d8549d07fc6fda8e1cce2dfcff2d5e9fd02300d
DiAL/openspec/specs/target-detail-drawer/spec.md
lanyuanxiaoyao 31fd3a2a43 refactor: 统一 target name/description 可空语义，前端展示 fallback 到 id 
- schema: name/description 允许省略或显式 null，TypeBox Union([Null, String])
- 类型: RawTargetConfig/ResolvedTargetBase/子类型/StoredTarget/TargetStatus name 改为 string | null
- checker resolve: name: t.name ?? null，不再 fallback 到 id
- 语义校验: 拒绝空字符串和纯空白 name
- SQLite: targets.name 列改为可空 TEXT
- 前端: 新增 getTargetDisplayName(target) 展示 name ?? id
- 测试: 覆盖 name/description null 全场景，查找改为按 id
- 文档: 更新 README/DEVELOPMENT 和 6 个 openspec specs
2026-05-17 20:12:39 +08:00

319 lines
17 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、多维度统计图表（4×2 Card 布局）和分页检查结果列表。
## Requirements
### Requirement: 目标详情 Drawer
Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。Drawer 内容 SHALL 拆分为独立的 Tab 组件，并优先通过 TDesign Drawer 原生生命周期能力控制显示、隐藏和滚动穿透。
#### Scenario: 打开 Drawer
- **WHEN** 用户点击某个目标表格行
- **THEN** 系统 SHALL 从右侧滑出 Drawer（placement="right"），使用响应式默认宽度，并将当前 Tab 重置为"概览"
#### Scenario: Drawer 标题栏
- **WHEN** Drawer 渲染
- **THEN** 标题栏 SHALL 使用 TDesign Space 组件（align="center"）布局，包含 StatusDot、目标展示名称（取值为 `target.name ?? target.id`，使用 TDesign Typography.Text strong）和类型标签（TDesign Tag，直接显示 target.type 原始文本），以及内建关闭按钮。不使用内联 style 的 flex 布局
#### Scenario: Drawer 标题栏 name 为 null
- **WHEN** Drawer 渲染某个 `target.name` 为 null 的目标
- **THEN** 标题栏 SHALL 显示该目标的 `target.id` 作为目标展示名称
#### Scenario: 关闭 Drawer
- **WHEN** 用户点击关闭按钮、ESC 键或遮罩层
- **THEN** Drawer SHALL 关闭并通过 TDesign Drawer 的 `visible` 状态隐藏
#### 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 状态重置为概览 Tab，且 MUST NOT 使用 `key={target.id}` 强制重建 Drawer 子树
#### 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 负责基本信息（直接展示 Descriptions）、多维度统计卡片（4×2 上下布局）和趋势图的渲染
#### 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 显示"暂无趋势数据"占位文本
#### Scenario: TrendChart memo 包裹
- **WHEN** TrendChart 的父组件重渲染但 data prop 引用未变
- **THEN** TrendChart SHALL 跳过重渲染（通过 React.memo shallow compare）
#### Scenario: chartData useMemo
- **WHEN** TrendChart 渲染
- **THEN** 内部 `chartData` 转换结果 SHALL 通过 `useMemo` 缓存，依赖为 `[data]`，data 引用不变时不重新计算
### Requirement: TargetBoard 分组 memoize
TargetBoard 组件的分组计算 SHALL 使用 useMemo 缓存，避免 targets 引用不变时重复计算分组。
#### Scenario: 分组结果 useMemo
- **WHEN** TargetBoard 渲染
- **THEN** 分组逻辑（Map 构建 + sort）SHALL 通过 `useMemo` 缓存，依赖为 `[targets]`
#### Scenario: targets 引用不变时跳过分组
- **WHEN** TargetBoard 因父组件重渲染而重渲染，但 targets prop 引用未变
- **THEN** 分组计算 SHALL 返回缓存结果，不重新执行 Map 构建和排序
### Requirement: TargetGroup 渲染优化
TargetGroup 组件 SHALL 使用 React.memo 包裹，在 props 引用不变时跳过重渲染。
#### Scenario: TargetGroup memo 包裹
- **WHEN** TargetBoard 重渲染但某个分组的 targets 数组引用未变
- **THEN** 对应的 TargetGroup SHALL 跳过重渲染（通过 React.memo shallow compare）
#### Scenario: TargetGroup props 稳定性
- **WHEN** TargetGroup 渲染
- **THEN** 其 props（columns、name、targets、onTargetClick）SHALL 全部具有引用稳定性：columns 通过 useMemo、name 为 string 原始值、targets 通过分组 useMemo、onTargetClick 通过 useCallback
### 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 查询缓存以降低重复打开成本，依赖 TanStack Query 全局 staleTime 自动管理过期
### 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** 用户在"记录"Tab 激活时点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 记录面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/history` 数据，并重置页码为 1
#### Scenario: 快捷按钮不预取未激活历史记录
- **WHEN** 用户在"概览"Tab 激活时点击 1小时/6小时/24小时/7天 快捷按钮
- **THEN** 系统 SHALL NOT 请求 `/api/targets/:id/history`，直到用户切换到"记录"Tab
#### Scenario: 自定义日期时间范围
- **WHEN** 用户通过 TDesign DateRangePicker（mode=date, enableTimePicker, format="YYYY-MM-DD HH:mm"）修改时间范围
- **THEN** 快捷按钮 SHALL 取消高亮，系统 SHALL 按新的时间范围刷新概览数据，并按当前 Tab 状态决定是否刷新历史记录
#### Scenario: 时间精度为分钟级
- **WHEN** 用户通过 DateRangePicker 选择时间
- **THEN** 选择器 SHALL 仅精确到分钟（format="YYYY-MM-DD HH:mm"），秒列固定为 00
#### Scenario: DateRangePicker 自适应显示
- **WHEN** Drawer 渲染
- **THEN** DateRangePicker SHALL 通过 CSS 类 `.drawer-date-range`（替代原 `.full-width`）自适应填充时间选择区剩余宽度，不使用内联 style 的 width: 100%
#### Scenario: 默认时间范围
- **WHEN** Drawer 打开
- **THEN** 时间选择器 SHALL 默认选中 "24小时" 快捷按钮
#### Scenario: 筛选触发数据刷新
- **WHEN** 时间范围发生变化
- **THEN** 系统 SHALL 重新请求趋势数据；若"记录"Tab 当前激活，系统 SHALL 同时重新请求历史记录，否则 SHALL 延迟到用户进入"记录"Tab 后请求历史记录
### Requirement: Tabs 内容组织
Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。Tabs SHALL 使用受控 value 管理当前激活 Tab，TabPanel 内边距通过 className prop 控制。
#### Scenario: Tab 标签
- **WHEN** Drawer 渲染
- **THEN** Tabs SHALL 显示两个标签：概览、记录
#### Scenario: Tabs 受控状态
- **WHEN** 用户切换 Tab
- **THEN** Tabs SHALL 通过 `value` 和 `onChange` 更新由 Drawer 状态 hook 管理的当前 Tab 值
#### Scenario: 默认概览 Tab
- **WHEN** Drawer 打开或切换到另一个目标
- **THEN** 当前 Tab SHALL 重置为 `overview`
#### Scenario: Tab 面板内边距
- **WHEN** TabPanel 渲染
- **THEN** TabPanel SHALL 通过 `className` prop 传入自定义类名（`tab-panel-padded`）控制内边距，不通过入侵 TDesign 内部类名（`.t-tab-panel`）覆盖
#### Scenario: TabPanel 懒渲染与缓存
- **WHEN** 用户在概览和记录 Tab 之间切换
- **THEN** 概览和记录 TabPanel 均 SHALL 配置 TDesign TabPanel 的 `destroyOnHide={false}`，隐藏时不销毁组件，保留已挂载的面板状态和已加载的数据；记录 TabPanel SHALL 额外配置懒渲染，首次进入前不渲染 HistoryTab
### Requirement: 概览面板
概览 Tab SHALL 按区域展示基本信息、多维度统计和趋势图。
#### Scenario: 区域排列顺序
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 按以下顺序展示区域：基本信息 → 统计 → 趋势，每个区域前 SHALL 显示 TDesign Divider（align="left"）作为小标题
#### Scenario: 基本信息直接展示
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"基本信息"区域直接使用 TDesign Descriptions 组件展示配置信息（不折叠）
#### Scenario: 基本信息内容
- **WHEN** 概览面板渲染
- **THEN** Descriptions SHALL 展示：目标地址、检查间隔、最新检查时间、状态详情、描述，其中描述 SHALL 位于最后一行
#### Scenario: 描述行占满整行
- **WHEN** 概览面板渲染基本信息
- **THEN** 描述项 SHALL 占据 Descriptions 的一整行，内容 SHALL 使用 `target.description ?? ""`，即使 description 为空也 SHALL 渲染该项
#### Scenario: 统计区上下布局卡片
- **WHEN** 概览面板渲染且有统计数据
- **THEN** 面板 SHALL 在"统计"区域使用 4 列 × 2 行的 Row/Col 布局，每个统计项使用 `overview-stat-card` 包裹，内部使用 TDesign Statistic 组件自带的上下布局（title 在上、value 在下），通过 `summary-stat-col` 类居中。系统 SHALL NOT 使用已移除的 `overview-stat-item` 左右 flex 布局
#### Scenario: 统计区内容
- **WHEN** 概览面板渲染
- **THEN** 统计区 SHALL 展示：可用率（suffix="%"）、平均延迟（suffix="ms"）、P95 延迟（suffix="ms"）、检查总数、MTTR（动态单位）、最长故障（动态单位）、故障次数（suffix="次"）、连续正常（suffix="次"）
#### Scenario: 趋势图
- **WHEN** 概览面板渲染且 metricsData.trend 可用
- **THEN** 面板 SHALL 在"趋势"区域展示 TrendChart 组件
#### Scenario: 统计区加载状态
- **WHEN** metricsData 正在加载
- **THEN** 统计区 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 统计区无数据
- **WHEN** metricsData 为 null 且未处于加载状态
- **THEN** 统计区 SHALL 展示占位状态
#### Scenario: 趋势数据加载中
- **WHEN** metricsData 正在加载
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
### Requirement: Drawer TDesign 原生生命周期与滚动控制
目标详情 Drawer SHALL 优先使用 TDesign Drawer 的原生 props 控制挂载、可见性和滚动穿透，不通过自定义滚轮事件实现滚动控制。
#### Scenario: Drawer 常驻受控渲染
- **WHEN** 未选中目标时
- **THEN** `TargetDetailDrawer` SHALL 保留 TDesign Drawer 组件并通过 `visible=false` 隐藏，而不是直接返回 `null` 卸载 Drawer 子树
#### Scenario: Drawer 防滚动穿透配置
- **WHEN** Drawer 渲染
- **THEN** Drawer SHALL 显式使用 `attach="body"`、`preventScrollThrough=true`、`showInAttachedElement=false` 和 `showOverlay=true`
#### Scenario: Drawer 关闭后保留子树
- **WHEN** 用户关闭 Drawer
- **THEN** Drawer SHALL 使用 `destroyOnClose=false` 保留已挂载内容，避免重复打开时重建完整子树
#### Scenario: Drawer 单一纵向滚动容器
- **WHEN** Drawer 内容高度超过可视区域
- **THEN** 系统 SHALL 依赖 Drawer 内容区域作为唯一纵向滚动容器，HistoryTab 中的 PrimaryTable SHALL 不配置 `height`、`maxHeight` 或纵向 `scroll` 来创建第二个纵向滚动区域
### Requirement: Drawer 宽度
Drawer 宽度 SHALL 根据视口宽度设置响应式默认值，并 SHALL 支持用户通过鼠标拖拽边缘在当前页面生命周期内调整宽度。系统 MUST NOT 将拖拽后的宽度持久化到 `localStorage`、后端、URL 或其他跨刷新存储。
#### Scenario: Drawer 响应式默认宽度
- **WHEN** Drawer 打开且用户尚未在当前页面生命周期内拖拽调整宽度
- **THEN** Drawer size SHALL 使用响应式默认宽度，宽屏时占视口比例 SHALL 小于窄屏时占视口比例，且窄屏下 SHALL 不超过视口安全宽度
#### Scenario: Drawer 边缘拖拽宽度
- **WHEN** 用户使用鼠标拖动右侧 Drawer 的左边缘
- **THEN** Drawer SHALL 通过 TDesign Drawer 原生拖拽能力调整宽度，不通过自定义全局鼠标事件实现拖拽
#### Scenario: Drawer 拖拽边界
- **WHEN** 用户拖拽调整 Drawer 宽度
- **THEN** Drawer 宽度 SHALL 被限制在最小可读宽度和视口安全最大宽度之间，避免内容不可读或横向溢出
#### Scenario: Drawer 当前页面生命周期内保留拖拽宽度
- **WHEN** 用户拖拽调整 Drawer 宽度后关闭并再次打开 Drawer，且页面未刷新、组件未重新挂载
- **THEN** Drawer SHALL 保留当前页面生命周期内的拖拽后宽度
#### Scenario: Drawer 拖拽宽度不持久化
- **WHEN** 页面刷新后用户再次打开 Drawer
- **THEN** Drawer SHALL 恢复响应式默认宽度，且 MUST NOT 从 `localStorage`、后端、URL 或其他跨刷新存储恢复拖拽宽度
### Requirement: 时间选择器单行布局
Drawer 顶部的时间范围快捷按钮和日期范围选择器 SHALL 在同一行展示。
#### Scenario: 单行布局
- **WHEN** Drawer 渲染时间选择区域
- **THEN** RadioGroup 和 DateRangePicker SHALL 使用 flex 布局在同一行水平排列
### 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