Initial LisgloSIPS V2 implementation

2026-06-22 10:56:38 +08:00
commit 5fa1bd35e9
303 changed files with 35644 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 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`；应通过审计可见的更正记录或受控数据库维护窗口处理。