From 234a476ec0758474f0b9246b6e4272f13c7c3fdd Mon Sep 17 00:00:00 2001 From: bot_dev2 Date: Wed, 5 Aug 2026 08:21:17 +0800 Subject: [PATCH] =?UTF-8?q?Merge=20PR=20#123=20(feat=20#93=20=E4=B8=8A?= =?UTF-8?q?=E7=BA=BF=E4=B8=8E=E8=B4=A8=E4=BF=9D=E8=A7=82=E5=AF=9F=E8=B7=9F?= =?UTF-8?q?=E8=B8=AA)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 1 + docs/_check_golive_warranty.py | 89 ++++++++++++++++++++++ docs/上线与质保观察跟踪.md | 135 +++++++++++++++++++++++++++++++++ 3 files changed, 225 insertions(+) create mode 100644 docs/_check_golive_warranty.py create mode 100644 docs/上线与质保观察跟踪.md diff --git a/docs/README.md b/docs/README.md index 711003f..39ab594 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ | [用户手册.md](./用户手册.md) | **最终业务用户手册**（监控/优化/LLM 助手三类场景） | v1.0 | | [部署手册.md](./部署手册.md) | **运维/交付部署手册**（Helm 一键部署、后端切换、巡检、灰度回滚） | v1.0 | | [UAT计划与执行支撑.md](./UAT计划与执行支撑.md) | **M5 客户 UAT 计划**（用例集/准入准出/缺陷管理/排期） | v1.0 | +| [上线与质保观察跟踪.md](./上线与质保观察跟踪.md) | **M5 上线与质保观察**（Go-Live/1个月观察/监控指标/回滚/闭环） | 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/_check_golive_warranty.py b/docs/_check_golive_warranty.py new file mode 100644 index 0000000..61f9247 --- /dev/null +++ b/docs/_check_golive_warranty.py @@ -0,0 +1,89 @@ +# -*- coding: utf-8 -*- +"""上线与质保观察跟踪文档（docs/上线与质保观察跟踪.md，issue #93）一致性检查。 + +检查项： +1. 必备章节齐全（阶段定位/上线/质保观察/闭环/交付物/风险）； +2. 验收流程最后三节点关键词存在（上线 / 质保观察 / 闭环，PRD §10）； +3. NFR 量化指标齐全（可用性≥99.8% / 丢失率≤0.02% / P99≤1.8s / 路由≥96.5% / PSI≤0.2）； +4. 回滚机制关键词存在（helm rollback / 回滚点，PRD §5.6 / §5.7）； +5. 功能安全红线关键词存在（不直接联动执行机构 / 人工确认 / 只读，PRD §9）； +6. 引用配套资产路径存在（healthz 探针）。 + +用法：python _check_golive_warranty.py +""" +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +DOC_PATH = os.path.join(HERE, "上线与质保观察跟踪.md") + +REQUIRED_SECTIONS = [ + "## 1. 阶段定位与目标", + "## 2. 上线（Go-Live）", + "## 3. 1 个月质保观察（Warranty Observation）", + "## 4. 闭环交付（Closure）", + "## 5. 交付物清单（上线 → 闭环阶段）", + "## 6. 风险与缓解", +] + +# PRD §10 验收流程后三节点 +FLOW_KEYWORDS = ["上线", "质保观察", "闭环"] + +# NFR / 模型质量量化底线 +NFR_KEYWORDS = ["99.8%", "0.02%", "1.8s", "96.5%", "0.2"] # 0.2 = PSI 漂移阈值 + +# 回滚机制 +ROLLBACK_KEYWORDS = ["helm rollback", "回滚点"] + +# 功能安全红线（PRD §9 安全-功能安全 / 网络） +SAFETY_KEYWORDS = ["不直接联动执行机构", "人工确认", "只读"] + +# 配套资产 +ASSET_PATHS = ["deploy/k8s/healthz/probe_availability.py"] + + +def main() -> int: + failures = [] + repo_root = os.path.dirname(HERE) + + if not os.path.isfile(DOC_PATH): + print("FAIL\n - 文档不存在：上线与质保观察跟踪.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 kw in ROLLBACK_KEYWORDS: + if kw not in text: + failures.append(f"缺少回滚机制关键词：{kw}") + + for kw in SAFETY_KEYWORDS: + if kw not in text: + failures.append(f"缺少功能安全红线关键词：{kw}") + + 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: 上线与质保观察跟踪 章节/流程节点/NFR指标/回滚/功能安全/资产校验通过") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/docs/上线与质保观察跟踪.md b/docs/上线与质保观察跟踪.md new file mode 100644 index 0000000..ae28416 --- /dev/null +++ b/docs/上线与质保观察跟踪.md @@ -0,0 +1,135 @@ +# iAOP 上线与质保观察跟踪（Go-Live & Warranty Observation） + +> 对应 issue #93「[M5] 上线与质保观察跟踪」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。 +> 配套 PRD §7.7 验收节点 / §9 NFR（可靠性·可维护）/ §5.6 部署底座 / §11 风险与缓解。 +> 本文档面向 **PM（bot_pm）+ 客户成功 + 运维（bot_dev）**，覆盖 PRD §10 验收流程最后三节点：**上线 → 1 个月质保观察 → 闭环交付**。 + +## 1. 阶段定位与目标 + +PRD §10 验收流程六节点：自测（bot_dev）→ 内部评审（bot_pm+bot_po）→ 客户 UAT（见《UAT计划与执行支撑》）→ **上线（本文 §2）→ 1 个月质保观察（本文 §3）→ 闭环（本文 §4）**。 + +**目标**： + +1. UAT 放行后，将平台平滑上线至客户生产环境，保证业务连续、可回滚； +2. 上线后进入 1 个月质保观察期，持续监控 NFR 指标与模型质量，及时处置线上问题； +3. 观察期满、指标稳定达标后，完成闭环交付，转入正式运维 / 售后 SLA。 + +## 2. 上线（Go-Live） + +### 2.1 上线准入（前置条件） + +进入上线前必须满足（承接 UAT 准出）： + +- [ ] UAT 验收通过，客户决策人（王主任）签字、bot_pm + bot_qa 会签放行； +- [ ] 生产环境部署就绪（见《部署手册》§3 一键部署），GPU/NPU 后端确认； +- [ ] 生产 DCS 点位字典导入校验通过，采集达标（P99 ≤ 1.8s / 丢失率 ≤ 0.02%）； +- [ ] 一期模型生产版本加载（质量预测 / 炉层杂质预警）； +- [ ] RAG 知识库生产版本导入，Prompt 模板版本锁定（semver，PRD §5.4）； +- [ ] 监控告警就绪（Prometheus + Grafana，结构化 JSON 日志，PRD §9 可维护）； +- [ ] 回滚预案与回滚点已确认（见 §2.4）。 + +### 2.2 上线步骤（灰度发布，对齐 PRD §5.6） + +1. **预演**：在验收命名空间用生产 values 跑通完整流程 + 可用性探针（`deploy/k8s/healthz/probe_availability.py`）连续达标； +2. **生产灰度部署**：`helm upgrade` 滚动发布（`maxUnavailable: 0, maxSurge: 1`），ArgoCD GitOps 同步； +3. **流量切入**：先旁路（只读监控/告警不影响生产控制），确认无误后切入业务流量； +4. **冒烟验证**：执行 UAT §4 核心用例子集（监控 A / LLM C），确认生产环境表现； +5. **上线确认**：连续观察 24h，可用性 ≥ 99.8%、无 S1 缺陷，宣布上线成功，进入质保观察。 + +> **功能安全红线（PRD §9）**：AI 输出作为"决策辅助"，关键告警/建议不直接联动执行机构；高利害输出人工确认；边缘网关严格只读不反控。 + +### 2.3 上线检查清单（Go-Live Checklist） + +| 项 | 通过准则 | 证据 | +| --- | --- | --- | +| 部署 | Deployment 就绪，`/health` 200 | `kubectl rollout status` | +| 采集 | P99 ≤ 1.8s，丢失率 ≤ 0.02% | 数据总线埋点 | +| 可用性 | ≥ 99.8% | 探针连续 PASS | +| 后端 | GPU/NPU 切换仅改 values | Helm 配置 | +| 监控告警 | Prometheus 采集 + 告警通道通 | Grafana 面板 | +| 功能安全 | 不联动执行机构 / 人工确认 | 网关只读自检 | + +### 2.4 回滚机制 + +- **应用层**：`helm rollback iaop `（见《部署手册》§6.2）； +- **模板/Prompt 层**：模板配置台版本 diff + 一键回滚（PRD §5.7），Prompt 版本库支持回滚（PRD §5.4）； +- **模型层**：保留上一版本模型权重，drift 触发或准确率下降时可切回（见 §3.2）； +- **回滚点**：上线前打 Git tag + Helm release revision 记录，作为回滚基准。 + +## 3. 1 个月质保观察（Warranty Observation） + +### 3.1 观察目标与周期 + +- **周期**：上线后 1 个月（PRD §7.7 / §11 M5）； +- **目标**：验证生产环境 NFR 指标持续达标、模型质量稳定、无重大线上缺陷，为闭环交付提供依据。 + +### 3.2 监控指标与频率 + +| 类别 | 指标 | 阈值（NFR） | 频率 | 处置 | +| --- | --- | --- | --- | --- | +| 可靠性 | 可用性 | ≥ 99.8% | 连续探针 | < 99.8% 告警 + 根因 | +| 可靠性 | 采集丢失率 | ≤ 0.02% | 实时 | 超标排查网关/总线 | +| 性能 | 采集 P99 | ≤ 1.8s | 实时 | 超标排查背压/缓存 | +| 性能 | 驾驶舱首屏 | ≤ 2s | 抽测 | 超标排查懒加载 | +| 模型质量 | 质量预测准确率 | ≥ 90% | 周（比对 LIMS） | 下降 → 评估是否回滚模型 | +| 模型质量 | 杂质预警误报率 | ≤ 8% | 周 | 上升 → 调阈值/重训 | +| 模型漂移 | PSI | ≤ 0.2（PRD §5.3） | 周 | 超限 → 触发重训（drift_check） | +| 安全 | 敏感度路由准确率 | ≥ 96.5% | 周 | 下降 → 调路由规则 | +| 安全 | DLP 拦截 | 100% | 周 | 漏拦 → 紧急修规则 | + +### 3.3 质保期问题处置（SOP） + +- **缺陷分级**：同 UAT §6（S1 阻断 / S2 严重 / S3 一般 / S4 建议）； +- **响应**：S1 当日响应修复（必要时回滚）；S2 质保期内修复；S3/S4 评估后纳入迭代； +- **模型退化**：准确率/误报率连续 2 周恶化或 PSI > 0.2 → 触发模型重训流程（PRD §5.3 `drift_check`），重训期间切回上一稳定版本； +- **记录**：质保期问题登记在 Gitea issue（label=warranty），关联本文档。 + +### 3.4 观察周报 + +每周由 bot_pm 汇总《质保观察周报》： + +- 本周 NFR 指标达标情况（附 Prometheus/Grafana 截图 + 探针报告）； +- 模型质量趋势（准确率/误报率/PSI）； +- 本周缺陷与处置； +- 风险与下周计划。 + +## 4. 闭环交付（Closure） + +### 4.1 闭环条件 + +质保观察期满（1 个月），且满足： + +- [ ] NFR 指标连续 4 周稳定达标（可用性 ≥ 99.8% / 丢失率 ≤ 0.02% / P99 ≤ 1.8s / 路由 ≥ 96.5%）； +- [ ] 模型质量稳定（准确率 ≥ 90% / 误报率 ≤ 8% / PSI ≤ 0.2）； +- [ ] S1/S2 缺陷清零或有明确遗留方案； +- [ ] 客户决策人确认接受； +- [ ] 交付物齐备（见 §5）。 + +### 4.2 闭环动作 + +- 出具《项目验收/闭环报告》，客户签字； +- 移交运维职责（转正式运维 + 售后 SLA，PRD §1.2 未覆盖范围另签）； +- 复盘总结（经验/教训/可复用资产沉淀到内核与模板，PRD §6 模板机制）； +- 关闭 EPIC 跟踪 issue（父 Issue #15）。 + +## 5. 交付物清单（上线 → 闭环阶段） + +- [ ] 上线检查清单签字件（§2.3）； +- [ ] 回滚预案与回滚点记录（§2.4）； +- [ ] 质保观察周报 ×4（§3.4）； +- [ ] 监控指标达标证据（Prometheus/Grafana + 探针报告）； +- [ ] 缺陷登记与处置记录（§3.3）； +- [ ] 项目验收/闭环报告（§4.2，客户签字）。 + +## 6. 风险与缓解 + +| 风险 | 触发 | 缓解 | +| --- | --- | --- | +| 上线后模型退化 | 准确率/误报率恶化、PSI > 0.2 | drift_check 自动检测 + 回滚上一稳定模型 + 重训（PRD §5.3） | +| 可用性不达标 | 探针 FAIL、可用性 < 99.8% | HPA 扩容 + 根因排查 + 必要时回滚 | +| 客户配合度（质保期响应） | 客户关键人缺席 | UAT 前签责任矩阵；明确质保期响应窗口 | +| 生产数据分布漂移 | PSI 持续超限 | 触发重训；一期 ①③ 必要时回退阈值/无监督（PRD §11） | + +--- + +**维护**：本文档随上线与质保观察实际进展填写证据与状态；闭环后归档为项目验收材料。