xiaozhi-esp32-server/docs/unified-fastapi-platform/quality-gates.md

质量门禁

1. 原则

自动测试负责证明“实现符合可观察的现有行为”；真实测试负责证明“设备、供应商和生产网络确实 按预期工作”。两类证据不得互相替代。

2. 测试层次

层次	目标	典型内容	运行时机
静态	快速发现格式、类型、依赖问题	Ruff、Mypy、前端 lint/type、配置校验	每次提交
单元	验证纯逻辑与状态转换	Token、协议解析、队列、配置版本、Provider DTO	每次提交
特征/契约	冻结现有可观察行为	旧服务黄金报文、API envelope、设备帧、Provider 请求	每个 PR
隔离集成	验证真实本地依赖	MySQL、Redis、文件、jobs、Pub/Sub、事务	每个相关 PR
模拟 E2E	验证用户和设备流程	manager-web、虚拟设备、Fake Provider、统一 gateway	每个里程碑
差分	比较旧/新实现	REST、OTA、WS 会话和副作用	M1 起持续运行
非功能	容量和恢复	多连接、背压、断线、摘流、资源泄漏、安全	M6/M7
真实环境	外部事实	ESP32、云 Provider、MQTT/RAGFlow、目标部署	M8

3. CI 分层

Tier A：快速门禁

目标是在常规 PR 中快速反馈，建议控制在 10 分钟内：

• FastAPI Ruff、Mypy、unit/contract pytest。
• manager-web i18n、unit、snapshot。
• xiaozhi-server/迁移代码语法与导入检查。
• 路由、消费者和生成文档一致性。
• Secret 扫描和部署配置静态检查。

从 P01 建立覆盖率基线后，变更行覆盖率不得低于 85%，协议解析和会话状态机的分支覆盖率 不得低于 90%，全局覆盖率不得下降。覆盖率用于发现遗漏，不允许为了数字制造无行为价值的测试。

Tier B：PR 集成门禁

• 隔离 MySQL/Redis。
• manager-web 生产构建及浏览器关键路径。
• 虚拟设备完整对话流程。
• Fake Provider 覆盖成功、超时、断流、取消和错误映射。
• API/realtime/jobs 镜像构建与 Compose readiness。
• 修改范围对应的旧/新差分。

Tier C：里程碑门禁

• 全量旧/新差分。
• 多 realtime worker 配置广播。
• 并发连接和 60 分钟模拟 soak。
• 优雅摘流、进程终止、Redis/MySQL 短暂故障恢复。
• 依赖漏洞、鉴权边界和恶意输入测试。
• 支持架构的镜像构建或至少可重复的构建证明。

Tier C 不在每个小 PR 重复运行，以节约资源；相关核心代码变化或阶段收口时必须运行。

性能采用相同 runner 上的新旧实现相对比较。初始自动门槛为：

• Fake Provider 下业务错误率为 0。
• WebSocket 握手和控制消息 p95 回退不超过 15%。
• 可完成会话吞吐回退不超过 10%。
• 每个 realtime PR 运行 20 个虚拟连接、5 分钟；RC 运行 100 个虚拟连接、60 分钟。
• 测试结束后 RSS、线程、async task、文件描述符和临时文件不得持续线性增长。

这些指标只约束模拟回归，不代表真机容量结论；如固定测试机不足，PR 必须记录实际档位，不能 静默降低门槛。

4. 必须建立的协议场景

虚拟设备测试至少覆盖：

1. OTA 获取 WebSocket/MQTT 信息和未绑定激活码。
2. WebSocket header 与 query 参数两种握手。
3. hello、listen、abort、ping、iot、mcp、server 控制消息。
4. Opus 音频输入、ASR 文本、LLM 流、TTS 文本及音频输出。
5. 唤醒、连续对话、主动中断、无语音超时。
6. 设备绑定前后的行为。
7. Provider 超时、断流、无内容、限流和取消。
8. 客户端断线、服务摘流和重连。
9. MQTT gateway 16 字节桥接帧的编码与解码。
10. 配置更新只影响约定的当前或后续会话。

黄金数据必须脱敏、可提交且带版本说明。不能从一次偶然运行直接认定为规范；旧代码、文档和至少 一个调用方必须交叉确认。

5. PR 合并门禁

所有 PR：

• 计划工作包和文件所有权明确。
• 新行为有测试，重构行为有特征/差分证据。
• 相关 Tier A 全绿。
• 无未解释 skip、xfail、warning 激增或生成文件漂移。
• 文档和配置随行为同步。
• 回滚方法明确。

高风险 PR 额外要求：

• 设备协议：协议 Reviewer + 虚拟设备差分。
• 鉴权/密钥：Security Reviewer + 失败路径和密钥泄露检查。
• 数据迁移：全新库、已有库、重复执行和回滚测试。
• 并发/任务：取消、超时、资源关闭和故障注入。
• Provider 公共接口：所有能力族契约测试通过。

6. RC 自动化退出条件

只有满足以下全部条件，才能转入真实测试：

• 所有计划 PR P00-P12 已合并或明确取消并记录理由。
• 公开兼容边界全部关联到自动测试。
• 虚拟设备和 manager-web E2E 全绿。
• 所有 Provider 适配器通过 Fake/契约矩阵。
• 没有 P0/P1 内部缺陷；P2 风险有接受或后续方案。
• 统一发行物在干净环境完成安装、升级和回滚。
• 模拟负载下没有无界内存、线程、任务或文件增长。
• 未验证项逐条映射到真实环境交接用例。

满足这些条件代表“纯 Agent 阶段完成”，不代表真实 Provider 或硬件已经通过。