Merge pull request 'feat(#92): [M5] UAT 计划与执行支撑' (#122) from feature/issue-92 into main

docs/README.md

@@ -6,6 +6,9 @@
 
 | 文档 | 说明 | 版本 |
 |------|------|------|
+| [用户手册.md](./用户手册.md) | **最终业务用户手册**（监控/优化/LLM 助手三类场景） | v1.0 |
+| [部署手册.md](./部署手册.md) | **运维/交付部署手册**（Helm 一键部署、后端切换、巡检、灰度回滚） | v1.0 |
+| [UAT计划与执行支撑.md](./UAT计划与执行支撑.md) | **M5 客户 UAT 计划**（用例集/准入准出/缺陷管理/排期） | v1.0 |
 | [产品设计文档_iAOP.md](./产品设计文档_iAOP.md) | **PRD 主文件**（开发依据） | v1.2 |
 | [产品设计文档_iAOP_对外评审.docx](./产品设计文档_iAOP_对外评审.docx) | 对外评审版（Word，含内嵌架构/流程/ER 图） | v1.2 |
 | [产品设计评审_iAOP.pptx](./产品设计评审_iAOP.pptx) | 内部评审/汇报版幻灯片 | v1.2 |

docs/UAT计划与执行支撑.md

@@ -0,0 +1,145 @@
+# iAOP UAT 计划与执行支撑（User Acceptance Test Plan）
+
+> 对应 issue #92「[M5] UAT 计划与执行支撑」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。
+> 配套 PRD §7.7 验收节点 / §9 NFR / §10 DoD / §2 角色画像与典型场景。
+> 本文档面向 **PM（bot_pm）+ 客户成功 + 客户方关键用户（王主任/李工/张工）**，是 M5 客户 UAT 阶段的执行手册。
+
+## 1. 目标与范围
+
+**目标**：在客户现场（或与客户一致的验收环境）由客户关键用户对 iAOP 平台 + Template-Ti 一期进行用户验收测试，确认满足 PRD §10 DoD 与合同验收口径，为生产上线放行。
+
+**范围（一期）**：
+
+- **内核（iAOP-Core）**：采集总线 / 模型框架 / LLM 网关 / 配置化驾驶舱 / 部署底座 / 模板配置台；
+- **首模板（Template-Ti 一期）**：①质量预测、③炉层杂质预警、LLM 报警解释 / 交接班报告 / NL 查询、驾驶舱 Ti 布局、移动端交接班摘要。
+
+**不在本期范围**：②配方优化 + ④跨工序寻优（二期，见 PRD §7.6）、商务结算、售后 SLA 条款签订。
+
+**验收流程六节点（PRD §10）**：自测（bot_dev）→ 内部评审（bot_pm+bot_po）→ **客户 UAT（本文档）** → 上线 → 1 个月质保观察 → 闭环。
+
+## 2. 角色与职责（RACI）
+
+| 角色 | 人员 | UAT 职责 |
+| --- | --- | --- |
+| UAT 负责人 | bot_pm | 排期、用例分发、缺陷分诊、协调、放行建议 |
+| 技术支撑 | bot_dev / bot_dev1 | 现场环境保障、缺陷修复、数据准备、日志取证 |
+| 质量仲裁 | bot_qa | 验收口径核对、回归验证、放行会签 |
+| 客户决策人 | 王主任（生产运行部主任） | 最终签收、上线决策 |
+| 客户执行人 | 李工（工艺工程师）、张工（值班长） | 执行用例、确认业务正确性、提缺陷 |
+| 客户 IT | 客户运维 | 网络/机房/DCS 配合、数据接入确认 |
+
+> **前置**：M1 即签订 UAT 排期与责任矩阵（PRD §11 风险「客户配合度」缓解措施）。
+
+## 3. 准入条件（Entry Criteria）
+
+UAT 启动前必须满足（由 bot_qa 核对）：
+
+- [ ] 内部自测 + 内部评审已通过（PRD §10 前两节点）；
+- [ ] 验收环境部署完成（见《部署手册》§3 一键部署），GPU/NPU 后端二选一就绪；
+- [ ] 客户 DCS 点位字典导入校验通过，采集达标（P99 ≤ 1.8s / 丢失率 ≤ 0.02%）；
+- [ ] 一期模型已训练并加载（质量预测 / 炉层杂质预警；标注不足时按阈值/无监督先行，PRD §11 风险缓解）；
+- [ ] RAG 知识库（工艺规范/SOP/国标）已导入；
+- [ ] UAT 测试账号、权限（RBAC）就绪；
+- [ ] 本 UAT 计划已与客户会签。
+
+## 4. UAT 测试用例集
+
+用例编号规则：`UAT-<场景>-<序号>`。每条用例含：步骤、预期、对应 DoD/NFR 条目、通过状态。
+
+### 4.1 场景 A：实时监控与告警处置（对应 PRD 场景A / DoD T-①③）
+
+| 编号 | 用例 | 步骤要点 | 预期（通过准则） | 依据 |
+| --- | --- | --- | --- | --- |
+| UAT-A-01 | 四状态流程视图渲染 | 打开驾驶舱 | Ti 四状态流程视图按布局正确渲染，绿/黄/红状态正确 | DoD T-驾驶舱、§5.5 |
+| UAT-A-02 | 实时趋势刷新 | 观察 `CLF-01.TEMP` 趋势 | 数据准实时刷新，首屏 ≤ 2s，交互 ≥ 30fps | NFR 性能 |
+| UAT-A-03 | 炉层杂质预警触发 | 制造/回放杂质超阈值工况 | 提前 ≥ 30 分钟告警，误报率 ≤ 8% | DoD T-③ |
+| UAT-A-04 | 告警 → LLM 报警解释 | 点击红色告警 | 展示原因+处置建议，附引用依据，可溯源 | §5.4、DoD T-LLM |
+| UAT-A-05 | 告警确认闭环 | 值班长确认/处置 | 告警面板状态正确流转（未确认→已确认→已处置） | 场景A |
+
+### 4.2 场景 B：质量预测与优化辅助（对应 PRD 场景B / DoD T-①）
+
+| 编号 | 用例 | 步骤要点 | 预期 | 依据 |
+| --- | --- | --- | --- | --- |
+| UAT-B-01 | 质量预测准确率 | 比对预测 vs LIMS 实测 | 准确率 ≥ 90%，误报率 ≤ 5% | DoD T-① |
+| UAT-B-02 | KPI 卡片展示 | 查看海绵钛纯度 KPI | 数值与趋势一致，更新及时 | §5.5 |
+| UAT-B-03 | （二期预留）配方建议 review | — | 一期不验收，仅确认入口存在 | §7.6 |
+
+### 4.3 场景 C：LLM 自然语言助手（对应 PRD 场景C / DoD T-LLM / NFR 安全）
+
+| 编号 | 用例 | 步骤要点 | 预期 | 依据 |
+| --- | --- | --- | --- | --- |
+| UAT-C-01 | NL 工艺查询 | 提问「最近一周 CLF-01 温度超标几次？」 | 返回数据 + 来源，路由准确 | §5.4、DoD T-NL查询 |
+| UAT-C-02 | 敏感度路由 | 提问含敏感工艺参数 | 敏感问题本地闭环，路由准确率 ≥ 96.5% | NFR 安全-数据 |
+| UAT-C-03 | DLP 防泄漏 | 尝试诱导输出敏感数据 | DLP 拦截率 100% | NFR 安全-数据 |
+| UAT-C-04 | 交接班报告生成 | 班次结束触发 | 自动汇总关键事件/能耗/待办，生成 ≤ 2 分钟 | DoD T-交接班 |
+| UAT-C-05 | RAG 答案溯源 | 提问国标要求 | 返回命中片段 + 来源引用 | §5.4 |
+| UAT-C-06 | 高利害输出人工确认 | 触发低信度处置建议 | 提示「需人工确认」，不直接联动执行机构 | NFR 功能安全 |
+
+### 4.4 非功能性用例（对应 PRD §9 NFR）
+
+| 编号 | 用例 | 预期 | 工具/方法 |
+| --- | --- | --- | --- |
+| UAT-N-01 | 采集性能 | P99 ≤ 1.8s，丢失率 ≤ 0.02% | 数据总线埋点 + 压测脚本 |
+| UAT-N-02 | 可用性 | ≥ 99.8% | `deploy/k8s/healthz/probe_availability.py` 连续探针 |
+| UAT-N-03 | 并发 | Web ≥ 50 / 移动端只读 ≥ 200 | 压测（tests/perf） |
+| UAT-N-04 | 后端可插拔 | GPU↔NPU 切换仅改 values | Helm `--set inference.backend` 切换演示 |
+| UAT-N-05 | 网络只读 | 边缘网关不反控 | `docs/采集网只读隔离与网闸配置.md` 验证清单 |
+| UAT-N-06 | 兼容性 | Chrome/Edge 最新两版；移动端 iOS14+/Android10+ | 多终端实测 |
+
+### 4.5 移动端用例
+
+| 编号 | 用例 | 预期 | 依据 |
+| --- | --- | --- | --- |
+| UAT-M-01 | 移动端只读查看 | 可查看驾驶舱/告警/报告 | DoD T-移动端 |
+| UAT-M-02 | 交接班摘要推送 | 班次报告推送至移动端 | 场景C |
+
+> 完整 DoD 勾选清单见关联 PR #（issue #90）的 `docs/DoD验收清单.md`；本文聚焦 UAT 执行层用例。
+
+## 5. 执行计划与排期
+
+UAT 阶段建议 1 周（PRD §11 M5 工期 4 周，含上线与质保；UAT 通常占其中 1 周）：
+
+| 天 | 活动 | 产出 | 负责 |
+| --- | --- | --- | --- |
+| D1 | Kickoff + 环境确认 + 准入核对 | 准入签字 | bot_pm |
+| D2 | 场景 A 用例执行 | 用例结果表 | 张工/李工 |
+| D3 | 场景 B + C 用例执行 | 用例结果表 | 李工 |
+| D4 | NFR + 移动端用例执行 | 性能/可用性报告 | bot_dev + 客户 IT |
+| D5 | 缺陷复测 + 放行评审 | UAT 验收报告、放行会签 | bot_pm + 王主任 |
+
+## 6. 缺陷管理（Bug Triage）
+
+- **严重度**：S1 阻断（核心功能不可用/数据错误）→ 当日修复；S2 严重（功能异常但有规避）→ UAT 内修复；S3 一般（体验/文案）→ 上线后修复；S4 建议 → backlog。
+- **通过准则**：S1=0、S2≤2 且有规避方案，方可放行；NFR 量化指标全部达标为硬门槛。
+- **记录**：缺陷统一登记在 Gitea issue（label=uat-bug），关联本 UAT 计划。
+
+## 7. 准出条件（Exit Criteria / 放行）
+
+UAT 通过、可进入上线，需同时满足：
+
+- [ ] §4 全部用例执行完毕，S1 缺陷为 0；
+- [ ] NFR 量化指标全部达标（P99≤1.8s / 丢失率≤0.02% / 可用性≥99.8% / 路由≥96.5% / 首屏≤2s / 准确率≥90% / 预警提前≥30min）；
+- [ ] 客户决策人（王主任）签字确认；
+- [ ] bot_pm + bot_qa 会签放行。
+
+**放行后**：进入「上线 → 1 个月质保观察 → 闭环」（见 issue #93 上线与质保观察跟踪）。
+
+## 8. 交付物清单（UAT 阶段）
+
+- [ ] 本 UAT 计划（已客户会签）；
+- [ ] 用例执行结果表（含每条用例通过/失败/截图/日志）；
+- [ ] NFR 性能与可用性报告（探针 + 压测输出）；
+- [ ] 缺陷登记与复测记录；
+- [ ] UAT 验收报告 + 放行会签单。
+
+## 9. 风险与缓解
+
+| 风险 | 触发 | 缓解 |
+| --- | --- | --- |
+| 客户关键人缺席 | M5 前 2 周未确认 UAT 时间 | M1 签排期责任矩阵；必要时按内部验收标准先行上线（PRD §11） |
+| 标注数据不足 | 监督模型准确率不达标 | ①③先以阈值/无监督上线，3 个月后转监督（PRD §11） |
+| 机房/网络环境不符 | 现场勘测不通过 | 提供云端演示环境；部署底座可移植（见《部署手册》） |
+
+---
+
+**维护**：本文档随 Template-Ti 一期功能开放节奏更新；二期（配方优化/跨工序寻优）UAT 用例在二期启动时补入 §4.2/4.3。

docs/_check_uat_plan.py

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+"""UAT 计划与执行支撑文档（docs/UAT计划与执行支撑.md，issue #92）一致性检查。
+
+检查项：
+1. 必备章节齐全（目标/角色/准入/用例集/执行计划/缺陷/准出/交付物/风险）；
+2. 验收流程六节点关键词存在（PRD §10：自测→内部评审→客户UAT→上线→质保观察→闭环）；
+3. NFR 量化指标齐全（PRD §9：P99≤1.8s / 丢失率≤0.02% / 可用性≥99.8% / 路由≥96.5% / 首屏≤2s）；
+4. 用例覆盖三类场景（监控A/优化B/LLM C）+ NFR + 移动端；
+5. 引用配套资产路径存在（部署手册/采集网隔离文档/healthz 探针）。
+
+用法：python _check_uat_plan.py
+"""
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DOC_PATH = os.path.join(HERE, "UAT计划与执行支撑.md")
+
+REQUIRED_SECTIONS = [
+    "## 1. 目标与范围",
+    "## 2. 角色与职责（RACI）",
+    "## 3. 准入条件（Entry Criteria）",
+    "## 4. UAT 测试用例集",
+    "## 5. 执行计划与排期",
+    "## 6. 缺陷管理（Bug Triage）",
+    "## 7. 准出条件（Exit Criteria / 放行）",
+    "## 8. 交付物清单（UAT 阶段）",
+    "## 9. 风险与缓解",
+]
+
+# PRD §10 验收流程六节点
+FLOW_KEYWORDS = ["自测", "内部评审", "客户 UAT", "上线", "质保观察", "闭环"]
+
+# PRD §9 NFR 量化底线
+NFR_KEYWORDS = ["1.8s", "0.02%", "99.8%", "96.5%", "2s"]
+
+# 用例场景覆盖（用例编号前缀）
+SCENARIO_PREFIXES = ["UAT-A-", "UAT-B-", "UAT-C-", "UAT-N-", "UAT-M-"]
+
+# 必须存在的配套资产路径（相对仓库根）
+# 注：部署手册（issue #91）随其 PR 合并后存在；本脚本校验本仓库主干已具备的资产。
+ASSET_PATHS = [
+    "docs/产品设计文档_iAOP.md",          # PRD（UAT 用例依据来源）
+    "docs/采集网只读隔离与网闸配置.md",    # UAT-N-05 网络只读验证依据
+    "deploy/k8s/healthz/probe_availability.py",  # UAT-N-02 可用性探针
+]
+
+
+def main() -> int:
+    failures = []
+    repo_root = os.path.dirname(HERE)
+
+    if not os.path.isfile(DOC_PATH):
+        print("FAIL\n - UAT 计划文档不存在：UAT计划与执行支撑.md")
+        return 1
+
+    text = open(DOC_PATH, "r", encoding="utf-8").read()
+
+    for sec in REQUIRED_SECTIONS:
+        if sec not in text:
+            failures.append(f"缺少必备章节：{sec}")
+
+    for kw in FLOW_KEYWORDS:
+        if kw not in text:
+            failures.append(f"缺少验收流程节点关键词：{kw}")
+
+    for kw in NFR_KEYWORDS:
+        if kw not in text:
+            failures.append(f"缺少 NFR 量化指标关键词：{kw}")
+
+    for prefix in SCENARIO_PREFIXES:
+        if prefix not in text:
+            failures.append(f"用例未覆盖场景前缀：{prefix}")
+
+    for rel in ASSET_PATHS:
+        if not os.path.isfile(os.path.join(repo_root, *rel.split("/"))):
+            failures.append(f"配套资产缺失：{rel}")
+
+    if failures:
+        print("FAIL")
+        for f in failures:
+            print(" -", f)
+        return 1
+    print("OK: UAT 计划章节/流程节点/NFR指标/场景覆盖/配套资产校验通过")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())