#!/usr/bin/env python3 """ docmap 输出质量验证脚本 检查生成的文档是否符合规范要求 检查项分两级： - 失败项（failed）：结构/内容缺失，退出码非零 - 警告项（warning）：可疑但不阻断（如 stateDiagram、模糊表述），不影响退出码 """ import re import sys from datetime import datetime from pathlib import Path from dataclasses import dataclass from typing import List # 模糊表述"等"的白名单（合理用法，不算模糊） DENG_WHITELIST = [ "等于", "等待", "对等", "等级", "等同", "同等", "均等", "不等", "稍等", "优等", "劣等", "等比", "等值", ] @dataclass class ValidationResult: passed: bool message: str file: str = "" warning: bool = False # True 表示警告项，不计入失败、不影响退出码 class DocmapValidator: def __init__(self, outputs_dir: str): self.outputs_dir = Path(outputs_dir) self.results: List[ValidationResult] = [] def validate(self) -> List[ValidationResult]: """执行所有验证""" self.results = [] # 检查目录结构 self._check_directory_structure() # 验证架构文档 self._validate_architecture_doc() # 验证模块文档 self._validate_module_docs() # 验证能力模型 self._validate_capability_doc() return self.results def _check_directory_structure(self): """检查输出目录结构""" if not self.outputs_dir.exists(): self.results.append(ValidationResult( False, "输出目录不存在", str(self.outputs_dir) )) return # 检查必需文件 required_files = ["01-产品整体架构.md", "03-系统能力模型.md"] for f in required_files: path = self.outputs_dir / f if not path.exists(): self.results.append(ValidationResult( False, f"缺少必需文件: {f}", str(self.outputs_dir) )) # 检查模块目录 module_dir = self.outputs_dir / "02-功能模块" if not module_dir.exists(): self.results.append(ValidationResult( False, "缺少功能模块目录", str(self.outputs_dir) )) def _validate_architecture_doc(self): """验证架构文档""" doc_path = self.outputs_dir / "01-产品整体架构.md" if not doc_path.exists(): return content = doc_path.read_text(encoding='utf-8') # 检查 7 个必需章节 required_sections = [ "产品定位", "系统整体架构", "业务架构图", "核心业务流程", "数据架构", "权限与角色体系", "系统扩展点分析" ] for section in required_sections: if section not in content: self.results.append(ValidationResult( False, f"缺少章节: {section}", str(doc_path) )) # 检查 Mermaid 图（至少 2 个） mermaid_count = content.count("```mermaid") if mermaid_count < 2: self.results.append(ValidationResult( False, f"Mermaid 图数量不足: 需要至少 2 个，实际 {mermaid_count} 个", str(doc_path) )) else: self.results.append(ValidationResult( True, f"Mermaid 图数量: {mermaid_count} 个", str(doc_path) )) # 检查模糊表述（警告项，不阻断） fuzzy_patterns = [r"等情况", r"等多种", r"其他相关", r"等等", r"诸如此类"] for pattern in fuzzy_patterns: matches = re.findall(pattern, content) if matches: self.results.append(ValidationResult( False, f"发现模糊表述 '{pattern}': 出现 {len(matches)} 次", str(doc_path), warning=True )) def _validate_module_docs(self): """验证模块文档""" module_dir = self.outputs_dir / "02-功能模块" if not module_dir.exists(): return module_files = list(module_dir.glob("*.md")) if not module_files: self.results.append(ValidationResult( False, "功能模块目录为空", str(module_dir) )) return for module_file in module_files: content = module_file.read_text(encoding='utf-8') # 检查功能清单表格 if "| 功能名称 |" not in content and "|功能名称|" not in content: self.results.append(ValidationResult( False, "缺少功能清单表格", str(module_file) )) # 检查状态流转 Mermaid（警告项，不阻断：无状态机的模块可豁免） if "```mermaid" not in content or "stateDiagram" not in content: self.results.append(ValidationResult( False, "缺少状态流转 Mermaid 图", str(module_file), warning=True )) # 检查模糊表述"等"（警告项，不阻断；白名单词不算命中） hit_lines = [] for lineno, line in enumerate(content.split('\n'), 1): stripped = line for word in DENG_WHITELIST: stripped = stripped.replace(word, "") if "等" in stripped: hit_lines.append(lineno) if hit_lines: self.results.append(ValidationResult( False, f"可能包含模糊表述 '等'（行: {', '.join(map(str, hit_lines))}）", str(module_file), warning=True )) def _validate_capability_doc(self): """验证能力模型文档""" doc_path = self.outputs_dir / "03-系统能力模型.md" if not doc_path.exists(): return content = doc_path.read_text(encoding='utf-8') # 检查能力依赖关系图 if "```mermaid" not in content: self.results.append(ValidationResult( False, "缺少能力依赖关系图", str(doc_path) )) # 检查平台级/业务定制能力区分 if "平台级能力" not in content or "业务定制能力" not in content: self.results.append(ValidationResult( False, "缺少平台级/业务定制能力区分", str(doc_path) )) def generate_report(self) -> str: """生成验证报告""" passed = [r for r in self.results if r.passed] warnings = [r for r in self.results if not r.passed and r.warning] failed = [r for r in self.results if not r.passed and not r.warning] report = ["# docmap 输出质量验证报告\n"] report.append(f"**验证时间:** {datetime.now().isoformat()}\n") report.append(f"**输出目录:** {self.outputs_dir}\n") report.append(f"**通过项:** {len(passed)}\n") report.append(f"**警告项:** {len(warnings)}\n") report.append(f"**失败项:** {len(failed)}\n\n") if failed: report.append("## ❌ 失败项\n") for r in failed: report.append(f"- **{r.file}**: {r.message}\n") report.append("\n") if warnings: report.append("## ⚠️ 警告项（不阻断）\n") for r in warnings: report.append(f"- **{r.file}**: {r.message}\n") report.append("\n") if passed: report.append("## ✅ 通过项\n") for r in passed: report.append(f"- **{r.file}**: {r.message}\n") return "\n".join(report) def main(): if len(sys.argv) < 2: print("Usage: python validate_output.py ") sys.exit(1) outputs_dir = sys.argv[1] validator = DocmapValidator(outputs_dir) validator.validate() report = validator.generate_report() print(report) # 保存报告 report_path = Path(outputs_dir).parent / "validation_report.md" report_path.write_text(report, encoding='utf-8') print(f"\n报告已保存: {report_path}") # 仅失败项影响退出码；警告项不阻断 failed = [r for r in validator.results if not r.passed and not r.warning] sys.exit(1 if failed else 0) if __name__ == "__main__": main()