refactor: 全面重构前端样式，消除内联 style 和硬编码色值，统一 TDesign 规范

- 重写 styles.css：CSS 变量化可用率色阶、状态色类、工具类、安全选择器 - 组件改造：StatusDot/StatusBar/TargetDetailDrawer/GroupHeader 等改用 CSS 类和 Typography - color-threshold 移除 getLatencyColor 死代码，保留 getAvailabilityProgressColor 返回 CSS 变量 - target-table-columns 状态列和延迟列切换为 CSS 类 - 新增 css-utility-classes spec，更新 4 个 main specs（probe/card/table/drawer） - README 和 config.yaml 写入前端样式开发规范
2026-05-12 12:42:11 +08:00
parent 3e8d01715f
commit 9f2b906063
19 changed files with 332 additions and 198 deletions
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -11,6 +11,8 @@ context: |
  - src/server目录下是基于bun实现的后端代码
  - src/web目录下是基于vite、react、TDesign实现的前端代码
  - 代码开发优先使用公共组件实现功能逻辑（优先级：官方库>主流三方库>项目公共工具>自行实现）
+  - 前端样式开发优先级：TDesign组件 > 组件props > TDesign CSS tokens(--td-*) > styles.css CSS类 > 自行开发组件
+  - 前端严禁：组件内联style属性、CSS覆盖TD内部类名、使用!important、硬编码色值
  - Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
  - 禁止创建git操作task
  - 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行
--- a/openspec/specs/card-dashboard/spec.md
+++ b/openspec/specs/card-dashboard/spec.md
@@ -5,7 +5,7 @@
 ## Requirements

 ### Requirement: 分组卡片布局
-Dashboard SHALL 按 group 字段将目标分组，每个分组包含带统计的分组标题和独立 TDesign PrimaryTable 表格。
+Dashboard SHALL 按 group 字段将目标分组，每个分组包含带统计的分组标题和独立 TDesign PrimaryTable 表格。分组标题使用 TDesign Typography 组件渲染。

 #### Scenario: 按分组展示目标
 - **WHEN** 用户打开 Dashboard 页面
@@ -13,7 +13,7 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组包含带统计的

 #### Scenario: 分组标题带统计标签
 - **WHEN** 页面渲染某个分组
- **THEN** 分组标题 SHALL 使用 TDesign Space + Tag 组件显示分组名称和三个标签：总数（theme=primary, variant=light）、正常数（theme=success, variant=light）、异常数（theme=danger, variant=light），标签仅显示数字
+- **THEN**       分组标题 SHALL 使用 CSS flex 布局（`display:flex; align-items:center`）显示分组名称和三个标签：总数（theme=primary, variant=light）、正常数（theme=success, variant=light）、异常数（theme=danger, variant=light），标签仅显示数字。分组名称 SHALL 使用 TDesign Typography.Title 组件（level="h4"）渲染，不使用原生 h2 标签和内联 style。Typography.Title 默认 margin SHALL 通过 CSS 覆盖归零

 #### Scenario: 分组统计标签提示
 - **WHEN** 鼠标悬停在分组统计标签上
@@ -23,6 +23,10 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组包含带统计的
 - **WHEN** 分组名称为 "default"
 - **THEN** 分组标题 SHALL 显示 "默认分组"

+#### Scenario: 分组标题间距
+- **WHEN** 分组标题渲染
+- **THEN** 标题与表格之间的间距 SHALL 通过 CSS 类控制，不使用内联 style 的 marginBottom
+
 ### Requirement: 响应式卡片网格
 Dashboard SHALL 使用 TDesign PrimaryTable 展示每个分组的目标，表格宽度自适应容器。

@@ -70,7 +74,7 @@ Dashboard SHALL 使用 TDesign PrimaryTable 展示每个分组的目标，表格
 - **THEN** 间隔列 SHALL 显示检查间隔（如 "5s"、"30s"），居中对齐，宽度 72px

 ### Requirement: 卡片交互
-表格行 SHALL 支持 hover 效果和点击打开 Drawer。
+表格行 SHALL 支持 hover 效果和点击打开 Drawer。cursor 样式通过 CSS 类实现。

 #### Scenario: 行 hover 效果
 - **WHEN** 鼠标悬停在表格行上
@@ -79,3 +83,7 @@ Dashboard SHALL 使用 TDesign PrimaryTable 展示每个分组的目标，表格
 #### Scenario: 行点击打开详情
 - **WHEN** 用户点击某个目标表格行
 - **THEN** 系统 SHALL 打开该目标的详情 Drawer
+
+#### Scenario: 行 cursor 样式
+- **WHEN** 表格渲染
+- **THEN** PrimaryTable SHALL 通过 CSS 类 `.clickable-table` 设置 cursor: pointer，不使用内联 style
--- a/openspec/specs/css-utility-classes/spec.md
+++ b/openspec/specs/css-utility-classes/spec.md
@@ -0,0 +1,69 @@
+## Purpose
+
+定义 styles.css 中集中管理的前端样式工具类和 CSS 自定义属性，供 TDesign 组件之外的自定义组件（StatusDot、StatusBar 等）引用。
+
+## Requirements
+
+### Requirement: 状态色 CSS 类
+styles.css SHALL 定义状态指示相关的 CSS 类，颜色使用 TDesign tokens。
+
+#### Scenario: StatusDot 颜色类
+- **WHEN** StatusDot 组件渲染
+- **THEN** 组件 SHALL 使用 `.status-dot` 基础类 + `.status-dot--up`（background: `--td-success-color`）或 `.status-dot--down`（background: `--td-error-color`）修饰类，不使用内联 style
+
+#### Scenario: StatusDot 发光阴影
+- **WHEN** StatusDot 组件渲染
+- **THEN** `.status-dot--up` SHALL 定义 `box-shadow` 使用 `--td-success-color`，`.status-dot--down` SHALL 定义 `box-shadow` 使用 `--td-error-color`
+
+#### Scenario: StatusBar 色块类
+- **WHEN** StatusBar 组件渲染色块
+- **THEN** 组件 SHALL 使用 `.status-bar-block` 基础类 + `.status-bar-block--up`（background: `--td-success-color`）、`.status-bar-block--down`（background: `--td-error-color`）或 `.status-bar-block--empty`（background: `--td-bg-color-component-disabled`）修饰类，不使用内联 style
+
+### Requirement: 可用率色阶 CSS 变量
+styles.css SHALL 定义 10 级可用率色阶 CSS 自定义属性，使用项目自定义色值。
+
+#### Scenario: 色阶变量定义
+- **WHEN** 可用率进度条渲染
+- **THEN** 色阶 SHALL 通过 CSS 自定义属性 `--avail-0` 到 `--avail-9` 定义，值为项目自定义色值（`#d54941` 到 `#3dba60`）
+
+#### Scenario: 色阶渐变方向
+- **WHEN** 色阶变量被引用
+- **THEN** 色阶 SHALL 从红色（0-30%）经橙色（30-60%）过渡到绿色（60-100%）
+
+### Requirement: 辅助工具类
+styles.css SHALL 定义前端组件复用的工具类。
+
+#### Scenario: 文本禁用色类
+- **WHEN** 延迟列无数据需要显示占位符
+- **THEN** 组件 SHALL 使用 `.text-disabled` 类（color: `--td-text-color-disabled`），不使用内联 style
+
+#### Scenario: 等宽数字类
+- **WHEN** 数值需要等宽显示
+- **THEN** 组件 SHALL 使用 `.tabular-nums` 类（font-variant-numeric: tabular-nums）
+
+#### Scenario: 延迟色值类
+- **WHEN** 延迟数值渲染
+- **THEN** 组件 SHALL 使用 `.latency-ok`（color: `--td-success-color`）、`.latency-warn`（color: `--td-warning-color`）或 `.latency-error`（color: `--td-error-color`）类，不使用内联 style
+
+#### Scenario: 全宽布局类
+- **WHEN** 组件需要占满父容器宽度
+- **THEN** 组件 SHALL 使用 `.full-width` 类（width: 100%），不使用内联 style
+
+#### Scenario: 可点击表格类
+- **WHEN** PrimaryTable 行支持点击交互
+- **THEN** 表格 SHALL 使用 `.clickable-table` 类（cursor: pointer），不使用内联 style
+
+#### Scenario: Tab 面板内边距类
+- **WHEN** Drawer 内 Tabs 面板需要内边距
+- **THEN** TabPanel SHALL 使用 `className="tab-panel-padded"` prop 传入类名，不通过入侵 TDesign 内部类名覆盖
+
+### Requirement: 异常行背景类
+styles.css SHALL 定义 DOWN 行的背景色，使用安全选择器且不使用 `!important`。
+
+#### Scenario: DOWN 行背景色
+- **WHEN** 表格行标记为 DOWN 状态
+- **THEN** 行 SHALL 通过 `.t-table tr.row-down` 选择器获得浅红色背景（引用 `--td-error-color-light` token），不使用 `!important`
+
+#### Scenario: DOWN 行 hover 状态
+- **WHEN** 鼠标悬停在 DOWN 行上
+- **THEN** 行背景 SHALL 通过 `.t-table--hoverable tbody tr.row-down:hover` 选择器显示 hover 状态色
--- a/openspec/specs/probe-dashboard/spec.md
+++ b/openspec/specs/probe-dashboard/spec.md
@@ -42,7 +42,7 @@ Dashboard SHALL 使用 TDesign Drawer 展示目标详情，包含时间范围筛
 - **THEN** Drawer SHALL 关闭

 ### Requirement: 页面加载与错误状态
-Dashboard SHALL 使用 TDesign 组件正确处理加载状态和 API 错误。
+Dashboard SHALL 使用 TDesign 组件正确处理加载状态和 API 错误。页面标题使用 TDesign Typography 组件渲染。

 #### Scenario: 首次加载
 - **WHEN** 页面首次加载且数据尚未返回
@@ -55,3 +55,7 @@ Dashboard SHALL 使用 TDesign 组件正确处理加载状态和 API 错误。
 #### Scenario: Drawer 内部加载状态
 - **WHEN** Drawer 内趋势数据或历史记录正在加载
 - **THEN** 概览面板的"趋势"区域 SHALL 显示 TDesign Skeleton 加载占位，记录表格 SHALL 显示 loading 状态
+
+#### Scenario: 页面标题
+- **WHEN** Dashboard 页面渲染
+- **THEN** 页面标题 SHALL 使用 TDesign Typography.Title 组件（level="h1"）渲染"DiAL"，副标题 SHALL 使用 Typography.Text 组件（theme="secondary"）渲染"统一拨测平台"，不使用原生 h1/p 标签和内联 style
--- a/openspec/specs/target-detail-drawer/spec.md
+++ b/openspec/specs/target-detail-drawer/spec.md
@@ -5,7 +5,7 @@
 ## Requirements

 ### Requirement: 目标详情 Drawer
-Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。
+Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。

 #### Scenario: 打开 Drawer
 - **WHEN** 用户点击某个目标表格行
@@ -13,7 +13,7 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示

 #### Scenario: Drawer 标题栏
 - **WHEN** Drawer 渲染
- **THEN** 标题栏 SHALL 显示 StatusDot、目标名称和类型标签（TDesign Tag），以及内建关闭按钮
+- **THEN** 标题栏 SHALL 使用 TDesign Space 组件（align="center"）布局，包含 StatusDot、目标名称（TDesign Typography.Text strong）和类型标签（TDesign Tag），以及内建关闭按钮。不使用内联 style 的 flex 布局

 #### Scenario: 关闭 Drawer
 - **WHEN** 用户点击关闭按钮、ESC 键或遮罩层
@@ -31,6 +31,10 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示
 - **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: 时间范围选择器
 Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录两个面板的数据。时间选择器 SHALL 分两行显示：第一行为快捷按钮，第二行为日期时间范围选择器。

@@ -52,7 +56,7 @@ Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录

 #### Scenario: DateRangePicker 全宽显示
 - **WHEN** Drawer 渲染
- **THEN** DateRangePicker SHALL 占满时间选择区第二行的宽度（width: 100%）
+- **THEN** DateRangePicker SHALL 通过 CSS 类 `.full-width` 占满时间选择区第二行的宽度，不使用内联 style 的 width: 100%

 #### Scenario: 默认时间范围
 - **WHEN** Drawer 打开
@@ -63,22 +67,30 @@ Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录
 - **THEN** 系统 SHALL 重新请求趋势数据和历史记录

 ### Requirement: Tabs 内容组织
-Drawer 内部 SHALL 使用 TDesign 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 按区域展示目标统计摘要、趋势图、状态分布和基本信息，每个区域使用小标题分隔。
+概览 Tab SHALL 按区域展示目标统计摘要、趋势图、状态分布和基本信息，每个区域使用 TDesign Divider 组件作为小标题分隔。

 #### Scenario: 区域排列顺序
 - **WHEN** 概览面板渲染
- **THEN** 面板 SHALL 按以下顺序展示区域：统计 → 趋势 → 状态分布 → 基本信息，每个区域前 SHALL 显示小标题
+- **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 横向排列
+- **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** 概览面板渲染且趋势数据可用
--- a/openspec/specs/target-table/spec.md
+++ b/openspec/specs/target-table/spec.md
@@ -24,11 +24,11 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
 - **THEN** 分组标题 SHALL 显示 "默认分组"

 ### Requirement: 表格列定义
-每个分组的 PrimaryTable SHALL 包含状态、名称、类型、可用率、最近状态条、延迟、间隔 7 列，不含分组列（同组内冗余）。
+每个分组的 PrimaryTable SHALL 包含状态、名称、类型、可用率、最近状态条、延迟、间隔 7 列，不含分组列（同组内冗余）。列渲染不使用内联 style。

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

 #### Scenario: 名称列
 - **WHEN** 表格渲染
@@ -40,15 +40,15 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立

 #### Scenario: 可用率列
 - **WHEN** 表格渲染
- **THEN** 可用率列 SHALL 使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色按可用率数值每 10% 一档：0-10% 最红（#d54941），每升高 10% 色阶偏移一档，经过橙色区间，90-100% 最绿（#3dba60），label 显示百分比数值，支持排序（升序优先，最差排最前）
+- **THEN** 可用率列 SHALL 使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色通过 CSS 自定义属性 `--avail-N`（基于项目自定义色值）控制，每 10% 一档，label 显示百分比数值，支持排序（升序优先，最差排最前）。color-threshold 函数 SHALL 返回 CSS 自定义属性引用而非硬编码色值

 #### Scenario: 最近状态列
 - **WHEN** 表格渲染
- **THEN** 最近状态列 SHALL 使用 StatusBar 组件渲染 30 格采样色块，宽度 220px，色块使用 flex:1 自适应列宽
+- **THEN** 最近状态列 SHALL 使用 StatusBar 组件渲染 30 格采样色块，宽度 220px。StatusBar SHALL 通过 CSS 类（`.status-bar-block--up` / `.status-bar-block--down` / `.status-bar-block--empty`）控制色块颜色，不使用内联 style

 #### Scenario: 延迟列
 - **WHEN** 表格渲染
- **THEN** 延迟列 SHALL 显示最近一次检查的延迟毫秒数，右对齐，颜色根据阈值变化：≤100ms 使用 --td-success-color、100-500ms 使用 --td-warning-color、>500ms 使用 --td-error-color，无数据显示"-"，支持数值排序
+- **THEN** 延迟列 SHALL 显示最近一次检查的延迟毫秒数，右对齐。颜色 SHALL 通过 CSS 类实现：≤100ms 使用 `.latency-ok`、100-500ms 使用 `.latency-warn`、>500ms 使用 `.latency-error`。无数据 SHALL 使用 `.text-disabled` 类显示 "-"，数值 SHALL 使用 `.tabular-nums` 类等宽显示。不使用内联 style

 #### Scenario: 间隔列
 - **WHEN** 表格渲染
@@ -62,11 +62,15 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
 - **THEN** 每个分组表格 SHALL 默认按状态降序排列，DOWN 目标排在同组最前面

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

 #### Scenario: DOWN 行背景色
 - **WHEN** 目标最近一次检查 matched=false
- **THEN** 该行 SHALL 使用浅红色背景（--td-error-color-light），与正常行形成视觉区分
+- **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。