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

18 KiB
Raw Blame History

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。新版本不因本指南而获得支持。
  • 每次操作使用一个完整、可恢复的项目副本和该副本对应的中央库映射。先完成 现场验收清单。
  • 不要绕开拒绝条件。缺少项目身份、完整库存、精确选择、保护字段、引脚或网络证据时,必须停在 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 运行(参数名和路径必须准确):

& "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:

& "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。

使用发现功能时,生成的候选列表不自动加入作业:

& "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,且仅有这两个列名:

old_part_number,new_part_number
OLD-001,NEW-001
OLD-002,NEW-002

工具会去除前后空白、保留展示拼写、按大小写不敏感方式比较。它拒绝空值、重复旧值(包括只差大小写)、旧新相同、链式映射和循环映射。不要写元件名、符号名、属性、引脚或描述;替换目标的唯一键是中央库 Part Number。

projects.txt 是 UTF-8 文本,每行一个绝对项目定义路径,例如:

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 当作生产步骤。无认证映射只能排除或交由站点认证负责人完成可丢弃试验。

创建评估作业:

& "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,也不要重新创建作业:

& "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;否则暂停启动器,由站点恢复负责人运行公开命令:

& "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 测试只能证明回归覆盖,不能把 现场验收清单 的项目标为通过。

在所有未勾选项目取得可追溯现场证据前,保持评估分类,继续只使用可丢弃副本。