feat(ai-customer-service): add gate readiness verification and handoff docs
This commit is contained in:
Your Name
@@ -1,126 +1,91 @@
|
||||
# 客服 SLA 与升级响应规范
|
||||
|
||||
> 版本：v1.0 | 状态：已生效
|
||||
> 关联：tech/INTERFACE.md、PRODUCTION_PHASE1_STATUS.md
|
||||
> 版本：v1.1
|
||||
> 状态：已更新为灰度门禁口径
|
||||
> 关联：`docs/MONITORING_ALERTING.md`、`docs/GRAY_DASHBOARD_MINIMUM.md`、`prd/GRAY_RELEASE_ROLLBACK_RUNBOOK.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 客服 SLA 定义
|
||||
## 1. Phase 1 灰度期 SLA
|
||||
|
||||
### 1.1 核心 SLA 指标
|
||||
灰度期的 SLA 不是最终商业承诺，而是**是否继续放量**的门槛。
|
||||
|
||||
| 指标 | 目标值 | 说明 |
|
||||
### 1.1 核心灰度门槛
|
||||
|
||||
| 指标 | 目标值 | 用途 |
|
||||
|------|--------|------|
|
||||
| Webhook 可用率 | ≥ 99.5% | 成功接收渠道消息的比率 |
|
||||
| 首次响应时间（机器人） | ≤ 5s | 从收到消息到发出首字的时间（P95） |
|
||||
| 机器人回答准确率 | ≥ 85% | FAQ 命中且用户未点"不满意" |
|
||||
| 转人工率 | ≤ 15% | 需要人工介入的会话比例 |
|
||||
| 工单响应时间 | ≤ 30min | 从创建到客服接单的时间（P95） |
|
||||
| 工单解决时间 | ≤ 4h | 从创建到解决的时间（P95） |
|
||||
| Webhook 成功率 | `>= 99%`（5 分钟窗口） | 是否允许继续放量 |
|
||||
| Webhook 5xx | `< 1%`（5 分钟窗口） | 超阈值即停止放量 |
|
||||
| Readiness 可用率 | `>= 99.5%` | 实例是否稳定接流量 |
|
||||
| PostgreSQL 依赖异常 | `= 0`（5 分钟窗口） | 关键依赖门禁 |
|
||||
| Audit 写入失败数 | `= 0`（5 分钟窗口） | 合规/追溯门禁 |
|
||||
| Handoff 比率 | `<= 25%` 或不高于基线 `2x` | 判断机器人能力是否异常退化 |
|
||||
| 工单接单时间 P95 | `<= 30 分钟` | 人工链路可承载性 |
|
||||
| 工单解决时间 P95 | `<= 4 小时` | 最小服务能力 |
|
||||
|
||||
> **注**：上述指标为生产一期目标值，实际值需在灰度阶段采集并调整基线。
|
||||
### 1.2 灰度期分级
|
||||
|
||||
### 1.2 SLA 优先级定义
|
||||
|
||||
| 优先级 | 定义 | 响应时间 | 解决时间 |
|
||||
|--------|------|----------|----------|
|
||||
| P1 | 机器人完全不可用（所有消息报错） | 15min | 1h |
|
||||
| P2 | 核心能力降级（签名/幂等失效、频繁 5xx） | 30min | 2h |
|
||||
| P3 | 非核心功能异常（部分渠道失败、偶发报错） | 2h | 8h |
|
||||
| 级别 | 定义 | 响应时间 | 恢复目标 |
|
||||
|------|------|----------|----------|
|
||||
| P0 | 数据库不可用、全量 5xx、审计主链断裂 | 5 分钟 | 30 分钟内恢复或回滚 |
|
||||
| P1 | 5xx > 1%、连续 readiness down、ticket 主链异常 | 15 分钟 | 1 小时内恢复或回滚 |
|
||||
| P2 | reject 异常升高、handoff 比率异常、重启抖动 | 30 分钟 | 4 小时内恢复 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 升级响应规范
|
||||
## 2. 升级与通知规则
|
||||
|
||||
### 2.1 升级链路
|
||||
|
||||
```
|
||||
告警/故障发现 → P3 处理（值班工程师） → 若恶化升级 P2 → 若继续恶化升级 P1
|
||||
```
|
||||
|
||||
### 2.2 告警触发条件
|
||||
|
||||
| 条件 | 级别 | 通知方式 |
|
||||
|------|------|----------|
|
||||
| Webhook 可用率 < 99% 持续 5min | P2 | 飞书群 + 电话 |
|
||||
| 错误率 > 5% 持续 5min | P2 | 飞书群 |
|
||||
| PostgreSQL 连接失败 | P1 | 电话 + 飞书群 |
|
||||
| 签名校验失败率 > 20% 持续 10min | P3 | 飞书群 |
|
||||
| 工单积压 > 50 个 open 状态 | P3 | 飞书群 |
|
||||
|
||||
> **注**：告警系统（metrics/tracing/SLO）属于 P1 缺口，**当前未落地**，告警触发依赖人工巡检。生产一期灰度阶段需补齐可观测性基础设施。
|
||||
|
||||
### 2.3 升级决策人
|
||||
|
||||
| 级别 | 第一响应人 | 升级对象 |
|
||||
|------|------------|----------|
|
||||
| P3 | 值班工程师 | Team Lead |
|
||||
| P2 | Team Lead | 技术总监 |
|
||||
| P1 | 技术总监 | 小龙/业务负责人 |
|
||||
|
||||
### 2.4 故障处理要求
|
||||
|
||||
- P1/P2 故障：故障清除后 24h 内提交故障报告
|
||||
- P3 异常：记录在运营日志，下周一回溯复盘
|
||||
- 所有故障必须在下一灰度周期前完成根因分析
|
||||
| 触发条件 | 等级 | 通知 |
|
||||
|----------|------|------|
|
||||
| Webhook 5xx `> 5%` 持续 5 分钟 | P0 | 电话 + 飞书，立即回滚 |
|
||||
| PostgreSQL 连接异常导致 `ready` 失败 | P0 | 电话 + 飞书，立即冻结放量 |
|
||||
| Audit 写入失败数 `> 0` 持续 5 分钟 | P1 | 飞书，立即停止继续放量 |
|
||||
| Handoff 比率 `> 25%` 或高于基线 `2x` | P2 | 飞书，需人工研判 |
|
||||
| 单实例 10 分钟内重启 `> 2` 次 | P2 | 飞书，冻结当前档位 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前阶段说明
|
||||
## 3. 当前实现与 SLA 的关系
|
||||
|
||||
### 3.1 可用性现状
|
||||
### 3.1 已有支撑
|
||||
|
||||
| 能力 | 当前状态 | 备注 |
|
||||
|------|----------|------|
|
||||
| Webhook 可用率监控 | 未完成 | P1 缺口，metrics/tracing 未落地 |
|
||||
| 错误率监控 | 未完成 | 同上 |
|
||||
| PostgreSQL 连接监控 | ✅ 已完成 | `/ready` 含 PostgreSQL 依赖检查 |
|
||||
| 工单积压监控 | 未完成 | 无定时任务扫描 open 工单 |
|
||||
| 安全拒绝事件审计 | ✅ 已完成 | `webhook_security.go` 的 `auditReject` 写入审计 |
|
||||
| 工单状态流转审计 | ✅ 已完成 | `TicketWorkflowStore.writeAudit` 在 assign/resolve/close 时调用 |
|
||||
- `live` / `ready` 探针已具备
|
||||
- PostgreSQL readiness 检查已接入
|
||||
- webhook HMAC / timestamp / dedup 已具备
|
||||
- ticket / audit / dedup 本地/容器化 Gate B 已证据化通过
|
||||
|
||||
### 3.2 接口级 SLA（当前代码能力）
|
||||
### 3.2 仍待落地
|
||||
|
||||
以下为代码中已实现的接口响应时间基准（本地压测数据，待灰度验证）：
|
||||
- 真实共享预生产环境上的统一指标采集
|
||||
- 告警平台接入
|
||||
- 灰度阶段的自动统计和 dashboard
|
||||
|
||||
| 接口 | 目标延迟 | 当前状态 |
|
||||
|------|----------|----------|
|
||||
| `POST /webhook` | < 200ms P99 | HMAC 校验 + 幂等检查开销约 5-10ms |
|
||||
| `GET /tickets` | < 300ms P99 | PostgreSQL 查询，无索引优化 |
|
||||
| `POST /tickets/{id}/assign` | < 200ms P99 | 单条 UPDATE |
|
||||
| `POST /tickets/{id}/resolve` | < 200ms P99 | 单条 UPDATE |
|
||||
| `GET /actuator/health` | < 50ms | 依赖 PostgreSQL |
|
||||
因此当前 SLA 结论应当理解为：
|
||||
|
||||
> **注**：当前压测数据为本地单实例，未经过真实渠道流量验证。
|
||||
> **门槛已定义，但真实共享预生产和灰度环境的观测接线仍需补齐。**
|
||||
|
||||
---
|
||||
|
||||
## 4. 错误码与 SLA 映射
|
||||
## 4. 与放量门禁的绑定
|
||||
|
||||
错误码定义见 `tech/INTERFACE.md`，与 SLA 相关联的快速参考：
|
||||
进入下一灰度档位前，必须满足：
|
||||
|
||||
| 错误码 | 含义 | SLA 影响 |
|
||||
|--------|------|----------|
|
||||
| `CS_SES_4001` | 会话不存在 | 返回 404，用户可重试 |
|
||||
| `CS_SES_4002` | 消息频率过高 | 返回 429，触发限流逻辑 |
|
||||
| `CS_TKT_4001` | 工单不存在 | 返回 404 |
|
||||
| `CS_TKT_4002` | 工单已被分配 | 返回 409，幂等性保证 |
|
||||
| `CS_LLM_5001` | LLM 服务不可用 | 触发转人工，SLA 降级 |
|
||||
| `CS_LLM_5002` | LLM 超时 | 同上 |
|
||||
1. 最近一个观察窗口 `webhook 5xx <= 0.5%`
|
||||
2. `audit 写入失败数 = 0`
|
||||
3. `postgres 连接异常 = 0`
|
||||
4. 无连续 `readiness down`
|
||||
5. handoff / ticket 指标没有异常飙升
|
||||
|
||||
任一条件不满足：
|
||||
|
||||
- 不允许继续放量
|
||||
- 必要时触发回滚
|
||||
|
||||
---
|
||||
|
||||
## 5. 持续改进
|
||||
## 5. 当前版本状态
|
||||
|
||||
SLA 基线在灰度第一周期（建议 2 周）后复盘，根据真实数据调整：
|
||||
- 若机器人响应时间 P95 > 5s，需优化 LLM 调用链路
|
||||
- 若转人工率 > 20%，需复盘意图识别准确率
|
||||
- 若工单解决时间 P95 > 4h，需增加客服人力或优化分流策略
|
||||
- 文档版本：`v1.1`
|
||||
- 本次更新日期：`2026-05-04`
|
||||
- 下次审查：灰度第一轮结束后
|
||||
|
||||
---
|
||||
|
||||
## 6. 当前版本状态
|
||||
|
||||
- **本文档版本**：v1.0
|
||||
- **生效日期**：2026-04-30
|
||||
- **下次审查**：灰度第一周期结束后
|
||||
|
||||
Reference in New Issue
Block a user