Industry
/
aps-agent
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
aps-agent/docs/product/external-acceptance.md

9.3 KiB
Raw Permalink Blame History

最终外部验收执行手册（矩阵 10 个 Partial 及关联生产环境验收）

目的：固化 10 个 Partial 及关联生产环境能力的最终外部验收步骤、前置条件、验收标准与代码锚点。 round-62 口径：最终验收仍依赖真实外部系统、设备或凭据，但仍存在可本地推进的适配、持久化和发布门禁缺口；资源未到位不等于本地工作必须停止。 状态保持 50 Done / 10 Partial / 0 Missing，不得因 Mock、首切片或本地取证虚假标记 Done。本文初版编写于 round-49，round-62 完成基线和引用收口。 为避免 Markdown 物理行号持续漂移，以下统一按矩阵需求名称引用，不再使用数字行号。

1. 真实 MES 对接（矩阵「真实 MES MCP 下发、状态和报工回流」/「MCP 插件管理与权限面板」）

前置：工厂 MES 提供 base URL、token、端点文档；MES_HTTP_* 环境变量可配（见 docs/integrations/mes-http.md）。

步骤：

  1. 配置 MES_HTTP_BASE_URL / MES_HTTP_TOKEN（+ 可选超时/重试 env）。
  2. GET /api/integrations/mes/readiness 确认 configured=true → POST .../probe 确认 connectivity=ok。
  3. 对齐端点路径/报文（适配器默认 /work-orders、/work-orders/{id}/reports、/work-orders/{id}/cancel；现场差异改 mes_http.py 内路径常量）。
  4. 验收：dispatch 幂等（重复 idemKey 不重复创建）→ 报工回执 → 状态轮询 → 撤单（saga 补偿）→ 断连/超时/5xx 显式失败。
  5. 测试：tests/golden/test_mes_http.py（stub 已覆盖协议语义，现场跑同用例集）。

验收标准：readiness ok；鉴权/幂等/超时/重试/回执/补偿全部通过真实系统；MCP 工具 mes.http_* 在权限放行后可调。

2. 真实 WMS 缺料对接（关联矩阵「真实 WMS 缺料/库存事件接入」的生产验收与 MCP 插件 Partial）

前置：WMS 缺料/库存事件端点。

步骤：按 server/integrations/wms_stub.py 的 MockWmsClient 契约实现/适配真实客户端（事件结构：eventId/seq/materialCode/oldStock/newStock/shortageQty）；接入 wms_events.py 消费管线（幂等去重已内置）。

验收标准：事件可重放；重复/乱序不重复触发；库存版本进证据链；缺料→重排→确认→MES 下发→回执全链通过（test_wms_events.py 全链用例为验收剧本）。

3. 干净离线机安装（矩阵「自包含 Python Sidecar、守护、随机端口和离线运行」/「黄金测试是发布门禁」）

前置：无 Python/无网络 Win10/11 x64 验证机。

步骤：

  1. scripts/offline-install-check.mjs 生成/校验安装包 SHA-256 清单；U 盘介质携带安装包+sidecar 产物。
  2. 验证机执行 NSIS 安装（scripts/nsis-install-smoke.mjs --run-uninstaller 已覆盖临时目录真装；用户落点安装按其 /D= 约定）。
  3. 验收项：20 次冷启动、端口冲突、崩溃重启、中文/空格路径（scripts/smoke-sidecar-local.mjs）、升级失败自动回滚（updater.cjs）、Defender 实时防护（下）。

验收标准：离线安装成功、冷启动/守护/回滚全部通过；perMachine（HKLM）路径与快捷方式行为符合预期。

4. Defender 实时防护演练 + Endpoint 门禁（矩阵「自包含 Python Sidecar」/「黄金测试是发布门禁」）

前置：受控 EICAR 样本 + Defender for Endpoint 门户/API 权限。

步骤：

  1. scripts/defender-scan.mjs 已做静态扫描（4/4 clean）；实时防护演练用受控样本验证拦截与隔离。
  2. 在 CI（或 Defender for Endpoint API）把扫描纳入门禁（workflow 已有 best-effort 步骤，正式化需门户凭据）。

验收标准：产物无威胁告警；实时拦截/隔离演练通过；CI 门禁生效。

5. 真实 ASR/VLM/OCR 接入（矩阵「语音、图片、文件多模态与低置信确认」）

前置：外部模型服务（HTTP/进程内）。

步骤：实现 Extractor 协议并经 ExtractorRegistry.register(replace=True) 覆盖 image_meta/新增 kind（契约见 multimodal.py 头注释）；attachments 批次域表写入语义接线（确认后入库）。

验收标准：test_multimodal_image.py 的 stub→VLM 行为切换用例在真实服务下通过；低置信确认门禁不变；不编造语义保持。

6. 信创四组合实机验收（矩阵「国产化/信创多架构交付」）

前置：麒麟 V10 / 统信 UOS × x86-64/ARM64 四台验证机（或同架构容器）。

步骤：

  1. scripts/platform-deps-check.py 在各机通过（依赖 wheel 覆盖见 docs/architecture/platform-matrix.md）。
  2. 安装 Sidecar/桌面端；跑黄金算例基线（test_cp_engine.py/test_nsga2_engine.py 大算例时限）。

验收标准：四组合安装成功；求解性能满足黄金时限；离线依赖（内网 pip 源/离线 wheel）可用；安全软件兼容。

7. 代码签名 / SBOM 上链（矩阵「CI/CD、构建矩阵、签名、SBOM、漏洞扫描和离线升级」/「黄金测试是发布门禁」）

前置：Authenticode 证书 + 时间戳服务；SBOM 存证端点/链。

步骤：packaging/upgrade-manifest.* 已预留 signature/provenance 字段——用证书签名安装包并填充；npm run sbom 生成 CycloneDX 后上链存证。

验收标准：签名产物可验证、时间戳有效；SBOM 随发布存证可溯源。

8. 真实 GitHub CI 跑通（矩阵「CI/CD、构建矩阵、签名、SBOM、漏洞扫描和离线升级」/「黄金测试是发布门禁」）

前置：代码推送授权 + GitHub 仓库。

步骤：push 后 .github/workflows/ci.yml（6 job）自动执行；Windows runner 上 pwsh 语法/glob 以实际结果为准修正。

验收标准：lint/frontend-build/backend-tests/e2e/sbom/node-tests 六 job 全绿。

9. WORM 物理介质 / HSM-KMS（矩阵「全审计」/「P3 外部副作用二次确认」/「审计 append-only」）

前置：光盘/WORM 盘；HSM/KMS 密钥设施。

步骤：audit_ledger.py 归档密封（manifest+只读+加密）落盘到物理介质；verify_archive 在介质上复核；密钥改由 KMS/HSM 提供（APS_AUDIT_ENCRYPT_KEY_FILE 派生已就绪）。

验收标准：介质不可覆写；篡改检出在介质环境有效；密钥轮换/托管符合安全要求。

10. MySQL 多主机实机（矩阵「P3 外部副作用二次确认」）

前置：MySQL 主从/多主机 + 网络故障注入环境。

步骤：APS_DATABASE_URL 指向 MySQL；test_approval_database_store.py（CAS/竞态/失败关闭）在实机复跑；断连/死锁故障注入验证。

验收标准：SQLite 已验证的契约在 MySQL 实机全绿；断连/死锁不产生不一致，失败关闭生效。

执行顺序建议（资源就绪时）

  1. 先完成可本地推进缺口并冻结发布基线。round-62 取证快照为 git status --porcelain 274 项，已覆盖 round-52~62；未提交工作区不等同已发布版本。
  2. 先收紧本地 CI/产物门禁，再执行 8（真实 GitHub CI），使后续外部验收有持续回归保障。
  3. 并行推进 1/2（真实 MES/WMS）与 5（ASR/VLM/OCR）；本地适配器、持久化和契约测试不必等待现场资源。
  4. 依次完成 3/4/6/7/9/10（离线机/Defender/信创/签名/WORM/MySQL）的最终外部验收。

11. 资源清单收集表（可先行准备，资源到位即可按单执行）

下表每行为一项外部资源的「需要什么」与「找谁要」；建议现在就收集，避免验收时再等待。

# 验收项 需要准备的资源 具体字段 / 获取方式
1 真实 MES 工厂 MES 接口 base URL（HTTPS）、token、端点文档（下单/报工/撤单/状态）、现场对接人
2 真实 WMS WMS 缺料/库存事件接口 事件端点 URL、凭据、事件字段样例（eventId/seq/materialCode/stock/shortageQty）
3 干净离线机 无 Python/无网 Win10/11 x64 验证机 系统镜像/版本、U 盘介质、管理员权限
4 Defender 演练 受控 EICAR 样本 + DfE 门户 门户账号/API 凭据、放行演练环境声明
5 ASR/VLM/OCR 外部模型服务 HTTP 服务 URL、API key、支持的文件类型/语言、模型名
6 信创四组合 麒麟 V10 / 统信 UOS × x86-64/ARM64 4 台实机（或同架构容器）、内网 pip 源/离线 wheel、安全软件清单
7 代码签名 Authenticode 证书 + 时间戳服务 .pfx/.cer 证书文件、证书口令、时间戳服务器 URL（如 http://timestamp.digicert.com）
8 GitHub CI 代码推送授权 + 仓库 仓库地址、main 分支权限、runner 类型（windows-latest）
9 WORM/HSM-KMS 物理介质 + 密钥设施 光盘/WORM 盘数量、HSM/KMS 访问凭据、密钥轮换策略联系人
10 MySQL 多主机 MySQL 主从/多主机 连接 DSN（用户/密码/主机/端口/库名）、网络故障注入环境、DBA 联系人

建议并行推进：本地先收紧 CI/适配器/持久化门禁；8（真实 GitHub CI）在授权推送后执行；1/2/5 找工厂 IT 要接口；3/4/6/7/9/10 分别找 IT/安全/发布/存储负责人收集资源。最终外部验收完成后再回写 plan-completion-matrix.md 对应需求状态；仅完成本地缺口不得直接标记 Done。