170 lines
18 KiB
Markdown
170 lines
18 KiB
Markdown
# 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) 的项目标为通过。
|
||
|
||
在所有未勾选项目取得可追溯现场证据前,保持评估分类,继续只使用可丢弃副本。
|