联调验收与排障
把“网络连通”“协议通过”和“业务结果正确”分开验证。每次联调保留接口名称与请求路径、请求 ID、HTTP 状态、组织与日期等必要信息；不要记录完整 Token 或用户原始内容。
八接口验收清单
| 接口 | 正常用例 | 必须覆盖的边界 |
|---|---|---|
| 获取最新统计日期 | 完整数据日期与 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 失败 | 企业新地址是否接受该凭据、组织授权是否一致 | 控制台允许沿用，不保证新服务接受它 |
完整联调记录
一次可交付的联调记录应包含：
- 办公安装版本、Provider 版本、协议版本与联调日期。
- 八接口逐项结果、相关请求 ID、响应校验结果。
- 测试组织与用户绑定、周期起止、单位换算和重试用例。
- 源 ds 与办公侧已发布 ds、组织及成员合计核对。
- 企业模型的真实消费及额度拦截结果。
涉及真实写入的用例应在独立测试组织执行。确认协议后，再按双方交付流程启用正式组织。