# 真实环境测试交接

## 1. 何时交接

只有 [质量门禁](quality-gates.md) 的 RC 自动化退出条件全部满足，才进入本清单。以下情况不属于
真实环境阻塞，必须由开发阶段解决：

- 本地依赖无法安装或镜像无法构建。
- 虚拟设备协议不一致。
- Fake Provider 成功/错误/取消契约失败。
- 数据库、Redis、文件权限或配置广播失败。
- 缺少测试脚本、日志字段或复现步骤。

## 2. 外部资产

| 资产 | 最低要求 | 提供方 |
| --- | --- | --- |
| ESP32 | 至少一台生产使用型号；记录固件版本 | Hardware QA |
| 网络 | 局域网与公网 WSS；可控制弱网/断网 | Ops/QA |
| 模型凭证 | 实际计划启用的 ASR、LLM、TTS，必要时 VLLM | Service owner |
| MQTT/UDP | 受支持版本的 gateway、broker 和端口 | Integration/Ops |
| RAGFlow | 受支持版本、测试数据集和访问凭证 | Knowledge owner |
| 可选服务 | 短信、声纹、语音克隆、MCP、Memory | 对应服务 owner |
| 目标主机 | 计划上线的 CPU/GPU/架构、Docker/Compose 或编排平台 | Ops |
| 域名证书 | HTTPS/WSS 域名、证书和反向代理权限 | Ops |

凭证不得写入 Issue、PR、测试产物或仓库；通过部署环境的 Secret 管理提供。

## 3. 必测场景

### 设备与音频

- 首次启动、OTA、激活和绑定。
- WebSocket 鉴权和长连接保持。
- 唤醒、单轮/连续对话、打断、静音超时和重连。
- 真实麦克风、扬声器、AEC、Opus 帧节奏和中文/非中文语音。
- 弱网、高延迟、短时断网和服务滚动发布。

### Provider

- 每个计划启用 Provider 的成功、流式、空结果、超时、限流和凭证错误。
- ASR 音频格式、TTS 音频参数、LLM 工具调用及取消行为。
- 供应商控制台侧请求量、错误和费用符合预期。

### 外部集成

- MQTT/UDP 上下行音频与控制消息。
- RAGFlow 上传、解析、检索、删除和故障补偿。
- Vision 图片上传、鉴权、大小/格式限制和真实结果。
- 按实际启用范围验证短信、声纹、语音克隆、MCP 和通讯录呼叫。

### 部署

- 全新安装、已有数据升级、滚动发布和回滚。
- 非 root 文件权限、模型卷、上传卷和日志采集。
- API、realtime、jobs 独立健康与告警。
- 目标容量下的连接数、CPU/GPU、内存、带宽和响应时间。

## 4. 证据格式

每条真实用例记录：

```text
Case ID：
日期/测试人：
硬件与固件：
服务版本/Commit：
外部服务及版本：
网络与部署环境：
步骤：
预期：
实际：
日志/指标/录屏位置：
结果：Pass / Fail / Blocked
缺陷链接：
```

敏感字段在上传前脱敏。失败必须能关联到服务器会话 ID、设备 ID 的脱敏标识和时间窗口。

## 5. 上线判定

生产批准至少要求：

- 选定 ESP32/固件矩阵通过。
- 实际启用的 Provider 和外部集成通过，不要求未启用供应商全部真实联调。
- 目标环境升级与回滚演练通过。
- 没有 P0/P1 缺陷。
- 监控、告警、值守和回滚负责人明确。

未提供的外部能力应标记为“未验收/不可启用”，不得以自动化 Mock 结果改为 Pass。