Merge remote-tracking branch 'origin/main' into feature/coupon-claim-integration

# Conflicts:
#	docs/api/README.md

docs/api/README.md

@@ -4,6 +4,7 @@
 > 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
 > 最后更新:2026-05-27
+> 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
 
 ---
 
@@ -22,11 +23,40 @@
 | 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan-coupons.md) |
 | 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan-feed.md) |
 | 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan-referral-link.md) |
+| **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend） |||
 | 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./compare-intent-recognize.md) |
 | 13 | `POST /api/v1/price/step` | 无 | [详情](./compare-price-step.md) |
+| **钱包 / 我的资产**（前缀 `/api/v1/wallet`） |||
+| 14 | `GET /api/v1/wallet/account` | Bearer | [详情](./wallet-account.md) |
+| 15 | `GET /api/v1/wallet/coin-transactions` | Bearer | [详情](./wallet-coin-transactions.md) |
+| 16 | `GET /api/v1/wallet/cash-transactions` | Bearer | [详情](./wallet-cash-transactions.md) |
+| 17 | `GET /api/v1/wallet/exchange-info` | 无 | [详情](./wallet-exchange-info.md) |
+| 18 | `POST /api/v1/wallet/exchange` | Bearer | [详情](./wallet-exchange.md) |
+| 19 | `POST /api/v1/wallet/bind-wechat` | Bearer | [详情](./wallet-bind-wechat.md) |
+| 20 | `POST /api/v1/wallet/unbind-wechat` | Bearer | [详情](./wallet-unbind-wechat.md) |
+| 21 | `GET /api/v1/wallet/withdraw-info` | Bearer | [详情](./wallet-withdraw-info.md) |
+| 22 | `POST /api/v1/wallet/withdraw` | Bearer | [详情](./wallet-withdraw.md) |
+| 23 | `GET /api/v1/wallet/withdraw/status` | Bearer | [详情](./wallet-withdraw-status.md) |
+| 24 | `GET /api/v1/wallet/withdraw-orders` | Bearer | [详情](./wallet-withdraw-orders.md) |
+| **签到**（前缀 `/api/v1/signin`） |||
+| 25 | `GET /api/v1/signin/status` | Bearer | [详情](./signin-status.md) |
+| 26 | `POST /api/v1/signin` | Bearer | [详情](./signin-do.md) |
+| **任务**（前缀 `/api/v1/tasks`） |||
+| 27 | `GET /api/v1/tasks` | Bearer | [详情](./tasks-list.md) |
+| 28 | `POST /api/v1/tasks/{task_key}/claim` | Bearer | [详情](./tasks-claim.md) |
+| **省钱**（前缀 `/api/v1/savings`） |||
+| 29 | `GET /api/v1/savings/summary` | Bearer | [详情](./savings-summary.md) |
+| 30 | `GET /api/v1/savings/battle` | Bearer | [详情](./savings-battle.md) |
+| 31 | `GET /api/v1/savings/records` | Bearer | [详情](./savings-records.md) |
+| **看广告发奖**（前缀 `/api/v1/ad`） |||
+| 32 | `GET /api/v1/ad/pangle-callback` | 验签 | [详情](./ad-pangle-callback.md) |
+| 33 | `GET /api/v1/ad/reward-status` | Bearer | [详情](./ad-reward-status.md) |
+| 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad-test-grant.md) |
 
 > ⚠️ 美团三个接口当前**无鉴权**,且 `referral-link` 的 `sid` 允许客户端传值覆盖默认渠道——见各接口"备注"。
-> `coupon/step` 及外卖比价的 `intent/recognize` / `price/step` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见各接口详情)。当前**所有业务接口均无鉴权**,只有 `/me`、`/logout` 需 Bearer。
+> `coupon/step` 及外卖比价的 `intent/recognize` / `price/step` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见各接口详情)。
+> 福利相关业务接口（wallet/signin/tasks/savings、`ad/reward-status`）均需 **Bearer**;`wallet/exchange-info` 是静态规则无鉴权;`ad/pangle-callback` 不走 JWT、靠穿山甲**验签**;`ad/test-grant` **仅本地联调**(开关控制,生产 404)。
+> 金额字段一律以**分**为单位（`*_cents`）。
 
 ---
 
@@ -42,6 +72,13 @@
   - `502` 上游调用失败（极光验证/解密失败、美团接口失败）
 - **接口文档（交互式）**:`APP_ENV` 非 prod 时开放 `GET /docs`（Swagger UI）、`GET /redoc`;生产环境关闭。
 
+### 游标分页约定
+钱包流水 / 提现单 / 省钱明细等列表接口统一用**游标分页**:
+
+- 请求 query:`limit`（每页条数,1–100,默认 20）、`cursor`（上一页返回的 `next_cursor`,首页不传）。
+- 响应:`{ "items": [...], "next_cursor": <int|null> }`。`next_cursor` 为**末条记录的 id**;为 `null` 表示已到底,无更多数据。
+- `items` 按 `id` 倒序（最新在前）。
+
 ---
 
 ## 复用数据结构