DxDesigner Part Replacement
面向 Windows 和 DxDesigner/Expedition Enterprise 7.9.5 的器件批量替换工具。工具通过 DxDesigner 原生 Replace Part 完成替换,并在写入前后保存快照、检查受保护字段、记录操作证据,支持桌面连续队列和可恢复的批处理流程。
当前发布级别:evaluation-only(仅评估)。 在目标现场完成 7.9.5 验收并取得可追溯证据之前,只能对完整、可丢弃的工程副本和对应中央库进行操作。不要用于唯一工程副本、生产库或未经认证的料号映射。
能做什么
| 使用路径 | 适合场景 | 结果含义 |
|---|---|---|
DxPartReplace.exe 桌面连续队列 |
选择工程目录和映射后,按“工程 → 图页 → 规则”串行执行 | 命中项经过替换、保存、关闭和重新打开核验;未命中项记录并跳过;“队列完成”不等于通过 Packager、ERC 或网表检查 |
| 桌面人工证据流程 | 由操作员在 DxDesigner 中完成替换,工具采集 Before/After 证据 | 只表示证据比较通过,不自动替换、保存或关闭工程 |
Start-PartReplacement.ps1 + dx_productivity CLI |
需要完整库存、认证、备份、恢复和外部检查门禁的评估批次 | 只有项目进入 verified_saved 且外部检查通过,批次才可报告为成功 |
三条路径的任务、日志和通过条件不同,不能互相替代。详细边界见 docs/user/trial-task-center.md。
运行前提
- Windows;真实替换基线为 DxDesigner/Expedition Enterprise 7.9.5。
- 源码运行和批处理 CLI 使用 Python 3.12(必须是 3.12)。
- 目标机器需要可用的 DxDesigner 安装、许可证和中央库;没有中央库时只能运行测试、构建和界面冒烟检查。
- 自动替换只能连接一个工程。开始前保存并关闭用户已经打开的工程;工具不会擅自关闭、切换或保存它。
- 每次现场试验使用完整工程副本,并保留备份、快照、状态、事件日志和报告。
发布包:最快上手
- 解压与目标 DxDesigner 版本匹配的发布包,保留
DxPartReplace.exe、_internal和data目录结构。 - 双击
DxPartReplace.exe。 - 新建任务,选择包含
.prj文件的工程目录并扫描;选择要处理的工程。 - 添加“旧 Part Number → 新 Part Number”映射,按需要设置 Value 和
/NC选项。 - 先确认工程已经保存并关闭,再点击 连续执行队列。
- 执行过程中不要在 DxDesigner 中切页、编辑或关闭当前工程。遇到“结果无法确认”、保护锁或恢复提示时,先保留现场文件并按恢复文档处理,不要重复点击。
发布版默认把可变数据放在 EXE 同目录的 data 下:
data/task-center.db 任务数据库
data/logs/application.log 应用日志
data/tasks/<task-id>/ 任务事件与证据
data/quick-run/ 连续队列交接文件、备份和运行日志
更新程序时只替换 EXE 和 _internal,不要删除 data。分发新包时使用未运行过的干净目录,不要把包含工程备份的本机 data 一起外发。
从源码运行
在仓库根目录使用 PowerShell:
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
启动桌面程序:
.\.venv\Scripts\python.exe -m dx_productivity.trial_task_center.application
# 或
.\.venv\Scripts\dx-part-replace-gui.exe
启动 CLI:
.\.venv\Scripts\python.exe -m dx_productivity --help
# 或
.\.venv\Scripts\dx-part-replace.exe --help
源码运行时,任务中心默认使用 %LOCALAPPDATA%\DxProductivity\trial-task-center。可以用 DX_TASK_CENTER_HOME 指定独立数据目录;发布版则默认使用 EXE 旁边的 data。
CLI 快速参考
CLI 的输出默认是便于阅读的文本;添加 --json 可获得脚本可消费的稳定 JSON。下面的命令只负责发现和创建作业,真实 DxDesigner 操作仍需要已验收的配置、中央库和现场操作流程。
发现候选项目后必须逐行审阅:
.\.venv\Scripts\python.exe -m dx_productivity --json discover "D:\Disposable\Projects" --output "D:\Qualification\projects-candidates.txt"
创建作业需要 UTF-8 映射、项目列表和认证文件:
.\.venv\Scripts\python.exe -m dx_productivity --json create "C:\DxProductivity\runs\part-replace-<GUID>" --mapping "D:\Qualification\replacement.csv" --projects "D:\Qualification\projects.txt" --certifications "D:\Qualification\certifications.json"
常用作业查询和恢复命令:
.\.venv\Scripts\python.exe -m dx_productivity --json status "C:\DxProductivity\runs\part-replace-<GUID>"
.\.venv\Scripts\python.exe -m dx_productivity --json restore "C:\DxProductivity\runs\part-replace-<GUID>" "<project_id>"
不要编辑 manifest、mailbox、状态文件或事件文件来推进任务;恢复必须使用原作业目录,不能用相同输入重新创建一个“看起来一样”的新作业。完整命令循环、状态和恢复前提见 docs/user/part-replacement.md。
原生批处理集成
这条路径用于需要兼容性配置、项目库存、认证映射、备份、恢复和 Packager/ERC/网表检查门禁的评估批次。
1. 安装运行目录
Install.ps1 会验证 Python 3.12 和 dx_productivity 导入,将现场 probe 产生的兼容性配置原子部署到 runs\compatibility-profile.json,并写入当前用户的设置。先用 -WhatIf 预览路径:
& "C:\DxProductivity\integration\dxdesigner795\Install.ps1" -InstallRoot "C:\DxProductivity" -PythonExecutable "C:\Python312\python.exe" -CompatibilityProfile "C:\Qualification\compatibility-profile.json" -WhatIf
确认输出后再去掉 -WhatIf。然后在 DxDesigner 中导入 integration\dxdesigner795\MenuAdd.vbs,使 Dx Productivity 菜单出现。
兼容性配置必须来自实际 probe 和现场验收。不能手工把 live_acceptance.checked 改成 true;未完成验收时,发布分类仍为 evaluation-only。
2. 准备输入
映射文件 replacement.csv 只有两个列名:
old_part_number,new_part_number
OLD-001,NEW-001
OLD-002,NEW-002
工具会拒绝空值、重复旧值、旧新相同、链式映射和循环映射。目标只能通过中央库 Part Number 指定,不能用元件名、符号名或引脚名代替。
项目列表 projects.txt 每行一个绝对 .prj 路径:
D:\Disposable\Board-A\Board-A.prj
D:\Disposable\Board-B\Board-B.prj
每个 old/new 映射都必须先在代表性、关闭的可丢弃副本上完成认证,并绑定中央库身份或目标指纹。当前交付没有公开的“生成认证”命令,不要伪造 certifications.json。
3. 启动作业
& "C:\DxProductivity\integration\dxdesigner795\Start-PartReplacement.ps1" -Mapping "D:\Qualification\replacement.csv" -Projects "D:\Qualification\projects.txt" -Certifications "D:\Qualification\certifications.json"
暂停时保留控制台打印的绝对作业路径,用 -ResumeJob 恢复;恢复时不要再次传入 Mapping、Projects、Certifications 或 DiscoveryRoot:
& "C:\DxProductivity\integration\dxdesigner795\Start-PartReplacement.ps1" -ResumeJob "C:\DxProductivity\runs\part-replace-<GUID>"
完整操作顺序和人工菜单动作见 docs/user/part-replacement.md。
安全边界与恢复
- 写入前先固定图页清单、检查工程身份,并为实际命中的工程创建原理图精简备份;备份包含文件清单和 SHA-256。
- 原生替换后检查 Part Number、RefDes、层级、放置单元、位置、旋转、镜像、门/槽、引脚集合、引脚坐标和网络身份。硬字段或连接无法证明未变时必须阻断。
- 连续队列按“工程 → 图页 → 规则”串行执行,同一时间不打开多个工程;图页新增、删除或重命名会在下一次写入前停止。
- 零命中会记录为
no_match并跳过替换,不等于替换成功,也不代表其他图页没有该料号。 - 保存、关闭、回读或监控结果不确定时保留保护锁、快照和证据,不要删除锁文件或强制重试。
- 恢复只能针对原作业、原工程和绑定证据执行;恢复失败时保留失败树、备份和隔离证据,交给现场负责人调查。
Value 内容、样式继承和 /NC 同步规则见 docs/user/value-copy-and-layout.md;连续队列和长期证据保留见 docs/user/continuous-queue.md。
日志、报告与支持交接
排查问题时保留目标工程副本和整个数据目录,至少包括:
logs/application.log;- 对应任务的
events.jsonl; quick-run/quick-part-replace.log、command.tsv、status.tsv;- 替换前后快照、原生 helper 报告、
uncertain.flag(如存在); - CLI 作业中的
reports/impact.csv、reports/differences.json、reports/summary.html。
交接记录还应包含 DxDesigner build、Windows 版本、工程规范路径、中央库身份/指纹、映射、操作员、日期及每份证据的 SHA-256。自动化回归和 mock 测试不能替代现场验收。
开发、测试与构建
运行完整测试:
.\.venv\Scripts\python.exe -m pytest -q
构建 Windows 发布目录:
.\packaging\Build-DxPartReplace.ps1 -PythonExecutable ".\.venv\Scripts\python.exe"
构建脚本会运行打包相关测试、调用 PyInstaller、检查 QuickPartReplace.vbs 是否完整复制,并启动 --smoke-test 验证 EXE 能创建和关闭日志。打包需要本机已注册的 DxDesigner EE 7.9.5 类型库;输出位于 dist\DxPartReplace。