Files
dxdesigner-part-replacement/docs/user/part-replacement.md
T

170 lines
18 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 7.9.5 元件替换操作指南
> **发布级别:仅评估(evaluation-only)。** 在现场 7.9.5 验收清单全部取得人工证据前,脚本、运行目录和报告均为评估产物。只能对可丢弃的完整项目副本操作,绝不用于唯一副本、生产库或生产发布。
本工具执行的是 DxDesigner 原生的库元件替换,不是修改 `Part Number` 属性、复制属性、改写设计文件或自动重新连线。生产写入路径固定为原生 Replace Part;目标元件、符号、引脚和库控制属性必须来自中央库的 `Library Wins` 选择。`ccomp`、`ChangeComponentPreserveRefdes`、直接文件编辑和键盘/坐标自动化均不是允许的操作路径。
## 1. 上线前边界
- 支持基线仅为 DxDesigner/Expedition Enterprise `7.9.5`。新版本不因本指南而获得支持。
- 每次操作使用一个完整、可恢复的项目副本和该副本对应的中央库映射。先完成 [现场验收清单](../testing/dxdesigner-795-part-replacement-live.md)。
- 不要绕开拒绝条件。缺少项目身份、完整库存、精确选择、保护字段、引脚或网络证据时,必须停在 `blocked`。
- AI 只能阅读库存、差异、Packager/ERC/网表和人工记录并给出建议;AI 不能改变快照、事件日志、硬校验、保存权限、认证或备份,也不能批准连通性改变或未认证的映射。
## 2. 安装、配置文件和卸载
安装根目录必须包含完整交付包,包括 `integration\dxdesigner795\PathSafety.ps1`、`PartReplacementContract.ps1`、`MenuAdd.vbs`、`MenuRuntime.vbs`、`PartReplaceMenuRuntime.vbs`、`BridgeCommon.vbs`、`PartReplaceProbe.vbs` 和 `PartReplaceBridge.vbs`。Python 可执行文件必须恰好为 Python `3.12`,并且能导入 `dx_productivity`。兼容性配置文件是现场 probe 产生并审阅过的 JSON,不要手工改写。未经现场验收的 probe 配置可以用于本指南限定的评估和人工回退,但不能授权自动写路线。
以普通用户 PowerShell 运行(参数名和路径必须准确):
```powershell
& "C:\DxProductivity\integration\dxdesigner795\Install.ps1" `
-InstallRoot "C:\DxProductivity" `
-PythonExecutable "C:\Python312\python.exe" `
-CompatibilityProfile "C:\Qualification\compatibility-profile.json"
```
`Install.ps1` 会验证 Python 版本和导入、验证并原子部署配置文件到 `C:\DxProductivity\runs\compatibility-profile.json`、写入 `%LOCALAPPDATA%\DxProductivity\settings.json`,并在当前用户范围设置 `DXTOOLS_HOME=C:\DxProductivity`。先使用同一命令加 `-WhatIf` 核对 `InstallRoot`、`PythonExecutable`、`CompatibilityProfile`、`SettingsPath`、`RunRoot` 和 `DXTOOLS_HOME`;`-WhatIf` 不写入配置或环境变量。
在 DxDesigner 启动导入 `C:\DxProductivity\integration\dxdesigner795\MenuAdd.vbs`。该入口会加载 `MenuRuntime.vbs`,并且只维护一个带标签的 `Dx Productivity` 菜单。确认可见的菜单项为:
- `Part replacement probe`
- `Inventory current project`
- `Continue part replacement`
### 配置文件部署与发现审阅
安装只接受部署后的 `runs\compatibility-profile.json`;`Start-PartReplacement.ps1` 不接受另一份运行配置文件或另一个运行根目录。审阅 probe JSON 中的 `dxdesigner.version`、`dxdesigner.build`、`project.identity`、`project.dirty`、`interfaces`、`routes`、`api_errors`、`safety` 和 `live_acceptance`。只有 `production_replace_route` 为 `native_replace_part`,并且所需的接口和路线有可追溯现场证据时,才可继续评估。
现场清单全部完成后,由站点负责人生成 `acceptance.json`。它必须逐项绑定 fixture、mapping、observation、tester、日期、唯一 evidence path 和对应文件的 SHA-256,并绑定原始 probe 配置的 SHA-256、精确 `7.9.5` version/build、操作员和中央库身份。用公开晋级命令验证并原子部署,不能直接把 `live_acceptance.checked` 改为 `true`:
```powershell
& "C:\Python312\python.exe" -m dx_productivity --json promote-profile `
"C:\Qualification\probe-profile.json" `
"C:\Qualification\acceptance.json" `
"C:\DxProductivity\runs\compatibility-profile.json"
```
当前清单仍全部未勾选,因此当前交付不得执行或声称已经通过这一步,发布分类仍为 `evaluation-only`。
使用发现功能时,生成的候选列表不自动加入作业:
```powershell
& "C:\DxProductivity\integration\dxdesigner795\Start-PartReplacement.ps1" `
-DiscoveryRoot "D:\Disposable\Projects"
```
它写入 `C:\DxProductivity\runs\discovered-projects.txt`。逐行审阅、删除不属于本次批次的候选项目并确认中央库映射后,另存为本次的 `projects.txt`。发现只是便利功能;不得把未审阅发现结果直接用于替换。
### 卸载
没有交付 `Uninstall.ps1`,因此不存在可宣称的公开卸载命令。完成或放弃所有评估作业后:在 DxDesigner 中移除启动导入的 `MenuAdd.vbs`;删除当前用户环境变量 `DXTOOLS_HOME`;仅在按保留制度导出/保存 `runs` 中的作业证据、备份清单和报告之后,再由桌面软件管理员移除安装根目录及 `%LOCALAPPDATA%\DxProductivity\settings.json`。不要删除仍可能用于恢复的作业备份;没有受控恢复或保留批准时,交接给站点管理员。
## 3. 输入和不可变作业
`replacement.csv` 必须是 UTF-8 CSV,且仅有这两个列名:
```csv
old_part_number,new_part_number
OLD-001,NEW-001
OLD-002,NEW-002
```
工具会去除前后空白、保留展示拼写、按大小写不敏感方式比较。它拒绝空值、重复旧值(包括只差大小写)、旧新相同、链式映射和循环映射。不要写元件名、符号名、属性、引脚或描述;替换目标的唯一键是中央库 `Part Number`。
`projects.txt` 是 UTF-8 文本,每行一个**绝对**项目定义路径,例如:
```text
D:\Disposable\Board-A\Board-A.prj
D:\Disposable\Board-B\Board-B.prj
```
路径会规范化但不改变磁盘大小写。重复、缺失、嵌套发现重复或不支持的项目标记会在库存前报告。短项目名不构成身份;报告中的项目 ID 来自规范化路径。
每一个 old/new 对必须先在代表性的、关闭的、可丢弃完整项目副本上完成认证:记录替换前后完整快照,使用原生 Replace Part + `Library Wins`,检查第 6 节硬不变量,并运行 Packager、ERC 和网表检查。认证应由站点流程生成/保管 `certifications.json`,其证据必须绑定 old/new `Part Number`、中央库身份/版本或目标指纹。当前交付**没有**公开“创建认证”CLI;不要伪造 JSON 或把内部 Python API 当作生产步骤。无认证映射只能排除或交由站点认证负责人完成可丢弃试验。
创建评估作业:
```powershell
& "C:\DxProductivity\integration\dxdesigner795\Start-PartReplacement.ps1" `
-Mapping "D:\Qualification\replacement.csv" `
-Projects "D:\Qualification\projects.txt" `
-Certifications "D:\Qualification\certifications.json"
```
脚本在 `C:\DxProductivity\runs\part-replace-<GUID>` 创建新作业,把本次输入复制为不可变记录,然后立即进入显式操作循环。每轮只调用一次 `operator-step`:至多消费一个已关联的 bridge 结果,再至多发布一个后续命令。当前命令以 manifest v2 写到 `C:\DxProductivity\runs\current-part-replacement.json`;其 `current_project_id`、`current_action` 和 `current_command_id` 必须同时与唯一项目记录及 `command.json` 精确一致。不要编辑 manifest、mailbox 或事件文件来推进作业。
控制台每轮显示 `CurrentProject` 和 `CurrentAction`;有人工步骤时还显示 `ManualRoute` 和 `Instruction`。`operator-step` 对未完成动作返回退出码 `4`,这是启动器已处理的正常“等待操作员”状态,不是成功或失败。完成整批后,manifest 会被原子改写为 `complete=true`,三个 current 绑定均为 `null`。记录输出的 `job_id`、作业目录和输入哈希,并让该控制台保持运行直到完成或明确暂停。
在提示处输入 `Q` 会保留当前作业、命令和 manifest,并打印准确的暂停作业路径。恢复时只传该绝对作业目录;不要再次传 Mapping、Projects、Certifications 或 DiscoveryRoot,也不要重新创建作业:
```powershell
& "C:\DxProductivity\integration\dxdesigner795\Start-PartReplacement.ps1" `
-ResumeJob "C:\DxProductivity\runs\part-replace-<GUID>"
```
恢复入口只调用现有作业的只读 `status` 来重建项目 allowlist,然后复用同一个 `operator-step` 循环。它拒绝相对路径、部署 `runs` 以外或非直接子目录、reparse path、损坏/不匹配的 status、重复项目和相对项目路径。已经 `verified_saved` 的项目不会重跑;未完成的同一命令保持原 command ID。
## 4. 库存、影响审阅和项目队列
严格按控制台当前轮次操作,不要自行跳到另一个项目或动作:
1. 当 `CurrentAction=inventory` 时,打开 `CurrentProject` 指向的正确可丢弃副本,确认已保存且非脏,然后选择 `Dx Productivity` -> `Inventory current project`。
2. 其他所有 `CurrentAction` 均选择 `Dx Productivity` -> `Continue part replacement`。初始 `open_project` 要求当前没有活动项目;其他初始动作要求活动项目规范路径精确等于 `CurrentProject`。
3. 菜单返回后,在控制台按 Enter。启动器只消费与当前 project/action/command ID 完整关联的状态;若状态尚未完成,它会再次发布同一绑定而不会生成第二个命令。
4. 若下一轮显示 `ManualRoute`/`Instruction`,先按指令完成原生人工动作,再选择 `Continue part replacement` 让 bridge 验证结果,然后回到控制台按 Enter。人工打开的项目必须成为精确的当前项目;人工关闭后可以没有活动项目。
菜单运行时拒绝已完成 manifest、零个或多个当前项目记录、命令 schema 错误、陈旧 project/action/command ID、越出 `DXTOOLS_HOME` 的 bridge 路径以及错误的活动项目。出现拒绝时不要改 JSON 绕过;保留文件并调查当前绑定。
必须为**每一个**已启用项目完成库存,才能进入 Apply。库存包括逻辑元件和所有已放置单元、`Part Number`、`RefDes`、层级/图纸、符号、门/槽、原点/位置/旋转/镜像、属性、引脚号/名/位置/网络以及项目指纹。无法取得唯一逻辑身份或任何受保护状态/引脚/网络证据,即为阻断问题。
审阅作业目录的 `reports\impact.csv` 和静态 `reports\summary.html`:影响矩阵的每一格给出项目、旧/新 Part Number、逻辑元件数、放置单元数和问题。审阅无匹配、过时/缺失 `Part Number`、重复 `RefDes`、多单元、未验证数据和所有硬问题。只启用通过认证且影响可接受的映射;没有“继续忽略”选项。
库存阶段覆盖 `projects.txt` 中每一个启用项目后,控制器才会进入 Apply。若某个项目没有任何映射命中,它会通过明确的 `no_changes_required` 事件完成,不会伪造 Apply 或 Save。活动项目身份不精确匹配时,停止,不要在当前项目上尝试。
## 5. Apply:每个项目/映射对
在开始每个项目之前,操作循环发布 `close_project`。bridge 先证明完整快照等于可信库存并证明项目非脏,再自动关闭或要求 `manual_close_project`;只有相关的关闭证据返回后,控制器才把完整项目树复制到作业 `backups` 区并验证文件大小和内容哈希清单。随后循环发布 `open_project`,自动打开或要求 `manual_project_open`,并重新核验项目身份和库存指纹。若项目在库存后发生变化,它是 stale,必须重新库存、重新审阅影响,不能继续旧选择。
对每个有命中的已启用映射,工具应显示旧/新 `Part Number` 和 `expected_count`,并且只选择该映射的准确逻辑元件组。操作员必须在任何原生对话框中再次核对显示的目标 `Part Number` 与预期数量。
1. 在可用并经 probe 与现场证据验证的路线中,bridge 精确选择命令中的逻辑组,写入 `native_dialog_opening` 状态,然后打开原生 Replace Part 对话框;仍由操作员选择精确目标、`Library Wins` 并确认。bridge 使用已验证的完成观察路线,确认对话框动作完成后才导出快照。
2. 若精确选择路线未验证,状态为 `manual_exact_selection`。按 `Instruction` 只选择显示的完整逻辑组,再选择 `Continue part replacement`;bridge 会先复核选择集合,然后进入原生对话框路线或下一人工步骤。
3. 若原生对话框路线未验证,状态为 `manual_native_dialog`。保留精确选择,不要改选其他对象。手动执行 `Edit -> Replace Symbol`,选择 `Replace part`,在 DxDataBook 中找到显示的精确新 `Part Number`,选择 `Library Wins`,只对当前选择组确认一次。
4. 原生对话框关闭后,选择 `Dx Productivity` -> `Continue part replacement`。菜单只在先前状态与当前命令完整关联时继续 `continue_after_manual_dialog`,并导出新的完整快照;不要以等待窗口标题、固定延时或重复菜单点击取代该步骤。
每个项目/映射对只确认一次原生 Replace Part;不逐个元件确认。取消发生在已验证保存之前会让当前项目保持未保存,并将作业记录为中断。
## 6. 即时验证、失败和保存门
原生替换后,立即检查:新 `Part Number` 等于请求值;命中和替换的逻辑元件数准确;`RefDes`、层级、已放置单元、原点、位置、旋转、镜像、门/槽、引脚号集合、引脚坐标和每个 `RefDes + pin number` 的网络身份均未变化;并且没有无关逻辑元件变化。任何新增、删除、改名或重新连接的引脚均失败。库控制的符号、引脚名和属性可能按 `Library Wins` 变化,应在差异报告中审阅,但不得以此掩盖保护字段失败。
若选择了错误目标或任一硬不变量失败:立即停止该项目。操作循环会发布与失败 Apply 使用同一 command ID 的 `undo`;只在配置文件已验证的路线中执行一次原生 Undo,或按 `manual_native_undo` 指令手工 Undo 后再次选择 Continue。bridge 和控制器都要把恢复快照与替换前快照逐项比较。Undo 不可用或不能精确恢复时,循环发布 `close_without_save`(或 `manual_close_without_save`),再核对磁盘树仍匹配 Apply 前备份。不要在不确定的内存状态继续,也不要通过移动、重画导线或编辑属性来“修复”校验。
所有映射通过后,在项目差异摘要处审阅库控制和非阻断属性变化。操作循环发布 `save`;只有在该轮确认 `Save and continue` 才执行,自动路线不可用时按 `manual_native_save` 完成原生 Save 并再次选择 Continue。bridge 必须确认项目非脏并重新枚举,控制器再把持久化快照与已硬验证的内存快照比较。随后循环按固定顺序发布 `packager`、`erc`、`netlist`,每项都要求现场验收过的 API 路线返回明确成功、相关 bridge 快照完整且设计未变化;全部通过后项目才进入 `verified_saved`。这些外部检查的自动路线未经现场验收时,停止并保留同一作业及命令,先按现场清单取得证据并用 `promote-profile` 部署已验收配置,再恢复操作循环;人工布尔确认或“未运行”都不能作为通过证据。
## 7. 状态、恢复、报告和隔离
项目持久状态依次为 `inventory_pending`、`inventory_complete`、`apply_pending`、`applying`、`awaiting_save_confirmation`、`awaiting_external_checks`、`verified_saved` 或 `blocked`。事件日志是追加式记录,状态文件只是投影。`verified_saved` 不应重做;处在 `applying`、`awaiting_save_confirmation` 或未知状态的项目,在继续前必须重新库存,并相对备份进行 reconcile。一个 `blocked` 项目不阻止其他项目继续,但整批报告不得描述为完全成功。
可查看 `reports\impact.csv`、`reports\differences.json` 和 `reports\summary.html`。HTML 中的 `SUCCESS` 只表示所有项目都处于 `verified_saved`;有完成与阻断混合时为 `PARTIAL`,并非批次成功。`differences.json` 区分硬问题和非阻断属性差异。报告同时给出输入哈希、项目状态、认证身份/目标指纹、外部检查、备份路径、恢复动作以及 AI 建议附件。AI 附件仅供参考,不能覆盖状态或验证结论。
收到异常、损坏或陈旧 mailbox 证据时,运行存储会把不可信文件隔离到作业 `history` 下并写事件。隔离不是通过,也不是可手动删除的恢复信号;保留其路径和事件记录,交给操作负责人调查后再创建受控的新命令/重新库存。
规范要求的恢复前提为:目标项目已有相关 `close_without_save` 关闭证据;目标规范路径与作业记录精确匹配;备份清单验证通过。若关闭后的磁盘树仍匹配备份,控制器可以直接进入受约束的 reconcile;否则暂停启动器,由站点恢复负责人运行公开命令:
```powershell
& "C:\Python312\python.exe" -m dx_productivity --json restore `
"C:\DxProductivity\runs\part-replace-<GUID>" "<project_id>"
```
`restore` 会先把失败磁盘树完整保留到返回的 `recovery_path`,再复制已验证备份并复核结果;任何前提缺失都会拒绝。只有 `restore_verified`、`close_without_save_verified` 或精确 `undo_verified` 等相关恢复证据才能授权无参数 `reconcile JOB PROJECT_ID`,reconcile 随后仍要求重新打开和重新库存。不要从 Python 内部 API、资源管理器覆盖或临时脚本拼凑恢复,也不要删除备份、失败树或隔离证据。
恢复/调查命令完成后,用上面的 `-ResumeJob` 重新进入同一操作循环;不得用原 Mapping/Projects/Certifications 创建一个外观相似的新作业来代替恢复。
## 8. 现场证据与支持交接
每次试验附上:确切 DxDesigner build、Windows 版本、活动项目规范路径、中央库身份/指纹、route profile、映射、备份清单、前后/保存后快照、状态/事件文件、差异报告、外部检查输出、操作员和日期。自动化或 mock 测试只能证明回归覆盖,不能把 [现场验收清单](../testing/dxdesigner-795-part-replacement-live.md) 的项目标为通过。
在所有未勾选项目取得可追溯现场证据前,保持评估分类,继续只使用可丢弃副本。