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

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 的 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 不是同一级根因，更直接的是跨度阈值误杀。