diff --git a/docs/README.md b/docs/README.md index 1693136..711003f 100644 --- a/docs/README.md +++ b/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 | diff --git a/docs/UAT计划与执行支撑.md b/docs/UAT计划与执行支撑.md new file mode 100644 index 0000000..9437ecb --- /dev/null +++ b/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。 diff --git a/docs/_check_uat_plan.py b/docs/_check_uat_plan.py new file mode 100644 index 0000000..e94e7e7 --- /dev/null +++ b/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())