# 人工伴随件模板 + 示例 —— 单一文件 `review_notes.md`(阻塞区 + 非阻塞区,合一)

> **只产一个文件 `review_notes.md`**(单一人工伴随件),内分两区、上下排布:
> - **阻塞区(在文件最上方)**:不处理则该用例**没法执行/没法判真**(跨 App、白盒、需构造特殊数据、空态执行顺序例外 等)。必须人工兜。
> - **非阻塞区(接在阻塞区之后)**:给人看的待办,**不挡执行**;每条标 `【优先级·高/中/低/无需动作】`(指对测试质量/覆盖的影响)。
>
> **绝不拆成两个文件**:不要再单独产 `manual-intervention.md` —— 阻塞内容是本文件顶部的一个区,不是另一个文件。同时存在多个伴随件会被 `validate.ts` 的 `manual_intervention_forbidden` / `companion_not_merged` 判 **FAIL**。
> **交付自包含**:无论内容由 generator、validator 还是 S6 写入/合并,最终的 `review_notes.md` 都必须单独可读。人工处理所需的未决项、原因、引文与建议直接写在文档内;不把过程产物、工作目录或本机绝对路径当作必需上下文。过程位置只留在运行日志。
> **写作者须按本文档结构产出**:有内容才出、空分类整段折叠;若阻塞区整体无内容则连同 `## 阻塞区` 标题一起省略,文件直接以非阻塞区起头。
> **示例边界**:以下内容仅示范文档结构与信息粒度;实体名称、数量、界面文案和场景内容必须来自当前输入的 SPEC / 适用参考资料,不得复用示例中的歌单内容。

---

## 完整示例 · 一个 `review_notes.md`(阻塞区在上 + 非阻塞区在下)— 被测应用「新建歌单」SPEC-01

> 下面**整块就是一个文件**:`# ...` 是文件标题,`## 阻塞区` / `## 非阻塞区` 是它的上下两半,`###` 是各自的小节。

```markdown
# 人工伴随件(review_notes.md)— 被测应用「新建歌单」SPEC-01

## 阻塞区 —— 不处理则对应用例无法执行/无法判真

### 【阻塞·跨应用】须人工在真机执行
- [ ] SPEC-01 Scenario 1-X [SKIP: 跨应用]「把歌单分享到系统分享面板→某 IM」: 动作跨出被测应用,自动化框架不可控 —— 须人工真机执行并回填结果。

### 【阻塞·特殊数据】须先构造测试数据(用例本身是正常用例,前置标「特殊测试数据」;不想构造可删该用例)
- [ ] SPEC-01 Scenario 1-Y(正常用例,非 SKIP)「歌单数量达上限后再新建」: 需预置约 N 个歌单才能触发上限 —— 须人工/脚本先构造该数据,这条才能跑;不想构造就删这条。

### 【阻塞·白盒】须查日志/DB,无 UI 出口
- [ ] SPEC-01 Scenario 1-Z [SKIP: 白盒]「歌单名首尾空白被后台去除」: 去空白是后台逻辑、UI 无稳定可观测出口 —— 须查存储/日志确认。

### 【阻塞·特殊执行顺序】须排在特定时刻执行(空态/冲突态用例,见 contract §4 类别三)
- [ ] SPEC-01 Scenario 1-W(空态用例,[推导])「全新安装无任何歌单时显示空态占位」: 须在执行任何前置段之前、于全新安装态运行 —— 一旦跑过建歌单的前置段,列表不再为空,该用例无法满足。

## 非阻塞区 —— 测试用例审查 TODO List(不挡执行)

> 优先级说明:【优先级·X】指对本次测试质量/覆盖的影响,非阻塞执行(阻塞的在上面 ## 阻塞区)。

### 【优先级·低】【请核对前缀是否清晰】公共操作前缀
> 请确认前缀是否清晰准确。

- [ ] SPEC-01 公共动作前缀(覆盖 4 个 Scenario,前缀长度 4 步,入口=主页 → 状态=新建歌单对话框):
      `打开 被测应用 -> 进入歌单页面 -> 点击更多菜单 -> 点击「新建歌单」按钮`

### 【优先级·低】【请决定是否补全】未派生的列举操作
- [ ] SPEC-01 名称长度边界(共 3 项):已派生「150 字符(超长)」,未派生「恰好上限值」「上限+1」—— plan 未明确上限是否含等于,按"≤上限合法"推导,请人工确认产品行为。
- [ ] SPEC-01 排序方式共 10 项:已保留「标题」与「添加到歌单时间」,其余排序项的操作和检查点相同,暂不逐项展开;请确认是否需要补全。
- [ ] SPEC-01 多入口 A/B:最终进入同一个流程、检查同一批结果,已选 2 个代表入口;请确认是否还需要覆盖更多入口组合。

### 【优先级·中】【请核对重写是否符合预期】含糊 TP 重写
- [ ] SPEC-01 Scenario 1-1 TP-1: 原文「提示输入有误」→ 重写为「弹出 toast「歌单名称不得为空」」(原文未指明文案,按 plan 错误提示推导)。

### 【优先级·高】【请补全具体预期】需人工补预期的 TP
- [ ] SPEC-01 Scenario 1-3 TP-2「该歌单仍可见」: 缺失方向 —— 未明确"可见"的判定位置(列表首位 / 任意位置),建议补观测点。

### 【优先级·中】【请协调人工/帧级抓取】SKIP·人工资源交还
> 写成 [SKIP: <reason>] 的意图,声明应有结果 + 交还给谁(对应 contract #5)。

- [ ] SPEC-01 Scenario 1-7 [SKIP: 不可观测]「点击确定瞬时 loading 指示」: 应有 —— 点击确定后瞬时出现 loading 指示;当前无法稳定观测该帧,**交还人工/帧级抓取**。

### 【优先级·低】【请反馈给 ui_elements 维护人】UI 元素覆盖缺失
> ui_elements 是软参照,缺失只记疑点、不阻塞(对应不变量 5)。

- [ ] SPEC-01: 元素「确定」「取消」按钮(位于新建歌单对话框内)未在 ui_elements.json 中定义,影响场景: Scenario 1-1 ~ 1-7(全部)。
- [ ] SPEC-01: 页面「新建歌单对话框」未在 ui_elements.json 的 pages[] 中独立定义,影响场景: 全部。

### 【优先级·中】【语义校验裁决,请确认】语义校验补充判断需确认
> 来自 validator(语义校验)的带引用裁决:补的判断须能说出依据(对应 contract #1 有源)。

- [ ] SPEC-01 特殊字符名称[推导]: SPEC 未对特殊字符设约束,语义校验按「非空且 ≤上限即合法」补一条判断(语义派生、非字面触发词),依据已记 `## 场景来源映射`;建议人工确认产品是否有过滤规则。

### 【优先级·低】【NIBV/缺口 > 0 时关注】覆盖率自评
| 有效 | 弱断言 | 不适用 | 冗余 | 漏测 |
|-----|-------|-------|-----|-----|
| 6   | 1     | 0     | 0   | 0   |
- [ ] 弱断言 1 条:见上「含糊 TP 重写」Scenario 1-1 TP-1,已重写。

### 【优先级·中】【请逐条决策】其他需人工关注事项
- [ ] SPEC-01: 多入口(歌单页 / 歌曲页「添加到歌单」弹窗)被判为 B 类(同组件同 oracle),抽样 2 入口未做笛卡尔,请确认采样可接受。
```

---

> 说明:上面是**示例**(填好的样子,**整体是一个文件**)。真实跑批时:阻塞区由 generator 的 SKIP 记账(跨应用/白盒)+ 须先构造的特殊数据 + 空态执行顺序例外汇成;非阻塞区由 generator(剪枝/采样记账 + 桩实现背景知悉项)与 validator(语义校验裁决)写入。**两区同处一个 `review_notes.md`,有内容才出、空分类折叠;绝不拆成第二个文件。**