From 76f921f994566f11243dd857e8d2c2f06ad3d189 Mon Sep 17 00:00:00 2001 From: bot_dev1 Date: Wed, 5 Aug 2026 02:34:00 +0800 Subject: [PATCH] =?UTF-8?q?feat(#90):=20DoD=20=E9=AA=8C=E6=94=B6=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E9=80=90=E6=9D=A1=E6=A0=B8=E5=AF=B9=EF=BC=88=E5=86=85?= =?UTF-8?q?=E6=A0=B8/=E9=A6=96=E6=A8=A1=E6=9D=BF/NFR/=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E8=8A=82=E7=82=B9+=E7=A8=8B=E5=BA=8F=E5=8C=96=E6=A0=B8?= =?UTF-8?q?=E5=AF=B9=E8=84=9A=E6=9C=AC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/DoD验收清单.md：把 PRD §9 NFR + §10 DoD + §7.7 交付物清单拆成勾选式清单 · iAOP-Core 6 模块 28 项（C-01~C-28）+ 首模板 8 项（T-01~T-08） · NFR 量化底线核对表（P99≤1.8s/丢失率≤0.02%/可用性≥99.8%/路由≥96.5%/首屏≤2s 等） · 验收流程六节点（自测→内部评审→客户UAT→上线→质保观察→闭环） · 风险登记（标注数据不足/UAT 配合度/机房环境）与四态状态口径 - docs/_check_dod.py：程序化核对必备章节/量化指标/状态口径/流程节点/证据路径 - 验证：6 个 docs 校验脚本全部通过（含新增 _check_dod.py），无回归 --- docs/DoD验收清单.md | 155 ++++++++++++++++++++++++++++++++++++++++++++ docs/_check_dod.py | 123 +++++++++++++++++++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 docs/DoD验收清单.md create mode 100644 docs/_check_dod.py diff --git a/docs/DoD验收清单.md b/docs/DoD验收清单.md new file mode 100644 index 0000000..662f925 --- /dev/null +++ b/docs/DoD验收清单.md @@ -0,0 +1,155 @@ +# DoD 验收清单（Definition of Done Checklist） + +> 关联工单：[#90 [M5] DoD 验收清单逐条核对](http://git.xayunmei.com/bot_ym/iAOP/issues/90) +> 父 Issue：[#15 [M5] 文档与验收（DoD 核查 + UAT 支撑）](http://git.xayunmei.com/bot_ym/iAOP/issues/15) +> 里程碑：iAOP v1.0 · Template-Ti 一期 +> 验收依据：《产品设计文档_iAOP.md》§9 NFR 指标 + §10 验收标准（Definition of Done） + +## 1. 目的与用法 + +本文档把《产品设计文档_iAOP.md》§9（非功能性需求 NFR）、§10（验收标准 Definition of Done） +及 §7.7（一期交付物清单与验收节点）中**可量化、可核对**的验收项，逐条拆成**勾选式清单**， +供 M4 内部集成测试 → M5 客户 UAT → 上线 → 1 个月质保观察 闭环逐条核对。 + +**状态口径**： + +| 状态 | 含义 | +|------|------| +| ☐ 未开始 | 模块/功能尚未达到可验收状态 | +| ◐ 待验证 | 已实现，待 M4 集成测试 / NFR 压测 / 客户 UAT 验证 | +| ✅ 通过 | 已按指标实测达标，附验证证据（脚本输出 / 截图 / 报告） | +| ⛔ 阻塞 | 因依赖（标注数据 / 客户配合 / 环境）暂不达标，已登记风险 | + +**核对流程**（对齐 PRD §10 验收流程）： +自测（bot_dev）→ 内部评审（bot_pm + bot_po）→ 客户 UAT（王主任 / 李工确认）→ 上线 → 1 个月质保观察期 → 闭环。 + +--- + +## 2. iAOP-Core 内核验收（§10 内核 + §9 NFR） + +### 2.1 ① 边缘采集网关（edge-gateway） + +| 编号 | 验收项 | 目标指标（首厂验收口径） | 状态 | 验证证据 | +|------|--------|--------------------------|------|----------| +| C-01 | 600 点位 1Hz 采集 P99 延迟 | P99 ≤ 1.8s | ◐ | core/data-bus/scripts/bench_write.py 压测输出 | +| C-02 | 断点续传丢失率 | ≤ 0.02% | ◐ | core/edge-gateway/scripts/verify_resilience.py | +| C-03 | 采集网只读隔离 | 零控制指令下发 | ◐ | docs/采集网只读隔离与网闸配置.md | +| C-04 | 采集配置外置（点位/采样率/协议参数化） | 去硬编码，换点位只改 CSV | ◐ | core/edge-gateway/config/point_dict.example.csv | +| C-05 | DCS 点位字典导入校验 | 校验通过、表头与内核 schema 一致 | ◐ | docs/_check_dcs_template.py | +| C-06 | LIMS 质检接口字段对齐 | 字段清单覆盖关键质检项 | ◐ | docs/LIMS质检接口字段清单.md | + +### 2.2 ② 数据总线（data-bus） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-07 | 批量写入吞吐 | P99 ≤ 1.8s（与 C-01 同口径） | ◐ | batch_writer.py + bench_write.py | +| C-08 | Kafka topic 命名/分区模板化 | 按模板+点位维度，去硬编码 | ◐ | core/data-bus/kafka_naming.py | +| C-09 | PostgreSQL 关系表 schema | 模板/模型/用户/权限齐备 | ◐ | postgres_schema.py | +| C-10 | 数据保留/归档/降采样策略 | 可配置，与 TDengine schema 对齐 | ◐ | retention_policy.py | +| C-11 | TDengine 时序 schema | 模板化、降采样配置化 | ◐ | tdengine_schema.py | + +### 2.3 ③ AI 模型框架（model-framework，RISK 配置化重构） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-12 | 模型框架配置化重构 | 切换行业模板零改码 | ◐ | core/model-framework（feature/issue-5..42 分支） | +| C-13 | 同一框架切换行业模板运行新模型 | 仅改配置即可 | ◐ | feature/issue-42 端到端 PoC | +| C-14 | 新增行业不新增模型代码 | 配置资产驱动 | ◐ | Model Recipe / FeatureSpec 机制 | + +### 2.4 ④ LLM 网关（llm-gateway） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-15 | 敏感度路由准确率 | ≥ 96.5% | ◐ | core/llm-gateway/router.py + 路由准确率评估脚本 | +| C-16 | DLP 拦截率 | 100% | ◐ | dlp.py + test_dlp.py | +| C-17 | 本地首 token 延迟 | ≤ 1.5s | ◐ | local70b.template.yaml（OpenAI 兼容 vLLM） | +| C-18 | 数据不出厂 | 敏感/核心内容走本地后端 | ◐ | backends.py Local70BBackend | + +### 2.5 ⑤ 配置化驾驶舱（cockpit） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-19 | 切换行业模板后驾驶舱自动重排 | 无需改前端代码 | ◐ | core/cockpit（布局 JSON Schema + RenderPlan） | +| C-20 | 首屏性能 | ≤ 2s，图表懒加载 | ◐ | perf 压测（feature/issue-54） | +| C-21 | 组件数 ≥ 30 性能策略 | 虚拟滚动/采样降频/WebWorker | ◐ | renderer.py 性能策略 | + +### 2.6 ⑥ 一键部署 / 推理后端 + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-22 | 一键 Helm 部署 | 内核 + 模板一键部署 | ◐ | deploy/k8s/helm/iaop | +| C-23 | 昇腾 NPU 后端切换 | 仅适配层，不改业务代码 | ◐ | core/inference-backend/npu_backend.py | +| C-24 | 可用性 | ≥ 99.8% | ◐ | 可用性监控探针（feature/issue-61） | +| C-25 | 回滚机制 | 一键部署脚本支持回滚 | ◐ | feature/issue-60 | + +### 2.7 ⑤.7 模板配置台（Template Console） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| C-26 | 配置台可用 | 新人 2–4 周完成新行业模板 | ◐ | feature/issue-9 / 62–67 | +| C-27 | 三级 RBAC 权限 | 平台 / 行业 / 运营 分权 | ◐ | feature/issue-62 | +| C-28 | "完成"定义达标 | 生产环境上线 Meta，非仅 Demo | ☐ | 待 M3 首模板上线后核对 | + +--- + +## 3. iAOP-Template-Ti 一期首模板验收（§10 首模板） + +| 编号 | 验收项 | 目标指标 | 状态 | 验证证据 | +|------|--------|----------|------|----------| +| T-01 | ① 质量预测上线 | 准确率 ≥ 90%，误报率 ≤ 5% | ☐ | 待标注数据 ≥ 6 个月（LIMS 对接后补标） | +| T-02 | ③ 炉层杂质预警上线 | 提前 ≥ 30 分钟，误报率 ≤ 8% | ◐ | templates/ti-cl4/impurity-forecast（阈值+无监督先行，feature/issue-70~72） | +| T-03 | LLM 报警解释 | 可用，路由准确率 ≥ 96.5% | ◐ | core/llm-gateway（同 C-15） | +| T-04 | 交接班报告生成 | ≤ 2 分钟 | ◐ | feature/issue-75 | +| T-05 | NL 查询 | 可用 | ◐ | feature/issue-76 | +| T-06 | 驾驶舱按 Ti 布局渲染 | 四状态流程视图 | ◐ | feature/issue-55 | +| T-07 | 移动端交接班摘要 | 可用 | ◐ | feature/issue-53 | +| T-08 | 客户 DCS 点位字典导入 | 校验通过 + 采集达标 | ◐ | 同 C-04/C-05/C-01 | + +--- + +## 4. NFR 量化底线核对表（§9） + +> 所有指标均来自已交付化工 AI 平台的真实基线或工业现场通用要求，作为验收测试输入。 + +| 维度 | 指标 | 底线 | 验收归类 | 状态 | +|------|------|------|----------|------| +| 性能-采集 | 采集 P99 延迟 | ≤ 1.8s（600 点位 1Hz） | C-01 | ◐ | +| 性能-前端 | 驾驶舱首屏 | ≤ 2s | C-20 | ◐ | +| 性能-LLM | 本地首 token | ≤ 1.5s | C-17 | ◐ | +| 性能-LLM | 交接班报告生成 | ≤ 2 分钟 | T-04 | ◐ | +| 可靠性-采集 | 丢失率 | ≤ 0.02% | C-02 | ◐ | +| 可靠性-平台 | 可用性 | ≥ 99.8% | C-24 | ◐ | +| 安全-网络 | 边缘网关只读、不反控；mTLS；等保 2.0 三级路线 | 安全合规验收 | C-03 | ◐ | +| 安全-数据 | 路由 96.5%、DLP 100%；敏感数据本地闭环；审计日志全量 | 安全合规验收 | C-15/C-16/C-18 | ◐ | +| 可扩展 | 切换模板零改码 | 平台化验收 | C-12/C-13/C-19 | ◐ | + +--- + +## 5. 验收流程与节点（§7.7 / §10） + +| 节点 | 阶段 | 责任人 | DoD 勾选门槛 | 状态 | +|------|------|--------|--------------|------| +| N-01 | 自测 | bot_dev | 内核 6 模块 + 首模板 5 项自测通过 | ◐ | +| N-02 | 内部评审 | bot_pm + bot_po | NFR §9 全部 ◐→✅，附验证证据 | ☐ | +| N-03 | 客户 UAT | 王主任 / 李工 | 首模板 T-01~T-08 客户确认 | ☐ | +| N-04 | 生产上线 | bot_pm + 客户成功 | 上线 Meta（非仅 Demo） | ☐ | +| N-05 | 质保观察 | 客户成功 | 上线后 1 个月无 P0 故障 | ☐ | +| N-06 | 闭环交付 | bot_pm | 质保期满、签收 | ☐ | + +--- + +## 6. 阻塞与风险登记（§12） + +| 风险 | 影响 | 当前缓解 / 触发条件 | 关联验收项 | +|------|------|---------------------|------------| +| 客户标注数据不足 | ①质量预测准确率不达标 | ①③先无监督/阈值上线，3 月后转监督；监督前标注 < 1000 条触发 | T-01 | +| 客户配合度（UAT） | M5 节奏延迟 | M1 即签订 UAT 排期与责任矩阵；必要时按内部验收标准先行上线 | N-03 | +| 网络/机房环境 | 无法部署本地 GPU | 提供云端 SaaS 演示环境或租赁方案 | C-17/C-22 | + +--- + +## 7. 一致性说明 + +- 本清单所有**量化指标**与《产品设计文档_iAOP.md》§9（NFR 表）、§10（DoD）、§7.7（交付物清单）逐字对齐， + `_check_dod.py` 用于程序化核对本文档的完整性（必备章节、关键指标短语、NFR 指标量化、状态口径）。 +- 任一条目从 ◐ 升级为 ✅ 时，须在「验证证据」列补可追溯的脚本输出 / 截图 / 报告链接。 diff --git a/docs/_check_dod.py b/docs/_check_dod.py new file mode 100644 index 0000000..ea07641 --- /dev/null +++ b/docs/_check_dod.py @@ -0,0 +1,123 @@ +# -*- coding: utf-8 -*- +"""DoD 验收清单文档（docs/DoD验收清单.md）完整性与指标一致性检查。 + +检查项： +1. 必备章节齐全（目的用法 / 内核验收 / 首模板验收 / NFR 核对 / 验收流程节点 / 风险登记 / 一致性说明）； +2. PRD §10 验收标准中的关键量化指标全部出现（P99≤1.8s / 丢失率≤0.02% / 可用性≥99.8% / + 路由准确率≥96.5% / 首屏≤2s / 质量预测准确率≥90% / 预警提前≥30分钟 / 误报率 / 本地首token≤1.5s / + 交接班报告≤2分钟）； +3. 状态口径四态（未开始 / 待验证 / 通过 / 阻塞）齐全； +4. 验收流程六节点（自测 / 内部评审 / 客户UAT / 上线 / 质保观察 / 闭环）齐全； +5. 引用的核心验收证据文件路径在仓库内真实存在。 + +用法：python _check_dod.py +""" +import os +import re +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +REPO_ROOT = os.path.dirname(HERE) +DOC_PATH = os.path.join(HERE, "DoD验收清单.md") + +REQUIRED_SECTIONS = [ + "## 1. 目的与用法", + "## 2. iAOP-Core 内核验收", + "## 3. iAOP-Template-Ti 一期首模板验收", + "## 4. NFR 量化底线核对表", + "## 5. 验收流程与节点", + "## 6. 阻塞与风险登记", + "## 7. 一致性说明", +] + +# PRD §9/§10 关键量化指标（去空格后匹配，兼容全角/半角差异） +KEY_METRICS = [ + "1.8s", # 采集 P99 + "0.02%", # 丢失率 + "99.8%", # 可用性 + "96.5%", # 路由准确率 / DLP（路由口径） + "2s", # 首屏 + "90%", # 质量预测准确率 + "30 分钟", # 预警提前量 + "1.5s", # 本地首 token + "2 分钟", # 交接班报告生成 + "100%", # DLP 拦截率 +] + +STATUS_TOKENS = ["未开始", "待验证", "通过", "阻塞"] + +# 状态表格中的符号（核对口径可勾选） +STATUS_SYMBOLS = ["☐", "◐", "✅", "⛔"] + +FLOW_NODES = ["自测", "内部评审", "客户 UAT", "生产上线", "质保观察", "闭环"] + +# 关键证据文件须真实存在（仓库内） +EVIDENCE_PATHS = [ + os.path.join(REPO_ROOT, "core", "data-bus", "scripts", "bench_write.py"), + os.path.join(REPO_ROOT, "core", "edge-gateway", "scripts", "verify_resilience.py"), + os.path.join(REPO_ROOT, "docs", "采集网只读隔离与网闸配置.md"), + os.path.join(REPO_ROOT, "core", "edge-gateway", "config", "point_dict.example.csv"), + os.path.join(REPO_ROOT, "core", "llm-gateway", "router.py"), + os.path.join(REPO_ROOT, "core", "llm-gateway", "dlp.py"), + os.path.join(REPO_ROOT, "deploy", "k8s", "helm", "iaop"), + os.path.join(REPO_ROOT, "templates", "resin", "version.yaml"), + os.path.join(REPO_ROOT, "templates", "ti-cl4", "point-dict", "point_dict.default.csv"), + os.path.join(REPO_ROOT, "docs", "LIMS质检接口字段清单.md"), + os.path.join(REPO_ROOT, "docs", "产品设计文档_iAOP.md"), +] + + +def _norm(s: str) -> str: + """归一化用于指标比对：移除所有空白。""" + return re.sub(r"\s+", "", s) + + +def main() -> int: + failures = [] + if not os.path.isfile(DOC_PATH): + print("FAIL") + print(" -", "DoD 验收清单文档缺失：DoD验收清单.md") + return 1 + + text = open(DOC_PATH, "r", encoding="utf-8").read() + + # 1) 必备章节 + for sec in REQUIRED_SECTIONS: + if sec not in text: + failures.append(f"缺少必备章节：{sec}") + + # 2) 关键量化指标（归一化后比对） + norm_text = _norm(text) + for metric in KEY_METRICS: + if _norm(metric) not in norm_text: + failures.append(f"缺少关键量化指标：{metric}") + + # 3) 状态口径四态齐全 + for token in STATUS_TOKENS: + if token not in text: + failures.append(f"缺少状态口径说明：{token}") + symbol_present = [sym for sym in STATUS_SYMBOLS if sym in text] + if len(symbol_present) < 3: + failures.append(f"状态符号至少覆盖 3 种，实际出现：{symbol_present}") + + # 4) 验收流程六节点 + for node in FLOW_NODES: + if node not in text: + failures.append(f"缺少验收流程节点：{node}") + + # 5) 引用证据文件真实存在 + for p in EVIDENCE_PATHS: + if not os.path.exists(p): + failures.append(f"引用证据路径不存在：{os.path.relpath(p, REPO_ROOT)}") + + if failures: + print("FAIL") + for f in failures: + print(" -", f) + return 1 + print("OK: DoD 清单章节/量化指标/状态口径/流程节点/证据路径校验通过") + return 0 + + +if __name__ == "__main__": + sys.exit(main())