# Quality Backend Runbook

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

## 1. 目标

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

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

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

## 2. API

质检规则：

```text
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
```

录音质检：

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

S24 的播放接口继续保留：

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

## 3. 权限

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

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

## 4. 稳定抽样

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

```text
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`；应通过审计可见的更正记录或受控数据库维护窗口处理。