# 报告格式说明

`qf_report` 产出两份文件，它们是同一份数据的两种呈现：

| 文件 | 用途 | 谁在用 |
| --- | --- | --- |
| `.qualityforge/QUALITYFORGE-REPORT.md` | 人类可读、**可逐条勾选** | 开发者评审、勾选修复范围、复测确认 |
| `.qualityforge/report.json` | 机器可读快照 | CI 门禁、看板、与其它系统集成 |
| `.qualityforge/audit.json` | 唯一真相来源 | 所有工具读写它；报告由它渲染 |

**报告是可再生的**：`audit.json` 不变，渲染结果就不变（同一 revision 永远得到同一份 Markdown），
因此报告可以安全地进代码评审、做 diff。

## 章节结构与用途

| 章节 | 内容 | 读者要做什么 |
| --- | --- | --- |
| 0 使用说明 | 勾选方式、如何把报告发回 Harness | 先读这一节 |
| 1 结论摘要 | 交付判定 + 关键计数 + 通过率 | 判断能不能交付 |
| 2 优先级与严重度分布 | 按 P0–P3 的分布、按测试域分布 | 判断风险结构 |
| 3 修复波次 | Wave 1 阻断级清零 → Wave 2 严重级收敛 → … | 决定修复顺序 |
| 4 问题清单 | **每条缺陷一行复选框**，含期望/实测/证据/复现/建议/位置 | 逐条修复并勾选 |
| 5 全部测试项核对表 | 按测试域 → 方法分组的全量清单（含通过项） | 证明覆盖度、抽查结论 |
| 6 未展开/不适用项 | 按项目类型被裁剪的项与原因 | 确认裁剪是否合理 |
| 7 执行证据 | 命令、退出码、耗时、失败输出尾部、探针结果 | 复核自动结论 |
| 8 项目画像 | 技术栈、类型、命令、工具链与已确认缺口 | 理解结论背景 |
| 9 复测与签署 | 修复确认 / 复测确认 / 发布批准 | 签署留痕 |

## 勾选语义（`qf_update sync=true` 如何解读）

复选框只表达"**这一条已经处理**"，不表达"已经复测通过"。同步规则：

| 报告中的写法 | 同步后的状态 | 含义 |
| --- | --- | --- |
| `- [ ] **QF-001** …` | 保持不变 | 未处理 |
| `- [x] **QF-001** …`（原为未通过/阻塞） | 已修复待复测 `fixed` | 开发者声明修好了，等待复测 |
| `- [x] **QF-001** …`（原为待测） | 通过 `pass` | 人工确认该条通过 |
| `- [x] **QF-001** … \`WONTFIX\`` | 接受风险 `wontfix` | 明确接受风险，不再修 |
| `- [x] **QF-001** … \`DEFER\`` | 延后 `deferred` | 有排期的延后 |
| `- [x] **QF-001** … \`NA\`` | 不适用 `na` | 该条确实不适用 |
| 取消勾选已关闭的条目 | 重新打开 `pending` | 复测发现问题，重新打开 |

只有 Harness 复测成功后才会置为 **复测通过 `verified`**——这样"修复"与"验证"不会被混为一谈。

同一编号在报告中出现两次（第 4 节问题清单与第 5 节核对表）。解析时**以文档中首次出现的为准**，
两处不一致会作为 `conflicts` 返回，要求人工确认，而不是静默选一个。

## 交付判定（闸门）

| 判定 | 触发条件 |
| --- | --- |
| ⛔ 不可交付 | 存在 P0 阻断级缺陷 |
| ⏳ 审计未完成 | 无 P0 缺陷，但待测项占比 > 25% |
| ⚠️ 有条件交付 | 无 P0、待测项已收敛，但存在 P1 严重级缺陷 |
| ✅ 可交付 | 无未关闭缺陷 |

判定刻意把"审计未完成"独立成一档：一份只跑了三成测试项的报告，不应该被读成"通过"。

## 修复范围协商

`qf_fixplan` 的 `scope` 参数就是把报告变成修复指令的方式：

| scope | 范围 | 典型说法 |
| --- | --- | --- |
| `all` | 全部未关闭项 | "全部修复" |
| `p0` | 仅 P0 阻断级 | "先让项目能发布" |
| `p0-p1` | P0 + P1 | "修最小可交付范围" |
| `defects` | 全部未通过/阻塞（默认） | "把缺陷都修了" |
| `pending` | 仅待测项 | "先把没测的测完" |
| `ids` + `excludeIds` | 指定/排除编号 | "除了 QF-003 之外全修" |

输出含可直接粘贴给 Harness 的**交接单**（`format=handoff` 或 `writeFile=true`），
其中包含每条问题的期望、实测、位置与建议，以及修复约束（不改范围外代码、必须可验证、
完成后回写勾选状态）。