feat: 新增两个 OpenSpec 变更提案 — 前端架构重构与 HTTP Checker 质量加固

- frontend-architecture-refactor: 拆分 hooks/组件、类型筛选器动态化 - http-checker-quality-hardening: ReDoS 防护、failure 格式修正、测试补全
2026-05-13 18:40:08 +08:00
parent 147a2559ae
commit 76b47006fe
14 changed files with 800 additions and 0 deletions
--- a/openspec/changes/frontend-architecture-refactor/specs/meta-api/spec.md
+++ b/openspec/changes/frontend-architecture-refactor/specs/meta-api/spec.md
@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Meta 信息 API
+系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。
+
+#### Scenario: 获取 checker 类型列表
+- **WHEN** 客户端请求 `GET /api/meta`
+- **THEN** 系统 SHALL 返回 JSON `{ checkerTypes: string[] }`，包含所有已注册的 checker 类型标识符（如 `["http", "command"]`）
+
+#### Scenario: 类型列表来源
+- **WHEN** 系统启动并注册了 checker
+- **THEN** `/api/meta` 返回的 `checkerTypes` SHALL 与 `CheckerRegistry.supportedTypes` 完全一致
+
+#### Scenario: 仅允许 GET/HEAD 方法
+- **WHEN** 客户端使用 POST/PUT/DELETE 等方法请求 `/api/meta`
+- **THEN** 系统 SHALL 返回 405 状态码
+
+#### Scenario: HEAD 请求返回空体
+- **WHEN** 客户端使用 HEAD 方法请求 `/api/meta`
+- **THEN** 系统 SHALL 返回 200 状态码和正确的 Content-Type header，body 为空
+
+### Requirement: MetaResponse 共享类型
+系统 SHALL 在 `src/shared/api.ts` 中定义 `MetaResponse` 类型。
+
+#### Scenario: MetaResponse 类型定义
+- **WHEN** 前后端引用 `MetaResponse` 类型
+- **THEN** 该类型 SHALL 包含 `checkerTypes: string[]` 字段
--- a/openspec/changes/frontend-architecture-refactor/specs/tanstack-query-data-layer/spec.md
+++ b/openspec/changes/frontend-architecture-refactor/specs/tanstack-query-data-layer/spec.md
@@ -0,0 +1,109 @@
+## MODIFIED Requirements
+
+### Requirement: TanStack Query 数据层
+前端 SHALL 使用 TanStack Query（@tanstack/react-query）管理所有 API 请求，数据层代码 SHALL 按职责拆分为独立 hook 文件。
+
+#### Scenario: QueryClient 配置
+- **WHEN** 应用启动
+- **THEN** 系统 SHALL 创建 QueryClient，默认配置 retry=1、refetchOnWindowFocus=true、staleTime=5000
+
+#### Scenario: QueryClientProvider 挂载
+- **WHEN** 应用渲染
+- **THEN** 根组件 SHALL 包裹在 QueryClientProvider 中，提供 QueryClient 实例
+
+### Requirement: queryKey 工厂
+系统 SHALL 提供统一的 queryKey 工厂函数，确保 queryKey 的唯一性和一致性。
+
+#### Scenario: summary queryKey
+- **WHEN** 查询 summary 数据
+- **THEN** queryKey SHALL 为 ["summary"]
+
+#### Scenario: targets queryKey
+- **WHEN** 查询 targets 数据
+- **THEN** queryKey SHALL 为 ["targets"]
+
+#### Scenario: meta queryKey
+- **WHEN** 查询 meta 数据
+- **THEN** queryKey SHALL 为 ["meta"]
+
+#### Scenario: trend queryKey
+- **WHEN** 查询某目标的趋势数据
+- **THEN** queryKey SHALL 为 ["trend", targetId, from, to]
+
+#### Scenario: history queryKey
+- **WHEN** 查询某目标的历史记录
+- **THEN** queryKey SHALL 为 ["history", targetId, from, to, page]
+
+### Requirement: Hook 文件拆分
+数据层 hook SHALL 按职责拆分为独立文件。
+
+#### Scenario: 全局查询 hook 文件
+- **WHEN** 开发者需要使用全局面板级查询
+- **THEN** `useSummary`、`useTargets`、`useMeta` SHALL 从 `hooks/use-queries.ts` 导出
+
+#### Scenario: Drawer 状态 hook 文件
+- **WHEN** 开发者需要使用 Drawer 状态管理
+- **THEN** `useTargetDetail` SHALL 从 `hooks/use-target-detail.ts` 导出
+
+#### Scenario: fetchJson 不导出
+- **WHEN** 数据层内部需要 fetch 封装
+- **THEN** `fetchJson` SHALL 定义在 `use-queries.ts` 内部，不作为公共 API 导出
+
+#### Scenario: queryKeys 不导出
+- **WHEN** 数据层内部需要 query key
+- **THEN** `queryKeys` 对象 SHALL 定义在 `use-queries.ts` 内部，不作为公共 API 导出
+
+### Requirement: Meta 查询
+系统 SHALL 提供 `useMeta` hook 查询系统元数据。
+
+#### Scenario: meta 查询配置
+- **WHEN** 应用启动
+- **THEN** `useMeta` SHALL 请求 `/api/meta`，配置 `staleTime: Infinity`（应用生命周期内只请求一次）
+
+#### Scenario: meta 数据返回
+- **WHEN** meta 查询成功
+- **THEN** hook SHALL 返回 `MetaResponse` 类型数据，包含 `checkerTypes` 字段
+
+### Requirement: Summary 轮询查询
+系统 SHALL 使用 useQuery 实现总览统计的自动轮询。
+
+#### Scenario: summary 自动轮询
+- **WHEN** Dashboard 页面处于打开状态
+- **THEN** 系统 SHALL 每 8 秒自动请求 /api/summary，使用 refetchInterval=8000
+
+#### Scenario: summary 后台刷新
+- **WHEN** 页面处于后台标签页
+- **THEN** 系统 SHALL 暂停轮询（refetchIntervalInBackground=false）
+
+### Requirement: Targets 轮询查询
+系统 SHALL 使用 useQuery 实现目标列表的自动轮询。
+
+#### Scenario: targets 自动轮询
+- **WHEN** Dashboard 页面处于打开状态
+- **THEN** 系统 SHALL 每 8 秒自动请求 /api/targets，使用 refetchInterval=8000
+
+### Requirement: 条件查询
+趋势和历史记录查询 SHALL 使用 enabled 条件控制，仅在目标被选中时触发。
+
+#### Scenario: 未选中目标时不请求
+- **WHEN** 用户未点击任何目标表格行
+- **THEN** trend 和 history 的 useQuery SHALL enabled=false，不发起请求
+
+#### Scenario: 选中目标时自动请求
+- **WHEN** 用户点击目标表格行
+- **THEN** trend 和 history 的 useQuery SHALL enabled=true，自动发起请求
+
+#### Scenario: 时间范围变化时重新请求
+- **WHEN** 用户更改时间范围
+- **THEN** trend 和 history 的 useQuery SHALL 因 queryKey 变化自动重新请求
+
+### Requirement: 开发调试面板
+开发环境下 SHALL 挂载 TanStack Query Devtools。
+
+#### Scenario: 开发环境显示 Devtools
+- **WHEN** 应用在开发模式下运行
+- **THEN** 页面 SHALL 显示 ReactQueryDevtools 浮动面板
+
+#### Scenario: 生产环境排除 Devtools
+- **WHEN** 应用在生产模式下构建
+- **THEN** ReactQueryDevtools SHALL 不被包含在产物中
--- a/openspec/changes/frontend-architecture-refactor/specs/target-detail-drawer/spec.md
+++ b/openspec/changes/frontend-architecture-refactor/specs/target-detail-drawer/spec.md
@@ -0,0 +1,91 @@
+## MODIFIED 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 状态
--- a/openspec/changes/frontend-architecture-refactor/specs/target-table/spec.md
+++ b/openspec/changes/frontend-architecture-refactor/specs/target-table/spec.md
@@ -0,0 +1,69 @@
+## MODIFIED Requirements
+
+### 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 使用 TDesign Progress 组件（theme=line, size=small）渲染，颜色通过 CSS 自定义属性 `--avail-N`（基于项目自定义色值）控制，每 10% 一档，label 显示百分比数值，支持排序（升序优先，最差排最前）。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 显示最近一次检查的延迟毫秒数，右对齐。颜色 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 共享同一套列定义常量。
+
+#### Scenario: 列定义提取为常量
+- **WHEN** 多个分组表格渲染
+- **THEN** 列定义 SHALL 从独立的 constants/target-table-columns.tsx 导入，不在组件中重复定义
--- a/openspec/changes/frontend-architecture-refactor/specs/target-type-display/spec.md
+++ b/openspec/changes/frontend-architecture-refactor/specs/target-type-display/spec.md
@@ -0,0 +1,13 @@
+## REMOVED Requirements
+
+### Requirement: 类型显示名称映射
+**Reason**: 前端不再维护 type → label 的静态映射，直接使用后端返回的 type 原始文本展示。类型筛选器列表改由 meta API 动态驱动。
+**Migration**: 所有使用 `getTargetTypeDisplay(type)` 的位置改为直接使用 `type` 字符串。`TARGET_TYPE_DISPLAY` 常量和 `target-type-display.ts` 文件删除。
+
+### Requirement: 映射可扩展性
+**Reason**: 不再需要前端映射扩展机制，新增 checker 类型时后端注册即自动通过 meta API 暴露给前端。
+**Migration**: 无需迁移，删除即可。
+
+### Requirement: 类型安全
+**Reason**: 不再有映射常量，无需 TypeScript 类型推导和 fallback 逻辑。
+**Migration**: 无需迁移，删除即可。