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

- 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
+27
View File
@@ -1,5 +1,32 @@
# tests —— 可运行的测试夹具
## 这些测试怎么跑、失败怎么办
本目录有两块东西,目的不同:
1. `uia-fixture/` —— 一个**独立进程**的真实 WinForms 窗口(`UiaFixture.exe`),用来让工具
跨进程做 UIA 读取/拾取/定位的人工验证。UIA 在**同一进程内**自读自身控件树会崩溃,所以必须
跨进程。构建并启动:`tests\run-fixture.cmd`(默认 Debug,可传 `Release`)。
2. `regression/RegressionTests.csproj` —— 自动化回归测试(net48 控制台程序),在纯内存快照或
本进程自建控件上跑断言,覆盖 XPath 定位、持久化/迁移、控件树增量刷新、悬浮条显示条件等。
它**不**用 UIA 读自身控件树(会崩溃)。
跑回归测试(不要在本目录直接 `dotnet build`,`src` 的 `bin\Debug` 可能被正在运行的工具进程锁定):
```bat
:: 用隔离的 OutputPath 构建,随后直接运行生成的 exe
dotnet msbuild tests\regression\RegressionTests.csproj -t:Build -p:Configuration=Debug ^
-p:OutputPath=%TEMP%\pacs-regression\ -v:minimal
%TEMP%\pacs-regression\RegressionTests.exe
```
- **退出码**:`0` = 全部用例通过;`1` = 存在失败(便于脚本/CI 判断)。
- **失败怎么办**:在输出里找 `FAIL <用例名>`,其下会打印异常的 message(含 expected/actual)。
按用例名到 `regression/*Tests.cs` 的 `Register(...)` 里定位对应方法。下拉/刷新类用例可设
环境变量 `PACS_REGRESSION_SCREENSHOTS=<目录>`,失败或关键步骤会自动把窗体截图写入该目录以便比对。
- **部分跳过是正常的**:个别断言依赖桌面上是否存在其他进程的窗口(如遮挡诊断的外部窗口用例),
缺失时会打印 `(... skipped)` 并跳过,不算失败。
真实 PACS/OCS 客户端要么不暴露 UIA(CEF 套壳),要么树太大没法人工核对。
这里放一个**普通 WinForms 窗口**,控件类型、名称、层级都是已知的,用来验证本工具的读取链路。