Quality Backend Runbook

任务：S25 - 质检后端
完成时间：2026-06-21 21:05 +08:00

1. 目标

S25 完成质检后端最小闭环：

质检抽样规则管理。
基于规则的稳定抽样。
录音列表、录音详情和上下条导航。
保存质检结果。
RBAC 权限和审计元数据。

本任务不做 Dashboard 聚合，不新增前端页面，不发布 B 当前 placeholder release。

2. API

质检规则：

GET    /api/v2/quality/rules
GET    /api/v2/quality/rules/:id
POST   /api/v2/quality/rules
PATCH  /api/v2/quality/rules/:id
DELETE /api/v2/quality/rules/:id
POST   /api/v2/quality/rules/:id/enable
POST   /api/v2/quality/rules/:id/disable

录音质检：

GET /api/v2/recordings
GET /api/v2/recordings/:id
PUT /api/v2/recordings/:id/review

S24 的播放接口继续保留：

GET /api/v2/recordings/:id/play

3. 权限

能力	权限
查看质检规则、录音列表、录音详情	`quality.view`
新增、修改、启停、删除质检规则	`quality.manage`
保存质检结果	`quality.manage`
播放录音	`recordings.play`

质检规则变更和保存质检结果都带 AuditAction 元数据，由既有审计拦截器记录。

4. 稳定抽样

当前 schema 没有单独“待质检任务表”，S25 采用计算型稳定抽样：

score = sha256(rule_id + ":" + recording_id) 的前 32 bit 映射到 [0, 100)
selected = score < ratio

规则匹配条件：

customerId 为空或等于录音关联 raw CDR 的 customerId。
lineGroupId 为空或等于录音关联 raw CDR 的 lineGroupId。
规则状态为 ENABLED。
当前时间在 effectiveAt 与 expiresAt 范围内。

同一规则和同一录音的抽样结果稳定不变，列表重复查询不会抖动。

5. 数据写入

S25 不新增数据库迁移，复用 S08 已建表：

quality_sampling_rules
quality_reviews
recordings

保存质检结果会新增一条 quality_reviews 记录，不覆盖历史结果；录音详情返回最新质检结果和历史列表。

6. 验证结果

corepack pnpm@10.33.0 exec vitest run apps/api/src/modules/quality/sampling.spec.ts apps/api/src/modules/recordings/recordings.service.spec.ts 通过，2 个测试文件 6 条测试。
corepack pnpm@10.33.0 typecheck 通过。
corepack pnpm@10.33.0 lint 通过。
corepack pnpm@10.33.0 build 通过。

7. 当前限制

B 当前 /opt/lisglosips/current 仍是 S05 placeholder release，本次只完成本地代码与构建验证，未部署到 B 当前 API 服务。
录音真实数据仍依赖 S28 端到端路由、媒体、CDR 和录音闭环产生。
Dashboard 中的待质检数量和趋势留给 S26 聚合任务。

8. 回滚

代码回滚：

删除或恢复 apps/api/src/modules/quality/。
恢复 apps/api/src/modules/recordings/ 到 S24 版本。
从 apps/api/src/modules/app.module.ts 移除 QualityModule。
重新执行 corepack pnpm@10.33.0 build。

数据回滚：

S25 未在远端执行数据库写入验证，无需清理远端数据。
若后续已运行 API 并产生质检记录，不应直接删除历史 quality_reviews；应通过审计可见的更正记录或受控数据库维护窗口处理。

3.3 KiB Raw Blame History