doc-reviewlisted

# 设计文档审查 审查 `$doc_dir` 目录下的设计文档，从测试视角评估其完整性和精炼度。未传 `$doc_dir` 时，默认审查当前 workspace 的 `docs/` 目录。 ## 审查流程 ### 第一步：文档盘点 读取 `$doc_dir` 下所有文件，将每份文档分类为： - **系统总览**：描述整体架构、API 列表、流程 - **迭代变更**：描述增量改动 - **接入指南**：描述组件/SDK 的使用方式 - **其他**：标注类型 ### 第二步：按 7 个维度逐项检查 每个维度给出评分： - **PASS**：覆盖充分 - **PARTIAL**：有覆盖但存在缺口（列出具体缺什么） - **MISSING**：完全未覆盖 #### 维度 1：API 契约完整性 对文档中提到的每个 API 端点检查： - 请求字段是否列出：字段名、类型、是否必填、默认值、取值范围 - 响应结构是否以表格或结构化方式定义 - 是否有错误响应的定义（错误码、触发条件、响应格式） - 是否至少有一个调用示例 **常见缺口**：迭代文档新增了字段但从未汇总成完整 Schema；字段只列了名字没标必填/可选/默认值；响应结构只有文字描述没有结构化定义。 #### 维度 2：错误处理与降级 对文档中涉及的每个外部依赖（缓存、下游服务、文件系统等）检查： - 依赖不可用时的行为是否说明 - 超时和重试策略是否定义 - 降级/兜底逻辑是否描述 - 错误是否会传播给调用方，以什么形式 **常见缺口**：只描述了正常流程；"读 Redis"但没说 Redis 不可用或 key 不存在时怎么办；下游服务故障完全未提及。 #### 维度 3：配置与数据格式 对文档中提到的每个配置文件、数据文件、数据存储检查： - 格式是否说明（JSON/YAML/TSV 等），是否有结构示例 - 每个字段的名称、类型、含义、取值范围是否定义 - 键值存储（如 Redis）的 Key 格式和 Value 类型是否说明 **常见缺口**："从配置读取"但没给配置结构；"存入 Redis"但没给 Key 格式；引用了特征字段数量但没列出字段名。 #### 维度 4：业务规则精确度 对文档中的每条业务规则检查： - 是否精确到可以直接编写测试断言 - 数值边界是否明确（左闭右开？包含还是不包含？） - 多规则冲突时的优先级/执行顺序是否定义 - 涉及计算的公式是否显式给出 **常见缺口**："按条件过滤"但没列出条件；"按优先级排序"但没定义优先级计算方式；区间表示不明确。 #### 维度 5：跨文档一致性 - 同一字段在不同文档中名称是否一致 - 默认值在不同文档中是否矛盾 - 流程描述在总览和详细文档中是否一致 - 总览文档是否已同步所有迭代变更（是否过时） **常见缺口**：总览文档仍然描述迭代前的行为；迭代文档说"改 X 为 Y"但总览还写着 X；同一概念在不同文档中命名不同。 #### 维度 6：辅助/管理接口覆盖 - 所有管理类、查询类 API 是否列出 - 每个接口是否有请求/响应定义 - 用途是否清晰（用于数据初始化、状态查询还是调试） **常见缺口**：管理接口只在表格中列了一行但无任何详细定义；测试基础设施接口（初始化数据、查询结果）完全没有文档。 #### 维度 7：精炼度与可读性 - 同一信息是否在多处重复且措辞不一致 - 关键信息是否使用表格/列表呈现（而非埋在大段文字中） - 单篇文档是否聚焦一