Files
dxdesigner-part-replacement/docs/user/bom-native-workflow.md
T

148 lines
13 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.
# BOM 导入、原生核验与网表比对(开发工作区)
2026-11-11 更新。本页描述当前源码中的新流程,旧发行 EXE 不会因同步源码自动更新。
## 使用流程
1. 在任务中心选择工程,导入一个或多个 BOM Excel。
2. 程序检查表格格式、工程归属及重复/冲突行,把有效清单保存到本机任务库。导入不打开 Designer、PCB,也不启动器件采集进程。
3. 位号计划区显示“待核验 BOM 清单”。清单在切换任务、关闭重开后保留;它还不是已经匹配真实器件的执行计划。未被本次 BOM 覆盖的已启用原计划会标为“原计划保留”,一起列入执行确认。需要修改请求时,修改 Excel 后重新导入;已有手动编辑须先保存或放弃。
4. 点击“核验并执行”,有未保存计划时先保存,再进入本次范围确认;不用保存后再次点击。按批执行时,轮到哪个工程才核验哪个工程;通过后生成包含真实位号和 UID 的位号计划。手动与 AI 使用相同的预检和执行回执,不再以 20 项划分两条执行路径。
5. 核验优先复用有效缓存,否则使用本机原生 CLI 读取已保存数据库副本。失败会显示具体原因并保留清单;不自动回退 CAD。批次继续处理其他工程。
6. 执行前捕获固定输入副本,后台导出 ASCII 分层/平铺属性和 Keyin 完整连接网表;实际替换继续使用现有工程备份及替换链。
7. 每个工程结束后立即固定新副本、后台导出,并比较实际器件属性、引脚和网络连接;问题重试保存后同样立即捕获。任务日志及执行回执记录独立比对状态和报告路径。完整导出在输入、工具和解析代码未变化时可在恢复时复用,成功工程不再进入空的问题轮次。
```mermaid
flowchart TD
A[导入 BOM] --> B[表格检查并持久化待核验清单]
B --> C[用户确认执行范围]
C --> D[逐工程进行原生 CLI 器件核验]
D -->|失败| E[保留清单与原因,处理其他工程]
D -->|通过| F[生成真实 UID 计划并捕获替换前副本]
F --> G[后台导出替换前连接图]
F --> H[按原有备份及替换流程执行]
H --> I[保存后捕获新副本并导出连接图]
G --> J[比较前后属性和连接]
I --> J
J --> K[任务日志、执行回执和独立比对报告]
```
## 状态与失败处理
“表格已保存”表示请求已经落地;“工程核验通过”表示请求已匹配真实器件;“独立网表比对通过”表示完整导出图满足本次明确声明的变化。程序分别显示这些结果。
工程采集失败不会再触发打开 CAD 的回退。清单仍可查看或重新导入。部分导入选项只保存整工程有效的请求,失败工程及原始 Excel 行号保留在报告中。
如果核验发现所有请求都已满足目标料号、Value 和 Cell,任务明确显示“无需替换,已跳过”;不启动替换,也不声称完成了替换或网表比对。仍需执行的原计划保留项不受此跳过影响。
新建批次中的多个工程共用一个受监督 CAD 会话。上一工程保存、关闭并确认完成后,直接在同一 CAD 中打开下一工程;整批完成或安全暂停后退出 CAD。发生异常时按原恢复规则处理,不能把未确认的工程状态带入下一工程。旧版按工程隔离的检查点仍按原路径恢复,不迁移或重放已保存的任务。
原生 CLI 使用隐藏进程和自有 Job 管理,不为读取创建私有桌面。实际 CAD 替换的资源及中断恢复机制继续生效;本次没有把未确认的写入结果当作可直接重放。
独立网表比对不会把“执行失败”或“未命中”显示为已完成替换。完整网表缺失、取消或不支持的结构会显示未完成,并保留原始报告;不会因生成了非空文件就宣称通过。它也不代表 ERC、PCB 同步或制造检查已通过。
独立网表发现差异或缺失时,最终运行回执标记验收未通过,同时保留实际“已保存”的执行条目;不能为了重做验收再次替换成功项。界面分别显示保存计数和独立网表结果,报告缺失也明确显示未完成。
未指定 Cell 不再读取 LibraryManager 封装关联;目标料号由实际原生替换链确认。明确指定 Cell 时才查询关联,所有工程任务共用同库同版本的有效缓存。只读历史查询不再禁用当前任务的执行确认。
失败收尾先保护执行证据,再尝试关闭确切归属本会话的工程并退出 Mentor。真实验证表明,Mentor 的“不保存关闭”仍可能持久化属性修改;因此资源释放不等于回滚,失败工程仍须核验。只有实际未派发或已证明未写入的可恢复失败才允许自动重试;模型建议不再额外否决已获授权、具有有效回执且仍有预算的确定安全操作。
## 完整执行与阻塞去向
```mermaid
flowchart TD
A[主程序或 Agent 建立任务,任务中心刷新] --> B[导入 BOM 或编辑计划]
B --> C[保存本次范围内的编辑并重新读取任务]
C --> D{配置、工程和既有资源状态允许执行?}
D -->|否| D1[显示具体原因,等待修改或资源收尾]
D1 --> C
D -->|是| E[一次确认范围和 Value 策略,记录执行轮次]
E --> F[轮到当前工程:CLI 核验请求,生成 UID 计划]
F -->|读取或输入失败| F1[保留 BOM 行号和原因,继续其他工程]
F -->|全部已满足| F2[标记无需替换,继续其他工程]
F -->|仍需替换| G[原始工程备份,固定前副本并异步导出网表]
G --> H[取得本批 CAD 会话,打开当前工程]
H --> I[按 UID 替换、还原声明属性、保存、重开回读]
I --> J{执行结果是否确定?}
J -->|已保存并回读通过| K[提交成功回执,立即固定后副本]
J -->|有证据证明未写入| L[记录失败,按共同判定继续独立项]
J -->|可能写入或保存尚未核验| M[保护未知结果,暂停后续写入]
H -->|打开或控制失败| J
H -->|尚未连接工程且已认证启动暂停| P
K --> N{还有工程且未请求暂停?}
L --> N
F1 --> N
F2 --> N
N -->|是| F
N -->|否,且允许问题轮次| O[只重试具备有效证据且共享预算未用完的问题项]
N -->|已暂停| P[保存检查点,不新增写入]
O -->|完成或仍有确定失败| Q[关闭工程,退出本批 Mentor,协调桌面释放]
O -->|未知或暂停| P
M --> P
P --> Q
Q --> R[汇总业务结果、独立网表验收及资源状态]
R --> S{是否仍有未解决问题?}
S -->|是且自动介入可用| T[确定安全重试先行;其余只读诊断或受限资源处理]
S -->|否| U[结束本轮]
T --> V[保留实际动作和证据;缺输入或未知写入等待核验]
V -->|明确恢复或重试并重新确认| C
```
Harness 的开始执行、恢复执行和手动运行排期使用相同的长任务结果等待(当前上限 24 小时),不会因恢复入口的旧 5 分钟超时而丢失正在执行的结果。暂停请求和只读查询仍使用各自的短等待;取消对话只结束对话等待,已确认执行需要单独请求安全暂停。
成功项始终保留。独立网表验收失败只能补验或处理差异,不能因此重新换料。用户暂停后,未处理的问题项也属于待恢复工作;不会因为主轮次最后一项已返回就自动取消暂停意图。手动准备重试和自动问题轮次共享同一原始失败项的自动预算,重新授权不会额外赠送一次自动重放。
启动阶段尚未连接工程时,只有绑定当前会话、任务及执行项的真实未派发回执,加上进程退出、工程未改和空工程检查点,才能将该项退回待执行;不会记作失败或额外消耗问题重试预算。暂停证明持久保存,临时派发标记被占用或收尾中断后也可接续处理。恢复仍使用原队列、原替换前基准及原授权范围,已保存项不重放。缺少这些证据时仍保留未知状态,不能仅凭进程退出断言未写入。
## Mentor 与桌面的释放顺序
```mermaid
flowchart TD
A[批次结束、安全暂停或 mentor_release_required] --> B[保存执行回执;失败时先保护未知结果]
B --> C[关闭确切自有工程,尝试正常 Quit,监督弹窗]
C --> D{自有 Mentor 和相关进程是否退出?}
D -->|未退出且退出预算耗尽| E[按既有失败回收路径终止确切自有进程树]
E --> E1{是否确认相关进程全部退出?}
E1 -->|是| G
E1 -->|否| F
D -->|未能确认| F[保留进程所有权及释放失败状态,桌面等待]
D -->|已确认| G[关闭自有桌面句柄]
G --> G1{桌面对象是否消失?}
G1 -->|是| H[资源已释放;保留原业务与验收结果]
G1 -->|外部引用仍在| I[等待引用退出,后续只观察对象是否消失]
I --> G1
G -->|原生句柄关闭失败| J[记录失败,显式重试资源释放]
```
两个释放作业分别记录状态,但桌面释放依赖相关进程退出证明。普通资源复查不会重复 Quit 或重复关闭已经关闭的桌面句柄;外部引用消失后可以自然确认释放。失败收尾也不按进程名称清理用户的其他 Mentor 会话。释放后若业务结果仍未知,仍须通过“核验并恢复”处理,不能把资源状态直接当作换料成功。
## 报告位置与比较范围
每个执行轮次的报告位于任务数据目录:
```text
tasks/<任务编号>/netlist-checks/<执行队列编号>/
before/ 固定的替换前输入及捕获记录
before-export/ 替换前原生导出和完整图
plan.json 本次计划及逐项 Value 策略
after-<编号>/ 保存后的输入及捕获记录
after-export-<编号>/ 保存后的原生导出和完整图
verification.json 独立比较结果、差异和执行计数
```
暂停续跑保留首次捕获的替换前副本;不会用部分替换后的工程重新建立“替换前”基准。BOM 请求展开为实际 UID 时保留原确认身份,之后实际修改计划仍需要重新确认。
比较允许所选器件按计划改变 Part Number、Value 及明确指定的 Cell Name;Part Name、Part Label 和目标符号的预期值取自已提交替换回执内绑定的实际库件记录,不从变化后的结果反向猜测。所选器件的连接按物理脚号比较,正常的逻辑引脚改名不会被当作断线;未选中器件仍逐项比较。未声明的属性、器件身份或物理连接变化会列为差异,报告不依赖原始文本行顺序。
Value 的“保留”沿用现有执行含义:保留原生替换后得到的值,可能来自目标库件,不能在执行前承诺等于旧值。比对从绑定当前工程、UID 和料号的持久化回读凭据取得实际保留值;自定义、料号和标签模式按各自明确的预期核对。ASCII 中的空串只证明序列化为空,不能单独证明 Value 属性存在,属性存在性另记于执行回读凭据。
原生工具的 Keyin 料号表在真实替换保存后可能仍保留旧料号;程序保存该原始表并记录诊断差异,实际料号以 effective ASCII 为准。两份导出的位号覆盖及物理连接仍须一致,不能用旧料号表覆盖实际属性,也不能跳过连接检查。
完整连接图已支持层级实例路径、重复实例、多 gate 物理脚覆盖及无独立 UID 的标注;通过完整原始 PON 工程的层级/平铺/Keyin 三份原生导出对照。工程层级按实际子块展开验证覆盖,标注及重复用户属性保留完整多重集合,不伪造器件 UID。
写入定位仍只接受能够唯一绑定的根图页器件;子实例、重复 UID、共享位号及不明确的属性归属不会被当作可直接替换目标。实际 PON 已验证一级重复子实例;更深层级目前有解析测试,尚无实机样本,复杂工程实际换料也须单独验收。这些情况不触发 CAD 查询回退。完整记录见 [复杂工程原生网表验收](../testing/2026-11-11-complex-native-netlist.md)。
## 大批量导入
工程匹配先为当前批次建立路径索引,不再对每一行重新解析全部工程路径。开发验收中,400 个模拟工程的纯表格导入由约 100 秒降到约 4–9 秒,期间没有原生采集进程;这不是 400 个真实数据库的采集耗时。