StellarX-kaifa/开发记录/Fix/Fix-BUG-20260409-0003-直接最大化触发收口保护导致黑背景与残影.md

Fix-BUG-20260409-0003

适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。

关联信息

• Fix ID: Fix-BUG-20260409-0003
• 关联 BUG ID: BUG-20260409-0003
• 修复目标: 取消对合法大跨度最大化的误拦截，仅保留非法尺寸保护
• 状态：已完成 / 待用户回归
• 负责人：Codex 协作修改
• 分支 / 版本：master

根因分析

• 旧逻辑问题：
  • runEventLoop() 的 resize 收口中存在“跨度保护”：
    • abs(finalW - width) > 1000 || abs(finalH - height) > 1000
  • 命中后直接跳过整个收口流程。
• 为什么会出问题：
  • 该判断关注的是“变化跨度”，而不是“尺寸是否合法”。
  • 在大屏、窗口初始尺寸较小、直接最大化等正常场景下，跨度超过 1000 很常见。
• 为什么之前未必稳定暴露：
  • 当初始尺寸较大时，最大化跨度较小，不会命中阈值。
  • 先手动拉大一点后再最大化，也会避开该阈值。

修复方案

• 修复思路：
  • 删除“跨度过大即跳过”的保护语义。
  • 改成“仅非法客户区尺寸才跳过”。
  • 保留关键 DEBUG 日志，方便追踪极端尺寸帧。
• 关键改动：
  • 删除旧的 >1000 误拦截分支。
  • 引入虚拟桌面尺寸：
    • SM_CXVIRTUALSCREEN
    • SM_CYVIRTUALSCREEN
  • 仅在以下情况下跳过本次收口：
    • actualWidth <= 0
    • actualHeight <= 0
    • actualWidth > max(10000, virtualScreenWidth * 2)
    • actualHeight > max(10000, virtualScreenHeight * 2)
  • 对“大跨度但合法”的 resize 增加 DEBUG 日志，但继续执行收口。
• 涉及文件 / 类 / 函数：
  • Window.cpp
  • Window::runEventLoop()
• 输出日志：
  • 尺寸调整被非法尺寸保护跳过
  • 检测到大跨度尺寸调整，继续执行收口

影响评估

• 对外行为变化：
  • 有。直接最大化不再被 >1000 阈值拦截。
• 兼容性影响：
  • 正向兼容。正常拖拽 resize、正常最大化都仍然走原有收口流程。
• 风险：
  • 如果系统偶发产生一次极端异常客户区尺寸，可能会更多依赖当前“非法尺寸保护”而不是原来的跨度阈值。
  • 但相较于误杀合法最大化，这个风险更合理。

验证结果

• 验证方式：
  1. 在 >1000 旧保护分支中先加 DEBUG 日志，确认 KEY == 1 / 2 命中。
  2. 替换为非法尺寸保护后，编译 Window.cpp。
  3. 按 KEY == 1 ~ 4 做逻辑推演。
• 理论结果：
  • KEY == 1 / 2：现在应打印“大跨度但继续执行收口”日志，并继续完成 尺寸调整已完成。
  • KEY == 3 / 4：原本正常，行为保持一致。
• 备注：
  • 当前这轮无法直接替用户跑 GUI 自动化，只能做逻辑推演和源码级编译验证。

落地信息

• Commit：
  • f567369：修改前快照
  • 当前工作区：已替换跨度保护，待提交
• 发布版本：待定
• 备注：
  • 同轮顺手删除了 Window.cpp 中一个未使用的 ExMessage mm; 遗留变量。