Merge PR #121 (feat #91 用户手册/部署手册编写)

2026-08-05 08:20:54 +08:00
parent 57ecb47d3f
commit 22106526d9
3 changed files with 400 additions and 0 deletions
@@ -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())