Fix maximize resize guard and add records

2026-04-09 04:19:56 +08:00
parent f567369300
commit 97710db9e3
5 changed files with 297 additions and 6 deletions
@@ -0,0 +1,68 @@
+# BUG-20260409-0003
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260409-0003
+- 标题: 直接最大化触发收口保护，导致黑背景与控件残影
+- 状态：已修复 / 待回归验证
+- 严重性：S2
+- 优先级：P0
+- 模块：Window / Resize / Scene Redraw
+- 版本 / 分支：`master`
+- 环境：Windows 桌面 + EasyX + VS2022
+- 发现人：用户反馈
+- 关联 Fix ID：`Fix-BUG-20260409-0003`
+
+## 问题描述
+
+- 现象：
+  - 某些用例在窗口初始大小下直接点击最大化后，新暴露出的区域显示为黑色背景。
+  - 已有控件可能出现残留、残影或旧内容未被覆盖。
+  - 若先手动拖动边框略微放大，再执行最大化，则问题消失。
+- 影响范围：
+  - 顶层窗口 resize 收口
+  - 背景完整重绘
+  - 控件 resize 后的快照/标脏收口
+- 期望结果：
+  - 无论是拖拽 resize 还是直接最大化，只要 `WM_SIZE` 进入收口流程，都应完成一次完整 redraw。
+- 实际结果：
+  - 某些“大跨度但合法”的最大化尺寸变化，会在收口中途被直接跳过，导致背景和控件未完成刷新。
+
+## 复现信息
+
+- 复现条件：
+  - 初始窗口尺寸与最大化后的客户区尺寸跨度较大。
+- 典型用例：
+  1. `KEY == 1`：`1200x400 -> 2160x1417`
+  2. `KEY == 2`：`700x510 -> 2160x1417`
+  3. `KEY == 3 / 4`：初始尺寸较大时不复现
+- 复现概率：高
+- 证据：
+  - `WM_SIZE：待处理=(2160x1417), isSizing=0`
+  - `调整窗口尺寸开始：width=... height=...`
+  - `尺寸调整被跨度保护跳过：old=(...) new=(...) diff=(...)`
+  - 异常日志中缺失 `尺寸调整已完成`
+
+## 初步分析
+
+- 疑似位置：
+  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp) 的 `runEventLoop()` resize 收口逻辑
+- 可疑代码特征：
+  - 使用 `abs(finalW - width) > 1000 || abs(finalH - height) > 1000` 作为跳过条件
+  - 命中后直接：
+    - `needResizeDirty = false`
+    - `continue`
+- 根因判断：
+  - 该分支把“跨度较大的合法最大化”误判为异常帧
+  - 导致后续 `Resize / adaptiveLayout / redrawScene / done log` 全部被跳过
+
+## 跟踪信息
+
+- 首次发现时间：2026-04-09
+- 最后更新时间：2026-04-09
+- 修复版本：当前工作区
+- 验证版本：待用户回归
+- 备注：
+  - 当前证据表明问题与 DPI 不是同一级根因，更直接的是跨度阈值误杀。