LuChiChick/Just-DataInspector
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
108 Commits 2 Branches 0 Tags
436dcbfd525c447252ac2cb067d95b53cec4eed0
Commit Graph
6 Commits
Author SHA1 Message Date
DeepSeek-V4.1-Flash 436dcbfd52 滚动过渡动画根治 + 快速连点跟手 + 分组名单击展开 + 光标吸附同源 + 按钮淡出对齐 + 滚动位置复位 
一、滚动过渡动画卡顿（用户报告：甚至不如手动拖滚动条）—— 三处独立根因
1) WM_TIMER(kScrollTimerId) 无条件整窗失效 ⇒ WM_PAINT 看到更新区域不在绘图区内 ⇒ 把
   m_chromeDirty 置真 ⇒ 每一帧都重绘标签栏/工具栏/面板。
   修法：用「推进之前」的面板动画状态决定失效范围 —— 面板动画（滚动到目标信号 / 分组折起展开）
   确实要改面板像素 ⇒ 整窗失效；只有绘图区动画（网格滚动到可视区 / 回到最上方）⇒ 只失效绘图区。
   实测：绘图区动画帧 13.6ms → 3.5ms；手动拖滚动条参照 4.2ms。
   ⚠️ 未改变 §9.41 的回送结构（仍是 if (fullFrame) {整窗} else {绘图区}）。
2) 图层预热不足：上百个离屏网格长期不建图层，长距离滚动动画扫进去时每一帧都有十几个网格
   没有图层像素，只能靠「网格底衬兜底」重画（约 0.5ms/网格 ⇒ +8ms/帧）。
   修法：LaneVisuallyRelevant(laneIndex, prefetchScreens) 增加 ±1 屏预取带（AnyVisibleLanePending 用），
   并新增 PrefetchStepAllowed()（kPrefetchMinIntervalMs=32 ⇒ 约 31 次/秒）限速地继续请求重绘，
   让整批图层在静置期间逐步建好。
   实测：lane-only + VERY_BIG_DATA 帧 13.9ms → 5.3ms；signal-click + VERY_BIG_DATA 18.3ms → 10.3ms。
3) 网格滚动量原本参与「宽基底可用性」判据（上一轮已修：SceneContentHash(..., includeLaneScroll=false)）。

二、光标吸附改用「放大自动点线」的同一判定（用户 2026-10-17 修订）
AutoPointLineNeeded 改名 MinorCellSparse（中性名，同一判定两处用途）：任一小格内有效数据点 < 5 即为稀疏。
- 「放大自动切点线」与「光标吸附」共用它；判定完全不看绘制方式 ⇒ 即使用户手动改过显示样式也照样吸附。
- 鼠标下方网格内既有符合又有不符合的信号时，只有符合的那条的数据点参与吸附；没有符合的则自由移动。
- 删除旧的整屏判据 SignalSnapEnabled 与 kSnapVisibleCellsPerPoint（死代码）。

三、「回到最上方」按钮淡出与「浮动提示」一致
kBackToTopFadeOutMs = kHintFadeMs（500ms）+ 线性 alpha，到达顶部立即开始淡出（不停留）。
淡入保留 170ms ease-out。实测 50% 时刻 alpha = 0.500（线性），旧 ease-out 会是 0.875。

四、快速连点跟手（根因：CS_DBLCLKS 合成 WM_LBUTTONDBLCLK 导致按下丢失）
组件各自实现 DoubleClickIsPlainPress(x, y)（该落点有没有双击语义），宿主 WM_LBUTTONDBLCLK 据此
选择走 OnLButtonDown（当作按下）还是 OnDoubleClick：
- PlotView：浮动面板（含复选框/滑块/复位/✕/标题栏）、「回到最上方」按钮、绘图区滚动条、GX 徽标 ⇒ 按下；
  时间光标线/读数标签/图例条目名/绘图区空白 ⇒ 保留双击。
- SignalPanel：样式区数值框、「目标」行名称与 GX 标签、行名称区域 ⇒ 保留双击；其余全部 ⇒ 按下。
- 弹出菜单 / 拾色器打开时，WM_LBUTTONDBLCLK 也按各自 OnLButtonDown 走。

五、分组行：名称恢复单击展开收起 + 只有快速双击进入改名
- OnLButtonDown 分组分支不再排除 RowPart::BODY：三角 /「组X」/ 名称本体统一折叠展开。
- OnDoubleClick 名称区域：只有快速双击（kGroupRenameDoubleClickMs=300，比系统 500ms 紧）才进入改名；
  超阈值的「慢双击」只当又一次单击；快速双击前先撤销按下那一次的折叠切换，保证进编辑时状态与点击前一致。

六、信号重现时网格滚动回到最上方
“有过需滚动条的网格 → 没有任何信号显示 → 又出现需滚动条数量的网格”这一类情形必须从最上方开始看。
修法：Application::SynchronizeView 的「首次出现可见信号」分支里，在 FitAll() 之后 tab.LaneScroll() = 0。

验证（全部离屏，不占用鼠标/键盘/屏幕）
- grabdanim（.preflight/perf/gridanim_main.cpp）93/93：真实消息循环帧距 + 逐帧渲染耗时（与手动拖滚动条
  对比）、光标吸附新判定、按钮淡出线性、快速连点路由、分组名单击/双击/慢双击、滚动位置复位。
- 既有回归：verify 49/49、panelanim 158/158（按新分组名规则更新 8 条断言）、datacheck 69/69、
  edgecheck 46/46、errcheck 19/19。
- make release / make debug 零错误零警告（用 TARGET_FILE_NAME=TargetCheck/TargetCheckD 避免与正在运行的实例冲突）。

文档：Documents/agent_mem.md 新增 §9.43、§11.2 第 125–133 条与变更日志一行。
 2026-10-17 03:17:42 +08:00
DeepSeek-V4.1-Flash 34375481de 网格底衬永不空白 + 动画流畅性根治 + 光标随首个信号重现 + 「放大自动点线」新判据 
一、网格底衬消失（半屏/局部/全屏，且要等一会才刷新好）—— 两个机制叠加
1) BlitWideBuffer 对「跨度已过期」的图层原用 StretchBlt 放大占位：深度放大时把一小段像素放大
   几十倍 ⇒ 整块网格变成一片无网格的模糊色块（用户看到的就是「网格叠底消失、没有任何内容」）。
   修法：删除占位拉伸；对拿不到（完整）图层像素的网格【就地补画网格底衬】
   （新增 PaintLaneGridBacking + m_renderGridOnly，复用 PaintLane 的网格部分，跳过波形/散点/
   派生曲线/Y 轴刻度/图例）。底衬代价极低，可每帧执行 ⇒ 网格永不空白/闪烁。
   ⚠️ 顺序：先画底衬（GDI+）再 g.GetHDC() 做 BitBlt；只有全部网格都贴不出像素时才交给整幅重绘。
2) 待重画队列按下标顺序消费（一次 1 个）⇒ 上百个网格时可视网格要等上百帧。
   修法：RenderPendingLaneRebuilds 里做稳定划分，【可视网格优先】（LaneVisuallyRelevant）；
   「结算」判据由 LanesAllReadyForView() 改为 LanesVisiblyReadyForView()。

二、过渡动画卡顿/不平顺/直接闪到终态 —— 三处根因
1) 「m_layerRebuildPending 非空就每帧请求再送一帧」：上百个网格时 700ms 内挤出 124 次重绘，
   而 WM_TIMER 优先级低于投递消息 ⇒ 动画定时器被饿死（实测 frames=124 / timerTicks=1）。
   修法：新增 AnyVisibleLanePending()，只用「还有没有可视网格待补」决定是否请求再送一帧；
   离屏网格改为机会式预热（实测 frames=25 / timerTicks=16）。
2) SetTimer 的间隔会被量化到系统 tick（默认 15.6ms）：请求 16ms 实际等到下一个 tick
   ⇒ 实测帧距 ~26ms（只有约 38fps）。修法：kScrollTimerPeriodMs 16 → 10（实测 ~15.5ms ≈ 64fps；
   真实消息循环帧距 ~25ms → ~16ms）。实测映射：8→15.8 / 10→15.5 / 12→16.5 / 16→26.4 / 31→37.9。
   ⚠️ timeBeginPeriod(1) 在本机无效（已 A/B 验证）。
3) 网格滚动联动 / 「回到最上方」每帧都改 LaneScroll()，而它原本参与「宽基底可用性」判据
   （SceneGeometryHash）⇒ 每一帧都退化成整幅重绘。修法：SceneContentHash 新增 includeLaneScroll 形参，
   宽基底可用性判据不计网格滚动量/各网格屏幕纵向位置（它们只是图层的贴图落点）；
   静态场景缓存的指纹仍然计入。实测网格滚动动画单帧 18.36ms → 1.19ms。

三、光标工具激活且没有任何信号绘制时，首个信号出现后按规则重新出现（用户要求）
新增 PlotView::ResetCursorPlacementOnFreshContent()（规则与 CycleCursorMode() 的「首次出现」同源：
单光标置于视图中心；双光标第二条紧邻第一条且落在可见范围内），由 Application::SynchronizeView
的「首次出现可见信号」分支在 FitAll() 之后调用。
实测：单光标 stale=4.60 → 新的视图中心 20.92；双光标 stale=(2.89,7.18) → (20.92,26.07)。

四、「放大自动点线」规则改为：任一小格内数据点少于 5 个即自动切换（用户重新定义）
新增 PlotView::AutoPointLineNeeded()（推翻此前「一屏内数据点 < N×4」）：按 GridMinorCellCount()
切成横向小格，只要存在任何一个小格内有效数据点 < kAutoPointLineMinPointsPerCell(=5) 就切「点线」。
实现：先「总有效点 < N×5」鸽巢 O(1) 充分判定；单调时间轴逐小格两次二分取区间（单格累计到 5 个即早退，
另给 kAutoPointLineCellScanCap=512 封顶）；非单调时间轴一次有界扫描分桶。保留「视界内至少一个可见点」保护。
⚠️ 光标吸附仍用旧的整屏判据 SignalSnapEnabled（用户明确要求「其它规则不变」）。

验证（全部离屏，不占用鼠标/键盘/屏幕）
- 新增 .preflight/perf/gridanim_main.cpp（gridanim.exe）55/55：
  [A] 缩放/适应视图/「预热未完成再滚动」等每个用例逐帧断言「每个可视网格都有网格底衬
      （有竖直锐边、无模糊占位、无未绘制带）」；[B] 直接驱动 + 真实消息循环两条路径统计每帧耗时、
      帧距均值/最大与进度单调性；[C] 光标重现；[D] 自动点线新判据（稠密不切、稀疏切换、恢复原样式）。
- 既有回归：verify 49/49、panelanim 156/156、datacheck 69/69、edgecheck 46/46、errcheck 19/19。
- make release 零错误零警告（使用 TARGET_FILE_NAME=TargetCheck 以避免与用户正在运行的实例冲突）。

文档：Documents/agent_mem.md 新增 §9.42、§11.2 第 117–124 条与变更日志一行。
 2026-10-17 00:56:19 +08:00
DeepSeek V4.1 Flash f845616938 回退 5b52eef 并修复「屏幕不刷新」根因：拖动滚动条卡顿 / 悬停高亮卡住 / 信号拖拽无效果 
根因（代码级确认）
- Render() 把界面画进后备缓冲区后用 GetDC + BitBlt 回送窗口，5b52eef 把回送写成
  `if (fullFrame) { BitBlt(整窗) } else if (panelOnly) { BitBlt(本帧重绘区域并集) }`，没有兜底 else。
- 「鼠标只在绘图区内移动」的帧（WM_MOUSEMOVE 的 plotOnlyMove 路径只 InvalidatePlotRect）恰好
  fullFrame == false && panelOnly == false ⇒ 后备缓冲区被正确重绘，窗口 DC 一个像素都不回送。
- 这一个根因同时造成用户报告的三个症状：悬停光晕卡住（移开不消失）、拖动滚动条不跟手/非常卡顿、
  拖拽信号换网格看不到任何结果。

修法
- git reset --hard HEAD~1 撤销 5b52eef（保留 backup-bad-commit 标签供 A/B）。
- 只挑回该提交里与更新区域无关的功能改动（用户明确要求过、本身正确）：
  * SignalPanel::ExpandGroupForSignal()：联动滚动前立刻展开折起的分组（不播展开动画）；
  * FitAll() / FitSinglePointCluster() 不再复位 Tab().LaneScroll()（适应视图不影响滚动条）；
  * 右下角「回到最上方」浮动按钮 + 网格滚动到可视区的平滑动画。
- Application.cpp 只保留 3 处最小改动：Render 里把 panelAnimating 计入整帧脏、WM_TIMER 推进
  AdvanceBackToTopAnimation() 且保持整窗失效、定时器存活判定带 BackToTopAnimationActive()。
  Render 的绘制与 BitBlt 路径逐字节等同于 82b5ebe。
- 彻底删除 m_paintPlot / m_panelDirty / panelOnly / InvalidatePanelRect / 并集回送。

验证（全部离屏执行，不移动真实光标、不抢焦点、不截屏）
- .preflight/diag（新增离屏探针，19/19）：窗口移到屏幕外 + WS_EX_TOOLWINDOW + SW_SHOWNOACTIVATE，
  保证有真实更新区域与 WM_PAINT 但不影响用户。断言滚动条拖动（滑块与绘图区都在后备缓冲区被重绘）、
  悬停光晕出现与消退（像素完全回到基线）、在曲线上按下进入 MOVE_SIGNAL 且拖到另一网格后归属正确。
- .preflight/check 137/137。
- .preflight/diag/verify_blit.ps1（新增源码级护栏，10/10）：断言 Render() 的回送块必须有无条件 else、
  不得出现 else if、m_paintPlot/m_panelDirty/panelOnly 必须不存在、失效只允许整窗或仅绘图区。
  A/B：换回 backup-bad-commit ⇒ 4 项如实失败；换回修复版 ⇒ 10/10。
- make release 零错误零警告。

文档：Documents/agent_mem.md 新增 §9.41、§11.2 第 108–116 条（含 §9.40 与旧 108–114 条的作废标注）
与变更日志一行。

教训（写进记忆）：① 离屏探针无法验证「窗口回送 / 合成」（屏幕外 DWM 不合成、窗口 DC 恒为空白）⇒
回送类约束必须有源码级护栏；② 离屏窗口 + TrackMouseEvent 会立刻收到 WM_MOUSELEAVE，探针须丢弃该消息；
③ 网格回收会让下标左移，断言要用锚信号。
 2026-10-16 17:33:08 +08:00
DeepSeek V4.1 Flash 2904699eae 修复五项交互缺陷：折起后滚动条 / 单点信号样式 / 线宽实时生效 / 网格菜单限高滚动 / 点选信号滚动绘图区 
1) 分组折起后再展开，信号列表的滚动条消失（筛选态与常规态均可复现）
   - 根因：AdvanceGroupAnimations 只在“折起完成”时重建行集合；而“展开完成”那一帧
     m_contentHeight 从收起态跳回展开态，却没有任何路径重算滚动条可见性 ⇒ 滚动条停在隐藏。
   - 修法：任一方向动画结束都 m_rowsDirty = true + BuildRows()，并每帧 RefreshScrollBar(false)。
     ⚠️ 动画期间不夹取滚动偏移，避免打断与滚动同步的折起动画（scrollSynced）。

2) 单点信号（finiteCount == 1）默认绘制方式由「点线」改为「散点」
   - ApplySinglePointDefaultStyle → DrawMode::SCATTER（仍取最大线宽）。
   - 新增 SignalPanel::ModeOptionEnabled：单点信号的「线段」「点线」置灰、不可点、
     且不参与悬停高亮（避免“看着能点其实点不动”）；样式区的绘制与命中都用它。
   - PlotView::UpdateAutoScatterStyles 跳过单点信号，否则“放大自动点线”会把它又改回「点线」。

3) 拖动线宽滑块完全不生效（拖动时线宽不变、松手瞬间变了、再移动鼠标又变回去）
   - 根因一：AcquirePolyline 的折线缓存键没有 lineWidth，而 BuildPolyline 把线宽烘进
     包络带几何（每个像素列的上下包络各向外扩 max(1,线宽)*scale*0.5，「梳状」判定也依赖它）
     ⇒ 稠密信号（采样数 > 绘图区宽度）永远复用旧线宽的顶点与包络带。
   - 根因二：样式补丁只更新“静态场景缓存 + 后备缓冲区”，而每网格图层（宽基底）仍是旧样式像素，
     下一帧命中“宽基底快路径”时把新样式覆盖回旧像素。
   - 修法：PolylineCacheEntry 增加 lineWidth 并进比较；
     样式补丁之后 QueueLaneRebuild(受影响网格) + RenderPendingLaneRebuilds(1)（沿用每帧至多 1 个的预算）。

4) 「目标」行的 GX 标签复用「所属网格」菜单，并先给 PopupMenu 增加「限高 + 条目区滚动 + 尾部固定项」
   - MenuLayoutConstraint::maxHeight（OpenLaneMenu 传客户区高度的 62%）；
   - 固定区 = 最后一个分隔线及其之后的条目（即「新建网格」）始终钉在菜单底部，其余条目可滚动；
   - 滚轮滚动条目区（Application 在菜单内滚动时不再关闭菜单，其余情形保持既有行为）；
   - 键盘移动悬停项自动滚入可视区（EnsureItemVisible）；ItemAtPoint 要求条目同时命中滚动视口；
   - 滚动区文本用 UiTextClipped（GDI 文本不遵循 GDI+ SetClip），并跳过完全不可见的条目（性能）；
   - BuildLayout 不再无条件清零 m_scrollOffset（否则 RebuildLayout 会把滚轮位置吃掉）；
   - 「目标」行 GX 标签点击**不参与**联动滚动（悬停联动保留）。

5) 点选信号名 ⇒ 绘图区自动把目标网格滚动到可视区内（上百个独立网格时旧有高亮无法定位）
   - SignalPanel::RequestPlotLaneScroll / TakePlotLaneScrollRequest；
     Application::ApplyPendingPlotLaneScroll（WM_LBUTTONDOWN 的面板分支）；
     PlotView::ScrollLaneIntoView（在可视区上方就上滚、在下方就下滚、已完整可见则不动）。
   - 只有“点击信号名”触发；悬停绝不改变视图；勾选框 / GX 徽标 / 移除 ✕ 也不触发。

验证（全部离屏执行，窗口 SW_HIDE + 只注入合成消息 + 进程与线程 BELOW_NORMAL，
不移动真实光标、不抢焦点、不截屏）：
- 新增 .preflight/check（不入库）68/68 通过；
- A/B：五处修复全部回退 ⇒ 17 项如实失败（B 4 / C 4 / D 7 / E 2）；“折起后滚动条”需要
  逐帧重绘驱动动画才能复现，单独回退时 ⇒ 5 项如实失败；恢复后 68/68；
- make release / make debug 零警告。

其它：
- 按要求删除工作区 Tools/（structcheck 脚本）并移除 Makefile 的 structcheck 目标；
- Documents/agent_mem.md 同步：新增 §9.38、§11.2 第 97–103 条与变更日志一行。
 2026-10-16 11:06:31 +08:00
DeepSeek V4.1 Flash d2e6fdd085 收尾：LanePanelState 抽取 + 错误提示非模态化（清空上一轮的“未完成”） 
一、Lane 的内聚性（上一轮建议 5，本轮完成）
- 新增 struct LanePanelState { bool open = true; double x = -1.0; double y = -1.0; }；
- Lane 的 12 个平铺面板字段（edgePanelOpen/X/Y 等 × 4 类实验性功能）
  → 4 个聚合成员 edgePanel / edgeCenterPanel / meanFilterPanel / weakPeakPanel；
- 访问点全部改为 lane.edgePanel.open 形式（DataModelTab.cpp 快照拷贝、
  PlotViewInteraction.cpp 面板拖拽、PlotViewPaint.cpp 面板层序绘制）；
- RebuildLanes 内部的 LaneCarry 同步收敛为 4 个 LanePanelState，
  12 行逐字段赋值简化为 4 行整体赋值。
- 教训：批量改名不能对“声明”和“使用”跑同一组替换对，
  否则声明行会变成 `bool edgePanel.open = true;` 这类非法代码。

二、错误提示与模态阻塞解耦（上一轮建议 1，本轮完成）
- Application 新增 SetModalErrorsEnabled(bool) / ModalErrorsEnabled()，
  成员 m_modalErrorsEnabled 默认 true（交互场景行为不变）；
- Initialize 最先执行 SetModalErrorsEnabled(showCommand != SW_HIDE)：
  隐藏窗口（自动化/离屏）下没人能点掉模态框，等于把进程钉死；
- SetStatusMessage(text, isError=true)：允许模态时原样 MessageBoxW，
  否则改走非模态通道 m_plot.ShowPersistentHint(text)（绘图区底部浮层）；
  普通提示与空文本依旧被忽略；
- PlotView 新增公开接口 ShowPersistentHint(text)（内部转 SetHintSticky），
  不向宿主暴露粘滞/淡出等内部细节。

三、顺带修掉一个真实缺陷
- PlotView::Paint 在 m_lanes.empty() 时提前 return，而提示浮层在其后的
  叠加层绘制 ⇒ 一个信号都没勾选时任何错误都显示不出来，恰恰是
  “文件加载失败”最需要提示的场景；该分支补一次 PaintHint(g)。

四、验证（全部离屏：SW_HIDE + 不注入输入 + BELOW_NORMAL）
- make release / make debug：通过，零警告；Build/Release/Target.exe = 764416 B；
- verify 49/49、datacheck 69/69、edgecheck 46/46、panelanim 156/156；
- 新增探针 .preflight/perf/errcheck 19/19：默认值 / 隐藏窗口自动降级 / 宿主显式开关；
  工作线程 + 5s 超时判定“不阻塞”（旧行为会永久阻塞，判失败并 ExitProcess，
  探针不会挂住）；EnumWindows 统计本进程 #32770 顶层窗口数量前后不变；
  错误文本进入 m_hintText / m_hintSticky / HintNeedsAnimation / m_hintShownAt；
  像素级：有提示帧与无提示帧在绘图区内的差异像素 3781，且全帧差异同为 3781
  （证明差异只来自提示）。

五、文档
- Documents/agent_mem.md：§9.37 新增第八节（本轮补齐）、第九节（仅剩 MF4 项）、
  §11.2 新增第 93–95 条硬约束、变更日志新增一行；
- Documents/refactor_report_2026-10-16.md：§7.3 / §7.4 标记完成，新增 §九 收尾补记
  （含 9.1–9.5：聚合化、解耦、探针、验证结果、变更清单）。
 2026-10-16 04:38:12 +08:00
DeepSeek V4.1 Flash e6b7bf66ec 按组件目录结构把四个巨型实现文件拆分为多个协作文件（PlotView / SignalPanel / Application / DataModel） 
承接上一条提交（0871eb0）—— 该提交只完成了 Components/Shared 与注释/命名清理，并**主动未做**
大文件拆分；本提交把大文件拆分补齐，至此“按功能拆分逻辑块到各组件自己的 Inc/Src”已落地。

## 一、拆分结果

| 原文件 | 拆分后 |
| --- | --- |
| Components/PlotView/Src/PlotView.cpp（13 695 行 / 544 KB） | PlotView.cpp(787) + PlotViewPaint.cpp(6 367) + PlotViewInteraction.cpp(2 715) + PlotViewFeatures.cpp(3 005) + PlotViewInternal.hpp(936) |
| Components/SignalPanel/Src/SignalPanel.cpp（4 184 行） | SignalPanel.cpp(1 141) + SignalPanelPaint.cpp(697) + SignalPanelInteraction.cpp(2 095) + SignalPanelInternal.hpp |
| Components/Application/Src/Application.cpp（3 135 行） | Application.cpp(1 427) + ApplicationCommands.cpp(1 184) + ApplicationLoading.cpp(270) + ApplicationInternal.hpp |
| Utilities/Src/DataModel.cpp（2 615 行） | DataModel.cpp(1 583，含自由函数区) + DataModelTab.cpp(732) + DataModelInternal.hpp |

分片职责（以 PlotView 为例）：
  core        视图核心：构造/析构、上下文、布局、坐标映射、视界与平移、网格结构与归属
  paint       渲染与像素缓存：全部绘制、场景/装饰缓存、每网格图层、宽基底与滚动补条
  interaction 交互与编辑：命中测试、鼠标/键盘、光标形状、内联输入框、浮动面板层序
  features    视图特性与派生数据：光标读数/提示/缩放、自适应、吸附、单点、派生曲线线程池、
              边沿统计、实验性功能参数
（SignalPanel 为 core/paint/interaction；Application 为 core/commands/loading；
  DataModel 为 core/tab。）

## 二、关键手法（这是能安全拆开的前提）

原文件的辅助区都是**匿名命名空间**（PlotView 约 870 行常量与工具函数），被所有成员函数广泛引用。
直接拆文件会让各 .cpp 拿不到这些工具，因此：

1. 把该块整块搬进 `<组件>Internal.hpp`，从 `namespace { }` 改为**具名**命名空间
   （pvdetail / spdetail / appdetail / dmdetail）；
2. 块内**每个函数与常量都标 inline** ⇒ 多个翻译单元共用同一个定义：既不重复符号，
   也不产生 N 份函数定义；
3. 头部末尾 `using namespace <ns>;` ⇒ 各 .cpp 函数体里原有的非限定调用（IntersectRect /
   NiceStep / ClampDouble …）**一行都不用改**；
4. 成员定义按「方法名 → 分片」归类后**整块搬移** —— 全程**纯代码搬移**，没有改动任何一行函数体。

## 三、拆分过程中踩到并修正的四个坑（已固化到 .preflight/perf/split_component.ps1）

1. `[[maybe_unused]]` 等属性**必须排在 inline 之前**（`inline [[x]] T` 非法）；
   单独的 `{`/`}` 行、注释行、`struct`/`enum`/`using`/`template` 行不能加 inline。
2. 匿名命名空间的**结束行可能带注释**（`} // namespace`），只认 `^\t}$` 会一路匹配到后面
   某个成员函数的结束括号，把大段成员定义误当成“辅助区”搬走。
3. **首个成员定义之前的所有行**必须跟着进核心文件：DataModel.cpp 在匿名命名空间之后、
   首个成员定义之前还有约 390 行命名空间外的自由函数（SignalStats / ComputeStats /
   CacheSparseSamples / ApplySinglePointDefaultStyle …），漏掉会被静默丢弃。
4. 内部头必须带上原文件真正用到的全部头：DataModel 需要 Theme.hpp / <cstring> / <cstdio> /
   <deque> / <atomic> / <cwctype> / <new>（原文件靠这些头才编译得过）。

## 四、附带完成的命名审计

PlotView 中残留的 File 语义命名一并修正：LaneSpansMultipleFiles → LaneSpansMultipleGroups、
firstFile → firstGroup、multiFile → multiGroup、SceneCacheKey::haloFile → haloGroup。

## 五、验证（全部离屏：SW_HIDE + 不注入真实输入 + 进程/线程 BELOW_NORMAL）

- .preflight/perf/verify.exe（PlotView 渲染/交互，含逐像素断言）49/49
- .preflight/perf/panelanim.exe（信号面板：卷尺式折起/展开、筛选态、悬浮组名、目标行）156/156
- .preflight/perf/datacheck.exe（数据层：单轴/多时间轴 CSV、MF4、重命名语义）69/69
- .preflight/perf/edgecheck.exe（边沿统计与面板排版）46/46
- make release / make debug 零警告。
即：拆分后**行为与拆分前完全一致**（纯代码搬移，四套探针全绿）。

## 六、体积（诚实记录）

  Target.exe: 754 176 → 764 416 B（+10 240 B，+1.4%）
因为 inline 工具函数会在每个引用它的翻译单元里各生成一份（PE/COFF 链接器没有 ICF 合并）。
这再次印证：拆分解决的是**可维护性**，不是体积（本轮的 −24.6% 全部来自 ICO 256×256 条目改 PNG）。

## 七、文档

Documents/agent_mem.md：§9.37 新增“七、多文件拆分（已完成）”与“八、仍未完成”（只剩
Lane → LanePanelState、模态提示解耦、MF4 压缩块三项）；§11.2 新增第 91、92 条（多文件化的
唯一安全手法 + 体积代价）。Documents/refactor_report_2026-10-16.md 同步更新 §五/§七/§八。
 2026-10-16 04:02:36 +08:00