# 祈盟SDK - AI 开发上下文必读

> 本文件是所有 AI 在为本项目生成代码前必须阅读的入口。
> 阅读时间：5 分钟。
> 最后更新：2026-06-30

## 1. 这是什么

祈盟SDK 是面向直播平台 + 推广员 + 游戏方的中间层，承载：
- 玩家登录/活跃数据采集
- 订单/充值数据推送
- 多端（Android/iOS/H5）统一接入
- 数据统计 + LTV/留存分析

## 2. 技术栈关键事实

- **后端**：Java + Spring Boot（v4.x 之前）/ Go（v4.25 部分模块）
- **数据库**：MySQL 8.0（分库分表后单库 8 千万行级）
- **缓存**：Redis Cluster（出口带宽 1Gbps 封顶）
- **对外协议**：HTTP REST + WebSocket
- **采集端**：Android Java / iOS Swift / H5 JS

## 3. 在开发前必读的 4 份文件

| 场景 | 必读文件 |
|------|---------|
| 写任何接口前 | `ARCHITECTURE-RULES.md` |
| 写批量查询/重试/缓存相关代码前 | `DANGER-ZONES.md` |
| 写完代码后 | `PERFORMANCE-CHECKLIST.md` |
| 遇到"这个设计为什么是这样"的问题 | `BUG-LESSONS.md` |

## 4. 4 条铁律（违反任何一条，PR 会被拒）

1. **任何批量查询必须分页**（单次 ≤ 2000 条）
2. **任何重试必须带指数退避**（起始 30s，封顶 5min，5 次后熔断）
3. **任何缓存时长必须小于服务端会话有效期**
4. **任何对外接口必须有 QPS 限流**

## 5. 不要做的事

- ❌ 不要用 `double(11,2)` 存储金额（精度溢出）
- ❌ 不要用 OR 条件拼 > 1000 个的 SQL
- ❌ 不要相信"上游会传正确的数据"——所有入参都要校验
- ❌ 不要在接口里直接查明细表做实时统计