监控告警 — 迭代需求
本模块用于保障 MVP 线上关键链路可用性，优先覆盖三方数据源余额、放款账户余额、短信触达质量、放款通道等会直接阻断注册、授信、放款和还款提醒的风险点。
完整运营后台可后置，但 P0 监控告警需随对应外部接入同步落地。
1. 业务目的
及时发现以下问题，避免业务链路静默失败：
- 登录验证码或还款提醒短信因供应商异常导致无法发送。
- KYC、活体、人脸、征信等三方数据源因余额不足、账号异常或成功率下降影响授信。
- Monnify / Paystack 放款账户余额不足，导致现金贷放款或手机分期商户放款失败。
- 放款成功率下降、回调延迟、未知状态堆积，影响客户到账和财务对账。
2. 监控范围
| 类别 | 监控对象 | 来源系统 | 关键指标 | 影响链路 |
|---|---|---|---|---|
| 短信触达 | 登录验证码短信供应商、还款提醒短信供应商 | crs / 供应商 API | 发送成功率、发送失败率、回执延迟 | 注册登录、客户登录、还款提醒 |
| 三方数据源账号 | KYC、活体、人脸比对、征信供应商 | crs / 供应商 API | 账号余额、调用成功率、超时率、错误码分布 | 实名、授信审批 |
| 放款账户 | Paystack、Monnify 放款账户 / balance wallet | pmt / 供应商 API | 可用余额、冻结余额、余额更新时间 | 现金贷放款、手机分期商户放款 |
| 放款交易 | Paystack、Monnify transfer / disbursement | pmt / fund_transaction | 放款成功率、失败率、处理中笔数、未知状态笔数、回调延迟 | 放款到账、财务对账 |
| 回调链路 | 支付回调、短信回执、三方结果回调 | pmt / crs | 回调成功率、回调积压、重复回调、签名失败 | 状态流转、对账、补偿 |
3. 告警分级
| 级别 | 触发条件 | 响应要求 | 通知对象 |
|---|---|---|---|
| P0 | 放款账户余额低于当日预计放款额；放款成功率 15 分钟内低于 90%；登录短信连续 5 分钟不可用 | 立即处理，必要时暂停对应通道或切换备用通道 | 技术负责人、支付负责人、crs 负责人、运营值班 |
| P1 | 任一三方账号余额低于 2 天预计消耗；短信成功率 30 分钟内低于 95%；放款未知状态超过阈值 | 2 小时内处理，确认是否补充余额或排查供应商 | 对应系统负责人、运营值班 |
| P2 | 余额低于 7 天预计消耗；单一供应商错误码异常上升；回调延迟高于日常水平 | 当日跟进，纳入日常巡检 | 系统负责人、运营 |
阈值需要支持按供应商、业务线、环境配置。上线初期先使用保守阈值，运行 1-2 周后基于真实消耗和成功率校准。
4. 指标定义
4.1 余额类指标
| 指标 | 计算口径 | 刷新频率 | 备注 |
|---|---|---|---|
third_party_account_balance | KYC / 活体 / 人脸 / 征信供应商账户余额或剩余调用次数 | 10 分钟 | 统一归口在 crs 采集 |
disbursement_account_balance | Paystack / Monnify 可用于放款的余额 | 1 分钟 | pmt 采集并落地快照 |
daily_estimated_consumption | 近 7 日平均消耗或运营配置的当日预计消耗 | 每日 / 手工配置 | 用于判断余额可支撑天数 |
balance_coverage_days | 当前余额 / 近 7 日日均消耗 | 每次余额刷新后计算 | 低于阈值触发 P1 / P2 |
4.2 成功率类指标
| 指标 | 计算口径 | 窗口 | 备注 |
|---|---|---|---|
login_sms_success_rate | 登录验证码短信发送成功数 / 实际发送请求数 | 5 / 15 / 30 分钟 | 以供应商受理成功 + 回执成功为准，需区分失败阶段 |
repayment_sms_success_rate | 还款提醒短信发送成功数 / 实际发送请求数 | 30 / 60 分钟 | FCS 生成提醒目标和变量后，直接对接 crs 发送短信 |
third_party_call_success_rate | 三方调用成功数 / 有效调用请求数 | 5 / 15 / 30 分钟 | 按供应商、场景、错误码维度拆分 |
disbursement_success_rate | 放款成功笔数 / 放款终态笔数 | 5 / 15 / 30 分钟 | 处理中不计入分母，但需单独监控积压 |
callback_success_rate | 回调处理成功数 / 收到回调数 | 5 / 15 / 30 分钟 | 签名失败、幂等冲突、状态非法需单独归因 |
4.3 积压与延迟指标
| 指标 | 说明 | 告警参考 |
|---|---|---|
pending_disbursement_count | 处理中放款笔数 | 超过近 7 日同时间段均值 2 倍触发 P1 |
unknown_disbursement_count | 超过 TTL 后仍未知的放款笔数 | 任一生产通道连续增长触发 P1 |
provider_callback_delay_seconds | 供应商回调延迟 | P95 超过 10 分钟触发 P2；超过 30 分钟触发 P1 |
sms_delivery_delay_seconds | 短信投递回执延迟 | P95 超过 3 分钟触发 P2 |
5. 页面能力
5.1 监控看板
| 区块 | 展示内容 | 操作 |
|---|---|---|
| 账号余额 | 三方数据源、Paystack、Monnify 当前余额和可支撑天数 | 刷新、查看历史、标记已充值 |
| 成功率趋势 | 登录短信、还款提醒短信、三方调用、放款成功率 | 按供应商 / 场景 / 时间筛选 |
| 当前告警 | 未恢复告警、级别、触发时间、持续时长、负责人 | 认领、备注、关闭 |
| 异常交易 | 放款处理中、未知、失败重试中的交易 | 跳转放款流水、导出 |
5.2 告警列表
| 字段 | 说明 |
|---|---|
| alert_id | 告警 ID |
| alert_level | P0 / P1 / P2 |
| alert_type | balance_low / success_rate_drop / callback_delay / pending_backlog |
| provider | Paystack / Monnify / 短信供应商 / 征信供应商等 |
| metric_name | 触发指标 |
| current_value | 当前值 |
| threshold_value | 阈值 |
| status | open / acknowledged / resolved / ignored |
| owner | 当前处理人 |
| first_triggered_at | 首次触发时间 |
| last_triggered_at | 最近触发时间 |
| resolved_at | 恢复时间 |
| remark | 处理备注 |
6. 数据与接口要求
6.1 pmt 侧
- 定时拉取 Paystack / Monnify 放款账户余额，落地余额快照。
- 记录放款请求、供应商受理、回调、终态、失败原因和重试次数。
- 对外暴露放款成功率、处理中笔数、未知状态笔数、回调延迟等指标。
- 支持按通道、业务线、交易类型拆分：现金贷客户放款、手机分期商户放款。
6.2 crs 侧
- 统一采集 KYC、活体、人脸、征信供应商余额或剩余次数；短信侧只采集发送结果和回执。
- 记录每次三方调用的场景、供应商、请求结果、错误码、耗时、是否计费。
- 记录短信发送请求、供应商受理结果、投递回执、失败原因。
- 还款提醒短信沿用 MVP 口径：FCS 生成提醒目标和变量后，直接对接
crs发送短信。
6.3 告警服务
- 从 pmt、
crs、业务库或指标系统读取指标。 - 支持阈值配置、连续触发去抖、恢复通知、告警认领和备注。
- 同一供应商、同一指标、同一窗口内告警合并，避免重复轰炸。
- 告警通知渠道先支持企业 IM / 邮件；短信告警后置，避免短信供应商故障时自监控失效。
6.4 余额查询接口
以下为监控告警采集侧需要封装的供应商余额查询接口。生产实现中不得把供应商密钥暴露给前端；由 pmt /
crs服务端定时采集并落地快照。
| 供应商 | 归属系统 | 用途 | Method | Endpoint | 认证 | 关键响应字段 | 采集频率 | 在线文档 |
|---|---|---|---|---|---|---|---|---|
| Dojah | crs | KYC / 活体 / 人脸 / 征信等 Dojah 钱包余额 | GET | {dojah_base_url}/api/v1/balance | Header: AppId: {app_id}；Authorization: {secret_key} | entity.wallet_balance | 10 分钟 | Dojah SDK - Get Dojah Wallet Balance |
| Paystack | pmt | Paystack 放款可用余额 | GET | https://api.paystack.co/balance | Header: Authorization: Bearer {secret_key} | data[].currency、data[].balance | 1 分钟 | Paystack Transfer Control - Check Balance |
| Monnify | pmt | Monnify 放款钱包余额 | GET | {monnify_base_url}/api/v2/disbursements/wallet-balance?accountNumber={walletAccountNumber} | Header: Authorization: Bearer {access_token} | responseBody.availableBalance、responseBody.ledgerBalance | 1 分钟 | Monnify Get Wallet Balance |
Dojah 余额查询
在线文档：Dojah SDK - Get Dojah Wallet Balance
GET {dojah_base_url}/api/v1/balance
AppId: {app_id}
Authorization: {secret_key}响应字段映射：
| 字段 | 映射到内部指标 | 说明 |
|---|---|---|
entity.wallet_balance | third_party_account_balance | Dojah 钱包余额；金额单位以 Dojah 账户配置币种为准 |
采集失败处理：
- HTTP 401 / 403：标记
provider_auth_failed，触发 P1。 - 连续 3 次超时或 5xx：标记
provider_balance_fetch_failed，触发 P2；不覆盖上一条有效余额。 - 返回余额为空或无法解析：记录原始响应摘要，触发 P2。
Paystack 余额查询
在线文档：Paystack Transfer Control - Check Balance
GET https://api.paystack.co/balance
Authorization: Bearer {secret_key}响应字段映射：
| 字段 | 映射到内部指标 | 说明 |
|---|---|---|
data[].currency | currency | 币种，如 NGN |
data[].balance | disbursement_account_balance | Paystack 返回金额为子单位；落库时同时保存原始值和标准金额 |
采集失败处理：
- HTTP 401 / 403：标记
paystack_auth_failed，触发 P0；放款可能已不可用。 - 连续 3 次超时或 5xx：标记
paystack_balance_fetch_failed，触发 P1。 data为空或缺少目标币种：触发 P1，并保留上一条有效余额用于看板展示。
Monnify 余额查询
在线文档：Monnify Get Wallet Balance
GET {monnify_base_url}/api/v2/disbursements/wallet-balance?accountNumber={walletAccountNumber}
Authorization: Bearer {access_token}环境配置：
| 环境 | Base URL |
|---|---|
| sandbox | https://sandbox.monnify.com |
| production | https://api.monnify.com |
响应字段映射：
| 字段 | 映射到内部指标 | 说明 |
|---|---|---|
requestSuccessful | provider_request_successful | 是否请求成功 |
responseCode | provider_response_code | Monnify 响应码 |
responseBody.availableBalance | disbursement_account_balance | 可用于放款的余额 |
responseBody.ledgerBalance | ledger_balance | 账面余额 |
采集失败处理：
- access token 过期：先刷新 token，再重试一次。
- HTTP 401 / 403：标记
monnify_auth_failed，触发 P0；同时检查 IP 白名单。 responseCode非0或requestSuccessful=false：触发 P1，并记录responseMessage。- 不要把客户子钱包余额接口误用于放款钱包。客户子钱包为
/api/v1/disbursements/wallet/balance?accountNumber={customerWalletAccountNumber}，文档见 Monnify Get Customer Balance，不作为本模块的放款余额口径。
7. MVP 落地边界
| 能力 | MVP | 后续 |
|---|---|---|
| Paystack 放款账户余额监控 | ✅ | 多币种、多账户聚合 |
| Monnify 放款账户余额监控 | ✅（接入后启用） | 自动切换通道建议 |
| 放款成功率 / 失败率监控 | ✅ | 根因自动归类 |
| 登录短信发送成功率监控 | ✅ | 供应商自动切换 |
| 还款提醒短信发送成功率监控 | ✅ | 模板维度分析 |
| 三方数据源余额监控 | ✅ | 成本消耗预测 |
| 告警通知 | ✅ | 值班排班、升级策略 |
| 可视化运营后台 | 🔄 | 完整看板、权限、工单闭环 |
8. 验收标准
- Paystack 放款账户余额低于配置阈值时，5 分钟内产生告警。
- 放款成功率在 15 分钟窗口低于阈值时，产生 P0 / P1 告警，并能定位到具体通道。
- 登录短信发送成功率下降时，能区分供应商受理失败、投递失败和超时无回执。
- KYC / 活体 / 人脸 / 征信任一账号余额低于阈值时，能按供应商生成告警。
- 告警支持认领、备注、恢复关闭；告警记录可追溯。
- 文档和系统内统一使用
crs命名。