联调验收与排障

更新时间:
复制 MD 格式

八接口验收清单

接口

正常用例

必须覆盖的边界

获取最新统计日期

完整数据日期与 ds=null

不提前发布未完成日期

查询组织用量概览

五周期、组织汇总、每日趋势

空余额保留 null;组织、日期及合计错误被发现

查询成员用量列表

全部分页、排序、筛选、真实绑定用户

超过 200 人、空集合、同值排序、重复及漏项

查询成员每日用量趋势

当前用户的连续每日趋势

days=1/30、编码用户 ID、已过期日期

查询额度规则与周期

当前周期、最小与最大限额

周期边界、无已知上限;产品最低 500 不被放宽

查询成员额度

已应用、未配置、未找到三种状态

响应次序与数量、空值和真实应用版本

设置成员限额

单用户 500 credit 限额与完整确认

重复请求、响应丢失后重试、确认字段不匹配;不累加、不清零用量

查询组织额度

实时组织总额度和已用量

已用超过总额、组织不匹配、未知额度报错

公共行为

正确凭据、组织及 JSON

401/403、参数错误、超时、非 JSON、超大响应、重定向

真实业务验收还要确认:模型调用关联同一第三方身份;企业模型执行限额;统计刷新发布新日期;页面、导出和成员趋势与企业数据一致。仅使用模拟 Provider 的固定样例不能证明真实计量或限额拦截完成。

错误处理

失败返回非 200 HTTP 状态和 JSON,不要用 HTTP 200 内的错误字段隐藏业务失败。

{
  "code": "snapshot_not_found",
  "message": "The requested dataset is not retained.",
  "request_id": "spi-demo-member-trend",
  "retryable": false
}

HTTP

code 示例

对接方应检查

400 / 422

invalid_argument / unsupported_period

参数、字段类型与周期;先修正请求

401 / 403

unauthenticated / forbidden

Token 与组织授权,不用空数据掩盖

404

member_not_found / snapshot_not_found

成员或历史数据是否存在;是否未实现对应接口

409

snapshot_not_ready

完整数据是否就绪;办公侧保留旧快照

429

rate_limited

限流预算,可返回 Retry-After

500 / 502 / 503 / 504

upstream_unavailable

企业依赖、网络与超时;沿宿主既有预算恢复

retryable 和 Retry-After 不承诺 SDK 立即重试;后台刷新与额度派发各自管理重试。客户端页面收到的是办公服务映射后的错误,不一定是企业服务原始 code,使用请求 ID 关联服务日志。

按现象定位

现象

优先检查

正确判断

本机 curl 成功,控制台检测失败

Biz 所在网络的 DNS、端口、证书、路由和 IP SAN

本机可达不等于 Biz 可达

检测成功,统计仍失败

最新统计日期的 JSON 响应、组织与成员用量的五周期数据、全部分页和身份绑定

检测仅看“获取最新统计日期”接口是否返回 HTTP 200,不解析响应

组织额度报错,其他接口正常

“查询组织额度”接口是否实现、是否返回字符串金额及正确组织

组织额度接口返回 404 不表示扩展关闭

HTTP 200 却提示协议错误

是否套 data;null、日期、JSON 类型、必填字段是否正确

HTTP 成功不等于合同校验通过

额度看起来差 10000 倍

额度接口是否返回 minor 字符串;统计接口是否使用 credit 数字

额度接口中的 "5000000" 表示 500 credit

设置成员限额一直重试

确认的用户、binding、revision、金额、有效期和周期是否完全匹配

不能只回显 desired_revision 就确认成功

统计只有前 200 人或整批失败

page_no、has_more、total、非末页长度、重复 ID

必须完整读取稳定分页

组织总量与成员不一致

五周期边界、所有页合计、cycle_used_credits 与 period 用量

同一 ds 使用同一统计口径

换了 Provider 或改样例后页面未变化

源日期是否大于本地已发布日期

相同日期快照不可变,不会重新覆盖

余额未知却显示成 0

是否把可空余额或重置日填成默认值

统计未知值用 null;组织额度未知时报错

换地址后沿用旧 Token 失败

企业新地址是否接受该凭据、组织授权是否一致

控制台允许沿用,不保证新服务接受它

完整联调记录

一次可交付的联调记录应包含:

  1. 办公安装版本、Provider 版本、协议版本与联调日期。

  2. 八接口逐项结果、相关请求 ID、响应校验结果。

  3. 测试组织与用户绑定、周期起止、单位换算和重试用例。

  4. 源 ds 与办公侧已发布 ds、组织及成员合计核对。

  5. 企业模型的真实消费及额度拦截结果。

涉及真实写入的用例应在独立测试组织执行。确认协议后,再按双方交付流程启用正式组织。