137 lines
9.6 KiB
Markdown
137 lines
9.6 KiB
Markdown
# DxDesigner 器件批量替换工具
|
||
|
||
<img src="docs/user/media/app-icon.png" width="64" height="64" alt="DxPartReplace 应用图标">
|
||
|
||
面向 **Windows + DxDesigner / Expedition Enterprise 7.9.5** 的器件批量替换工具。一个工程对应一个任务,可以只替换同料号下的部分位号;支持直接编辑和 Excel BOM 导入,同批工程按顺序执行。
|
||
|
||
**最新版本:V1.1.3** · [下载便携包](https://git.simgreek.com/simgreek/dxdesigner-part-replacement/releases/download/v1.1.3/DxPartReplace-1.1.3.zip) · [版本说明与附件](https://git.simgreek.com/simgreek/dxdesigner-part-replacement/releases/tag/v1.1.3) · [完整使用说明](docs/user/v1.1.0-project-tasks.md)
|
||
|
||
本版提供[目标封装选择](docs/user/target-cell-selection.md):目标封装可留空,此时工具不主动覆写封装,可后续与中心库同步;需要指定时,在料号规则中读取并选择合法封装。BOM 保持原 11 列。
|
||
|
||
## 窗口操作教程
|
||
|
||
下面的 GIF 录制于 V1.1.2,操作步骤仍适用于 V1.1.3,图标与版本号以新版为准。包含创建任务、BOM 导入、错误行提示、保存、顺序执行、查看结果和开始新一轮。共 20 个步骤、47.5 秒;仅记录工具及其弹窗,CAD 等待已压缩,Excel 填表示例在录制之外完成。
|
||
|
||

|
||
|
||
如果图片没有自动播放,可以[单独打开 GIF](docs/user/media/v1.1.2-window-bom-tutorial.gif)。
|
||
|
||
## 开始使用
|
||
|
||
1. 下载并完整解压便携包,保留 `DxPartReplace.exe` 和 `_internal` 的相对位置。**便携包无需安装 Python**,本机仍需安装可用的 DxDesigner、许可证和中央库。
|
||
2. 双击 `DxPartReplace.exe`。首次运行会自动创建同目录的 `data`,保存任务、日志和执行证据。
|
||
3. 点击左侧 **新建**,在弹窗填写工程根目录,点击 **读取工程**,勾选需要处理的 `.prj`,再点击 **创建任务**。每个工程自动创建一个任务。
|
||
|
||
首次使用请在完整工程副本上验证映射与库配置。执行前保存并关闭待处理工程;工具会启动自己的后台 CAD,主桌面仍可查看其他文件。
|
||
|
||
## 方式一:通过 BOM 批量配置
|
||
|
||
### 1. 导出本批模板
|
||
|
||
选择任务,打开顶部 **本批位号计划**,点击 **BOM 模板**。只要已导入工程,就能导出同批所有工程的一张空白表,**不需要先采集位号或填写料号规则**。
|
||
|
||
工程名称、工程路径自动填写。工程路径用于唯一分配任务,请保持原样;同一工程有多条替换时,可以复制该工程行。
|
||
|
||
### 2. 在 Excel 填写替换项
|
||
|
||
保留原模板的 11 列表头,按需要填写:
|
||
|
||
| 列名 | 填写内容 |
|
||
| --- | --- |
|
||
| `old_part_number` | 工程当前的旧料号 |
|
||
| `new_part_number` | 中央库中的目标新料号 |
|
||
| `refdes` | 要处理的位号,例如 `RV05`;一行可以写多个位号,以逗号、分号、空格或顿号分隔 |
|
||
| `enabled` | `TRUE` / `是` 表示替换,`FALSE` / `否` 表示保留 |
|
||
| `sync_nc` | 是否同步 NC,默认开启,可逐行关闭 |
|
||
| `custom_value` | 可选的自定义 Value;填写后优先写入,留空沿用任务的 Value 策略 |
|
||
|
||
例如,首次配置的旧料号同时对应 `RV05`、`RV11`,只想替换 `RV05`,可以只填写 `RV05` 的启用项;首次采集的其余位号默认不替换。
|
||
|
||
**再次导入时,BOM 中未列出的既有计划行会保留原勾选和编辑状态。** 如果这轮只想执行 BOM 列出的目标,请在预览中检查其他启用行,并明确取消勾选,或在 BOM 中填写对应的 `enabled=FALSE` 行。
|
||
|
||
同名位号分布在不同图页时,补填 `schematic_name`、`sheet_number` 或 `uid` 消除歧义。`enabled` 留空默认替换,`sync_nc` 留空默认开启;建议显式填写。料号按文本填写;导入不接受公式,也不接受旧新相同、链式或循环替换。
|
||
|
||
### 3. 导入并检查报告
|
||
|
||
点击 **导入 BOM**,选择填好的文件。工具先校验表格格式、工程归属,以及能从表中确定的重复声明和料号冲突;通过后,只核验本表涉及的工程。已有位号库存覆盖旧料号时直接匹配;缺少库存时优先通过原生 CLI 采集,不可用时才回退到后台 CAD 只读采集。
|
||
|
||
新一轮导入开始后,旧报告会清除,界面显示读表、获取库存、匹配位号等进度;取消选择文件则保留原报告。导入失败或取消会保留已有预览和手动编辑。保存和执行前仍会核验工程。
|
||
|
||
- 校验报告显示通过、失败、未检查的行数,并标明 Excel 行号及原因。
|
||
- 有错误时,整批不会生成新的可保存预览,也不会部分写入计划。修正后重新导入。
|
||
- 全部通过后,先得到预览;可以切换任务,检查或修改各工程的位号计划。
|
||
|
||
### 4. 保存并执行
|
||
|
||
确认预览后点击 **保存本批位号计划**;普通单工程编辑时按钮显示 **保存位号计划**。
|
||
|
||
点击 **执行当前任务** 处理当前工程,或点击左侧 **顺序执行本批任务** 处理同批工程。确认范围后,工具逐项执行原生 Replace Part、保存、关闭并重新打开核验。
|
||
|
||
**左侧搜索和显示排序只影响浏览,不改变本批执行范围。** 调整执行顺序请使用上移、下移任务按钮。
|
||
|
||
## 方式二:直接在界面编辑
|
||
|
||
1. 在 **本批料号规则** 添加旧、新料号,按需配置 Value 与同步 NC;规则提供采集条件和默认值。
|
||
2. 切到 **本批位号计划**,点击 **采集所有匹配位号**。
|
||
3. 勾选需要替换的行,逐行填写新料号、自定义 Value 和 NC。查找可按位号、UID、料号、图页或 Value 过滤;批量操作的范围会显示为当前工程或可见行。
|
||
4. 保存计划后执行。位号计划模式以**已保存的每行计划**为准,手动覆盖的值不会因修改默认规则而被随意覆盖。
|
||
|
||
两种方式可以配合使用,不必为了编辑而先导出 Excel。切换任务会保留编辑草稿;关闭时有未保存内容会提示保存全部、放弃或取消。
|
||
|
||
## Value、暂停与执行结果
|
||
|
||
- 顶部 **Value 策略** 开关控制当前任务是否将替换后的 Part Label 写入 Value;逐行自定义 Value 优先。处理多个任务时,分别确认各任务的开关。
|
||
- **同步 NC** 是逐行选项,默认开启,可以关闭。
|
||
- 点击 **完成当前项后暂停** 后,工具在当前步骤安全收尾后停止,不会在原生写入中途强行中断。
|
||
- 点击 **替换结果 / 日志** 查看图页、位号、旧料号、实际回读料号和核验状态。失败、未命中、未核验不会显示为已保存成功;完整日志支持翻页。
|
||
- 日志和 BOM 详情按需打开,关闭后释放窗口;数据和证据仍保留。
|
||
|
||
## 完成后再执行一轮
|
||
|
||
已完成任务可以点击 **开始新一轮**。工具归档旧计划、命令、快照与执行证据,清空过期位号基线,将同批已完成任务恢复为待配置。
|
||
|
||
接着按工程**当前料号**重新填 BOM 或修改规则,重新采集、保存并执行。旧轮次可通过 **查看轮次证据** 打开。出现状态不确定或恢复提示时,先使用 **核验并恢复**,不要直接重复执行。
|
||
|
||
## 更新程序与保留数据
|
||
|
||
先关闭旧程序并备份 `data`。完整解压新包,用新 EXE 和 `_internal` 配合原 `data` 使用;不要混用不同版本的依赖目录,也不要删除原数据。
|
||
|
||
```text
|
||
DxPartReplace/
|
||
DxPartReplace.exe
|
||
_internal/
|
||
data/ 首次运行后创建,更新时保留
|
||
task-center.db 任务数据库
|
||
logs/application.log 应用日志
|
||
tasks/<任务ID>/ 任务事件、备份、快照及轮次证据
|
||
```
|
||
|
||
不同版本不要同时打开同一数据目录。排查失败时保留日志、原生报告和工程副本;不要手工删除锁文件、状态或恢复证据来强行续跑。
|
||
|
||
## 验证范围与已知限制
|
||
|
||
V1.1.3 的业务代码沿用本机已验收候选:两工程实际替换和独立回读、362 字符工程路径、BOM 失败/成功导入、Part Label 写入 Value、可选封装、旧版任务数据副本、新轮次和自有后台资源释放。新增图标及版本元数据另做冻结包检查。详见[验收报告](docs/testing/2026-10-19-release-preparation.md)。
|
||
|
||
当前按 **evaluation-only(评估试用)** 交付。不同机器、中央库和 CAD 版本仍需用工程副本确认兼容性;替换回读通过不代表已通过 Packager、ERC 或网表检查。
|
||
|
||
首次采集与 CAD 启动可能需要较长时间,存在已知的偶发 COM 启动阻塞;启动有等待上限和清理机制。验收候选的两工程执行为 167 秒;千步模拟队列为 21.09 秒,两者测量范围不同。长路径兼容已覆盖验证场景,不代表旧 CAD 或中央库支持任意路径。
|
||
|
||
## 开发与更多资料
|
||
|
||
源码运行需要 Python 3.12:
|
||
|
||
```powershell
|
||
py -3.12 -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
|
||
.\.venv\Scripts\python.exe -m dx_productivity.trial_task_center.application
|
||
```
|
||
|
||
源码默认数据目录为 `%LOCALAPPDATA%\DxProductivity\trial-task-center`,可用 `DX_TASK_CENTER_HOME` 指定独立目录。运行回归:`python -m pytest -q`;构建使用 `packaging/Build-DxPartReplace.ps1`。
|
||
|
||
- [完整桌面使用说明](docs/user/v1.1.0-project-tasks.md)
|
||
- [中断核验与恢复](docs/user/interrupted-recovery.md)
|
||
- [Value 与属性继承](docs/user/value-copy-and-layout.md)
|
||
- [历史流程和独立 CLI 说明](docs/user/trial-task-center.md)
|
||
- [CLI 与原生批处理集成](docs/user/part-replacement.md)
|
||
- [V1.1.3 版本说明](docs/releases/v1.1.3.md)
|