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