# BugCollect 摄取防雪崩设计

## 目标

线上同一故障可能在短时间内由大量设备同时触发。摄取链路必须保护数据库和服务线程，
同时不能让 BugCollect 故障阻断宿主 App。

## 权威链路

1. SDK 本地按指纹采样和限频，批量上报最多 30 条。
2. 服务端按 `appKey` 统计固定窗口内的事件数，默认每分钟 6000 条。
3. 多实例部署使用 Redis Lua 原子计数；Redis 不可用时退回进程内窗口，继续保护当前实例。
4. 超限返回 HTTP 429、`message=BUGCOLLECT_RATE_LIMITED` 和标准
   `Retry-After` 秒数。
5. RN/Android SDK 保留原队列，按 `Retry-After` 冷却，最长一小时；冷却期间不重复请求。
6. `BUGCOLLECT_DISABLED` 仍表示租户关闭服务，SDK 清队列并停用。它与临时限流不能混用。

## 配置

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `BUGCOLLECT_MAX_EVENTS_PER_MINUTE` | `6000` | 单个 appKey 每个窗口允许的事件数，最小 30 |
| `BUGCOLLECT_RATE_WINDOW_SECONDS` | `60` | 固定窗口长度，最小 10 秒 |

限流属于平台容量保护，不是租户发布配置。租户平台不向开发者暴露“上传网络建议”或
让租户关闭服务端保护。

## 验收

- 单批 31 条必须在 Bean Validation 阶段拒绝。
- Redis 可用时，多实例共享同一 appKey 计数。
- Redis 不可用时，单实例超过本地额度仍返回 429。
- 429 必须携带正整数 `Retry-After`。
- SDK 收到 429 后不得丢队列、立即重试或向宿主业务线程抛未处理异常。
- 服务关闭返回 403 `BUGCOLLECT_DISABLED`，行为不受限流改动影响。