feat: release v3.2.1 with fix for Mutual Validation tree view display issue and code cleanup

Author: buptanswer

CHANGELOG.md

@@ -4,6 +4,20 @@
 
 完整的发布说明请查看：[docs/release-notes/](./docs/release-notes/)
 
+## [3.2.1] - 2026-02-14
+
+### 修复
+- **Mutual Validation 树形视图显示问题** 🐛
+  - 修复了 Mutual (Doc/Res Consistency) 验证后树形视图完全空白的严重 bug
+  - 根本原因：Treeview 的 parent 设置顺序错误导致 tkinter 渲染失败
+  - 解决方案：修正控件创建顺序，确保容器先创建，子控件直接在容器中创建
+  - 影响：此 bug 导致 Mutual 验证的批量修复功能完全不可用
+  - 详细分析：[docs/MUTUAL_VALIDATION_TREEVIEW_FIX.md](./docs/MUTUAL_VALIDATION_TREEVIEW_FIX.md)
+
+### 改进
+- 清理了修复过程中产生的调试代码和临时测试文件
+- 代码质量提升：移除了不必要的 UI 更新调用
+
 ## [3.2.0] - 2026-02-12
 
 ### 新增

docs/MUTUAL_VALIDATION_TREEVIEW_FIX.md

@@ -0,0 +1,296 @@
+# Mutual Validation Tree View 显示问题修复报告
+
+**修复日期**: 2026年2月14日  
+**问题严重度**: 高 - 完全阻塞Mutual验证的修复功能  
+**修复状态**: ✅ 已解决
+
+---
+
+## 问题描述
+
+### 用户报告
+在运行 Mutual (Doc/Res Consistency) 验证时，系统能够成功检测到问题并自动跳转到 Repair 标签页，但"Issue Comparison"树形视图**完全空白**，无任何内容显示：
+- 看不到数据行
+- 看不到列标题
+- 看不到任何界面元素
+- 即使按键盘方向键、Ctrl+A全选等操作都无响应
+
+### 影响范围
+- **Mutual验证**：完全无法使用批量修复功能
+- **Compare验证**：工作正常（对照组）
+
+---
+
+## 问题分析过程
+
+### 第一阶段：数据流验证
+**假设**: 数据未正确传递到GUI
+
+1. 检查 `validate_mutual_operation` 返回值 → 发现只返回日志，未返回结构化数据
+2. 对比 `analyze_compare_operation` → 返回 `CompareAnalysisResult` 包含完整问题列表
+3. **发现**: Mutual验证使用了错误的operation函数
+
+**修复尝试**:
+```python
+# 修改 execute_validate() 在 mutual 模式下调用
+analyze_doc_res_repair_operation()  # 替代原来的 validate_mutual_operation()
+```
+
+**结果**: ❌ 树形视图仍然空白
+
+---
+
+### 第二阶段：数据详情验证
+**假设**: 数据有传递但缺少详细信息（size, mtime, hash）
+
+添加调试日志验证：
+- ✅ `CompareAnalysisResult.issues` 包含1个问题
+- ✅ `issue.details` 字典包含 `new_size`, `new_mtime`, `new_hash` 等
+- ✅ `_build_repair_tree_row()` 成功构建8列数据
+- ✅ `tree.insert()` 成功执行
+- ✅ `tree.get_children()` 返回1个item ID
+
+**结果**: ❌ 数据完整但树形视图仍然空白
+
+---
+
+### 第三阶段：UI更新机制验证
+**假设**: tkinter渲染未及时刷新
+
+**修复尝试**:
+```python
+self.repair_tree.update_idletasks()
+self.repair_tree.update()
+self.repair_tree.see(first_item)
+self.repair_tree.selection_set(first_item)
+```
+
+**结果**: ❌ 强制更新无效
+
+---
+
+### 第四阶段：Tab可见性验证
+**假设**: 数据插入时树形视图不可见（在隐藏的tab中）
+
+**修复尝试**:
+```python
+# 先切换tab，再加载数据
+self.notebook.select(self.repair_frame)
+self.notebook.update_idletasks()
+self.load_compare_result_for_repair(payload, ...)
+```
+
+**结果**: ❌ 改变顺序无效
+
+---
+
+### 第五阶段：Widget几何信息诊断
+**假设**: 控件布局或渲染异常
+
+添加详细几何信息日志：
+```
+Tree geometry: 1159x285, visible=1
+First item bbox: (2, 33, 1560, 25)  ← 关键发现！
+Parent (tree_container) geometry: 1196x339, visible=1
+Grandparent (list_frame) geometry: 1216x746, visible=1
+```
+
+**关键发现**:
+- Tree宽度: 1159px
+- Item bbox宽度: **1560px** (超出树宽度401px)
+- 但这不是根本原因，因为应该有横向滚动条
+
+**继续深挖**: 用户反馈连**列标题**都看不到，说明是更根本的显示问题
+
+---
+
+### 第六阶段：Widget Parent层级检查
+**假设**: 控件的parent设置错误导致渲染失败
+
+检查树形视图的创建代码：
+
+```python
+# ❌ 原代码 - PARENT设置混乱
+self.repair_tree = ttk.Treeview(
+    list_frame,  # 第一次指定parent为list_frame
+    columns=tree_columns,
+    show="headings",
+    ...
+)
+...
+tree_container = ttk.Frame(list_frame)  # 随后创建中间容器
+tree_container.grid(row=0, column=0, sticky=NSEW)
+...
+self.repair_tree.pack(in_=tree_container, ...)  # 后来用in_参数改parent
+```
+
+**问题本质**:
+1. 树先创建在 `list_frame` (父容器)
+2. 中间容器 `tree_container` 后创建
+3. 用 `pack(in_=tree_container)` 尝试将树"移动"到中间容器
+
+这种**parent关系混乱**违反了tkinter的widget层级模型，导致渲染系统无法正确处理控件的显示。
+
+---
+
+## 最终解决方案
+
+### 核心修复
+**修正控件创建顺序**，确保parent层级清晰：
+
+```python
+# ✅ 修复后 - 正确的parent层级
+# 1. 先创建容器
+tree_container = ttk.Frame(list_frame)
+tree_container.grid(row=0, column=0, sticky=NSEW)
+
+# 2. 树直接在容器中创建
+self.repair_tree = ttk.Treeview(
+    tree_container,  # parent明确为tree_container
+    columns=tree_columns,
+    show="headings",
+    ...
+)
+
+# 3. 滚动条也在同一容器中
+scrollbar = ttk.Scrollbar(tree_container, orient=VERTICAL, ...)
+h_scrollbar = ttk.Scrollbar(tree_container, orient=HORIZONTAL, ...)
+
+# 4. pack布局不需要in_参数
+self.repair_tree.pack(side=LEFT, fill=BOTH, expand=YES)
+```
+
+### 配套修改
+为了使Mutual验证能获取完整的问题详情用于修复：
+
+1. **execute_validate() 修改** ([gui.py#L2055](../kb_folder_manager/gui.py#L2055))
+   ```python
+   elif mode == 'mutual':
+       # 使用 analyze_doc_res_repair_operation 获取详细问题数据
+       thread = OperationThread(
+           analyze_doc_res_repair_operation,
+           self.result_queue,
+           log_capture,
+           Path(doc.get()),
+           Path(res.get()),
+           self.config,
+           log_dir_path,
+       )
+   ```
+
+2. **check_operation_results() 处理** ([gui.py#L2433](../kb_folder_manager/gui.py#L2433))
+   ```python
+   elif op_name == 'validate_mutual' and isinstance(payload, CompareAnalysisResult):
+       if blockers:
+           self.notebook.select(self.repair_frame)
+           self.load_compare_result_for_repair(
+               payload, 
+               context_type='doc_res', 
+               summary_title='Mutual Validation'
+           )
+   ```
+
+---
+
+## 验证结果
+
+### 修复前
+```
+[DEBUG] Tree now has 1 items
+[DEBUG] Tree geometry: 1159x285, visible=1
+[DEBUG] First item bbox: (2, 33, 1560, 25)
+用户反馈: 完全看不到任何内容，包括列标题
+```
+
+### 修复后
+- ✅ 树形视图正常显示
+- ✅ 列标题可见
+- ✅ 数据行正确渲染
+- ✅ 滚动条正常工作
+- ✅ 选择、导航功能正常
+
+---
+
+## 经验总结
+
+### 问题根源
+**tkinter的widget必须在创建时就明确唯一的parent**，不能事后通过 `pack(in_=...)` 或 `grid(in_=...)` 改变parent关系。这种操作虽然不会报错，但会导致渲染系统无法正确处理widget的显示。
+
+### 调试教训
+1. **分层验证**: 从数据流 → UI更新 → 布局层级，逐层排查
+2. **对照实验**: Compare工作正常但Mutual不工作，说明是Mutual特有的代码路径问题
+3. **几何诊断**: `winfo_width()`, `winfo_viewable()`, `bbox()` 等方法帮助定位渲染问题
+4. **简化测试**: 创建最小复现用例（`test_treeview_simple.py`）验证控件本身功能正常
+
+### 代码规范
+**创建tkinter widget的正确模式**:
+```python
+# 顺序: 父容器 → 子控件 → 布局
+parent = ttk.Frame(root)
+parent.grid(...)  # 父容器先布局
+
+child = ttk.Widget(parent)  # 子控件明确指定parent
+child.pack(...)  # 子控件在自己的parent中布局
+```
+
+**禁止的模式**:
+```python
+# ❌ 错误: 先创建子控件，后指定parent
+child = ttk.Widget(wrong_parent)
+container = ttk.Frame(correct_parent)
+child.pack(in_=container)  # 企图改变parent - 可能导致渲染问题
+```
+
+---
+
+## 代码变更清单
+
+### 修改文件
+- `kb_folder_manager/gui.py`
+
+### 关键代码段
+1. **树形视图创建** (行 ~965-1010)
+   - 修改前: 树创建在 `list_frame`，后用 `pack(in_=tree_container)` 移动
+   - 修改后: 先创建 `tree_container`，树直接创建在其中
+
+2. **Mutual验证operation调用** (行 ~2045-2065)
+   - 修改前: `validate_mutual_operation`
+   - 修改后: `analyze_doc_res_repair_operation`
+
+3. **结果处理分支** (行 ~2433-2453)
+   - 新增: `validate_mutual` 返回 `CompareAnalysisResult` 的处理逻辑
+
+### 删除的调试代码
+- 所有 `print("[DEBUG] ...")` 语句
+- 不必要的 `update_idletasks()`, `update()` 调用
+- 临时测试文件:
+  - `test_gui_actual_run.py`
+  - `test_gui_deep_debug.py`
+  - `test_gui_fix_verification.py`
+  - `test_gui_full_simulation.py`
+  - `test_gui_mapping.py`
+  - `test_instructions.py`
+  - `test_mutual_issue.py`
+  - `test_treeview_simple.py`
+
+---
+
+## 受益功能
+
+修复后，以下功能完全可用：
+- ✅ Mutual (Doc/Res Consistency) 验证的问题检测
+- ✅ Mutual验证结果的可视化展示
+- ✅ Doc/Res不一致问题的批量修复
+- ✅ 问题类型筛选和策略选择
+- ✅ 修复操作的preview和应用
+
+---
+
+## 相关文档
+- 用户指南: [docs/user-guide.md](user-guide.md)
+- 开发者指南: [docs/developer-guide.md](developer-guide.md)
+- GUI使用指南: [docs/legacy/GUI使用指南.md](legacy/GUI使用指南.md)
+
+---
+
+*本报告记录了一个典型的GUI渲染问题的完整调试过程，供后续开发参考。*