Files
dxdesigner-part-replacement/README.md
T

230 lines
15 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.4 Beta 4(预发布)** · [下载便携包](https://git.simgreek.com/simgreek/dxdesigner-part-replacement/releases/download/v1.1.4-beta.4/DxPartReplace-1.1.4-beta.4.zip) · [版本说明与附件](https://git.simgreek.com/simgreek/dxdesigner-part-replacement/releases/tag/v1.1.4-beta.4) · [完整使用说明](docs/user/v1.1.0-project-tasks.md)
所有发布均标记为 **Beta 预发布**。V1.1.4 Beta 1 因 BOM 导入缺少 `win32timezone` 已撤回,请使用 Beta 4;旧 Git 标签保留供回溯。升级前备份 `data`,完整更新 EXE 与 `_internal`,不要只替换 EXE。
Beta 4 面向停止与资源收尾复测:普通暂停等待当前项保存核验,写入中无进度不再自动杀进程;新增明确确认的强制结束,保留中断证据与恢复入口。[本版变更和复测说明](docs/releases/v1.1.4-beta.4.md)。
本版提供[目标封装选择](docs/user/target-cell-selection.md):目标封装可留空,此时工具不主动覆写封装,可后续与中心库同步;需要指定时,在料号规则中读取并选择合法封装。BOM 保持原 11 列。
## 图文教程
按下面 **13 步**,完成“创建任务 → 填 BOM → 导入校验 → 保存计划 → 替换 → 查看结果”。本例有两个工程 `Audio_D2128`、`Audio_T605A`,各自只替换 `RV05`,保留同料号下的 `RV11`。
截图来自真实窗口:起始页为 V1.1.3,后续操作图取自已验收的 V1.1.2 业务流程,操作位置相同。点击图片可以放大查看;BOM 填写图为示意。
### 第 1 步:解压并打开应用
[下载 V1.1.4 Beta 4 便携包](https://git.simgreek.com/simgreek/dxdesigner-part-replacement/releases/download/v1.1.4-beta.4/DxPartReplace-1.1.4-beta.4.zip),**完整解压**,双击 `DxPartReplace.exe`。保留它与 `_internal` 的相对位置,无需安装 Python;本机需要可用的 DxDesigner、许可证和中央库。
打开后看到下图主窗口。首次使用请准备完整的工程副本,执行前保存并关闭待处理工程。
![第 1 步:打开应用,进入任务主窗口](docs/user/media/tutorial/01-open.png)
### 第 2 步:新建任务,读取工程目录
点击左下方 **新建**。在弹窗中填写工程根目录,或点击 **选择目录**,再点击 **读取工程**。
**完成标志:** 弹窗列表显示该目录下找到的 `.prj` 工程。
![第 2 步:填写根目录,点击读取工程](docs/user/media/tutorial/02-read-projects.png)
### 第 3 步:勾选工程,创建任务
勾选这次要处理的工程,点击右下角 **创建任务**。本例勾选两个工程。
**完成标志:** 左侧出现两个任务,**一个工程对应一个任务**。
![第 3 步:勾选两个工程,点击创建任务](docs/user/media/tutorial/03-create-tasks.png)
### 第 4 步:导出本批 BOM 模板
选中左侧任意一个任务,切换到顶部 **本批位号计划**,点击 **BOM 模板**,选择文件保存位置。
**完成标志:** 导出的 Excel 包含本批所有工程,工程名称和完整路径已经填写好。此时不需要先采集位号,也不需要先添加料号规则。
![第 4 步:切换本批位号计划,导出 BOM 模板](docs/user/media/tutorial/04-export-template.png)
### 第 5 步:在 Excel 中填写替换项
打开刚导出的模板,**保留全部 11 列表头以及原工程路径**。同一工程需要填写多条替换时,复制该工程行后再填写。
本例在两个工程行中分别填写相同的旧、新料号和 `RV05`:
![第 5 步:BOM 填写示意,两个工程各替换 RV05](docs/user/media/tutorial/05-fill-bom.png)
| 要填写的列 | 填法 |
| --- | --- |
| `old_part_number` | 工程当前的旧料号,本例为 `4100-CA0000-T7` |
| `new_part_number` | 中央库中的目标新料号,本例为 `4100-CA0000-T0` |
| `refdes` | 要替换的位号,本例为 `RV05`;多个位号可用逗号、分号、空格或顿号分隔 |
| `enabled` | `TRUE` / `是` 表示替换,`FALSE` / `否` 表示保留;留空默认替换,建议显式填写 |
| `sync_nc` | 是否同步 NC,默认开启;按需要填 `TRUE` 或 `FALSE` |
| `custom_value` | 可选的自定义 Value;留空时使用任务的 Value 策略 |
料号按**文本**填写,不要使用公式。相同位号出现在多个图页时,补填 `schematic_name`、`sheet_number` 或 `uid` 消除歧义。旧新相同、链式或循环替换会被拒绝。
**本例首次导入只列出 RV05,采集到的 RV11 默认保留。再次导入时,未列出的既有计划行会保留原勾选;需要停用时,请取消勾选或明确填写 `enabled=FALSE`。**
填完后保存 Excel 文件。
### 第 6 步:导入填写好的 BOM
返回应用,在 **本批位号计划** 点击 **导入 BOM**,选择刚保存的 Excel,等待校验结果。
导入会检查表格和工程归属,并匹配相关工程的位号。缺少库存时优先调用原生 CLI 采集,不可用时回退到后台 CAD 只读采集。**导入不会执行替换,也不会直接保存计划。**
![第 6 步:点击导入 BOM,选择填写好的 Excel](docs/user/media/tutorial/06-import-bom.png)
### 第 7 步:检查导入报告,有错误先修正
点击校验状态条中的 **详情**。报告会显示通过、失败、未检查的行数,以及 Excel 行号和错误原因。
下图是故意填入不存在位号的示例:**通过 2 行、失败 1 行**,错误定位到 Excel 第 4 行。按报告修正 Excel、保存文件,再次点击 **导入 BOM**。
**有错误时不会部分保存。全部通过后再继续下一步。** 新一次导入开始后旧报告会清除;导入失败仍保留已有预览和手动编辑,取消文件选择则保留原报告。
![第 7 步:查看校验详情,按 Excel 行号修正错误](docs/user/media/tutorial/07-import-errors.png)
### 第 8 步:核对每个工程的预览,保存计划
报告全部通过后,关闭详情,依次选中左侧各任务,核对:
- 需要替换的 `RV05` 已勾选,新料号正确。
- 需要保留的 `RV11` 未勾选。
- 自定义 Value、同步 NC 等逐行设置符合预期。
确认后点击 **保存本批位号计划**;单工程编辑或保存完成后,按钮显示 **保存位号计划**。
**完成标志:** 底部提示计划保存完成。下图为保存后的状态,只有 RV05 启用。
![第 8 步:检查替换勾选和新料号,保存本批位号计划](docs/user/media/tutorial/08-review-save.png)
### 第 9 步:按任务确认 Value 与封装设置
选中一个任务,按需设置顶部 **Value 策略**:勾选后,将替换后的 **Part Label 写入 Value**;逐行自定义 Value 优先。处理多个工程时,分别确认各任务的开关。
本例开启该选项。**复制的是 Part Label,不是把新料号直接写进 Value。**
![第 9 步:按当前任务设置 Part Label 写入 Value](docs/user/media/tutorial/09-value-policy.png)
目标封装可留空,工具不主动覆写 Cell Name,可后续与中心库同步。需要本轮指定时,在 **本批料号规则** 中编辑对应旧、新料号规则,读取并选择合法封装,核对计划中的选择后保存。详见[封装操作说明](docs/user/target-cell-selection.md)。
### 第 10 步:选择执行范围,确认后开始
只处理选中工程,点击底部 **执行当前任务**;处理同批工程,点击左侧 **顺序执行本批任务**。本例使用后者。
在确认弹窗中核对工程数量和执行范围,确认无误再点击 **Yes / 是**。
![第 10 步:核对两个工程的执行范围,确认顺序执行](docs/user/media/tutorial/10-confirm-execution.png)
**搜索和显示排序只影响浏览,不改变本批执行范围。** 调整实际执行顺序,请使用左下方 **上移任务 / 下移任务**。
### 第 11 步:等待后台执行和保存重开核验
工具按工程顺序执行替换,保存、关闭并重新打开核验。左侧显示各任务状态,底部显示当前阶段和进度。
![第 11 步:观察任务状态和底部执行进度](docs/user/media/tutorial/11-running.png)
运行期间可以在主桌面查看其他文件,请勿打开或修改本次正在处理的同一工程。需要暂停时,点击 **完成当前项后暂停**,等待当前步骤安全收尾。
Beta 4 在保存或核验尚未确认时保留应用等待,可先 **导出诊断包**。只有明确接受中断后需要核验时,才选择 **强制结束…**;之后先核验恢复,不能直接重复替换。详见[停止、强制结束与恢复](docs/user/safe-stop-and-recovery.md)。
**完成标志:** 任务显示已完成,底部提示本批执行结束。还要打开结果核对,不能只看进度条。
### 第 12 步:查看实际修改结果与日志
选中要检查的任务,点击右下角 **替换结果 / 日志**,查看 **位号替换结果**。
本例应看到:`RV05` 的旧料号为 `4100-CA0000-T7`,回读料号为 `4100-CA0000-T0`,核验状态为 **已保存并核验**。
![第 12 步:查看位号、旧料号、实际回读料号和核验状态](docs/user/media/tutorial/12-results.png)
需要排查原因时,切到 **完整日志**,查看具体阶段和耗时;可用 **上一页日志 / 最新日志** 翻页。失败、未命中或未核验不会被当作已保存成功。
![第 12 步补充:完整日志显示各阶段和处理信息](docs/user/media/tutorial/12-complete-log.png)
### 第 13 步:需要继续替换时,开始新一轮
已完成任务可以点击底部 **开始新一轮**:
![第 13 步入口:任务完成后,底部出现开始新一轮](docs/user/media/tutorial/13-new-round-entry.png)
核对弹窗中的任务范围,再确认。
![第 13 步:核对新一轮范围及旧证据归档说明](docs/user/media/tutorial/13-new-round.png)
**完成标志:** 已完成任务恢复为待配置,旧计划、命令、快照和日志归档保留。接下来按工程**当前料号**重新填 BOM 或修改规则,重新采集、保存后执行;旧轮次通过 **查看轮次证据** 打开。
出现状态不确定或恢复提示时,先使用 **核验并恢复**,按[恢复说明](docs/user/interrupted-recovery.md)处理。
## 不使用 Excel:直接在界面编辑
1. 在 **本批料号规则** 添加旧、新料号,按需配置 Value 与同步 NC;规则提供采集条件和默认值。
2. 切到 **本批位号计划**,点击 **采集所有匹配位号**。
3. 勾选需要替换的行,逐行填写新料号、自定义 Value 和 NC。查找可按位号、UID、料号、图页或 Value 过滤;批量操作的范围会显示为当前工程或可见行。
4. 保存计划后执行。位号计划模式以**已保存的每行计划**为准,手动覆盖的值不会因修改默认规则而被随意覆盖。
两种方式可以配合使用,不必为了编辑而先导出 Excel。切换任务会保留编辑草稿;关闭时有未保存内容会提示保存全部、放弃或取消。
## Value、NC 与日志选项
- 顶部 **Value 策略** 开关控制当前任务是否将替换后的 Part Label 写入 Value;逐行自定义 Value 优先。处理多个任务时,分别确认各任务的开关。
- **同步 NC** 是逐行选项,默认开启,可以关闭。
- 点击 **完成当前项后暂停** 后,工具在当前步骤安全收尾后停止,不会在原生写入中途强行中断。
- 点击 **替换结果 / 日志** 查看图页、位号、旧料号、实际回读料号和核验状态。失败、未命中、未核验不会显示为已保存成功;完整日志支持翻页。
- 日志和 BOM 详情按需打开,关闭后释放窗口;数据和证据仍保留。
## 更新程序与保留数据
先关闭旧程序并备份 `data`。完整解压新包,用新 EXE 和 `_internal` 配合原 `data` 使用;不要混用不同版本的依赖目录,也不要删除原数据。
```text
DxPartReplace/
DxPartReplace.exe
_internal/
data/ 首次运行后创建,更新时保留
task-center.db 任务数据库
logs/application.log 应用日志
tasks/<任务ID>/ 任务事件、备份、快照及轮次证据
```
不同版本不要同时打开同一数据目录。排查失败时保留日志、原生报告和工程副本;不要手工删除锁文件、状态或恢复证据来强行续跑。
## 验证范围与已知限制
V1.1.4 Beta 4 沿用批次后台资源管理:一次 BOM 导入或顺序执行共用一个私有桌面,CAD 按需启动并在同批工程间复用,批次结束统一退出。若提示 **资源释放待处理**,已保存核验的结果保留,请点击 **重新清理资源**;该操作只清理后台资源,不会再次替换。旧的工程保护锁仍按“核验并恢复”处理。设计、异常边界与实机结果见[批次运行时验收记录](docs/testing/2026-10-21-batch-private-runtime.md)。
资源释放会追加日志:在 **替换结果 / 日志 → 完整日志** 查看本批开始释放、释放成功/失败及重新清理的结果。独立文件位于 `data/batch-resources/<批次ID>/resource-release.log`,记录批次、桌面、CAD PID、退出码、释放耗时、句柄关闭和桌面消失的分别确认,以及失败原因;同时保留 `session.json` 的原始释放证明。重启后重新检查也会追加记录,不覆盖原失败日志。
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`。
- [历史窗口 GIF(补充演示,录制于 V1.1.2)](docs/user/media/v1.1.2-window-bom-tutorial.gif)
- [完整桌面使用说明](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)