Files
dxdesigner-part-replacement/README.md
T

137 lines
9.6 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.
# 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 填表示例在录制之外完成。
![V1.1.2 窗口操作教程](docs/user/media/v1.1.2-window-bom-tutorial.gif)
如果图片没有自动播放,可以[单独打开 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)