DiAL/openspec/specs/target-table/spec.md

Purpose

定义分组表格的列配置、排序、筛选、行交互和 DOWN 行视觉强化。

Requirements

Requirement: 分组表格展示

Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立的 TDesign PrimaryTable，分组间使用 TDesign Space 垂直排列。

Scenario: 按分组渲染独立表格

• WHEN 用户打开 Dashboard 页面
• THEN 页面 SHALL 按 group 字段将目标分组，每个分组包含带统计的分组标题和一个独立 PrimaryTable

Scenario: 分组顺序

• WHEN 页面渲染多个分组
• THEN "default" 分组 SHALL 排在最上面，其余分组按 YAML 配置中首次出现的顺序排列

Scenario: 分组标题统计标签

• WHEN 页面渲染某个分组的标题
• THEN 标题 SHALL 使用 TDesign Tag 组件显示分组名称和三个统计标签：总数（theme=primary, variant=light）、正常数（theme=success, variant=light）、异常数（theme=danger, variant=light）

Scenario: "default" 分组显示名称

• WHEN 分组名称为 "default"
• THEN 分组标题 SHALL 显示 "默认分组"

Scenario: Dashboard 容器占满宽度

• WHEN 用户打开 Dashboard 页面
• THEN Dashboard 容器 SHALL 占满浏览器宽度，不设置 max-width 限制

Scenario: 分组间统一间距

• WHEN 页面渲染多个分组
• THEN 分组之间 SHALL 使用 TDesign Space 组件（direction=vertical, size=32px）统一间距

Requirement: 表格列定义

每个分组的 PrimaryTable SHALL 包含状态、名称、类型、可用率、最近状态条、延迟、间隔 7 列，不含分组列（同组内冗余）。列渲染不使用内联 style。列定义 SHALL 通过工厂函数动态生成。

Scenario: 状态列

• WHEN 表格渲染
• THEN 状态列 SHALL 使用 StatusDot 组件渲染，标题显示"#"，宽度 60px，fixed="left"，居中对齐，支持筛选（UP/DOWN/全部）。StatusDot SHALL 通过 CSS 类（.status-dot--up / .status-dot--down）控制颜色，不使用内联 style

Scenario: 名称列

• WHEN 表格渲染
• THEN 名称列 SHALL 显示目标名称，支持字母排序（zh-CN），ellipsis 超长名称自动省略并 Tooltip 显示全名

Scenario: 类型列

• WHEN 表格渲染
• THEN 类型列 SHALL 使用 TDesign Tag 组件（size=small, theme=primary, variant=light-outline）直接显示 target.type 原始文本，支持单选筛选

Scenario: 类型筛选器动态生成

• WHEN 表格渲染
• THEN 类型列的筛选器列表 SHALL 从 meta API 返回的 checkerTypes 动态生成，包含"全部"选项和每个 checker 类型选项（label 和 value 均为 type 原始文本）

Scenario: 可用率列

• WHEN 表格渲染
• THEN 可用率列标题 SHALL 展示为"可用率(24h)"（基于 Dashboard 默认 window=24h），使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色通过 CSS 自定义属性 --avail-N（基于项目自定义色值）控制，每 10% 一档，label 显示百分比数值，支持排序（升序优先，最差排最前）。前端 SHALL 使用 DashboardResponse.targets[].stats.availability 字段作为数据来源。color-threshold 函数 SHALL 返回 CSS 自定义属性引用而非硬编码色值

Scenario: 最近状态列

• WHEN 表格渲染
• THEN 最近状态列 SHALL 使用 StatusBar 组件渲染采样色块，宽度 220px。StatusBar SHALL 通过 CSS 类（.status-bar-block--up / .status-bar-block--down / .status-bar-block--empty）控制色块颜色，不使用内联 style

Scenario: 连续状态列渲染

• WHEN 表格渲染
• THEN 表格 SHALL 在「最近状态」列之后、「延迟」列之前展示「连续状态」列，标题为"连续"，宽度 100px

Scenario: 连续正常展示

• WHEN 目标 currentStreak 为 { up: true, count: N }
• THEN 列 SHALL 使用 TDesign Tag 组件（theme=success, variant=light, size=small）展示 "▲ N次"

Scenario: 连续异常展示

• WHEN 目标 currentStreak 为 { up: false, count: N }
• THEN 列 SHALL 使用 TDesign Tag 组件（theme=danger, variant=light, size=small）展示 "▼ N次"

Scenario: 连续状态数据来源

• WHEN 表格需要渲染连续状态
• THEN 前端 SHALL 使用 DashboardResponse.targets[].currentStreak 字段，不在表格列中自行遍历 recentSamples 计算核心指标

Scenario: 超过样本上限

• WHEN currentStreak.capped 为 true
• THEN 列 SHALL 展示 "▲ N+" 或 "▼ N+"

Scenario: 无样本数据

• WHEN 目标 currentStreak 为 null
• THEN 列 SHALL 展示 "-"

Scenario: 延迟列

• WHEN 表格渲染
• THEN 延迟列 SHALL 显示最近一次检查的延迟毫秒数，右对齐。颜色 SHALL 通过 CSS 类实现：≤100ms 使用 .latency-ok、100-500ms 使用 .latency-warn、>500ms 使用 .latency-error。无数据 SHALL 使用 .text-disabled 类显示 "-"，数值 SHALL 使用 .tabular-nums 类等宽显示。不使用内联 style

Scenario: 间隔列

• WHEN 表格渲染
• THEN 间隔列 SHALL 显示检查间隔（如 "5s"、"30s"），居中对齐，宽度 72px

Requirement: 列定义工厂函数

列定义 SHALL 通过工厂函数生成，接收动态参数。

Scenario: createTargetTableColumns 函数

• WHEN 需要生成表格列定义
• THEN 系统 SHALL 调用 createTargetTableColumns(checkerTypes: string[]) 函数，返回 PrimaryTableCol<TargetStatus>[]

Scenario: checkerTypes 为空数组

• WHEN meta API 尚未返回或返回空数组
• THEN 类型列的筛选器 SHALL 仅包含"全部"选项

Scenario: 列定义缓存

• WHEN TargetBoard 组件渲染
• THEN 列定义 SHALL 通过 useMemo 缓存，仅在 checkerTypes 变化时重新生成

Requirement: TargetGroup 接收 columns prop

TargetGroup 组件 SHALL 通过 prop 接收列定义，不再直接导入静态常量。

Scenario: columns prop

• WHEN TargetGroup 渲染
• THEN 组件 SHALL 接收 columns: PrimaryTableCol<TargetStatus>[] prop 并传递给 PrimaryTable

Scenario: TargetBoard 传递 columns

• WHEN TargetBoard 渲染子组件
• THEN TargetBoard SHALL 调用 createTargetTableColumns 生成列定义并传递给每个 TargetGroup

Requirement: 默认排序

表格 SHALL 默认按状态降序排列，异常（DOWN）目标排在最前面。

Scenario: 页面初始排序

• WHEN 用户打开 Dashboard 页面
• THEN 每个分组表格 SHALL 默认按状态降序排列，DOWN 目标排在同组最前面

Requirement: DOWN 行视觉强化

表格中状态为 DOWN 的行 SHALL 具有视觉区分，使用安全 CSS 选择器实现。

Scenario: DOWN 行背景色

• WHEN 目标最近一次检查 matched=false
• THEN 该行 SHALL 通过 .t-table tr.row-down CSS 选择器获得浅红色背景（--td-error-color-light），不使用 !important

Scenario: DOWN 行 hover 状态

• WHEN 鼠标悬停在 DOWN 行上
• THEN 行背景 SHALL 通过 .t-table--hoverable tbody tr.row-down:hover 选择器显示 hover 状态色，与正常行 hover 效果协调

Requirement: 行点击交互

表格行 SHALL 支持点击打开目标详情 Drawer。

Scenario: 点击行打开 Drawer

• WHEN 用户点击某一行
• THEN 系统 SHALL 打开该目标的详情 Drawer

Scenario: 行 hover 效果

• WHEN 鼠标悬停在表格行上
• THEN 行 SHALL 显示 hover 高亮效果（TDesign Table hover prop）

Scenario: 行 cursor 样式

• WHEN 鼠标悬停在表格行上
• THEN cursor SHALL 显示为 pointer

Requirement: 表格外观

表格 SHALL 使用 TDesign PrimaryTable 统一外观。

Scenario: 表格样式

• WHEN 表格渲染
• THEN 表格 SHALL 设置 size="small"、stripe、hover、bordered

Requirement: 列定义复用

所有分组的表格 SHALL 共享同一套列定义。

Scenario: 列定义提取为常量

• WHEN 多个分组表格渲染
• THEN 列定义 SHALL 从独立的 constants/target-table-columns.tsx 导入，不在组件中重复定义