130 lines
9.3 KiB
Markdown
130 lines
9.3 KiB
Markdown
# 最终外部验收执行手册（矩阵 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`。
|