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
parent a62007083d
commit 31aeee6d60
41 changed files with 713 additions and 902 deletions
--- a/openspec/specs/meta-api/spec.md
+++ b/openspec/specs/meta-api/spec.md
@@ -0,0 +1,31 @@
+## Purpose
+
+定义系统运行时元数据 API：checker 类型列表等元信息的对外暴露方式。
+
+## 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/specs/probe-api/spec.md
+++ b/openspec/specs/probe-api/spec.md
@@ -130,3 +130,29 @@
 #### Scenario: 无失败信息
 - **WHEN** 检查结果 matched=true
 - **THEN** API SHALL 返回 failure 为 null
+
+### Requirement: Meta 信息 API
+系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。
+
+#### Scenario: 获取 checker 类型列表
+- **WHEN** 客户端请求 `GET /api/meta`
+- **THEN** 系统 SHALL 返回 JSON `{ checkerTypes: string[] }`，包含所有已注册的 checker 类型标识符
+
+#### 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/specs/tanstack-query-data-layer/spec.md
+++ b/openspec/specs/tanstack-query-data-layer/spec.md
@@ -5,7 +5,7 @@
 ## Requirements

 ### Requirement: TanStack Query 数据层
-前端 SHALL 使用 TanStack Query（@tanstack/react-query）管理所有 API 请求，替代手写 fetch hooks。
+前端 SHALL 使用 TanStack Query（@tanstack/react-query）管理所有 API 请求，数据层代码 SHALL 按职责拆分为独立 hook 文件。

 #### Scenario: QueryClient 配置
 - **WHEN** 应用启动
@@ -34,6 +34,40 @@
 - **WHEN** 查询某目标的历史记录
 - **THEN** queryKey SHALL 为 ["history", targetId, from, to, page]

+#### Scenario: meta queryKey
+- **WHEN** 查询 meta 数据
+- **THEN** queryKey SHALL 为 ["meta"]
+
+### 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: 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: Summary 轮询查询
 系统 SHALL 使用 useQuery 实现总览统计的自动轮询。

--- 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，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。
+Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。Drawer 内容 SHALL 拆分为独立的 Tab 组件。

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

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

 #### Scenario: 关闭 Drawer
 - **WHEN** 用户点击关闭按钮、ESC 键或遮罩层
@@ -35,6 +35,65 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 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 分两行显示：第一行为快捷按钮，第二行为日期时间范围选择器。

--- a/openspec/specs/target-table/spec.md
+++ b/openspec/specs/target-table/spec.md
@@ -32,7 +32,7 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
 - **THEN** 分组之间 SHALL 使用 TDesign Space 组件（direction=vertical, size=32px）统一间距

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

 #### Scenario: 状态列
 - **WHEN** 表格渲染
@@ -44,7 +44,11 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立

 #### Scenario: 类型列
 - **WHEN** 表格渲染
- **THEN** 类型列 SHALL 使用 TDesign Tag 组件（size=small, theme=primary, variant=light-outline）显示类型名称，支持单选筛选
+- **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** 表格渲染
@@ -52,7 +56,7 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立

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

 #### Scenario: 延迟列
 - **WHEN** 表格渲染
@@ -62,6 +66,32 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
 - **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）目标排在最前面。

@@ -103,7 +133,7 @@ Dashboard SHALL 按 group 字段将目标分组，每个分组渲染一个独立
 - **THEN** 表格 SHALL 设置 size="small"、stripe、hover、bordered

 ### Requirement: 列定义复用
-所有分组的表格 SHALL 共享同一套列定义常量。
+所有分组的表格 SHALL 共享同一套列定义。

 #### Scenario: 列定义提取为常量
 - **WHEN** 多个分组表格渲染
--- a/openspec/specs/target-type-display/spec.md
+++ b/openspec/specs/target-type-display/spec.md
@@ -1,42 +0,0 @@
-## Purpose
-
-定义目标类型（Target Type）的前端显示名称映射系统，支持从后端类型标识符到 TDesign Tag 组件展示的可扩展转换。
-
-## Requirements
-
-### Requirement: 类型显示名称映射
-系统 SHALL 提供目标类型到显示名称的映射，将后端类型标识符转换为 TDesign Tag 组件的展示文本。
-
-#### Scenario: HTTP 类型显示
- **WHEN** 目标类型为 "http"
- **THEN** 前端 SHALL 使用 TDesign Tag 组件（size=small, theme=primary, variant=light-outline）显示 "HTTP"
-
-#### Scenario: Command 类型显示
- **WHEN** 目标类型为 "command"
- **THEN** 前端 SHALL 使用 TDesign Tag 组件显示 "CMD"
-
-#### Scenario: 未知类型处理
- **WHEN** 目标类型不在映射表中
- **THEN** 前端 SHALL 将类型名称转换为大写显示在 TDesign Tag 组件中
-
-### Requirement: 映射可扩展性
-类型映射系统 SHALL 支持后续新增类型，无需修改多处代码。
-
-#### Scenario: 新增类型映射
- **WHEN** 需要新增目标类型（如 "tcp"、"dns"、"grpc"）
- **THEN** 开发者 SHALL 仅需在映射常量中添加一条记录
-
-#### Scenario: 映射单一数据源
- **WHEN** 前端组件需要显示目标类型
- **THEN** 组件 SHALL 调用统一的映射函数，不直接硬编码映射逻辑
-
-### Requirement: 类型安全
-类型映射系统 SHALL 提供类型安全的访问方式。
-
-#### Scenario: TypeScript 类型推导
- **WHEN** 使用映射常量
- **THEN** TypeScript SHALL 能够推导出正确的类型（使用 `as const`）
-
-#### Scenario: 运行时安全
- **WHEN** 传入无效类型
- **THEN** 系统 SHALL 返回 fallback 值，不抛出异常