机器人综合统计报表对外接口(robot_stats)集成文档

• 适用版本:口径版本 caliberVersion = 1.3(1.3/1.2/1.1 变更内容见 §9)
• 接口标识:opt=robot_stats(经 /bridge/jsoncfg 通用 JSON 通道)
• 实现模块:HibernateService(JsonRobotStatsService)
• 读者:交管部门集成方工程师(本文档为对接唯一契约文档)
• 相关设计文档:docs/superpowers/specs/2026-08-26-robot-stats-report-design.md

1. 概述与调用方式

1.1 端点

GET/POST http://<host>:<port>/bridge/jsoncfg?opt=robot_stats&json={...}

• opt 固定为 robot_stats;json 为 URL 编码后的 JSON 字符串(见参数表)。
• GET:opt/json 均走 query 参数;POST:Content-Type: application/x-www-form-urlencoded 时 opt/json 走表单参数,其他 Content-Type(如 application/json)时 body 直接放 JSON 原文 (此时 opt 仍走 query 参数)。POST body 上限 1MB。
• 业务层成败不体现在 HTTP 状态码上:鉴权通过后,HTTP 状态恒为 200,成败看响应体 JSON 的 code 字段(见 §4.1 信封与 §7 错误全表)。仅鉴权失败为 HTTP 401(非 JSON,见 §2)。

1.2 请求参数(json 字段)

参数校验顺序:鉴权闸(§2)→ granularity → 日期 → accessNumber。任一失败返回对应 400 文案(§7)。

1.3 调用示例(curl)

curl -G "http://192.168.1.10:12121/bridge/jsoncfg" \
     -u user:pwd \
     --data-urlencode "opt=robot_stats" \
     --data-urlencode 'json={"startDate":"2026-08-01","endDate":"2026-08-20","accessNumber":"031195128","granularity":"day"}'

注意:json 中的 {、}、" 必须按 URL 编码传递(上面的 --data-urlencode 已自动处理); 手拼 URL 时请先 encodeURIComponent。

2. 鉴权与开通

本接口走 /bridge/jsoncfg 通道的既有双层鉴权,两种方式任一通过即放行(OR 语义):

1. IP 前缀白名单(配置键 legitimate.servlet.client.ip.prefix,代码常量 LEGITIMATE_SERVLET_CLIENT_IP_FREFIX):逗号分隔的 IP 前缀列表,客户端 IP 以任一前缀 开头即通过。注意是字符串前缀匹配:填 192.168.1.8 会连 192.168.1.80 一起放行。
2. HTTP Basic 认证(配置键 legitimate.servlet.basic.auth,代码常量 LEGITIMATE_SERVLET_BASIC_AUTH):请求头 Authorization: Basic base64(user:password), 客户端传明文密码,服务端做摘要常量时间比对。

规则要点:

• 127.0.0.1 恒放行(本机调试直接 curl 即可,前提是已配置下述任一鉴权)。
• 未通过任一鉴权 → HTTP 401(Tomcat 默认错误页,非 JSON,body 无 code 字段)。
• 本接口 fail-closed:当 IP 白名单与 Basic 两键均未配置时,本接口对所有来源(含 127.0.0.1)返回 HTTP 200 + {"code":503,"message":"authentication not configured, contact administrator"} ——即接口开通前不可裸调。配置任一键后即恢复可用。
• 开通流程:请联系系统管理员,在 OMS「安全维护」页(加白 IP / 配置 Basic 账号)或修改 配置区 configuration/com.mediapbx.utilityservice/service.properties 中的上述两个键, 改完重载配置后重试。

时区说明

所有日期与时间均按服务器本地时区(典型部署为 Asia/Shanghai)理解:

• 入参 startDate/endDate、返回的 statDate、asOf 均为服务器本地时区;
• day 粒度按服务器本地时区的自然日分桶,month 粒度按自然月分桶;
• 服务端启动后会校验数据库会话时区与服务器时区一致,不一致时返回 500(§7),需管理员对齐。

3. 完整示例

3.1 day 粒度

请求:

GET http://<host>:<port>/bridge/jsoncfg?opt=robot_stats&json={"startDate":"2026-08-01","endDate":"2026-08-20","accessNumber":"031195128","granularity":"day"}

响应(HTTP 200,节选,list 仅示窗口最后一天,其余天同构):

{
  "code": 200,
  "message": "success",
  "requestId": "0fb9c2a4-6b8d-4a1e-9c3d-2e5f7a8b9c01",
  "asOf": "2026-08-26 10:30:15",
  "caliberVersion": "1.3",
  "data": {
    "source": "cache",
    "compliantRingSeconds": 7,
    "list": [
      {
        "cityName": "",
        "accessNumber": "031195128",
        "statDate": "2026-08-20",
        "totalInboundCalls": 5300,
        "totalAnsweredCalls": 5260,
        "totalAnswerRate": 0.9925,
        "aiStats": {
          "totalCalls": 5000,
          "transferToHumanCount": 1200,
          "transferToHumanRate": 0.2400,
          "avgTalkDurationSec": 45.0
        },
        "humanAgentStats": {
          "answeredCount": 1440,
          "compliantAnsweredCount3s": 1200,
          "compliantAnswerRate3s": 0.8333,
          "avgResponseTimeSec": 2.1
        },
        "satisfactionStats": { "evaluatedCount": 1100, "positiveRate": 0.9650 }
      }
    ],
    "summary": {
      "totalInboundCalls": 11800,
      "totalAnsweredCalls": 11600,
      "totalAnswerRate": 0.9831,
      "aiTotalCalls": 11200,
      "transferToHumanCount": 2700,
      "transferToHumanRate": 0.2411,
      "avgTalkDurationSec": 48.5,
      "humanAnsweredCount": 3400,
      "compliantAnsweredCount3s": 2900,
      "compliantAnswerRate3s": 0.8529,
      "avgResponseTimeSec": 2.8,
      "evaluatedCount": 2480,
      "positiveRate": 0.9400
    }
  }
}

3.2 month 粒度

请求(granularity 改为 month,statDate 变为 yyyy-MM):

GET http://<host>:<port>/bridge/jsoncfg?opt=robot_stats&json={"startDate":"2026-07-01","endDate":"2026-08-31","accessNumber":"031195128","granularity":"month"}

响应(HTTP 200,节选,信封同上):

{
  "code": 200,
  "message": "success",
  "requestId": "3d1a5c7e-8f2b-4d94-a1b6-7c8e0f2a4b66",
  "asOf": "2026-08-26 10:31:02",
  "caliberVersion": "1.3",
  "data": {
    "source": "db",
    "compliantRingSeconds": 7,
    "list": [
      {
        "cityName": "",
        "accessNumber": "031195128",
        "statDate": "2026-07",
        "totalInboundCalls": 123000,
        "totalAnsweredCalls": 122100,
        "totalAnswerRate": 0.9927,
        "aiStats": {
          "totalCalls": 118000,
          "transferToHumanCount": 28700,
          "transferToHumanRate": 0.2432,
          "avgTalkDurationSec": 45.2
        },
        "humanAgentStats": {
          "answeredCount": 34100,
          "compliantAnsweredCount3s": 28100,
          "compliantAnswerRate3s": 0.8240,
          "avgResponseTimeSec": 2.7
        },
        "satisfactionStats": { "evaluatedCount": 25700, "positiveRate": 0.9588 }
      },
      {
        "cityName": "",
        "accessNumber": "031195128",
        "statDate": "2026-08",
        "totalInboundCalls": 128000,
        "totalAnsweredCalls": 126900,
        "totalAnswerRate": 0.9914,
        "aiStats": {
          "totalCalls": 121000,
          "transferToHumanCount": 29500,
          "transferToHumanRate": 0.2438,
          "avgTalkDurationSec": 44.7
        },
        "humanAgentStats": {
          "answeredCount": 34400,
          "compliantAnsweredCount3s": 28300,
          "compliantAnswerRate3s": 0.8227,
          "avgResponseTimeSec": 2.5
        },
        "satisfactionStats": { "evaluatedCount": 26100, "positiveRate": 0.9612 }
      }
    ],
    "summary": {
      "totalInboundCalls": 251000,
      "totalAnsweredCalls": 249000,
      "totalAnswerRate": 0.9920,
      "aiTotalCalls": 239000,
      "transferToHumanCount": 58200,
      "transferToHumanRate": 0.2435,
      "avgTalkDurationSec": 45.0,
      "humanAnsweredCount": 68500,
      "compliantAnsweredCount3s": 56400,
      "compliantAnswerRate3s": 0.8234,
      "avgResponseTimeSec": 2.6,
      "evaluatedCount": 51800,
      "positiveRate": 0.9600
    }
  }
}

3.3 空结果示例

查询范围内无数据时正常返回,list 为空数组,summary 各计数为 0、各比率为 0:

{
  "code": 200,
  "message": "success",
  "requestId": "…",
  "asOf": "2026-08-26 10:32:00",
  "caliberVersion": "1.3",
  "data": {
    "source": "cache",
    "compliantRingSeconds": 7,
    "list": [],
    "summary": {
      "totalInboundCalls": 0, "totalAnsweredCalls": 0, "totalAnswerRate": 0.0000,
      "aiTotalCalls": 0, "transferToHumanCount": 0, "transferToHumanRate": 0.0000,
      "avgTalkDurationSec": 0.0,
      "humanAnsweredCount": 0, "compliantAnsweredCount3s": 0,
      "compliantAnswerRate3s": 0.0000, "avgResponseTimeSec": 0.0,
      "evaluatedCount": 0, "positiveRate": 0.0000
    }
  }
}

4. 字段字典

计数单位约定(重要):

• 呼叫 = 按 (主叫号码, IVR应答时间) 去重后的一通电话。一通转人工的电话在系统里产生 多条记录,呼叫级指标只计 1。
• 行 = 通话记录表(calllog)的一条记录(一通电话的一条"腿")。行级指标按记录条数累加。
• 秒 = 时长单位。
• 比率 = 0~1 之间的四位小数(如 0.9925,即 99.25%);分母为 0 时输出 0。
• 均值 = 一位小数(如 45.0)。

4.1 信封字段(每次响应都有)

4.2 data 字段

4.3 list 行字段

4.4 summary 字段

与行字段一一对应,仅命名前缀不同(均与 list 同单位):

5. 口径说明

5.1 呼叫归属与去重

• 一通打到接入号的电话在系统里最多产生 4 类记录(IVR 挂断行 / 机器人行 / 坐席腿行 / 排队异常行), 全部共享 (主叫号码, IVR应答时间) 组合键——该键即"同一通电话"的判定依据。
• 归属条件:接入号匹配该行 且 IVR 已应答 且 主叫为外线(非内部分机/内部分组号)。
• 未到 IVR 应答的呼叫无法归属到接入号,天然不计入 totalInboundCalls 分母(已知边界,属预期)。

5.2 总接通率(呼叫级)

• 分母 = 去重呼叫数;分子 = 存在任一接通证据的呼叫数: 机器人接起(AI_ROBOT 行且状态为已接通且时长 >0),或人工接起(转接类行且坐席分机接通)。
• 一通"机器人接听后转人工再接通"的电话只计 1 通接通(呼叫级去重)。
• IVR 放音阶段挂断、排队/振铃中无人接起的呼叫计入分母、不计入分子。

5.3 AI 指标(aiStats)

• 统计对象为机器人行(business=AI_ROBOT,含方向过滤——主叫或被叫号码长度 ≥5, 与 OMS 机器人报表"全部"视图一致,见 §6)。
• 外线前提(v1.2,2026-09-03):主叫须为外线(非内部分机/内部分组号)——内部分机 (如 804)呼入接入号时,callee=接入号(≥5 位)会穿过方向过滤,此类呼叫不计入 AI 通话量/时长/转人工,与 §5.1 呼叫级归属口径对齐;主叫为空同样不计(无法归属)。
• AI 转人工:该行转人工标识(forward)非空即计。
• avgTalkDurationSec = 机器人行时长总和 ÷ 机器人行总量(含 0 时长行,见 §6)。

5.4 人工接听(humanAgentStats)

• 人工呼入量指标已删除(v1.1,2026-09-03):呼入规模请使用 totalInboundCalls(总呼入量)。
• 人工接听量(answeredCount),须同时满足:
  • 主叫为外线(非内部分机/内部分组号);
  • 转接类行(business = AI_ROBOT_TRANSFER_IN 或 IVR_TRANSFER);
  • 坐席真实接通:state=STATE_RECEIVED 且被叫为坐席分机号码—— callee 为接入号(如 1000)等非分机号码的行不算人工接听;
  • 排队中放弃、振铃未接的行不计——STATE_FAILED 归漏接,体现在 总接通率(§5.2)的分母中。
• 合规接听(阈值可配置,v1.3):接听且该腿振铃时长 ≤N 秒(含边界),N = 系统配置 statistical.compliant.ring.threshold(默认 7,2026-09-10 定,分机振铃有延迟;现场可调,如收紧回 3); 本响应实际生效值透出在 data.compliantRingSeconds。分母为人工接听量(answeredCount)。
• avgResponseTimeSec 仅对接听的行求振铃时长均值(不含排队时长)。

5.5 满意度(satisfactionStats)

• 参评 = 通话结束按键评价有效(非空且非 '0',即按键 1..maxkey;maxkey 由系统满意度 按键配置决定);好评 = 按键 '1'。
• positiveRate = 好评行数 ÷ 参评行数;参评为 0 时输出 0。

6. 口径偏差表(与 OMS 既有报表对比)

本接口指标与 OMS 既有报表存在以下三处有意差异,对账时请注意:

除上述三处外,其余指标(呼入识别、接听判定、满意度公式)复用既有报表同款公式,数值可对账。

7. 错误全表

说明:

• 上表除 HTTP 401 外,业务错误(code=400/404/500/503)的 HTTP 状态均为 200,错误信息在 响应体 JSON 中;集成方解析逻辑应以 code 字段为准,且不能假定 data 一定存在。
• 400/500/503 响应均含 requestId/asOf/caliberVersion;404 为容器级返回,仅含 code/message。
• 容器层其他错误(与本接口业务无关,沿用通道既有行为):缺 opt 参数 → HTTP 400 + {"error":"Missing required parameter 'opt'"};POST body 超 1MB → HTTP 413; 缺 json 参数或 json 体不可解析 → HTTP 200 + 裸字符串 "420"(即上表 json 行,同样 是容器层既有行为,非 JSON 信封,集成方解析响应体前应先判断是否以 { 开头)。

8. 限值与使用建议

8.1 跨度限值

超限拆分建议:按边界切分为多次调用后本地累加。计数类字段可直接相加;比率与均值不要 直接相加或平均,请用 summary 的分子分母口径(或保存各行原始计数)自行重算。示例:查询 2025-01-01 ~ 2026-12-31(day)超限,可拆为 2025-01-012025-12-31 与 2026-01-012026-12-31 两次调用。

8.2 数据量与查询建议

• 不传 accessNumber 时返回全部接入号的分组行:day 粒度 × 全部接入号 × 全年可达 万行级。建议集成方固定携带 accessNumber 参数按接入号拉取。
• list 顺序不保证,请按 (accessNumber, statDate) 自行排序/建索引。

8.3 数据新鲜度与边界(均为预期行为,非故障)

• 通话记录按 15 秒周期批量落库,统计为 T+15 秒新鲜度:刚结束的通话最多 15 秒后 才进入统计;进行中的通话不计入。
• endDate 为当天时,最后不足 15 秒的末段不计入;如需当天完整数据,请在次日再拉取 或多次补拉。
• 可查历史范围 = calllog 数据保留期,以现场归档策略为准(归档清理后的历史窗口将 返回空结果,见 §3.3),部署时请与系统管理员确认保留时长。

8.4 运行时路径与性能预期

• 查询范围在系统呼叫记录缓存覆盖期内时(source=cache),统计纯内存聚合完成,不逐行 访问数据库(每次查询仅读取一次分机号/分组号配置集);覆盖期之外(source=db)走单条 聚合 SQL。两条路径结果经内部交叉验证保证一致,source 仅供参考与运维核对。
• 性能预期:缓存路径毫秒级;数据库路径与既有 KPI 统计同量级。
• P99 粗测数据(本地开发环境,localhost 单机串行 curl,N=10,P99 以最大值近似,非压测,生产负载需另行压测):
  • 缓存路径(source=cache,2026-08-19~2026-08-20 day 粒度):中位约 2.2ms,最大 2.8ms;
  • 数据库路径(source=db,2025-01-01~2026-08-20 month 粒度,12 组,走 idx_calllog_accessnum_begintime 复合索引):中位约 14.2ms,最大 15.4ms;空结果窗口(2026-01)最大 3.2ms。

9. 版本与兼容

• 响应中的 caliberVersion 为口径版本号,当前 "1.3"。指标定义发生任何调整时版本号 递增,集成方可据此识别口径切换并对账。
• v1.3(2026-09-10)变更:合规接听阈值由固定 3 秒改为系统配置 statistical.compliant.ring.threshold(默认 7,2026-09-10 定——分机实际振铃有延迟; 振铃 ≤N 秒含边界,现场可调)。新增 data.compliantRingSeconds 透出本次实际生效阈值; compliantAnsweredCount3s/compliantAnswerRate3s 字段名不变(3s 为 v1.0 固定 3 秒时 的历史命名)——本版起取值口径默认即为 ≤7 秒,与 1.2 及更早(固定 3 秒)不同;若需 回到 1.2 对账口径,由管理员将配置调为 3 即可。消费方解释合规口径时以 data.compliantRingSeconds 为准,阈值调整前后的合规率不可直接互比。
• v1.2(2026-09-03)变更 指标(aiStats 的通话量/时长/转人工)加外线前提—— 主叫须为外线(非内部分机/内部分组号),主叫为空不计。此前内部分机(如 804)呼入接入号时, callee=接入号(≥5 位)穿过方向过滤会被计入 AI 通话量/平均时长;修正后与 §5.1 呼叫级归属 口径一致。字段集不变,仅取值口径修正。
• v1.1(2026-09-03)变更:①删除人工呼入量字段(行级 humanAgentStats.inboundCount、 汇总 summary.humanInboundCount),呼入规模改用 totalInboundCalls;②人工接听口径收紧: 仅计"外线 + 转接类行 + 坐席分机真实接通"——callee 为接入号等非分机号码不再计入, STATE_FAILED 归漏接;③3 秒合规接听率分母由人工呼入量改为人工接听量。 该删除发生在任何外部对接完成之前(接口尚无集成方),无兼容性影响。
• 字段只增不减(自 1.1 起):1.x 范围内后续演进只新增字段、不删除、不改既有字段名与 语义;集成方解析时应容忍新增字段(前向兼容)。唯一例外:v1.3 起 compliantAnsweredCount3s/ compliantAnswerRate3s 的取值随可配置阈值 N 变化(字段名不变,默认 N=7,配 3 时与 1.2 一致,实际阈值见 data.compliantRingSeconds),已按上述 v1.3 条目明示。
• 重大不兼容变更(删除/改名字段、改行唯一键等)将启用新的 opt 值 robot_stats_v2, 原 robot_stats 保持可用,迁移窗口提前通知。
• cityName 本期恒为空串;未来填充真实城市时,行唯一键将由 (accessNumber, statDate) 扩展为 (accessNumber, cityName, statDate)——属重大变更,将按上述承诺提前书面通知 并同步升级 caliberVersion / 切换 v2。

• 文档版本:1.3(2026-09-10,口径 1.3:合规阈值可配置默认 7+新增 data.compliantRingSeconds;口径 1.2:AI 指标加外线前提;口径 1.1:删人工呼入量、人工接听收紧;初版 1.0 于 2026-08-26 随 robot_stats 首版交付)
• 问题支持:凭响应 requestId 联系系统管理员查日志(服务端日志含同 ID 的请求摘要)。