feat(#91): [M5] 用户手册/部署手册编写（业务用户三类场景+Helm部署/后端切换/巡检/灰度回滚+一致性核对脚本）

2026-08-05 04:23:56 +08:00
parent e2d24f1839
commit 394d08db68
4 changed files with 402 additions and 0 deletions
@@ -6,6 +6,8 @@

 | 文档 | 说明 | 版本 |
 |------|------|------|
+| [用户手册.md](./用户手册.md) | **最终业务用户手册**（监控/优化/LLM 助手三类场景，面向工艺工程师/值班长/管理者） | v1.0 |
+| [部署手册.md](./部署手册.md) | **运维/交付部署手册**（Helm 一键部署、后端切换、健康巡检、灰度回滚） | v1.0 |
 | [产品设计文档_iAOP.md](./产品设计文档_iAOP.md) | **PRD 主文件**（开发依据） | v1.2 |
 | [产品设计文档_iAOP_对外评审.docx](./产品设计文档_iAOP_对外评审.docx) | 对外评审版（Word，含内嵌架构/流程/ER 图） | v1.2 |
 | [产品设计评审_iAOP.pptx](./产品设计评审_iAOP.pptx) | 内部评审/汇报版幻灯片 | v1.2 |
@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""用户手册 / 部署手册（issue #91）文档一致性检查。
+
+检查项：
+1. 两份手册必备章节齐全；
+2. 关键红线 / 验收关键词存在（PRD §5.6 / §7.7 / §9 NFR）；
+3. 跨文档引用与配套资产路径存在；
+4. 角色画像 / 场景流关键词存在（PRD §2 角色画像）。
+
+用法：python _check_user_deploy_manual.py
+"""
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+USER_DOC = os.path.join(HERE, "用户手册.md")
+DEPLOY_DOC = os.path.join(HERE, "部署手册.md")
+
+USER_SECTIONS = [
+    "## 1. 平台简介",
+    "## 2. 角色与权限（RBAC）",
+    "## 3. 登录",
+    "## 4. 场景 A：实时监控与告警处置",
+    "## 5. 场景 B：工艺优化",
+    "## 6. 场景 C：LLM 自然语言助手",
+    "## 7. 交接班报告",
+    "## 8. 常见问题（FAQ）",
+]
+
+DEPLOY_SECTIONS = [
+    "## 1. 部署目标与边界",
+    "## 2. 环境要求（前置条件）",
+    "## 3. 一键部署（Quick Start）",
+    "## 4. 配置点速查（values.yaml）",
+    "## 5. 健康巡检（可用性 ≥ 99.8%）",
+    "## 6. 灰度发布与回滚",
+    "## 7. 升级流程",
+    "## 8. 故障排查（SOP）",
+]
+
+USER_KEYWORDS = ["可溯源", "敏感度", "DLP", "交接班", "驾驶舱"]
+DEPLOY_KEYWORDS = [
+    "inference.backend",       # 后端可切换配置点
+    "nvidia-5090",
+    "ascend-910b",
+    "99.8%",                    # 可用性验收口径
+    "helm install",
+    "helm rollback",
+]
+
+# 必须存在的配套资产路径（相对仓库根）
+ASSET_PATHS = [
+    "deploy/k8s/helm/iaop/README.md",
+    "deploy/k8s/helm/iaop/values.yaml",
+    "deploy/k8s/healthz/probe_availability.py",
+]
+
+
+def main() -> int:
+    failures = []
+    repo_root = os.path.dirname(HERE)
+
+    if not os.path.isfile(USER_DOC):
+        failures.append("用户手册不存在：用户手册.md")
+    if not os.path.isfile(DEPLOY_DOC):
+        failures.append("部署手册不存在：部署手册.md")
+
+    user_text = open(USER_DOC, "r", encoding="utf-8").read() if os.path.isfile(USER_DOC) else ""
+    deploy_text = open(DEPLOY_DOC, "r", encoding="utf-8").read() if os.path.isfile(DEPLOY_DOC) else ""
+
+    for sec in USER_SECTIONS:
+        if sec not in user_text:
+            failures.append(f"用户手册缺少章节：{sec}")
+
+    for sec in DEPLOY_SECTIONS:
+        if sec not in deploy_text:
+            failures.append(f"部署手册缺少章节：{sec}")
+
+    for kw in USER_KEYWORDS:
+        if kw not in user_text:
+            failures.append(f"用户手册缺少关键词：{kw}")
+
+    for kw in DEPLOY_KEYWORDS:
+        if kw not in deploy_text:
+            failures.append(f"部署手册缺少关键词：{kw}")
+
+    # 部署手册必须正确引用用户手册（跨文档链接）
+    if "用户手册.md" not in deploy_text:
+        failures.append("部署手册缺少对『用户手册』的引用链接")
+
+    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: 用户手册/部署手册 章节齐全、关键词与配套资产校验通过")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,117 @@
+# iAOP 用户手册（User Guide）
+
+> 对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。
+> 本手册面向 **最终业务用户**（工艺工程师 / 值班长 / 生产管理者），即 PRD §2 角色画像中的张工、李工、王主任。
+> 部署 / 运维操作请见《[部署手册](./部署手册.md)》。
+
+## 1. 平台简介
+
+iAOP（云美工业 AI 优化平台）= **可配置、可复制的工业 AI 优化内核** + **按行业沉淀的行业模板**。
+
+- **内核（iAOP-Core）**：采集 → 模型推理 → LLM 解释 → 驾驶舱呈现，一次建设、多行业复用；
+- **行业模板**：氯化车间/海绵钛（Template-Ti）、吸附树脂（Template-Resin）等，决定 ~90% 落地工作量。
+
+你日常接触的是**配置化驾驶舱**（Web / 移动端）与 **LLM 自然语言助手**。本手册教你如何用它们完成监控、优化、辅助三类场景。
+
+## 2. 角色与权限（RBAC）
+
+| 角色 | 主要入口 | 权限 |
+| --- | --- | --- |
+| 工艺工程师 / 值班长（张工、李工） | 驾驶舱、LLM 助手 | 查看实时数据 / 告警 / 趋势；发起查询；接收优化建议并 review |
+| 生产管理者（王主任） | 驾驶舱大屏、移动端助手 | 查看 KPI / 趋势 / 报表；接收交接班报告 |
+
+> 配置台（模板配置台 Template Console）三级权限 Viewer / Editor / Publisher 面向**实施/行业工程师**，普通业务用户无需使用，详见《模板开发手册》。
+
+## 3. 登录
+
+1. 浏览器打开驾驶舱地址（由实施提供，形如 `http://iaop.example.com`）；
+2. 输入管理员分配的账号密码登录；
+3. 登录后默认进入「实时监控」驾驶舱。
+
+> 移动端：扫描实施提供的二维码，使用同一账号登录（只读模式，支持查看告警 / 报表 / 推送）。
+
+## 4. 场景 A：实时监控与告警处置
+
+**目标**：及时发现工艺异常并了解原因。
+
+1. 进入驾驶舱「实时监控」页：
+   - **四状态工艺流程视图**：直观展示氯化/还原等工序当前状态（绿/黄/红）；
+   - **实时趋势**：关键点位（如 `CLF-01.TEMP`）实时曲线；
+   - **KPI 卡片**：核心指标（如 `Ti_purity` 海绵钛纯度）；
+   - **告警面板**：当前未确认告警列表。
+2. 当出现红色告警（如炉层温度异常）：
+   - 点击告警条目 → 系统展示 LLM 生成的**报警解释**（原因 + 处置建议，附引用依据，可溯源）；
+   - 值班长确认后，按建议处置或转交相关人员；
+   - 处置完成后在告警面板标注「已确认 / 已处置」。
+
+> 不使用 iAOP 时：靠人工盯趋势、微信群喊人，平均 20–40 分钟才发现，且无根因解释。iAOP 将发现到解释压缩到分钟级。
+
+## 5. 场景 B：工艺优化（配方 / 参数建议）
+
+**目标**：给定质量目标，让模型给出参数建议，review 后下发。
+
+1. 进入「优化建议」页（一期质量预测 + 炉层杂质预警上线后，二期配方优化 / 跨工序寻优逐步开放）；
+2. 输入或确认本批次质量目标（如目标纯度、约束条件）；
+3. 系统给出**可溯源优化建议**：
+   - 建议参数（决策变量取值）；
+   - 目标函数值与约束满足情况；
+   - 跨工序权重与依据（引用上游 TiCl₄ 指标 → 下游海绵钛寻优）；
+4. 工艺工程师（李工）**review 建议**，确认后下发 DCS；
+5. 实际质量反馈回流，持续训练模型。
+
+> 建议为「辅助决策」，高利害输出低于信度阈值时系统会提示「需人工确认」。
+
+## 6. 场景 C：LLM 自然语言助手
+
+**目标**：用自然语言提问，获得带引用的答案 / 报表。
+
+支持四类能力：
+
+| 能力 | 示例提问 | 说明 |
+| --- | --- | --- |
+| NL 工艺查询 | 「最近一周 CLF-01 温度超标几次？」 | NL→SQL/API，返回数据 + 来源 |
+| 报警解释 | （点击告警自动触发） | 原因 + 处置建议 + 引用 |
+| 交接班报告 | （班次结束自动生成） | 汇总关键事件/能耗/待办，≤ 2 分钟 |
+| 配方 RAG 问答 | 「国标对 XX 指标的要求？」 | 命中领域知识库，强制引用溯源 |
+
+**安全说明**：平台内置**敏感度分级路由**（准确率 ≥ 96.5%）+ **DLP 防泄漏**（拦截率 100%）：敏感/核心问题在本地 70B 模型闭环，脱敏/通用问题走云端，结果均附引用来源，可追溯。
+
+## 7. 交接班报告
+
+每班次结束时，系统自动生成交接班报告（汇总关键事件、能耗、待办），并推送给下一班。
+
+- 查看入口：驾驶舱「交接班」页 / 移动端推送；
+- 报告可导出（PDF）；
+- 历史报告在「报告归档」中可检索。
+
+> 不使用 iAOP 时：手写记录本 + 口头交代，遗漏率约 15%，夜班回溯困难。
+
+## 8. 常见问题（FAQ）
+
+**Q1：建议 / 解释能否给出依据？**
+A：所有 LLM 输出强制引用溯源（返回命中文档片段 + 来源），可点击查看原文。
+
+**Q2：数据准吗？多久更新？**
+A：采集 P99 ≤ 1.8s，驾驶舱数据准实时刷新；批量写入 5k 点 / 100ms。
+
+**Q3：看不到某个功能？**
+A：功能按行业模板与里程碑分批开放（一期：监控+预警+LLM；二期：优化寻优）。确认你的模板版本与权限。
+
+**Q4：发现数据异常 / 误报怎么办？**
+A：在告警面板标注「误报」并留言，系统回流用于模型迭代；紧急情况联系运维（见《部署手册》§8）。
+
+## 9. 移动端使用
+
+- **只读模式**：查看驾驶舱、接收告警 / 报告推送；
+- 登录账号与 Web 一致；
+- 支持 ≥ 200 并发只读用户（PRD §9 NFR）。
+
+## 10. 帮助与反馈
+
+- 使用问题：联系工艺主管或实施工程师；
+- 功能建议：在配置台「反馈」入口提交（如已开放）；
+- 故障：参考《部署手册》§8 故障排查 SOP，或联系运维 bot_dev。
+
+---
+
+**维护**：本文档随行业模板与功能开放节奏更新。当前对应 Template-Ti 一期（氯化车间/海绵钛）。
@@ -0,0 +1,178 @@
+# iAOP 部署手册（Deployment Guide）
+
+> 对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。
+> 配套 PRD §5.6「⑥ 部署底座」与 `deploy/k8s/helm/iaop/`。本手册面向 **运维/交付工程师（bot_dev、现场运维）**。
+> 业务最终用户的日常使用请见《[用户手册](./用户手册.md)》。
+
+## 1. 部署目标与边界
+
+iAOP 采用「内核 + 行业模板」分层架构，部署目标：
+
+- **内核（iAOP-Core）**：6 大模块（采集总线 / 模型框架 / LLM 网关 / 配置化驾驶舱 / 部署底座 / 模板配置台）一次部署，多行业复用；
+- **行业模板（iAOP-Template）**：作为「模板资产包」随内核发布，切换行业仅改配置不改码。
+
+**验收口径（PRD §5.6 / §10）**：内核 + 模板一键 Helm 部署；昇腾后端切换仅需适配层，不改业务代码；可用性 ≥ 99.8%。
+
+**本手册覆盖范围**：生产 / 验收环境部署、推理后端切换、健康巡检、灰度与回滚。
+**不覆盖**：商务定价、第三方 License 采购、单厂实施方案（由交付阶段单独产出）。
+
+## 2. 环境要求（前置条件）
+
+### 2.1 软件依赖
+
+| 组件 | 版本 | 说明 |
+| --- | --- | --- |
+| Kubernetes | ≥ 1.26 | 生产集群（建议 3 控制面 + N 工作节点） |
+| Helm | ≥ 3.12 | 一键部署工具 |
+| kubectl | 与集群匹配 | 集群操作 |
+| ArgoCD（可选） | ≥ 2.7 | GitOps 灰度发布 |
+| Python | ≥ 3.10 | 探针 / 离线校验脚本运行时 |
+| 容器运行时 | containerd ≥ 1.7 | 集群默认即可 |
+
+### 2.2 推理后端硬件（二选一，PRD §5.6）
+
+| 后端 (`inference.backend`) | 设备 (`inference.device`) | 运行时 | 驱动要求 |
+| --- | --- | --- | --- |
+| `gpu` | `nvidia-5090` | vllm / triton | NVIDIA Driver + nvidia-container-toolkit |
+| `npu` | `ascend-910b` / `ascend-310p` | mindie / onnx-ascend | CANN 工具链（见 `inference.cannVersion`） |
+
+> 切换后端 = 改 `values.yaml` 的 `inference.backend` / `inference.device`，业务代码零改动（差异收敛在 `core/inference-backend/` 适配层）。
+
+### 2.3 资源配额基线（默认 values，可调）
+
+| 资源 | requests | limits |
+| --- | --- | --- |
+| CPU | 2 core | 8 core |
+| 内存 | 8 Gi | 32 Gi |
+| 模型权重存储 | 100 Gi（PVC） | — |
+
+> 生产环境建议启用 HPA（`autoscaling.enabled: true`，min 2 / max 8，CPU 70%）。
+
+## 3. 一键部署（Quick Start）
+
+### 3.1 部署内核 + 模板（默认 GPU 后端）
+
+```bash
+# 1) 命名空间（一次性）
+kubectl create namespace iaop
+
+# 2) Helm 一键部署（Chart 在仓库 deploy/k8s/helm/iaop/）
+helm install iaop deploy/k8s/helm/iaop \
+  -n iaop \
+  --set inference.backend=gpu \
+  --set inference.device=nvidia-5090
+
+# 3) 验证
+kubectl -n iaop rollout status deployment/iaop-inference
+kubectl -n iaop get svc iaop-inference   # ClusterIP :8000
+```
+
+部署成功标志：Deployment 就绪、`/health` 返回 200（见 §5 健康巡检）。
+
+### 3.2 切换为华为昇腾 NPU 后端
+
+```bash
+helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
+  --set inference.backend=npu \
+  --set inference.device=ascend-910b \
+  --set inference.cannVersion=8.0
+```
+
+切换行为（模板自动处理，无需手工干预）：
+
+- `backend-configmap.yaml` 渲染对应后端适配层配置（npu 追加 `cann_version`）；
+- `deployment.yaml` 的 nodeSelector 自动切到 `ascend.com/npu=true`（GPU 为 `nvidia.com/gpu=true`）；
+- Pod 标签标注 `iaop.ai/inference-backend`，便于灰度与监控分流。
+
+### 3.3 开启域名入口（可选）
+
+```bash
+helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
+  --set ingress.enabled=true \
+  --set ingress.host=iaop.example.com \
+  --set ingress.className=nginx
+```
+
+## 4. 配置点速查（values.yaml）
+
+完整配置见 `deploy/k8s/helm/iaop/values.yaml`，常用项：
+
+| 配置点 | values 路径 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| 推理后端 | `inference.backend` | `gpu` | `gpu` / `npu` |
+| 模型名 | `inference.model` | `iaop-ti-cl4-v1` | 随模板切换 |
+| 副本数 | `replicaCount` | `2` | 生产 ≥ 2 |
+| 滚动策略 | `rollingUpdate` | `maxUnavailable:0, maxSurge:1` | 灰度发布策略 |
+| HPA | `autoscaling.enabled` | `false` | 生产建议 `true` |
+| 资源配额 | `resources.requests/limits` | 见 §2.3 | CPU/内存 |
+| 存储 | `storage.size` | `100Gi` | 模型权重持久卷 |
+| 域名 | `ingress.host` | — | 可选 |
+
+**多环境分离**：用 `values.dev.yaml` / `values.prod.yaml` 覆盖，例如：
+
+```bash
+helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
+  -f deploy/k8s/helm/iaop/values.prod.yaml
+```
+
+## 5. 健康巡检（可用性 ≥ 99.8%）
+
+部署底座提供可用性探针（EPIC #8 子任务 #61）：
+
+```bash
+# 轮询 60 轮（每 1s），目标可用率 99.8%
+python deploy/k8s/healthz/probe_availability.py \
+  --endpoints http://<iaop-inference>:8000 \
+  --rounds 60 --interval 1 --target 0.998
+```
+
+- 退出码 `0` = 达标（PASS）；`1` = 低于目标（FAIL）；
+- 建议以 K8s CronJob 定时执行，FAIL 时触发告警（接 Prometheus / 企业微信）。
+
+## 6. 灰度发布与回滚
+
+### 6.1 ArgoCD 灰度（推荐）
+
+Chart 已内置滚动策略（`maxUnavailable: 0, maxSurge: 1`），配合 ArgoCD 可实现 GitOps 灰度：
+
+```bash
+# 1) Chart 纳入 Git 仓库，ArgoCD Application 指向该仓库
+# 2) 升级 = 改 values 并提交，ArgoCD 自动同步 + 滚动
+```
+
+### 6.2 Helm 回滚
+
+```bash
+helm history iaop -n iaop          # 查看修订历史
+helm rollback iaop <REVISION> -n iaop   # 回滚到上一版本
+```
+
+> 模板资产包发布同样走「校验 → 灰度 → 回滚点」流程（PRD §5.7 模板配置台），配置台支持版本 diff 与一键回滚。
+
+## 7. 升级流程
+
+1. **预演**：在 dev 命名空间用 `values.dev.yaml` 部署，跑通探针与冒烟用例；
+2. **生产灰度**：`helm upgrade`，观察 `rollout status` 与探针可用率；
+3. **质保观察**：上线后进入 1 个月质保观察期（PRD §7.7），监控 NFR 指标（可用性 ≥ 99.8% / P99 ≤ 1.8s）。
+
+## 8. 故障排查（SOP）
+
+| 现象 | 排查步骤 |
+| --- | --- |
+| Deployment 不就绪 | `kubectl describe pod` 看 nodeSelector / 镜像 / 资源；GPU/NPU 驱动是否就绪 |
+| `/health` 不通 | `kubectl logs`；确认推理后端适配层加载（`core/inference-backend/`） |
+| 可用率 < 99.8% | 看探针 FAIL 轮次分布；HPA 是否触发；节点资源是否打满 |
+| 推理慢 | 确认 `inference.runtime` 与硬件匹配；检查 `maxTokens/temperature` |
+
+## 9. 交付物清单（对应 PRD §7.7）
+
+部署阶段交付：
+
+- [ ] 内核 + 模板 Helm 一键部署通过（GPU / NPU 各验一次）；
+- [ ] 可用性探针连续达标（≥ 99.8%）；
+- [ ] 灰度 + 回滚演练通过；
+- [ ] 故障排查 SOP（本文 §8）就绪。
+
+---
+
+**维护**：本文档随部署底座（`deploy/`）演进，版本与 Chart `appVersion` 对齐。模板资产打包发布见 `templates/<行业>/version.yaml`。