lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity
Files
6e485cc9916ba7d63935f83de7776e5d2c2edc2b
DiAL/openspec/specs/target-detail-drawer/spec.md
lanyuanxiaoyao 31aeee6d60 refactor: 前端架构重构 — hook拆分、组件拆分、类型筛选器动态化、Meta API 
- 后端新增 GET /api/meta 端点（checkerRegistry.supportedTypes）及 MetaResponse 类型
- 前端 hook 拆分为 use-queries.ts（全局查询+useMeta）和 use-target-detail.ts（Drawer状态）
- TargetDetailDrawer 拆分为 OverviewTab + HistoryTab + history-table-columns + stats.ts
- 类型筛选器由 meta API 动态驱动，删除 target-type-display 静态映射
- 列定义改为工厂函数 createTargetTableColumns(checkerTypes)，TargetGroup 新增 columns prop
- 修复 StatusDonut key、StatusBar maxSlots prop、TrendChart 移除 loading prop
- 补充 utils/time、utils/stats、动态列工厂测试，删除旧 mapping 测试
- 同步 delta specs 到主 specs，归档 frontend-architecture-refactor change
2026-05-13 20:55:42 +08:00

188 lines
9.1 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 组织概览/记录两个面板、统计图表和分页检查结果列表。
## 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` 实现，接收数据 props 进行渲染。
#### Scenario: OverviewTab 组件职责
- **WHEN** 概览 Tab 渲染
- **THEN** `OverviewTab` 组件 SHALL 负责统计卡片、趋势图、状态分布环形图和基本信息的渲染
#### Scenario: 统计计算使用纯函数
- **WHEN** OverviewTab 需要计算 totalChecks、upChecks、downChecks
- **THEN** 计算逻辑 SHALL 通过 `utils/stats.ts` 中的纯函数实现，并使用 `useMemo` 缓存结果
#### Scenario: OverviewTab props
- **WHEN** OverviewTab 渲染
- **THEN** 组件 SHALL 接收 `target: TargetStatus`、`trendData: TrendPoint[]`、`trendLoading: 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: 时间范围选择器
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** 用户通过 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 按区域展示目标统计摘要、趋势图、状态分布和基本信息，每个区域使用 TDesign Divider 组件作为小标题分隔。
#### Scenario: 区域排列顺序
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示 TDesign Divider（align="left"）作为小标题，不使用内联 style 的 h4 标签
#### Scenario: 区域间距
- **WHEN** 概览面板渲染
- **THEN** 各区域之间的间距 SHALL 通过 TDesign Space 组件（direction="vertical"）统一管理，不使用内联 style 的 margin
#### Scenario: 统计数值卡片
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"统计"区域使用 TDesign Statistic 组件展示 4 个统计值：总检查（color=blue）、正常（color=green）、异常（color=red）、可用率（color=green, suffix="%"），使用 TDesign Row/Col 横向排列。Row 的外层间距 SHALL 通过 TDesign Space 或 CSS 类控制，不使用内联 style
#### Scenario: 趋势折线图
- **WHEN** 概览面板渲染且趋势数据可用
- **THEN** 面板 SHALL 在"趋势"区域展示 recharts 双 Y 轴折线图（TrendChart）：耗时线（--td-brand-color）和可用率线（--td-success-color）
#### Scenario: 趋势数据加载中
- **WHEN** 概览面板渲染且趋势数据正在加载
- **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
#### Scenario: 状态分布环形图
- **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 在"状态分布"区域展示 recharts 环形图（StatusDonut），外圈显示 UP/DOWN 比例，中间显示可用率百分比
#### 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