outlookEmailPlus/docs/LOG/LOG-00003-可调整布局系统-执行日志.md

执行日志：可调整布局系统（00003）

• 日期：2026-02-27
• 目的：按 docs/TODO/TODO-可调整布局系统.md 推进未完成项（阶段五/六为主），补齐 恢复默认布局（F3）/窗口尺寸适配（F5）/键盘可访问性（F6），并用可验证证据（测试/文档）确保不回归主业务功能。

---

2026-02-27

启动记录

• 本轮开始依据的目标文档：docs/TODO/TODO-可调整布局系统.md
• 约束：
  • 不引入前端构建链（保持零构建、外链 CSS/JS）。
  • 现有主业务功能（分组/账号/邮件）行为不回归。
  • 关键路径用 Jest（tests/layout-system/）提供可验证证据。

计划推进范围

• 阶段五：恢复默认布局（F3.1~F3.4）
• 阶段六：窗口适配与键盘支持（F5.1F5.3、F6.1F6.4）

阶段五（进行中）：恢复默认布局（F3）

• 决策：沿用现有 .modal/.show 交互模式（与 addGroup/addAccount 等一致），不引入新依赖；重置逻辑在 LayoutManager.resetLayout() 内完成，且显式取消未到期的保存防抖，避免“重置后又被定时器写回”导致 localStorage 未真正清空。

产出

• 导航栏增加恢复按钮：
  • templates/index.html
• 恢复确认对话框：
  • templates/partials/modals.html（#resetLayoutModal）
• 重置动画与按钮样式：
  • static/css/layout.css（.layout-resetting、.reset-layout-btn、#resetLayoutModal .text-muted）
• 重置逻辑与动画封装：
  • static/js/layout-manager.js（resetLayout()、withResettingAnimation()、debounce 增加 cancel()）
• UI 绑定（show/hide/confirm + ESC 关闭）：
  • static/js/layout-bootstrap.js

阶段六（进行中）：窗口适配与键盘支持（F5/F6）

• 决策：
  • 窗口适配以 LayoutManager 统一处理：resize 防抖 200ms（FD F5.1），断点自动折叠/恢复仅作用于 autoCollapsed 面板（避免覆盖用户手动折叠偏好）。
  • 键盘宽度调整直接复用 calculateNewWidth()，确保与鼠标拖动共享同一套最小/最大/详情最小宽度约束。
  • 兼容既有“移动端隐藏列表”逻辑：隐藏时同步将 Grid 列宽置 0，避免出现“元素 display:none 但列宽仍占位”的空白列回归。

产出

• 窗口适配 + 键盘调整：
  • static/js/layout-manager.js（handleWindowResize()、onWindowResize()、onResizerKeydown()、expandPanel(panelType, auto)）
• 业务隐藏邮件列表与 Grid 列宽联动：
  • static/js/features/emails.js（syncEmailListVisibility()，替换原 .hidden 仅改 display 的实现）

验证

• 布局系统 Jest（含新增 F3/F5/F6 用例）：npm test 通过（11 suites / 93 tests）
• 全量 Python 单测回归：python -m unittest discover -s tests -v 通过（95 tests）

---

UI 问题修复：窄屏下“全部折叠后无法再展开”（F2/F5 交互回归）

现象

• 当窗口较窄（触发 @media (max-width: 768px)）且 LayoutManager 自动折叠/用户折叠侧边栏后：
  • 分组面板 / 账号面板的折叠指示器会被一起移出屏幕（left 为负值），导致用户看起来“面板消失且再也打不开”。
  • 若同时触发业务侧的“隐藏邮件列表”（.email-list-panel.hidden），则左侧三个区域都不可恢复，交互卡死。

根因定位

• static/css/main.css 在窄屏下仍保留历史规则：.group-panel,.account-panel { position: fixed; left:-280px; }
• 新的可调整布局系统（static/js/layout-manager.js）在折叠时把 Grid 列宽置 0，并依赖 折叠指示器 提供“展开入口”。
• 当历史规则把面板整体移出屏幕时，折叠指示器作为面板子元素也一并移出，造成不可展开。

修复方案

• 在布局系统初始化时，为 <html> 添加标记类：layout-system-enabled。
• 将窄屏历史侧栏滑入样式限定在 “布局系统未启用” 的场景：
  • 仅对 html:not(.layout-system-enabled) 生效，避免影响 LayoutManager 的折叠/指示器逻辑。

变更点

• static/js/layout-bootstrap.js：LayoutManager 初始化前添加 layout-system-enabled。
• static/css/main.css：@media (max-width: 768px) 内的 .group-panel/.account-panel 固定定位规则增加 html:not(.layout-system-enabled) 限定。

验证

• npm test 通过（11 suites / 93 tests）。
• Playwright 窄屏复现验证（viewport=600）：
  • 修复前：groups/accounts 指示器 x < 0（不可见）
  • 修复后：groups/accounts/emails 指示器分别落在 x=0/48/96（可见且可点击展开）

---

UI 问题修复：折叠后页面出现滚动条、指示器高度观感异常（“太长”）

现象

• 在桌面宽屏下手动折叠侧边栏（如：账号/邮件列表）后，页面右侧出现 body 滚动条。
• 因 body 被撑出滚动高度，用户会看到主容器整体被滚动，折叠指示器与布局区域的高度/对齐出现“太长/不正确”的观感。

根因定位

• 折叠时 Grid 列宽被置为 0px（layout-width），但我们仅用 opacity:0 隐藏面板内容：
  • 面板内容仍参与布局计算；
  • 在 0 宽度下文本/控件会被强制换行，导致折叠面板内部出现异常的“高度溢出”；
  • 溢出内容默认 overflow: visible，会把 body 的滚动高度撑大。

修复方案

• static/css/layout.css：
  • .main-container 增加 overflow: hidden;，阻止溢出影响 body 滚动条；
  • .main-container > * 增加 min-height: 0;，允许 Grid 子项在固定高度下正确收缩；
  • .resizable-panel.collapsed > :not(.collapsed-indicator) 增加 display: none;，让折叠时隐藏内容不参与布局与滚动高度计算。

验证

• Playwright 复现验证（宽屏，折叠 accounts/emails）：
  • 修复前：documentElement.scrollHeight > clientHeight（出现滚动条）
  • 修复后：documentElement.scrollHeight === clientHeight（滚动条消失），折叠指示器高度与主容器一致