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

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-13 15:44:15 +08:00

125 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 代码导览(接手必读)
> 目的:拿到这份代码的人,能在几分钟内知道**哪个功能在哪个文件**、**改动要动哪里**、**哪些地方有坑**。
>
> 项目:.NET Framework 4.8 + WinForms,只读的 Windows UI 自动化检查/监控工具。
> 解决方案:`pacs_win_uia.sln`(主工程 `src/pacs_win_uia`,测试夹具 `tests/uia-fixture`,回归测试 `tests/regression`)。
---
## 一、一分钟建立全局印象
```
Program.cs 进程入口
├─ 无参数 → 单实例:第一个进程当 owner 并开 MainForm,后面的进程把请求转发给它
└─ --read-saved/-config → 无界面读取(也可以被转发到正在运行的 GUI 实例里执行)
MainForm(UI/MainForm.cs) 三栏主界面:窗口列表 | 控件树/列表结果 | 属性 + 控件监控列表
├─ 窗口列表 NativeWindowService(Win32 枚举)
├─ 控件树 ControlTreeService → UIA / MSAA / Win32 三个来源
├─ 路径与定位 ControlPath(XPath)+ ControlLocatorService(回读)
├─ 控件监控列表 ControlMonitorEditorControl → ControlMonitorStore(JSON)
├─ 悬浮条 FloatingBarManager + FloatingToolbarForm
└─ 拾取控件 CrosshairPicker + TargetProbeService + PickerOverlayForm
```
数据流(最重要的一条):
```
窗口(PID/类名/标题) → 控件树快照(ControlTreeNode) → XPath 路径(ControlPath)
↓
监控项 JSON(只存稳定定位信息)
↓
回读:重新读树 → XPath 求值 → 唯一命中 → 读值/画框
```
**核心原则**(改代码前请先接受这四条,否则很容易改出"看起来能用但定位到错控件"的 bug):
1. **找不准就说找不到**。XPath 多处命中、树读取不完整、路径语法不对,一律明确报错,绝不"取第一个"。
2. **动态的东西不落盘**。RuntimeId、实时值、焦点状态、会变的 Name 都不写进长期配置。
3. **跨进程调用可能永久卡住**。任何 UIA/MSAA 调用都要有预算(`ReadBudget`)、独立线程和取消,不能占 UI 线程。
4. **只读**。不注入、不改目标、不点击目标控件(连拾取时的鼠标左键都用低级钩子吞掉)。
---
## 二、"我要改 X,看哪个文件"
| 我想改… | 主要文件 | 备注 |
|---|---|---|
| 主界面布局/按钮/三栏比例 | `UI/MainForm.cs` | 布局自检 `VerifyLayout()` 会报错,改动后看日志 |
| 控件树怎么显示、要不要闪烁 | `UI/ControlTreeReconciler.cs` | 增量更新,绝不清空重建 |
| 控件树读取来源与顺序 | `Services/ControlTreeService.cs` | Auto = UIA → MSAA → Win32 |
| UIA 快照/缓存/Pattern | `Services/UiAutomationService.cs` | 统一 RawView + CacheRequest |
| 列表读取(行列/单元格/降级) | `Services/ListReaderService.cs` | 最长的文件,见其顶部导览 |
| 取值(Name/Value/Text/选中/焦点/OCR) | `Services/ControlValueReader.cs` | valueKey 的语义都在这里 |
| Path(XPath)生成与求值 | `Services/ControlPath.cs` | **定位核心**,改这里影响全局 |
| 保存路径时的字段与校验 | `Services/ControlLocatorBuilder.cs` | 与回读共用匹配逻辑 |
| 回读定位(含窗口匹配) | `Services/ControlLocatorService.cs` | 唯一命中才返回 |
| 监控项 JSON 读写 | `Services/ControlMonitorStore.cs` | 加载宽松、保存严格 |
| 监控列表 UI/编辑/定位 | `UI/ControlMonitorEditorControl.cs` | Path 可 F2 编辑、双击多行编辑 |
| 设置界面 | `UI/SettingsForm.cs` | 各页保存到 `AppSettings` |
| 设置的默认值与兼容 | `Models/AppSettings.cs` | `Normalize()` 是兼容旧 JSON 的地方 |
| 悬浮条的显示条件/跟随 | `Services/FloatingBarManager.cs` | 见下面"悬浮条规则" |
| 悬浮条外观(自绘/透明) | `UI/FloatingToolbarForm.cs` | layered window,注意 GDI 释放 |
| 遮挡/可见性判断 | `Services/WindowVisibility.cs` | 两个 API 用途不同,见文件头 |
| 高亮框/跟随 | `Services/HighlightFollower.cs` | 跟随锚点窗口的相对偏移 |
| 全部控件框绘制 | `UI/NodeMapOverlayForm.cs` | 只在前台窗口且未遮挡处绘制 |
| 拾取器 | `Picker/CrosshairPicker.cs` + `UI/PickerOverlayForm.cs` | 不抢焦点、吞左键 |
| 单实例/转发 | `Services/SingleInstanceService.cs` + `Program.cs` | Mutex + 命名管道 |
| 无界面读取 | `Services/HeadlessConfigReader.cs` | 每条独立计时,统计口径在文件头 |
| 截图 / OCR | `Services/ScreenshotService.cs`、`Services/OcrClient.cs` | OCR 默认关闭 |
| 命令时机与退出清理 | `Services/CommandRunner.cs`、`Services/ProcessJob.cs` | 退出时结束整棵进程树 |
| 日志 | `Diagnostics/AppLog.cs` | GUI 启动会自建控制台窗口 |
---
## 三、几条容易踩的坑(都是踩过的)
- **不要在 UI 线程做 UIA/MSAA 调用**:Provider 挂住时界面直接冻结。后台线程 + `ReadBudget` + 序号丢弃旧结果。
- **不要用会变的显示文本做身份**:控件名可能随患者/文件/语言/计数变化。身份只用 AutomationId / ClassName / RuntimeId(运行期)/ HWND(Win32)。
- **不要清空重建控件树**:300ms 刷新时清空会闪烁并丢失选择/展开,用 `ControlTreeReconciler`。
- **不要"取第一个匹配"**:不确定就报错,让人重新拾取。
- **PropertyGrid 正在编辑时不要去 rebind**:会打断用户输入,`MainForm` 里有专门判断。
- **悬浮条的"名称"不是定位条件**:定位条件是进程名/窗口类/标题关键词 + 可选导入 XPath。
- **旧路径格式已停用**:`[Uia] A[id] > B:name`、`Type[id]` 之类不再执行,只保留给人工编辑修正。
- **本工具自己的窗口不算遮挡**:主界面/设置窗口压住目标不影响悬浮条显示(否则在设置页里根本测不了)。
- **bin\Debug 的 exe 被运行时锁定**:改完代码要编译时,先关掉正在运行的工具,或编译到别的输出目录。
---
## 四、悬浮条显示规则(当前版本)
只有**同时**满足下面条件才会显示:
1. 悬浮条 `Enabled = true`,且至少有一个启用的按钮;
2. 窗口条件(进程名 / 窗口类 / 标题关键词)已填写的部分**全部**满足,且**唯一**匹配到一个窗口;
- 匹配时**优先选可见窗口**,跳过 UWP 留下的最小化同名框架窗口;
3. 如果导入了监控项 XPath,该 XPath 在该窗口里**唯一命中**;
4. 勾选了"窗口可见且未被遮挡时才显示"时:锚定窗口存在、可见、未最小化,且**没有被别的程序完全遮住**(部分遮挡不影响;本工具自己的窗口一律忽略)。
检测结果显示"当前不显示"时,会说明卡在哪一步,并在被外部程序遮挡时点名是哪个窗口。
---
## 五、测试与验证
- 回归测试(纯内存,不需要目标程序):
```
dotnet msbuild tests\regression\RegressionTests.csproj -t:Build -p:Configuration=Debug -v:minimal
tests\regression\bin\Debug\RegressionTests.exe
```
想同时保留正在运行的工具实例时,加 `-p:OutputPath=<临时目录>\` 编译到别处再运行。
- 跨进程手工夹具:`tests\run-fixture.cmd`(见 `tests/README.md`)。
- **重要**:不要在本进程里用 UIA 读本工具自己的窗口,会原生崩溃。验证 UIA 逻辑必须用独立进程的夹具。
- 真机验收清单:控件树内容、拾取后树一致、列表读取行列、Path 往返(复制→按 path 定位)、
监控项保存后无界面 `--read-saved` 命中、悬浮条按条件显示/隐藏、遮挡/最小化行为。
---
## 六、想要继续开发,建议的顺序
1. 先跑一次界面 + 回归测试,确认基线正常;
2. 改一个功能点,同时补一条回归用例(`tests/regression` 里新增 `Register` 项);
3. 涉及跨进程读取的改动,用独立夹具实测,不要只看编译通过;
4. 改完在 `TODO.md` 记录"已验证 / 未验证",未在真实 PACS 上测过的不要写成已完成。