verify-module

# ⚖ 校验关卡 · 模块完整性 ## 核心原则 ``` 模块 = 代码 + README.md + DESIGN.md 缺一不可，残缺即异端 ``` ## 自动扫描 运行扫描脚本（跨平台）： ```bash # 在 verify-module 目录下运行（推荐） node scripts/module_scanner.js <模块路径> node scripts/module_scanner.js <模块路径> -v # 详细模式 node scripts/module_scanner.js <模块路径> --json # JSON 输出 ``` ## 校验标准 一个完整的模块必须包含： ``` module/ ├── README.md # 必须 - 模块是什么、为什么存在 ├── DESIGN.md # 必须 - 设计决策、权衡取舍 ├── src/ # 代码实现 └── tests/ # 测试用例（如适用） ``` ## 检测项 ### 必须存在 | 文件 | 说明 | 缺失后果 | |------|------|----------| | `README.md` | 模块说明文档 | 🔴 阻断交付 | | `DESIGN.md` | 设计决策文档 | 🔴 阻断交付 | ### 推荐存在 | 文件/目录 | 说明 | 缺失后果 | |-----------|------|----------| | `tests/` | 测试目录 | 🟠 警告 | | `__init__.py` | Python 包标识 | 🟡 提示 | | `.gitignore` | Git 忽略配置 | 🔵 信息 | ### README.md 必须包含 - [ ] **模块名称与定位** — 一句话说明是什么 - [ ] **存在理由** — 为什么需要这个模块 - [ ] **核心职责** — 做什么、不做什么 - [ ] **依赖关系** — 依赖谁、被谁依赖 - [ ] **快速使用** — 最简示例 ### DESIGN.md 必须包含 - [ ] **设计目标** — 要解决什么问题 - [ ] **方案选择** — 考虑过哪些方案、为何选当前方案 - [ ] **关键决策** — 重要的技术决策及理由 - [ ] **已知限制** — 当前方案的局限性 - [ ] **变更历史** — 重大变更记录 ## 自动触发时机 | 场景 | 触发条件 | |------|----------| | 新建模块 | 模块创建完成时 | | 模块重构 | 重构完成时 | | 提交前 | 代码提交前检查 | ## 校验流程 ``` 1. 运行 module_scanner.js 自动扫描 2. 检查文件结构是否完整 3. 检查 README.md 各项是否齐全 4. 检查 DESIGN.md 各项是否齐全 5. 检查代码与文档描述是否一致 6. 输出校验报告 ``` ## 校验报告格式 ``` ## 模块校验报告 ### 模块: <模块名> ✓ 通过 | ✗ 未通过 ### 文件检查 - README.md: ✓ 存在 / ✗ 缺失 - DESIGN.md: ✓ 存在 / ✗ 缺失 - tests/: ✓ 存在 / ⚠️ 缺失 ### 内容检查 - README 完整性: ✓ 完整 / ⚠️ 缺少 [X, Y, Z] - DESIGN 完整性: ✓ 完整 / ⚠️ 缺少 [X, Y, Z] ### 结论 可交付 / 需补充后交付 ``` ## 快速修复 如果缺少文档，可使用文档生成器： ```bash /gen-docs <模块路径> ``` ---