给全部源码补中文注释,并新增代码导览

- 67 个 .cs 文件加中文注释:每个文件顶部说明职责/调用方/线程与节拍/
  已知限制/「要改什么就改哪里」,字段与方法逐条一行说明,复杂逻辑内插关键步骤
- 纯注释改动:脚本校验所有新增行都是注释、无非注释改动(仅 2 个文件的 BOM
  随新头部注释下移,文件仍以 BOM 开头)
- 新增 docs/代码导览.md:模块地图、「我要改 X 看哪个文件」对照表、易踩的坑、
  悬浮条显示规则、测试与验收指引
- 编译通过,回归测试 23/23 通过

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-13 15:44:15 +08:00
parent 9eff3ec410
commit 66ab309939
72 changed files with 3907 additions and 2 deletions
+15
View File
@@ -1,3 +1,15 @@
// =====================================================================================
// TreeRefreshTests —— 控件树增量刷新(ControlTreeReconciler)的节点身份保持回归。
//
// 覆盖范围:在同一棵 System.Windows.Forms.TreeView 上反复 Apply(fresh) 时,
// 未变化的节点必须复用原 TreeNode(句柄、选中、展开状态不丢),只有真正新增/
// 删除/移动的节点才变更;RuntimeId 缺失时的回退身份不得依赖可变的 Name。
//
// 为什么这样测:用本进程自建的 TreeView 与内存快照对拍,不调用 UIA、不枚举真实窗口。
// 这里跑的是 WinForms 自身控件(安全),危险的是 UIA 自读——两者不要混淆。
//
// 新增用例:加到 Register(...) 列表并实现 private static void 方法,断言走 Check.*。
// =====================================================================================
using System;
using System.Collections.Generic;
using System.Windows.Forms;
@@ -10,8 +22,11 @@ namespace PacsWinUia.RegressionTests
{
public static void Register(IList<KeyValuePair<string, Action>> tests)
{
// 防:静置或仅改名时整树被重建,导致句柄/选中/展开状态丢失、Tag 未重绑。
tests.Add(new KeyValuePair<string, Action>("Tree refresh retains native items when unchanged or renamed", RetainsItems));
// 防:结构调整时误重建根节点,移动/重挂的节点丢失身份,选中与展开状态被清。
tests.Add(new KeyValuePair<string, Action>("Tree refresh applies only insert, remove and move differences", StructuralChanges));
// 防:无 RuntimeId 时的回退身份依赖可变的 Name,改名即被当成新节点。
tests.Add(new KeyValuePair<string, Action>("Tree fallback identity ignores mutable Name", FallbackIdentity));
}