Files
cbb-refresh-verify-795/docs/superpowers/specs/2026-09-20-bridge-execution-and-unc-design.md
T
阿白叔 11a2b2e46e Import CBB refresh verify r4 stability baseline
Preserve tested Verify source, authoritative READY checks, bounded bridge retries, diagnostics and failure-only reporting. Include 336-test suite and packaging assets; exclude live Mentor samples, field logs, backups and distributions.
2026-09-29 15:05:20 +08:00

11 KiB
Raw Blame History

CBB 桥接执行与 UNC 网络库设计

目标

把中心库状态读取、PCB 文档身份、Project Integration、保存关闭和最终 Verify 状态收敛到结构化桥接接口,消除固定窗口标题、图标、Cert 时间戳和跨进程独立超时造成的误判。同时支持直接选择 UNC 中心库,在不保存凭据、不覆盖用户盘符的前提下自动建立并释放临时网络盘符。

已确认接口

Library Manager 状态接口

  • LMCDLL70.dll::IsVerifiedReuseBlock(CStringT, eReuseBlockType, const CStringT&) 已在本机 x86/MFC ABI 桥中验证,可返回权威 READY/PENDING。
  • LMCDLL70.dll 同时导出 GetStatusRBInContextOfCL、VerifyReuseBlock 和 UnVerifyReuseBlock。
  • LibManagerDBPI.dll 导出 GetReusableCircuitVerificationStatus(const CStringT&, const CStringT&, int, int&)。
  • VerifyReuseBlock/UnVerifyReuseBlock 是私有写接口,本设计不调用。原始状态接口只允许在只读探针中验证参数语义,未通过已知样本一致性测试前不参与生产判定。

Expedition PCB 公开自动化接口

注册表和 Mentor 自带类型库确认:

  • MGCPCB.Application:CLSID {EDEDED02-D5F6-4B04-8FE7-EDEDEDEDED00},本地服务器为 XtremeDesignSessionWG.exe。
  • IMGCPCBApplication.ActiveDocument、Quit()。
  • IMGCPCBDocument.Name、FullName、ProjectIntegration、Validate()、Save()、IsSaved()、Close(Boolean)。
  • MGCPCBAutomationLicensing.Application.GetToken(Long)。
  • IMGCPCBProjectIntegration.ProjectFile。
  • ForwardAnnotationStatus、SynchCESStatus、LoadCESStatus、BackAnnotationStatus。
  • IsForwardAnnotationAllowed()、IsSynchCESAllowed()、IsLoadCESAllowed()、IsBackAnnotationAllowed()。
  • ForwardAnnotate()、SynchCES()、LoadCES()、BackAnnotate()。

ProjectIntegration.dll 中的 EPrjIntStatus 枚举值为:

  • 1: Required
  • 2: InSynch
  • 3: NoCES

因此执行桥不需要通过 GUI 打开 Setup/Project Integration,也不需要用窗口颜色判断进度。

架构

1. 中心库路径租约

新增 LibraryPathLease,为一次读取或 Verify 会话提供两个路径:

  • display_path: 用户选择的原始路径,仅用于 UI 和日志。
  • mentor_path: 传给 Mentor DLL、PCB 和中心库文件访问的稳定路径。

本地盘符路径直接使用。UNC 路径先检查是否已有指向同一共享根的用户映射;存在时复用但绝不释放。不存在时通过 Windows WNet API 从空闲高位盘符创建 CONNECT_TEMPORARY 映射,使用当前登录会话已有的 SMB 凭据,不接受也不保存账号密码。租约结束时只释放工具自己创建且仍指向同一共享根的映射。

映射、文件存在性、目录枚举和释放都必须记录原始 UNC、盘符路径、是否复用、Win32 错误码和耗时。网络不可达或映射失败返回 NETWORK_UNAVAILABLE,不能转换成空列表或全 PENDING。

2. 权威状态桥

保留 x86/MFC CbbStatusBridge32.exe --server,但每个请求必须回显:

  • request_id
  • block_name
  • display_lmc_file
  • mentor_lmc_file
  • path_kind
  • status
  • source
  • raw_status
  • elapsed_ms

Python 客户端必须核对 request_id、条目名和解析后库路径。缺字段、错序响应或路径不一致一律视为桥协议错误。

状态读取仍以经过验证的 IsVerifiedReuseBlock 为生产权威源。GetReusableCircuitVerificationStatus 作为隔离只读探针,通过已知 READY/PENDING 样本确认参数顺序和枚举语义;只有样本全部一致后才加入响应作为第二证据。两接口不一致时返回 STATUS_CONFLICT,UI 不允许勾选为已完成,也不自动 Verify。

3. PCB 启动与弹窗监督桥

现场失败证据表明,六个启动超时任务的最后一个共同事件都是 Select the desired product license,之后没有产生 identity_verified。现有实现向按钮异步投递 BM_CLICK 后立即把 (hwnd, texts) 放入 handled;它没有确认点击被应用接受或窗口已经关闭。若点击发生在弹窗尚未完成初始化时,窗口会继续存在,但后续轮询会永久跳过它。

弹窗监督必须改为显式状态机,并先于 PCB COM 执行桥:

  1. 在私有桌面枚举本次 Job Object 的完整进程树窗口,不只匹配最初的 PCB PID;许可、数据库和辅助进程创建的弹窗都纳入同一作用域。
  2. 记录窗口句柄、所属 PID、类名、标题、正文、全部按钮/列表/单选控件的 ID、enabled/checked/selected 状态。
  3. 对已知弹窗选择确定动作后,用有时限的按钮调用发起操作。
  4. 点击后必须等待窗口销毁、隐藏或内容进入下一已知状态,才能记录 dialog_resolved 并刷新活动超时。
  5. 弹窗仍存在时不得写入“已处理”缓存;按有限次数和退避间隔重试。达到上限后以 DIALOG_STUCK 结束当前项并保留控件现场。
  6. 同一窗口句柄被复用但正文变化时视为新状态,不沿用旧结论。

许可弹窗不能只根据存在一个 OK 按钮就判定成功。桥需要确认许可列表已有有效选择、OK 处于 enabled 状态,并在点击后确认弹窗消失。打开锁和 Database Restoration 同样必须确认选择状态及窗口消失。

窗口枚举回调必须显式返回 True。EnumWindows 或 EnumChildWindows 自身失败返回 WINDOW_ENUM_ERROR,不能伪装成等待超时。

4. PCB 执行桥

新增独立的 32 位 PCB 自动化桥。它与状态桥共享 JSONL 信封格式,但不把 Library Manager 私有 DLL 和 Expedition COM 放入同一进程。每个 CBB 使用独立桥进程,避免 Mentor COM 状态跨条目泄漏。

弹窗监督确认启动阻塞已清除后,执行桥按状态机运行:

  1. attach: 轮询 MGCPCB.Application,取得 ActiveDocument。
  2. identify: 同时核对 Document.Name/FullName 和 ProjectIntegration.ProjectFile 与请求中的 PCB/PRJ;任何一项不符都不得执行动作。
  3. integration_snapshot: 返回四项状态及四项 Allowed 标志。
  4. integration_step: 每次只执行一个 Required 且 Allowed 的动作,随后重新读取完整快照。状态变化才算活动。
  5. validate: 通过 Automation Licensing 获取 token 并调用 Document.Validate。
  6. save: 要求 Save() 返回真,随后 IsSaved() 返回真。
  7. post_save_snapshot: 四项必须仍为 InSynch。
  8. close: 调用 Close(True);仅在文档关闭后调用 Application.Quit()。

桥按事件输出 attached/identity/integration/action/validated/saved/closed/error,每条包含单调递增序号和 HRESULT。Python 不再直接持有 PCB COM 对象,也不再等待固定标题。

5. 弹窗与失败优先级

窗口监督由独立适配层运行,只枚举本次私有桌面和 Job Object 进程树,不接触用户前台窗口。

弹窗规则分为三类:

  • 可恢复:许可选择、打开锁确认、Database Restoration。处理后产生结构化活动事件。
  • 进度:Project Integration 正在运行,仅观察,不点击 Cancel。
  • 致命:Error saving the Reusable Block、数据库加载终止、无法运行设计服务器等。可以点击确认以便清理,但结果必须锁定为 FAIL,后续 Save/Close 标记不能覆盖。

不认识的弹窗不盲点默认按钮,记录标题、正文、控件 ID 后让当前项失败并继续队列。

6. 单一超时所有者

父进程是唯一的活动超时所有者。PCB 启动、已处理弹窗、桥状态变化、执行动作、保存标记和关闭事件都会刷新同一个 30 秒 inactivity deadline。重复的相同快照不刷新。

执行桥内部不再维护另一份 30 秒截止时间,只响应父进程终止;父进程超时时通过 Job Object 结束执行桥、PCB 和辅助进程。另设总时长上限,防止不断变化但永不完成的异常流程。

7. 网络库性能

删除每次读取时对整个 ReusableBlocksLP 的递归元数据指纹。桥读取 383 条实际只需数秒,跨次缓存带来的收益不足以抵消 UNC 全树扫描和陈旧状态风险。

每次用户点击“读取 CBB”都重新请求桥状态。检查点只用于同一次扫描被中断后的恢复,使用以下轻量快照:

  • 解析后的 LMC 路径
  • LMC 大小和最后修改时间
  • ReusableBlocksLP 顶层目录的最后修改时间
  • 本次已枚举的 CBB 名称集合摘要

目录枚举放到可终止的子进程,单次网络操作有硬超时。超时返回网络错误,不让 UI 工作线程无限等待。Verify 的证据备份继续采用三秒 best-effort,但网络路径默认只备份当前 CBB 的稳定小文件;备份失败不阻塞执行。

结果判定

一次 PASS 必须同时满足:

  1. 执行桥确认目标 PCB/PRJ 身份;
  2. 四项 Project Integration 为 InSynch;
  3. Validate、Save、IsSaved、Close(True) 均成功;
  4. 本次没有任何致命弹窗或新产生的 Project Integration 错误;
  5. PCB 退出后,状态桥重新读取该 CBB 为 READY。

Cert 文件存在或时间戳变化仅写入诊断日志,不单独构成 PASS。最终状态桥仍为 PENDING、发生桥冲突或桥不可用时,结果为 FAIL/UNAVAILABLE,不伪报成功。

故障隔离

  • 单个 CBB 的网络、桥、COM、Project Integration、保存或状态确认错误只影响当前项。
  • 每项结束都关闭执行桥并回收其 Job Object。
  • 状态桥崩溃时重启后处理下一项;连续启动失败时将剩余项标为环境不可用,避免重复等待。
  • 临时盘符租约贯穿整批任务,批次结束或异常退出时释放;释放失败写日志但不改写 Verify 结果。

测试与验收

  • TDD 覆盖临时映射创建、复用、冲突、释放和 UNC 超时。
  • 协议测试覆盖请求关联、错序响应、路径不一致、桥崩溃和状态冲突。
  • 弹窗状态机测试覆盖异步点击未生效、窗口未关闭不记成功、控件延迟初始化、句柄复用、子进程弹窗和有限重试。
  • 使用假 COM 对象验证四项状态机、身份不符拒绝执行、Fatal 弹窗优先于保存标记。
  • 回归测试证明 EnumWindows/EnumChildWindows 回调始终返回真。
  • 383 条 UNC 模拟库读取不递归访问 CBB 子目录。
  • 180/3000 条状态扫描保持单桥串行、单条失败隔离和可恢复。
  • 冻结包必须包含两个桥及其脚本/类型库依赖,并通过无窗口启动 smoke test。
  • 真实 Mentor 验收先用一个可恢复副本和一个 CBB;确认状态桥由 PENDING 变 READY 后,才允许生产中心库批量测试。

明确不做

  • 不调用 VerifyReuseBlock 或 UnVerifyReuseBlock 私有写接口。
  • 不依赖 TreeView 图标、颜色、右键菜单、鼠标、键盘或固定窗口标题。
  • 不并发修改同一个中心库。
  • 不保存网络凭据,不覆盖或删除用户已有映射。