Files
dxdesigner-part-replacement/docs/research/v1.1.0-native-interface-probe.md
T

70 lines
12 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.
# V1.1.0 DxDesigner 7.9.5 原生替换接口调研
调研日期:2026-10-14。范围为现有工作区源码、已有测试、本机注册的 7.9.5 COM TypeLib 与安装帮助;本次没有附着、启动或修改任何 CAD 工程,也没有做写入式 live probe。
**安装版 TypeLib 复核更正:** 本机实际注册的 `viewdraw.tlb` 是版本 `1.0`,不含 `ReplacePart`、`OpenReplacePartDialog`、`ReplacePartCompleted` 或 `SelectExactSet`。工作区保存的一份同名 `designer_ifc.py` 是声明版本 `119.0` 的 makepy wrapper,虽然含 `IVdApp.ReplacePart(SourcePart, Scope, DestinationPart, PinMapping, PropertyMapping)`、`SRP_Selection=5` 和 `PropMT_LibraryWins=3`,但**不能用于证明本机 7.9.5 有这些成员**。下文旧桥中的这些名称应按候选/模拟接口理解。本机真实接口结果以 [离线 TypeLib 证据](v1.1.0-native-typelib-evidence.json) 为准。
## 结论
现有的 `Viewdraw.Application` COM 接口足以读取工程/图页/器件,按 UID 精确选中指定器件,并在替换前后核对选中集合。V1.1.0 的“一个旧料号只替换部分位号”可沿用这条选择链路。**写入路径仍应调用原生 Replace Symbol / Replace Part 并明确核验 Library Wins**。目前没有证据表明 `Block.ChangeComponentPreserveRefdes` 或 `ExecuteCommand("ccomp ...")` 能完整实现中央库选件、Library Wins、引脚及网络保持、Undo 和 Packager 通过。两者只适合作为可丢弃工程上的隔离探针,不能注册为默认执行后端。
这里的“原生接口”需要分清层次:现行自动执行使用 COM 读写选中状态,再从 `viewdraw.exe` 菜单资源识别 Replace Symbol 命令并发送 `WM_COMMAND`,随后通过 DxDesigner 原生对话框选择库行及选项。这是**原生 UI 工作流的自动化**,不是已证明存在的“传入旧件、新料号、Library Wins 参数的一次性 COM API”。
## 现有证据
| 路线 | 已有证据 | 当前判断 |
| --- | --- | --- |
| `Viewdraw.Application` | `QuickPartReplace.vbs:184,402,416` 附着/创建对象;`native_helper.py:196-204` 从活动对象取得 `IVdApp`;一叶知秋 `integration/dxdesigner795/CompatibilityProbe.vbs:122-132` 使用 `GetProjectData` 和 `DesignComponents` 枚举全工程。 | 可用作工程上下文、清单和选中控制;实际环境、精确 build 和 32/64 位组合仍需现场验收。 |
| 按器件精确选择 | `native_helper.py:214-249` 以 UID 设置 `Selected` 并重新读取选中 UID;本机 TypeLib 有 `IVdComp.Selected/_SetSelected` 和 `IVdApp.SelectComponent`;旧桥 `PartReplaceBridge.vbs:2097-2150` 所用的 `SelectExactSet` 不在安装版 TypeLib。一叶知秋 `core/Mailbox.vbs:365-375` 已用 `SelectByName` 定位单件。 | 位号应在扫描阶段绑定项目、图页、UID、旧料号;执行前重查完整身份和选中集合。仅用 RefDes 文本不能跨图页唯一定位。 |
| 原生 Replace Part + Library Wins | `native_helper.py:165-193,437-445` 从 Viewdraw 菜单资源识别 Replace Symbol;`:450-517` 打开原生对话框、选择精确库行、检查目标 Part Number/符号、确认原生选项,再执行;`:519-553` 验证结果及未选中件未变。`QuickPartReplace.vbs:780-815` 调用 helper;`:837-865` 对未保存失败做原生 Undo 和快照验证。 | 是已有的自动写入路线;需在现场 build/中央库上回归,并以证据确认每个控件 ID 对应的选项,不能只依赖 ID。 |
| `Application.OpenReplacePartDialog` | 旧桥 `PartReplaceBridge.vbs:2260-2261,2341-2384` 调用该名称并读 `ReplacePartCompleted`;旧 probe `PartReplaceProbe.vbs:951-985` 将其列为候选,`ccomp_research` 明确 `production_enabled=false`。本机 7.9.5 `IVdApp` TypeLib 没有这两个成员。 | 旧桥属于未证实候选/模拟路径;不能注册为本机可调用 COM 接口。 |
| `Block.ChangeComponentPreserveRefdes` | 本机 7.9.5 TypeLib 的 `IVdBlock` 确有 DISPID `42`,参数 `OldComp, NewComp`,返回 `VARIANT_BOOL`;保存的 wrapper `designer_ifc.py:5005,9943` 也有相同名称。现有设计 `docs/superpowers/specs/2026-09-01-dxdesigner-795-part-replacement-design.md:50-61` 记录符号原点及 Packager 失败的社区线索。 | 存在方法不等于可用于库料号替换;签名没有 Library Wins 参数,也未说明只作用于选中位号、如何选库及连接语义。 |
| `ExecuteCommand("ccomp ...")` | 类型库包装 `designer_ifc.py:1385,2974,3926` 暴露 `ExecuteCommand(CommandString)`;现有脚本只在 `QuickPartReplace.vbs:845,1143` 对 `undo` 使用它。旧设计 `...part-replacement-design.md:50-60` 仅记载 `ccomp :component_name` 候选,旧 probe 将 `Application.CComp` 标为研究项。全工作区未找到执行 `ExecuteCommand("ccomp ...")` 的生产调用或成功报告。 | 命令存在性、准确语法、选择范围及 Library Wins 行为均未证实。不能用 `undo` 可执行推断 `ccomp` 可执行。 |
已有文档 `docs/user/part-replacement.md:5,129-142` 对生产边界、精确选择与硬不变量作了明确约束。旧设计 `...part-replacement-design.md:37` 曾写“Python 不直接附着 COM”,但当前 `native_helper.py:196-204` 已直接附着。V1.1.0 文档应以当前实现和 live 证据为准,修正这处历史差异;不要把旧设计中的未验证候选当作生产能力。模拟测试 `tests/integration/test_part_replace_probe.py:498-562` 与 `test_part_replace_bridge.py:336-355` 只能证明协议和错误处理,不构成真实 7.9.5 行为证据。
## 本机安装版 TypeLib 细查
注册表 `HKLM\SOFTWARE\Classes\TypeLib\{4ADEF4E1-690A-11CE-9261-0020C5E26659}\1.0\0\win32` 指向 `D:\Mentor\7.9.5EE\SDD_HOME\wv\win32\bin\viewdraw.tlb`,SHA-256 为 `09323c8940f1acf3f469d887dcfdf7bcd114164a29b01ebeb9a7f978fa1a0df7`,共 223 个 TypeInfo。离线脚本 `tools/research/probe-native-capabilities.py` 直接调用 `pythoncom.LoadTypeLib(path)` 读这个文件,并与保存的 wrapper 比较;它不调用 `GetActiveObject` 或 `CreateObject`。输出 `docs/research/v1.1.0-native-typelib-evidence.json` 的 `wrapper_matches_installed_version=false`。
安装版真实可见成员包括 `IVdApp.ExecuteCommand(CommandString)` DISPID 29、`SelectComponent(sSchName, sSheetName, sCompUID)` DISPID 266、`QueryPages` DISPID 46、`DesignComponents` DISPID 59、`GetProjectData` DISPID 228;`IVdComp.Selected` 和 `_SetSelected`;`IVdBlock.DeSelectAll`、`ChangeComponent` DISPID 24、`ChangeComponentPreserveRefdes` DISPID 42。**没有任何名称含 Replace 的 TypeLib 函数**。旧桥引用的 `SelectExactSet`、`OpenReplacePartDialog`、`ReplacePartCompleted` 在安装版各接口中均未出现;目前测试里的同名 mock 不能当作原生接口。
外部 wrapper 的 `IVdApp.ReplacePart` 确有 DISPID 300、两个 BSTR、三个 32 位整数/枚举、布尔返回,以及 `SRP_Selection=5`、`PinMT_ByPinNumber=2`、`PropMT_LibraryWins=3`。它的声明版本是 `119.0`,与安装版 `1.0` 不同。因此可作为**未来版本接口线索**,但本机 V1.1.0 后端 capability 必须返回 `unavailable`,不能尝试按 DISPID 300 盲调。只有安装的 TypeLib 与运行时真实包含该方法,且 Selection + 精确 UID 选中 + Library Wins 的现场语义全部验证,才能为对应 build 启用直接 API 后端。
安装版 `automate.chm` 尝试用系统 `hh.exe -decompile` 提取,但没有得到可读文件;工作区的 `designer_auto_ref.pdf` 为较新 Xpedition Designer Automation Reference,页 696-697 解释 PinMapping/PropertyMapping 枚举,却不能代表本机 7.9.5 的接口集。故本结论优先依据安装版二进制 TypeLib,帮助材料只用于理解候选语义。
## 建议的 live probe
1. 准备已关闭、可丢弃的完整工程副本,记录 DxDesigner 版本/build、中央库身份、工程树哈希;选择同一旧料号的两个以上器件,其中仅一个目标位号需要替换。另选一个多单元或引脚较多的代表件。
2. 先只读探测 `ProjectPath`、`QueryPages`、`DesignComponents`、每个器件的 UID/RefDes/层级/图页/旧料号/Value/引脚/网络;在不同图页和同页重复位号场景验证身份是否唯一。记录 COM 调用返回值与错误号。
3. 在副本上单独验证 `IVdComp.Selected` 与 `IVdApp.SelectComponent`:只选目标 UID,重新枚举选中集合。若集合不一致则停止。记录目标与同旧料号未选中器件的完整前快照。`SelectExactSet` 不作为本机 7.9.5 探针调用。
4. 建立基准:使用现行原生对话框路线对目标位号执行一次 Replace Part + Library Wins,记录库行、目标符号、控件文本/状态、替换后全图页快照、Undo、保存关闭再打开回读、Packager/ERC/网表结果。
5. 对 `ChangeComponentPreserveRefdes` 和 `ccomp` **分别使用新的副本**做最小写入探针。先只读确认签名和命令语法;确认可恢复后仅改一个目标件。记录实际作用范围、库控制字段、RefDes/位置/方向、引脚号与网络、非目标件、Undo、保存回读和 Packager。任一步不确定就关闭副本且不保存,并留证;不能把属性值或 Part Number 单字段变化视为通过。
6. 只有候选路线在多类器件、多图页、现场中央库上满足与基准相同的硬不变量,且有可重复证据和精确 build 绑定,才考虑提升为可选后端。选择一组目标位号后,必须证明未选中的同料号位号保持原样。
现行代码核验目标及未选中件料号(`native_helper.py:519-547`),但后端晋级标准还要使用 `docs/user/part-replacement.md:140` 的完整保护字段,并核对 NC/Value 策略、保存回读和独立 Packager/ERC/网表结果。现场报告应保存命令、参数、返回值/错误、前后快照、差异及文件 SHA-256,而不是只保存“成功”布尔值。
## V1.1.0 后端边界建议
将**计划和身份验证**留在任务层;替换后端只负责一组已冻结的目标 UID。在单工程任务内按图页、旧料号、新料号及 Value/NC 策略分组,后端逐组处理。最小契约可表达为:
```text
ReplacementRequest:
project_path, project_fingerprint, sheet_identity
targets: [{uid, refdes, old_part_number, baseline_fingerprint}]
new_part_number, library_identity, policy, command_id
ReplacementBackend:
capability(build, library_identity) -> supported / research_only / unavailable
inspect(request) -> current target identities and full-sheet baseline
replace(request, evidence_dir) -> result with attempted/committed/uncertain status
verify(request, result) -> selected and unselected differences
recover(request, result) -> verified undo or close_without_save evidence
```
生产后端先封装当前 native dialog/helper 路线。`ChangeComponentPreserveRefdes` 与 `ccomp` 应放入独立研究适配器,并强制 `research_only`、可丢弃副本和显式试验入口。后端不能自行扩大目标集合;命令中无 UID、旧料号或工程指纹匹配失败时,必须在写入前失败。结果须区分“未开始”“已变更但未确认”“已验证”和“已恢复”,使批次调度器遇到不确定状态时停下。
## 外部资料与证据等级
现有设计在 `...part-replacement-design.md:69` 引用了 Siemens 社区关于 `ChangeComponentPreserveRefdes` 导致封装失败的讨论。此次网络可访问 Siemens 支持门户首页(HTTP 200),但未取得公开的 7.9.5 API 正文或可复核的 `ccomp`/Library Wins 参数说明;搜索请求超时。因此报告中对这两条路线的判断以本机类型库、工作区源码与设计记录为依据,**没有宣称公开资料证明其替换语义**。下一轮应优先取得站点安装包里的 Automation Reference、命令手册和现场 build 录屏/日志,再做写入试验。