# 文档索引

项目文档结构说明。后续大模型增补/更新文档时，按此分类找到对应目录。

---

## API 接口文档 (`api/`)

按业务领域分类，每个子目录对应一类接口。

### 分类目录

| 目录 | 分类 | URL 前缀 | 说明 |
|------|------|----------|------|
| [api/auth/](api/auth/) | 认证 | `/api/v1/auth` | 用户登录（极光一键登录/短信验证码）、Token 刷新（access + refresh）、登出、当前用户信息查询 |
| [api/ad/](api/ad/) | 广告 | `/api/v1/ad` | 穿山甲 S2S 回调验签发奖、激励视频/信息流广告奖励结算、eCPM 上报、发奖状态查询、测试发奖（仅本地） |
| [api/wallet/](api/wallet/) | 钱包 | `/api/v1/wallet` | 账户资产查询（金币/现金余额）、金币与现金流水、兑换规则与执行、绑定/解绑微信、提现申请/状态/记录、免确认收款授权 |
| [api/coupon/](api/coupon/) | 领券 | `/api/v1/coupon` | CPS 领券透传（step/session）、引导窗频控（should-show/shown/dismiss/reset）、每日完成状态、累计领券统计 |
| [api/compare/](api/compare/) | 比价记录 | `/api/v1/compare` | 比价记录上报/列表/详情/统计、比价战绩里程碑查询及奖励领取（按成功比价数解锁金币） |
| [api/savings/](api/savings/) | 省钱 | `/api/v1/savings` + `/api/v1/platform/savings-feed` | 省钱大作战（battle）、省钱明细/汇总、平台省钱动态 Feed |
| [api/signin/](api/signin/) | 签到 | `/api/v1/signin` | 每日签到执行、签到加速（看广告多领）、签到状态查询 |
| [api/tasks/](api/tasks/) | 任务 | `/api/v1/tasks` | 任务列表查询、任务奖励领取（按 task_key） |
| [api/invite/](api/invite/) | 邀请 | `/api/v1/invite` | 邀请码/分享链接生成、已邀请列表、邀请绑定（支持 clipboard/manual/fingerprint 三种归因） |
| [api/user/](api/user/) | 用户 | `/api/v1/user` | 个人资料编辑（昵称）、头像上传、新手引导状态/完成标记、注销账号 |
| [api/device/](api/device/) | 设备 | `/api/v1/device` | 设备注册/推送 token 更新、无障碍存活心跳、掉线检测（后置 pull）、告警确认 |
| [api/platform/](api/platform/) | 平台配置 | `/api/v1/platform` | 平台统计数据、Feature Flag 开关、广告配置（穿山甲 ID）、App 版本更新检查（OTA）；全部不鉴权 |
| [api/intent/](api/intent/) | 意图/电商 | `/api/v1/intent` + `/api/v1/price` + `/api/v1/ecom` | 比价意图识别（Phase 1 单次/多帧/预券）、电商意图识别、比价步进（Phase 2） |
| [api/meituan/](api/meituan/) | 美团 CPS | `/api/v1/meituan` | 美团券列表/信息流/推广链接/销量榜；全部无鉴权 |
| [api/other/](api/other/) | 其它 | 分散 | 健康检查、CPS 短链重定向（含微信 OAuth）、反馈提交/配置/记录、埋点上报、订单上报、更低价上报、Trace 收尾 |
| [api/admin/](api/admin/) | 管理后台 | `/admin/api` | Admin 独立子应用，二级目录按子资源拆分：`auth/`(登录)、`users/`(用户管理/财务操作)、`wallet/`(流水查询)、`withdraws/`(提现审核/对账)、`feedbacks/`(反馈处理)、`admins/`(管理员管理)、`ad/`(广告对账/收益)；单文件留根：审计日志、数据大盘、跑马灯种子、统计概览 |
| [api/internal/](api/internal/) | 内部接口 | `/internal` | 服务间调用（pricebot→app-server）：价格事实回写、店铺映射、启动确认样本、App 版本写入；X-Internal-Secret 鉴权 |

### 接口索引入口

完整接口列表（含路径、方法、鉴权方式）见 [api/README.md](api/README.md)。

### 文档命名规则

单端点文档按 URL 路径命名：`{prefix}-{resource}.md`（如 `wallet-withdraw.md`、`auth-sms-send.md`）。
含子资源的合并文档按族命名（如 `device-liveness.md` 覆盖 register/heartbeat/liveness/liveness-ack 四个端点）。
文件名唯一确定文档位置：大类目录 + 文件名前缀 → 直接匹配。

---

## 数据库文档 (`database/`)

数据库表结构说明，每表一个文件，[database/OVERVIEW.md](database/OVERVIEW.md) 为索引入口。

---

## 第三方集成 (`integrations/`)

外部 SDK/API 集成架构与实现说明：[integrations/README.md](integrations/README.md)。

| 文件 | 说明 |
|------|------|
| [jiguang.md](integrations/jiguang.md) | 极光一键登录（REST 验证 + RSA 解密） |
| [pangle.md](integrations/pangle.md) | 穿山甲广告 S2S 回调 |
| [wxpay.md](integrations/wxpay.md) | 微信支付 V3（提现/授权） |
| [meituan.md](integrations/meituan.md) | 美团 CPS 网关 |

---

## 开发指南 (`guides/`)

| 文件 | 说明 |
|------|------|
| [邀请功能-实现原理与本地测试.md](guides/邀请功能-实现原理与本地测试.md) | 邀请系统实现细节 |
| [CPS发券分发与微信授权.md](guides/CPS发券分发与微信授权.md) | CPS 发券 + 微信网页授权流程 |
| [看广告赚金币上线清单.md](guides/看广告赚金币上线清单.md) | 广告功能上线检查清单 |
| [待办与技术债.md](guides/待办与技术债.md) | 待办事项与技术债务 |

---

## 架构与设计 (`superpowers/`)

需求规格与设计文档，按 `YYYY-MM-DD-<topic>-design.md` 命名。

---

## 后端技术实现 (`后端技术实现.md`)

后端整体技术架构说明。