# 真实终端与RTC/语音供应商一致性证据说明

## 1. 目标与最小矩阵

`cmd/rtc-conformance`把同一发布候选的终端身份、RTC房间、语音供应商任务、状态时间线、双向媒体、最终字幕、用量、质量结论和资源回收形成`real-device-rtc-conformance-report-v1`。它用于防止模拟供应商、单一语音方式或“能够入房”被误登记为真实通话闭环已经完成。

为降低重复测试强度，真实验收采用6通最小矩阵：

1. `s2s_pure`、`s2s_hybrid`、`cascade`各完成1次`NORMAL_COMPLETION`；
2. 另外各完成1次`TOKEN_RENEWAL`、`NETWORK_SWITCH_RECOVERY`和`CONTROLLED_STOP`，异常场景可分配到任一已批准方式；
3. 6通总体至少覆盖3台不同量产候选终端，每台至少参与1通。

协议模拟只能输出`PROTOCOL_SIMULATION/external_validation_required=true`。只有真实硬件与非模拟RTC/语音供应商证据完整时，报告才为`REAL_DEVICE_RTC_PROVIDER/external_validation_required=false`。

## 2. 单通通过标准

每通证据必须同时满足：

- 终端使用自己的受控身份创建通话，房间、设备RTC用户、Agent RTC用户和供应商任务引用完整且与其他通话不重复；
- 状态按`ROOM_ISSUED → STARTING_AGENT → ACTIVE → STOPPING → COMPLETED`收敛；
- 终端入房成功，上行、下行、近端音频发布和远端Agent音频播放均通过；
- 供应商启动和停止得到确认，同一稳定任务没有重复创建，终止后RTC与供应商资源已释放；
- 最终字幕可见，用量已归集，业务方采用现场冻结的质量方法判定`PASS`；校验器不虚构主观分数阈值；
- 凭证续签场景必须证明新短期凭证生效；网络切换场景必须证明媒体与状态恢复；
- 保存云端、设备、供应商、质量和用量五类脱敏证据引用。

不得把RTC Token、AppKey、AK/SK、设备密钥、原始录音、完整字幕正文或个人信息写入采集JSON。房间、用户和任务使用脱敏稳定引用即可。

## 3. 采集结构

输入使用`real-device-rtc-capture-v1`：

| 区域 | 关键字段 |
|---|---|
| 候选 | `candidate_version`、`build_digest`、`environment` |
| 供应商 | `rtc_provider_ref`、`voice_provider_ref`、`rtc_application_ref`、`region_ref` |
| 管理 | `change_ticket_ref`、执行人、独立复核人、复核/采集时间 |
| 终端 | 设备公开引用、型号、主板、固件、身份引用、音频配置引用 |
| 通话 | 方式、场景、房间/用户/任务引用、时间线、媒体、恢复、字幕、用量、质量、去重、回收和五类引用 |

真实采集的`evidence_source`固定为`HARDWARE_PROVIDER_CAPTURE`，环境只能为`STAGING`或`PRODUCTION`，执行人与复核人不能相同。模拟或本地工具使用`PROTOCOL_SIMULATION/LOCAL`。

## 4. 17项一致性检查

报告固定检查：采集模式、来源、候选身份、候选绑定、供应商身份、环境身份、设备覆盖、会话身份、三模式覆盖、四场景覆盖、RTC媒体路径、状态生命周期、凭证/网络恢复、供应商生命周期、字幕/用量/质量、证据引用和执行时间线。

`REAL_DEVICE_RTC`不可豁免。索引标记为`VERIFIED`时，第一个文件必须是同候选的`PASS/REAL_DEVICE_RTC_PROVIDER`报告。证据包中的`real_device_rtc_validation`汇总终端数、通话数、三模式、四场景及各自通话数量；协议模拟报告会被拒绝。

## 5. 现场执行流程

1. 冻结候选镜像、三种已发布路由模板、真实RTC应用、语音供应商资源和3台候选终端。
2. 依次执行三次正常闭环，确认终端不根据`engine_mode`改变固定媒体协议，只由云端选择供应商处理链。
3. 使用剩余三通覆盖短期凭证续签、Wi-Fi/蜂窝或批准网络之间切换恢复、设备/运营发起的受控停止。
4. 每通结束后核对供应商任务、云端状态、最终字幕、用量、质量记录和资源回收；发现不确定启动时确认稳定TaskId重试未产生重复任务。
5. 由独立复核人核对脱敏引用后生成报告：

```powershell
go run ./cmd/rtc-conformance `
  -capture E:\evidence\real-device-rtc-capture.json `
  -candidate-version 0.63.0-rc.1 `
  -build-digest sha256:<64位摘要> `
  -output E:\evidence\real-device-rtc-report.json
```

6. 将报告作为`REAL_DEVICE_RTC`首个文件，重建候选证据包并确认`coverage_complete=true`。

本地只验证结构工具链：

```powershell
.\scripts\smoke-rtc-conformance-toolchain.ps1
```

该脚本不会连接真实RTC，不修改业务数据，也不会把模拟结果计入真机门禁。