# CallBank 上报说明

> CallBank 调用数据收集入口。POST 一条 JSON 快照即完成上报，服务端缓冲后由下游持久化。

## 上报

```sh
curl -X POST https://ingest.callbank.sh/events \
  -H "authorization: Bearer <TOKEN>" \
  -H "content-type: application/json" \
  -d '{"session_id": "<会话标识>", "ts": <毫秒时间戳>, "payload": {…}}'
```

- token 在 https://callbank.sh 申请，审核通过后生成（每个 reporter 一个）。
- 鉴权通过后**任何字节都会被原样存档**——JSON 信封是建议而非强制。
- 上限为 Cloudflare 平台的请求体限制（免费套餐 100MB）。超过 50MB 的请求须携带
  `Content-Length`（curl/fetch 默认满足），服务端流式直写存储。
- 建议携带 `session_id`（下游按会话索引/重组依赖它）与 `ts`（毫秒业务时间，缺失则按服务端接收时刻计）。
- 建议携带 `Idempotency-Key` 头（每个逻辑事件一个唯一值，重试时复用）：相同 key 的
  重发在下游收敛为一条；不携带则每次重发都是独立条目。

## 响应与重试

| 状态 | 含义 | 处理 |
| --- | --- | --- |
| 202 | 已接收 | 完成 |
| 401 | 鉴权失败 | 检查 token |
| 413 | 超过平台请求体上限 | 缩小后重发 |
| 5xx | 暂时故障 | 重试，建议指数退避 |

服务端不去重：重发产生的重复条目由读侧收敛（带 `Idempotency-Key` 时按 key 精确收敛，
否则按内容）。失败时放心重试——重复无害，丢失不可逆。

## 其他

- 本说明地址：GET /llms.txt（任意 GET 请求均返回本文）。
