feat: 优化目标详情 Drawer 性能 — TDesign 生命周期控制、Tab 感知延迟加载、滚动穿透修复

openspec/specs/tanstack-query-data-layer/spec.md

@@ -91,19 +91,27 @@
 - **THEN** 系统 SHALL 按用户选择的刷新间隔自动请求数据，轮询间隔与 summary 查询保持一致
 
 ### Requirement: 条件查询
-趋势和历史记录查询 SHALL 使用 enabled 条件控制，仅在目标被选中时触发。
+详情指标和历史记录查询 SHALL 使用 enabled 条件控制。指标查询 SHALL 在目标和时间范围有效时触发；历史记录查询 SHALL 仅在目标、时间范围有效且"记录"Tab 激活后触发。
 
 #### Scenario: 未选中目标时不请求
 - **WHEN** 用户未点击任何目标表格行
-- **THEN** trend 和 history 的 useQuery SHALL enabled=false，不发起请求
+- **THEN** metrics 和 history 的 useQuery SHALL enabled=false，不发起请求
 
-#### Scenario: 选中目标时自动请求
-- **WHEN** 用户点击目标表格行
-- **THEN** trend 和 history 的 useQuery SHALL enabled=true，自动发起请求
+#### Scenario: 打开 Drawer 默认只请求指标
+- **WHEN** 用户点击目标表格行并打开 Drawer
+- **THEN** metrics 的 useQuery SHALL enabled=true 并自动发起请求，history 的 useQuery SHALL enabled=false 且不发起请求
 
-#### Scenario: 时间范围变化时重新请求
-- **WHEN** 用户更改时间范围
-- **THEN** trend 和 history 的 useQuery SHALL 因 queryKey 变化自动重新请求
+#### Scenario: 激活记录 Tab 时请求历史记录
+- **WHEN** 用户切换到"记录"Tab 且目标与时间范围有效
+- **THEN** history 的 useQuery SHALL enabled=true，并请求当前页码对应的 `/api/targets/:id/history` 数据
+
+#### Scenario: 概览 Tab 时间范围变化时不请求历史记录
+- **WHEN** 用户在"概览"Tab 修改时间范围
+- **THEN** metrics 的 useQuery SHALL 因 queryKey 变化自动重新请求，history 的 useQuery SHALL 保持 enabled=false 且不发起请求
+
+#### Scenario: 记录 Tab 时间范围变化时重新请求历史记录
+- **WHEN** 用户在"记录"Tab 修改时间范围
+- **THEN** metrics 和 history 的 useQuery SHALL 因 queryKey 变化自动重新请求，并将 history 页码重置为 1
 
 ### Requirement: 开发调试面板
 开发环境下 SHALL 挂载 TanStack Query Devtools。

openspec/specs/target-detail-drawer/spec.md

@@ -5,11 +5,11 @@
 ## Requirements
 
 ### Requirement: 目标详情 Drawer
-Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。Drawer 内容 SHALL 拆分为独立的 Tab 组件。
+Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示该目标的详细统计信息和检查记录。Drawer 标题栏和内容不使用内联 style。Drawer 内容 SHALL 拆分为独立的 Tab 组件，并优先通过 TDesign Drawer 原生生命周期能力控制显示、隐藏和滚动穿透。
 
 #### Scenario: 打开 Drawer
 - **WHEN** 用户点击某个目标表格行
-- **THEN** 系统 SHALL 从右侧滑出 Drawer（placement="right"），宽度为 52%
+- **THEN** 系统 SHALL 从右侧滑出 Drawer（placement="right"），宽度为 52%，并将当前 Tab 重置为"概览"
 
 #### Scenario: Drawer 标题栏
 - **WHEN** Drawer 渲染
@@ -17,7 +17,7 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示
 
 #### Scenario: 关闭 Drawer
 - **WHEN** 用户点击关闭按钮、ESC 键或遮罩层
-- **THEN** Drawer SHALL 关闭
+- **THEN** Drawer SHALL 关闭并通过 TDesign Drawer 的 `visible` 状态隐藏
 
 #### Scenario: Drawer 无底部按钮
 - **WHEN** Drawer 渲染
@@ -29,7 +29,7 @@ Dashboard SHALL 在用户点击目标表格行后从右侧滑出 Drawer，展示
 
 #### Scenario: 切换目标重置 Tab
 - **WHEN** 用户从目标 A 切换到目标 B（点击不同的表格行）
-- **THEN** Drawer SHALL 重置为概览 Tab，使用 key={target.id} 确保组件状态不残留
+- **THEN** Drawer SHALL 通过受控 Tab 状态重置为概览 Tab，且 MUST NOT 使用 `key={target.id}` 强制重建 Drawer 子树
 
 #### Scenario: Drawer 内容区间距
 - **WHEN** Drawer 内容渲染
@@ -104,10 +104,10 @@ StatusBar 组件 SHALL 支持可配置的格数。
 
 #### Scenario: Drawer 关闭清理查询缓存
 - **WHEN** 用户关闭 Drawer
-- **THEN** 系统 MAY 清理 metrics 和 history 查询缓存，避免旧目标数据残留
+- **THEN** 系统 MAY 保留 metrics 和 history 查询缓存以降低重复打开成本，依赖 TanStack Query 全局 staleTime 自动管理过期
 
 ### Requirement: 时间范围选择器
-Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录两个面板的数据。
+Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览面板的数据；当记录面板处于激活状态或后续首次进入记录面板时，时间范围也 SHALL 影响记录面板的数据。
 
 #### Scenario: 快捷时间按钮
 - **WHEN** Drawer 渲染
@@ -121,21 +121,25 @@ Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录
 - **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
 - **THEN** 概览面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/metrics` 数据
 
-#### Scenario: 快捷按钮联动历史记录
-- **WHEN** 用户点击 1小时/6小时/24小时/7天 快捷按钮
+#### Scenario: 快捷按钮联动激活的历史记录
+- **WHEN** 用户在"记录"Tab 激活时点击 1小时/6小时/24小时/7天 快捷按钮
 - **THEN** 记录面板 SHALL 使用对应的时间窗口重新请求 `/api/targets/:id/history` 数据，并重置页码为 1
 
+#### Scenario: 快捷按钮不预取未激活历史记录
+- **WHEN** 用户在"概览"Tab 激活时点击 1小时/6小时/24小时/7天 快捷按钮
+- **THEN** 系统 SHALL NOT 请求 `/api/targets/:id/history`，直到用户切换到"记录"Tab
+
 #### Scenario: 自定义日期时间范围
 - **WHEN** 用户通过 TDesign DateRangePicker（mode=date, enableTimePicker, format="YYYY-MM-DD HH:mm"）修改时间范围
-- **THEN** 快捷按钮 SHALL 取消高亮，系统重新请求对应时间范围的数据
+- **THEN** 快捷按钮 SHALL 取消高亮，系统 SHALL 按新的时间范围刷新概览数据，并按当前 Tab 状态决定是否刷新历史记录
 
 #### Scenario: 时间精度为分钟级
 - **WHEN** 用户通过 DateRangePicker 选择时间
 - **THEN** 选择器 SHALL 仅精确到分钟（format="YYYY-MM-DD HH:mm"），秒列固定为 00
 
-#### Scenario: DateRangePicker 全宽显示
+#### Scenario: DateRangePicker 自适应显示
 - **WHEN** Drawer 渲染
-- **THEN** DateRangePicker SHALL 通过 CSS 类 `.full-width` 占满时间选择区的宽度，不使用内联 style 的 width: 100%
+- **THEN** DateRangePicker SHALL 通过 CSS 类 `.drawer-date-range`（替代原 `.full-width`）自适应填充时间选择区剩余宽度，不使用内联 style 的 width: 100%
 
 #### Scenario: 默认时间范围
 - **WHEN** Drawer 打开
@@ -143,19 +147,31 @@ Drawer SHALL 在 Tabs 外层提供时间范围选择器，影响概览和记录
 
 #### Scenario: 筛选触发数据刷新
 - **WHEN** 时间范围发生变化
-- **THEN** 系统 SHALL 重新请求趋势数据和历史记录
+- **THEN** 系统 SHALL 重新请求趋势数据；若"记录"Tab 当前激活，系统 SHALL 同时重新请求历史记录，否则 SHALL 延迟到用户进入"记录"Tab 后请求历史记录
 
 ### Requirement: Tabs 内容组织
-Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。TabPanel 内边距通过 className prop 控制。
+Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。Tabs SHALL 使用受控 value 管理当前激活 Tab，TabPanel 内边距通过 className prop 控制。
 
 #### Scenario: Tab 标签
 - **WHEN** Drawer 渲染
 - **THEN** Tabs SHALL 显示两个标签：概览、记录
 
+#### Scenario: Tabs 受控状态
+- **WHEN** 用户切换 Tab
+- **THEN** Tabs SHALL 通过 `value` 和 `onChange` 更新由 Drawer 状态 hook 管理的当前 Tab 值
+
+#### Scenario: 默认概览 Tab
+- **WHEN** Drawer 打开或切换到另一个目标
+- **THEN** 当前 Tab SHALL 重置为 `overview`
+
 #### Scenario: Tab 面板内边距
 - **WHEN** TabPanel 渲染
 - **THEN** TabPanel SHALL 通过 `className` prop 传入自定义类名（`tab-panel-padded`）控制内边距，不通过入侵 TDesign 内部类名（`.t-tab-panel`）覆盖
 
+#### Scenario: TabPanel 懒渲染与缓存
+- **WHEN** 用户在概览和记录 Tab 之间切换
+- **THEN** 概览和记录 TabPanel 均 SHALL 配置 TDesign TabPanel 的 `destroyOnHide={false}`，隐藏时不销毁组件，保留已挂载的面板状态和已加载的数据；记录 TabPanel SHALL 额外配置懒渲染，首次进入前不渲染 HistoryTab
+
 ### Requirement: 概览面板
 概览 Tab SHALL 按区域展示基本信息、多维度统计和趋势图。
 
@@ -195,6 +211,25 @@ Drawer 内部 SHALL 使用 TDesign Tabs 组织概览和记录两个面板。TabP
 - **WHEN** metricsData 正在加载
 - **THEN** "趋势"区域 SHALL 显示 TDesign Skeleton 加载占位
 
+### Requirement: Drawer TDesign 原生生命周期与滚动控制
+目标详情 Drawer SHALL 优先使用 TDesign Drawer 的原生 props 控制挂载、可见性和滚动穿透，不通过自定义滚轮事件实现滚动控制。
+
+#### Scenario: Drawer 常驻受控渲染
+- **WHEN** 未选中目标时
+- **THEN** `TargetDetailDrawer` SHALL 保留 TDesign Drawer 组件并通过 `visible=false` 隐藏，而不是直接返回 `null` 卸载 Drawer 子树
+
+#### Scenario: Drawer 防滚动穿透配置
+- **WHEN** Drawer 渲染
+- **THEN** Drawer SHALL 显式使用 `attach="body"`、`preventScrollThrough=true`、`showInAttachedElement=false` 和 `showOverlay=true`
+
+#### Scenario: Drawer 关闭后保留子树
+- **WHEN** 用户关闭 Drawer
+- **THEN** Drawer SHALL 使用 `destroyOnClose=false` 保留已挂载内容，避免重复打开时重建完整子树
+
+#### Scenario: Drawer 单一纵向滚动容器
+- **WHEN** Drawer 内容高度超过可视区域
+- **THEN** 系统 SHALL 依赖 Drawer 内容区域作为唯一纵向滚动容器，HistoryTab 中的 PrimaryTable SHALL 不配置 `height`、`maxHeight` 或纵向 `scroll` 来创建第二个纵向滚动区域
+
 ### Requirement: Drawer 宽度
 Drawer 宽度 SHALL 设置为 52%。