Excel 的质量管控文档设计
下面是一套可直接落地为 Excel 的质量管控文档设计，适用于交付项目型研发团队 + AI 编码 + SDD（Spec Driven Development）模式。
建议 Excel 包含以下 6 个 Sheet：
- 《总览-质量门禁》
- 《节点1-需求Spec质量》
- 《节点2-接口文档与接口质量》
- 《节点3-单元测试质量》
- 《节点4-冒烟测试质量》
- 《问题跟踪与整改》
Sheet 1：《总览-质量门禁》
| 阶段 | 质量节点 | 主责角色 | 参与角色 | 准入条件 | 准出条件 | 主要产物 | 是否必须通过 | 未通过处理 |
|---|---|---|---|---|---|---|---|---|
| 需求阶段 | 需求 Spec 质量 | 产品经理 | 项目经理、开发、测试 | 项目范围明确，已有原始需求或客户输入 | Spec 评审通过，无 P0/P1 疑问未关闭 | 需求 Spec、验收标准、业务规则、异常场景 | 是 | 禁止进入开发 |
| 设计阶段 | 接口文档和接口质量 | 开发 | 产品经理、测试、项目经理 | 需求 Spec 已通过 | 接口文档评审通过，Mock 或联调契约明确 | API 文档、字段说明、错误码、Mock 数据 | 是 | 禁止接口开发或联调 |
| 开发阶段 | 单元测试质量 | 开发 | 测试、项目经理 | 接口设计明确，代码开发完成 | 单测通过率、覆盖率达标，无阻塞缺陷 | 单测代码、覆盖率报告、AI 生成代码审查记录 | 是 | 禁止提测 |
| 提测阶段 | 冒烟测试质量 | 测试 | 开发、产品经理、项目经理 | 开发自测完成，部署到测试环境 | 核心链路冒烟通过，无阻塞问题 | 冒烟用例、测试报告、缺陷记录 | 是 | 打回开发修复 |
Sheet 2：《节点1-需求 Spec 质量》
| 检查维度 | 检查项 | 具体质量标准 | 准入条件 | 准出条件 | 操作步骤 | 主责角色 | 参与角色 | 检查方式 | 产物/证据 | 结果 |
|---|---|---|---|---|---|---|---|---|---|---|
| 需求完整性 | 是否包含业务背景 | 说明业务目标、用户角色、使用场景、业务价值 | 已有客户需求、会议纪要或合同范围 | 背景描述清晰，无重大遗漏 | 产品经理整理业务背景；项目经理确认范围 | 产品经理 | 项目经理 | 人工评审 | 需求 Spec 文档 | 通过/不通过 |
| 需求完整性 | 是否包含功能范围 | 明确做什么、不做什么，边界清晰 | 原始需求已收集 | 功能边界无歧义 | 列出功能清单、非功能清单、排除项 | 产品经理 | 开发、测试 | 评审会议 | 功能范围清单 | 通过/不通过 |
| 需求明确性 | 是否存在模糊描述 | 不出现“尽量”“大概”“支持一下”“优化”等不可验证描述 | 初版 Spec 已完成 | 所有描述可被开发和测试理解 | 使用 AI 辅助检查模糊词；产品经理修订 | 产品经理 | 开发、测试 | AI 检查 + 人工复核 | 模糊项整改记录 | 通过/不通过 |
| 需求可测试性 | 是否定义验收标准 | 每个需求至少有一条可验证的验收标准 | 功能点已拆分 | 验收标准覆盖正常、异常、边界场景 | 按 Given-When-Then 编写验收标准 | 产品经理 | 测试 | 用例反推 | 验收标准列表 | 通过/不通过 |
| 业务规则 | 是否列出业务规则 | 规则包含条件、计算逻辑、状态流转、权限控制 | 需求场景明确 | 规则无冲突、无遗漏 | 梳理规则表、状态机、权限矩阵 | 产品经理 | 开发、测试 | 评审 | 业务规则表 | 通过/不通过 |
| 异常场景 | 是否覆盖异常和边界 | 包含空值、重复、超限、无权限、数据不存在、并发等场景 | 主流程已明确 | 异常场景有处理规则 | 测试基于 Spec 补充异常场景 | 测试 | 产品经理、开发 | 测试评审 | 异常场景清单 | 通过/不通过 |
| 数据要求 | 是否明确数据字段 | 字段名称、类型、必填、默认值、取值范围清晰 | 功能设计完成 | 字段定义可支撑接口设计 | 产品经理列字段，开发补充技术约束 | 产品经理 | 开发 | 文档检查 | 字段说明表 | 通过/不通过 |
| 权限要求 | 是否明确角色权限 | 不同角色可见、可操作范围明确 | 用户角色已定义 | 权限矩阵评审通过 | 建立角色-功能-数据权限矩阵 | 产品经理 | 开发、测试 | 权限矩阵检查 | 权限矩阵 | 通过/不通过 |
| 非功能需求 | 是否包含性能、安全、兼容性要求 | 有明确指标，如响应时间、并发量、日志、安全限制 | 项目交付标准明确 | 指标可验证、可测试 | 项目经理协调客户确认指标 | 项目经理 | 产品、开发、测试 | 评审 | 非功能需求表 | 通过/不通过 |
| AI 编码准备 | 是否适合 AI 编码输入 | Spec 结构化、无歧义、可拆分为开发任务 | Spec 初版完成 | 可作为 AI Prompt 或 SDD 输入 | 将 Spec 拆为用户故事、任务、验收条件 | 产品经理 | 开发 | AI Prompt 检查 | AI 编码输入文档 | 通过/不通过 |
Sheet 3：《节点2-接口文档和接口质量》
| 检查维度 | 检查项 | 具体质量标准 | 准入条件 | 准出条件 | 操作步骤 | 主责角色 | 参与角色 | 检查方式 | 产物/证据 | 结果 |
|---|---|---|---|---|---|---|---|---|---|---|
| 接口完整性 | 是否覆盖所有功能接口 | 每个功能点都有对应接口或说明无需接口 | 需求 Spec 已通过 | 接口清单完整，无遗漏 | 开发根据 Spec 输出接口清单 | 开发 | 产品、测试 | Spec 对照检查 | 接口清单 | 通过/不通过 |
| 接口定义 | 是否包含基本信息 | 包含接口名称、URL、Method、描述、调用方、提供方 | 接口清单完成 | 信息完整，命名规范 | 按统一模板编写接口文档 | 开发 | 测试 | 文档检查 | API 文档 | 通过/不通过 |
| 请求参数 | 是否明确请求参数 | 字段名、类型、是否必填、默认值、枚举、长度、示例齐全 | 接口定义完成 | 参数无歧义，可直接开发和测试 | 开发补充请求字段说明 | 开发 | 测试 | 文档检查 | 请求参数表 | 通过/不通过 |
| 响应参数 | 是否明确响应结构 | 返回码、message、data 结构、分页结构、空数据结构明确 | 请求参数完成 | 前后端可基于文档联调 | 开发补充响应示例 | 开发 | 前端/测试 | Mock 校验 | 响应示例 | 通过/不通过 |
| 错误码 | 是否定义错误码 | 错误码统一、语义明确、处理建议清晰 | 接口流程明确 | 常见异常均有错误码 | 维护错误码表 | 开发 | 测试 | 异常场景对照 | 错误码表 | 通过/不通过 |
| 权限控制 | 是否说明鉴权逻辑 | 登录态、角色权限、数据权限、Token 规则明确 | 权限需求明确 | 权限校验点清晰 | 根据权限矩阵标注接口权限 | 开发 | 产品、测试 | 权限用例检查 | 接口权限说明 | 通过/不通过 |
| 幂等与并发 | 是否考虑重复提交和并发 | 涉及新增、支付、审批、状态变更类接口必须说明幂等策略 | 业务规则明确 | 幂等规则和并发处理方式确认 | 开发设计幂等 Key、锁或状态校验 | 开发 | 测试 | 设计评审 | 幂等设计说明 | 通过/不通过 |
| 数据校验 | 是否定义参数校验规则 | 必填、格式、范围、枚举、跨字段校验明确 | 参数定义完成 | 校验失败返回明确错误码 | 开发补充校验规则 | 开发 | 测试 | 用例反推 | 参数校验表 | 通过/不通过 |
| Mock 支持 | 是否提供 Mock 数据 | 核心接口提供成功、失败、空数据、异常示例 | API 文档完成 | 前端/测试可提前验证 | 使用工具生成 Mock 或示例 JSON | 开发 | 测试 | Mock 调用 | Mock 地址/JSON | 通过/不通过 |
| 接口可测性 | 是否可被自动化测试 | 接口可通过 Postman、Apifox、JMeter 等工具调用 | 测试环境或 Mock 可用 | 核心接口具备自动化验证基础 | 测试编写接口测试集合 | 测试 | 开发 | 工具执行 | 接口测试集合 | 通过/不通过 |
| AI 编码适配 | 是否可作为 AI 生成代码输入 | 接口文档结构清晰，可生成 Controller、DTO、Client、测试代码 | 接口文档完成 | AI 生成代码无需二次猜测字段含义 | 开发将接口文档输入 AI 生成代码初稿 | 开发 | 项目经理 | AI 输出审查 | AI 生成代码记录 | 通过/不通过 |
Sheet 4：《节点3-单元测试质量》
| 检查维度 | 检查项 | 具体质量标准 | 准入条件 | 准出条件 | 操作步骤 | 主责角色 | 参与角色 | 检查方式 | 产物/证据 | 结果 |
|---|---|---|---|---|---|---|---|---|---|---|
| 单测范围 | 是否覆盖核心业务逻辑 | 核心服务、规则计算、状态流转、权限判断必须覆盖 | 代码开发完成 | 核心逻辑覆盖率达标 | 开发根据 Spec 和业务规则编写单测 | 开发 | 测试 | 代码检查 | 单测代码 | 通过/不通过 |
| 覆盖率 | 单测覆盖率是否达标 | 行覆盖率建议 ≥ 70%，核心模块 ≥ 80%，关键方法必须覆盖 | 单测可运行 | 覆盖率报告达标 | 执行覆盖率工具，如 JaCoCo、Coverage.py | 开发 | 项目经理 | 工具检查 | 覆盖率报告 | 通过/不通过 |
| 用例完整性 | 是否覆盖正常场景 | 每个核心方法至少覆盖一个正常路径 | 单测框架已配置 | 正常路径全部通过 | 基于验收标准设计单测 | 开发 | 测试 | 单测执行 | 单测报告 | 通过/不通过 |
| 异常场景 | 是否覆盖异常输入 | 空值、非法值、越界、无权限、状态不合法等场景有测试 | 异常规则明确 | 异常断言明确 | 使用 AI 生成异常测试用例，开发复核 | 开发 | 测试 | 单测执行 | 异常用例 | 通过/不通过 |
| 边界场景 | 是否覆盖边界值 | 最小值、最大值、临界状态、空集合、大集合等有测试 | 字段规则明确 | 边界断言通过 | 根据字段约束生成边界用例 | 开发 | 测试 | 单测执行 | 边界用例 | 通过/不通过 |
| 断言质量 | 是否有有效断言 | 禁止只调用不断言；断言必须验证关键输出、状态或异常 | 单测已编写 | 无无效单测 | Review 单测断言 | 开发 | 测试 | Code Review | Review 记录 | 通过/不通过 |
| Mock 使用 | 外部依赖是否 Mock | 数据库、第三方服务、消息队列、远程接口应 Mock 或隔离 | 依赖清单明确 | 单测可独立稳定运行 | 使用 Mock 框架隔离外部依赖 | 开发 | 测试 | 单测执行 | Mock 配置 | 通过/不通过 |
| 可重复执行 | 单测是否稳定 | 连续执行 3 次均通过，不依赖执行顺序、不依赖脏数据 | 单测环境可用 | 无随机失败 | CI 或本地重复执行 | 开发 | 项目经理 | CI 检查 | CI 报告 | 通过/不通过 |
| AI 生成代码审查 | AI 生成代码是否经过人工审查 | AI 生成代码必须进行逻辑、安全、性能、边界检查 | AI 参与编码 | 审查问题已关闭 | 开发提交 AI 代码审查清单 | 开发 | 项目经理 | Code Review | 审查记录 | 通过/不通过 |
| 静态扫描 | 是否通过静态代码检查 | 无阻塞级问题，无高危安全漏洞，无明显重复代码 | 代码提交完成 | 静态扫描通过 | 执行 SonarQube、Lint 等工具 | 开发 | 项目经理 | 工具扫描 | 扫描报告 | 通过/不通过 |
| 提测门禁 | 是否满足提测条件 | 单测通过率 100%，覆盖率达标，无 P0/P1 缺陷 | 开发自测完成 | 允许提交测试 | 开发填写提测单并附报告 | 开发 | 测试、项目经理 | 提测审核 | 提测单 | 通过/不通过 |
Sheet 5：《节点4-冒烟测试质量》
| 检查维度 | 检查项 | 具体质量标准 | 准入条件 | 准出条件 | 操作步骤 | 主责角色 | 参与角色 | 检查方式 | 产物/证据 | 结果 |
|---|---|---|---|---|---|---|---|---|---|---|
| 提测准入 | 是否满足提测条件 | 代码合并完成、部署成功、单测通过、接口文档更新 | 开发提交提测单 | 测试确认可测 | 测试检查提测材料 | 测试 | 开发、项目经理 | 提测单检查 | 提测单 | 通过/不通过 |
| 环境可用 | 测试环境是否可用 | 服务正常启动，数据库、缓存、队列、第三方依赖可用 | 部署完成 | 环境无阻塞问题 | 测试执行环境健康检查 | 测试 | 开发 | 环境检查 | 环境检查记录 | 通过/不通过 |
| 核心链路 | 是否覆盖主流程 | 覆盖用户登录、核心业务新增/查询/修改/提交/审批等主链路 | 环境可用 | 核心链路全部通过 | 测试执行冒烟用例 | 测试 | 产品、开发 | 手工/自动化执行 | 冒烟测试报告 | 通过/不通过 |
| 接口冒烟 | 核心接口是否可调用 | 核心接口返回正常，响应结构符合文档 | 接口服务启动 | 核心接口全部通过 | 使用 Apifox/Postman 执行接口集合 | 测试 | 开发 | 工具执行 | 接口冒烟报告 | 通过/不通过 |
| 页面冒烟 | 页面是否可访问和操作 | 核心页面无白屏、无阻塞 JS 错误、按钮和表单可用 | 前端部署完成 | 核心页面操作通过 | 测试访问核心页面并操作 | 测试 | 开发 | 手工检查 | 页面截图/录屏 | 通过/不通过 |
| 权限冒烟 | 基础权限是否正确 | 不同角色只能访问授权功能和数据 | 测试账号准备完成 | 权限无重大问题 | 使用不同角色账号执行冒烟 | 测试 | 产品 | 用例执行 | 权限测试记录 | 通过/不通过 |
| 数据正确性 | 关键数据是否落库正确 | 新增、修改、状态流转、金额、数量等关键数据正确 | 主流程可执行 | 数据与预期一致 | 测试通过页面/API/数据库校验 | 测试 | 开发 | 数据核对 | 数据验证记录 | 通过/不通过 |
| 异常提示 | 基础异常提示是否正确 | 必填、格式错误、权限不足、数据不存在有明确提示 | 主流程通过 | 无明显错误提示或空白提示 | 测试执行基础异常操作 | 测试 | 产品 | 手工测试 | 异常截图 | 通过/不通过 |
| 缺陷级别 | 是否存在阻塞缺陷 | 不允许存在 P0/P1 缺陷；P2 需评估是否影响继续测试 | 冒烟执行中 | 阻塞缺陷清零 | 测试记录缺陷，开发修复 | 测试 | 开发、项目经理 | 缺陷评审 | 缺陷单 | 通过/不通过 |
| 冒烟结论 | 是否允许进入系统测试 | 冒烟通过率 100%，无阻塞问题 | 冒烟执行完成 | 允许进入正式测试 | 测试出具冒烟结论 | 测试 | 项目经理 | 报告确认 | 冒烟测试报告 | 通过/不通过 |
Sheet 6：《问题跟踪与整改》
| 问题编号 | 所属节点 | 问题描述 | 问题等级 | 发现人 | 责任人 | 发现日期 | 计划解决日期 | 实际解决日期 | 当前状态 | 解决方案 | 验证人 | 验证结果 | 备注 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Q-001 | 需求 Spec 质量 | 需求中“优化查询效率”无明确指标 | P1 | 开发 | 产品经理 | 2025/01/01 | 2025/01/02 | 待处理 | 补充响应时间指标，如 2 秒内返回 | 测试 | 待验证 | ||
| Q-002 | 接口文档和接口质量 | 查询接口缺少分页参数说明 | P2 | 测试 | 开发 | 2025/01/01 | 2025/01/02 | 待处理 | 补充分页字段 pageNo/pageSize/total | 测试 | 待验证 | ||
| Q-003 | 单元测试质量 | 核心价格计算方法无边界测试 | P1 | 测试 | 开发 | 2025/01/01 | 2025/01/02 | 待处理 | 增加最大值、最小值、折扣为空等用例 | 测试 | 待验证 | ||
| Q-004 | 冒烟测试质量 | 提交审批后状态未更新 | P0 | 测试 | 开发 | 2025/01/01 | 2025/01/01 | 修复中 | 排查状态流转逻辑 | 测试 | 待验证 |
角色视角检查表
项目经理角色检查表
| 质量节点 | 项目经理关注点 | 必做动作 | 准入检查 | 准出确认 | 质量标准 |
|---|---|---|---|---|---|
| 需求 Spec 质量 | 范围、计划、交付边界 | 组织需求评审，确认需求是否可进入开发 | 客户需求或合同范围明确 | Spec 评审通过，遗留问题有负责人和时间 | 无 P0/P1 需求疑问 |
| 接口文档和接口质量 | 联调风险、跨端协作 | 确认接口评审是否完成 | Spec 已冻结或基线化 | 接口文档通过评审 | 接口变更可追踪 |
| 单元测试质量 | 开发提测质量 | 检查单测报告、覆盖率报告、静态扫描报告 | 代码开发完成 | 单测通过率 100%，覆盖率达标 | 不允许无报告提测 |
| 冒烟测试质量 | 是否允许进入正式测试 | 跟踪冒烟缺陷关闭情况 | 提测材料完整 | 冒烟通过，无 P0/P1 | 不通过则打回开发 |
产品经理角色检查表
| 质量节点 | 产品经理关注点 | 必做动作 | 准入检查 | 准出确认 | 质量标准 |
|---|---|---|---|---|---|
| 需求 Spec 质量 | 需求清晰、完整、可验收 | 编写 Spec、验收标准、业务规则 | 原始需求明确 | 开发和测试无重大理解偏差 | 每个功能都有验收标准 |
| 接口文档和接口质量 | 接口是否符合业务语义 | 参与接口评审，确认字段和业务含义 | Spec 已通过 | 关键字段、状态、错误提示符合业务 | 不得与业务规则冲突 |
| 单元测试质量 | 核心业务规则是否被覆盖 | 协助确认核心规则测试点 | 业务规则已明确 | 核心规则有测试覆盖 | 关键规则不遗漏 |
| 冒烟测试质量 | 主流程是否符合验收预期 | 参与核心链路验收 | 冒烟环境可用 | 主流程符合产品预期 | 核心业务可正常流转 |
开发角色检查表
| 质量节点 | 开发关注点 | 必做动作 | 准入检查 | 准出确认 | 质量标准 |
|---|---|---|---|---|---|
| 需求 Spec 质量 | 是否可开发、无歧义 | 评审需求，提出技术疑问 | Spec 初稿完成 | 技术疑问关闭 | 不带疑问进入编码 |
| 接口文档和接口质量 | 接口可实现、可联调 | 编写接口文档、Mock、错误码 | Spec 通过 | 接口文档评审通过 | 字段、参数、响应、错误码完整 |
| 单元测试质量 | 代码正确性和稳定性 | 编写单测、执行覆盖率、静态扫描 | 代码完成 | 单测和扫描通过 | 单测通过率 100%，覆盖率达标 |
| 冒烟测试质量 | 缺陷快速修复 | 支持测试环境和问题定位 | 提测完成 | 冒烟问题关闭 | P0/P1 必须当天响应 |
测试角色检查表
| 质量节点 | 测试关注点 | 必做动作 | 准入检查 | 准出确认 | 质量标准 |
|---|---|---|---|---|---|
| 需求 Spec 质量 | 需求是否可测试 | 评审 Spec，补充异常和边界场景 | Spec 初稿完成 | 测试疑问关闭 | 每个需求可设计测试用例 |
| 接口文档和接口质量 | 接口是否可测 | 检查接口参数、响应、错误码、Mock | 接口文档初稿完成 | 可编写接口测试 | 接口无明显缺字段 |
| 单元测试质量 | 是否达到提测质量 | 检查单测报告和核心场景覆盖 | 开发提交报告 | 允许提测 | 关键逻辑有单测覆盖 |
| 冒烟测试质量 | 是否允许进入正式测试 | 执行冒烟用例，输出报告 | 测试环境可用 | 冒烟通过 | 核心链路 100% 通过 |
推荐 Excel 字段下拉值
结果字段
| 字段 | 可选值 |
|---|---|
| 结果 | 通过 / 不通过 / 不适用 / 待确认 |
问题等级
| 等级 | 说明 |
|---|---|
| P0 | 阻塞交付或主流程不可用 |
| P1 | 严重影响核心功能或存在重大理解偏差 |
| P2 | 一般问题，不阻塞主流程 |
| P3 | 优化建议或轻微问题 |
当前状态
| 状态 | 说明 |
|---|---|
| 待处理 | 问题已发现但未开始处理 |
| 处理中 | 责任人正在处理 |
| 待验证 | 已修复，等待验证 |
| 已关闭 | 验证通过 |
| 挂起 | 暂不处理，需说明原因 |
四个节点统一准入准出汇总
| 质量节点 | 准入 | 准出 |
|---|---|---|
| 需求 Spec 质量 | 有原始需求、客户输入、合同范围或会议纪要 | Spec 评审通过，需求清晰、完整、可测试、可用于 AI 编码 |
| 接口文档和接口质量 | 需求 Spec 已通过或基线化 | API 文档完整，Mock/错误码/权限/异常/字段说明清晰 |
| 单元测试质量 | 代码开发完成，接口设计明确 | 单测通过率 100%，覆盖率达标，静态扫描无阻塞问题 |
| 冒烟测试质量 | 提测单完整，部署成功，开发自测完成 | 核心链路通过，无 P0/P1 缺陷，可进入正式测试 |