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

# Conflicts: # docs/api/README.md
2026-05-28 10:33:35 +08:00
parent aa34ad7d0b 6e99287c77
commit 16b78478c0
83 changed files with 5089 additions and 134 deletions
@@ -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` 倒序（最新在前）。
+
 ---

 ## 复用数据结构
@@ -0,0 +1,40 @@
+# GET /api/v1/ad/pangle-callback — 穿山甲 GroMore 激励视频发奖回调(S2S)
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:**无 JWT,靠验签**（穿山甲 GroMore 服务器调用） | 限流:同 IP ≤300 次/分 | [← 返回 API 索引](./README.md)
+>
+> ⚠️ 我们客户端用 `useMediation(true)`(GroMore 融合),回调走 **GroMore 广告位层级**(规范见 supportcenter/26240),**不是**联盟代码位层级(5416)。两者密钥、响应格式都不同,别混。后台配置入口:**GroMore 聚合管理 → 搜广告位ID → 编辑 → 勾选「服务端激励回调」**(广告位层级配了就别再在代码位层级重复配,会冲突)。
+>
+> 集成实现:见 [integrations/pangle](../integrations/pangle.md)（验签算法、m-key 来源、设计动机）。
+
+## 入参（query，由 GroMore 拼装）
+GroMore 以 GET 回调,关键参数:
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `user_id` | string | 客户端 `setUserID` 传入的用户标识（须为数字 = 本系统 user.id） |
+| `trans_id` | string | 交易号（**幂等键** + **唯一参与签名的字段**） |
+| `reward_name` | string | 奖励名（广告位配置,入库备注） |
+| `reward_amount` | int | 奖励数量（广告位配置）→ **本次发放金币**。缺/坏/≤0 回退 `AD_REWARD_COIN`,超 `MAX_AD_REWARD_COIN` 夹紧 |
+| `extra` | string | 客户端透传的 customData（可空,入库备注） |
+| `mediation_rit` | string | 代码位 ID（GroMore 带,目前仅入 raw 备查） |
+| `prime_rit` | string | 广告位 ID（同上） |
+| `adn_name` | string | 实际出广告的 ADN 名（同上,可用于收益分析） |
+| `ecpm` | string | 本次广告 eCPM（同上,可用于收益分析） |
+| `sign` | string | 签名,见下 |
+
+**验签**:`sign = SHA256("{m-key}:{trans_id}")` 十六进制（只签 `trans_id`，其余参数不参与）。算法细节、m-key 来源、为什么这样设计 → 见集成文档 [integrations/pangle](../integrations/pangle.md)。
+
+## 出参
+响应 `200`,**响应体必须是 `{"is_verify": bool, "reason": int}`**（GroMore 规范）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `is_verify` | bool | `true`=校验通过、发放奖励（发奖成功 或 当日达上限,均算已处理、不重试） |
+| `reason` | int | `is_verify=false` 时的错误码,透传客户端 SDK:`1`=参数缺/坏,`2`=user 不存在;成功为 `0` |
+
+## 错误码
+- `403` 验签失败（`bad sign`,留给真请求重试）
+- `503` 回调未配置（`pangle_callback_configured=false`）
+
+## 说明
+**发奖唯一可信入口**:验签 → 取 `user_id` → 按 `reward_amount` 解析金币 → 幂等发金币（按 `trans_id` 去重 + 每日上限）。客户端不参与发奖,被破解也刷不到钱。验签过但参数缺/坏或 user 不存在 → 不发（`is_verify=false` + `reason`）;granted / capped → `is_verify=true` + `reason=0`。
@@ -0,0 +1,19 @@
+# GET /api/v1/ad/reward-status — 今日看广告发奖进度
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`AdRewardStatusOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `used_today` | int | 今日已成功发奖次数 |
+| `daily_limit` | int | 每日发奖次数上限 |
+| `remaining` | int | 今日剩余可领次数 |
+| `coin_per_ad` | int | 看完一个激励视频发的金币 |
+
+## 说明
+福利页「看视频赚金币」用:展示「今日还能看 N 次」「看一次得 M 金币」。真正发奖走 [ad-pangle-callback](./ad-pangle-callback.md)（穿山甲 S2S）。
@@ -0,0 +1,27 @@
+# POST /api/v1/ad/test-grant — [仅本地联调]模拟穿山甲回调发奖
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤60 次/分 | [← 返回 API 索引](./README.md)
+>
+> ⚠️ **仅本地联调**,受 `AD_REWARD_TEST_GRANT_ENABLED` 开关控制,**生产必须关闭**（默认 False → 一律 404）。
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`TestGrantOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `granted` | bool | 本次是否真发了金币（达每日上限则 false） |
+| `status` | string | `granted` / `capped`（达上限） |
+| `coin` | int | 本次发放金币（capped 时 0） |
+| `used_today` | int | 今日已成功发奖次数 |
+| `daily_limit` | int | 每日发奖次数上限 |
+| `remaining` | int | 今日剩余可领次数 |
+| `coin_per_ad` | int | 看完一个激励视频发的金币 |
+
+## 错误码
+- `404` 开关未开（伪装不存在） / 用户不存在
+
+## 说明
+没公网、穿山甲 S2S 回调打不到本地时,debug 客户端看完广告后调它,直接走与 [ad-pangle-callback](./ad-pangle-callback.md) 相同的发奖逻辑（每次新 `trans_id`,幂等 + 每日上限）。它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
@@ -1,6 +1,8 @@
 # POST /api/v1/auth/jverify-login — 极光一键登录

 > 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/jiguang](../integrations/jiguang.md)（极光核验链路、RSA 解密策略、私钥配对踩坑）。

 ## 入参

@@ -17,4 +19,4 @@
 - `403` 账号被禁用

 ## 说明
-后端拿 `login_token` 调极光 `loginTokenVerify` 验真 → 取回 RSA 加密的手机号 → 用私钥解密 → 注册即登录（手机号不存在则建号）→ 签发 JWT。
+后端验真 `login_token` 取回并解密手机号 → 注册即登录（手机号不存在则建号）→ 签发 JWT。极光核验 + RSA 解密的实现细节见 [integrations/jiguang](../integrations/jiguang.md)。
@@ -1,6 +1,8 @@
 # POST /api/v1/auth/sms/login — 手机号 + 验证码登录

 > 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/sms](../integrations/sms.md)（验证码校验逻辑）。

 ## 入参

@@ -1,6 +1,8 @@
 # POST /api/v1/auth/sms/send — 发送短信验证码

 > 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/sms](../integrations/sms.md)（mock 模式、频控、接真供应商 TODO）。

 ## 入参

@@ -1,6 +1,8 @@
 # POST /api/v1/meituan/coupons — 券列表 / 搜索

 > 所属:美团 CPS 组（前缀 `/api/v1/meituan`,**全部无鉴权**） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/meituan](../integrations/meituan.md)（CPS S-Ca 签名、入参换算坑）。

 ## 入参

@@ -1,6 +1,8 @@
 # POST /api/v1/meituan/feed — 首页混合推荐流

 > 所属:美团 CPS 组（前缀 `/api/v1/meituan`,**全部无鉴权**） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/meituan](../integrations/meituan.md)（CPS S-Ca 签名、入参换算坑）。

 ## 入参

@@ -1,6 +1,8 @@
 # POST /api/v1/meituan/referral-link — 换取推广链接

 > 所属:美团 CPS 组（前缀 `/api/v1/meituan`,**全部无鉴权**） | 鉴权:无 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/meituan](../integrations/meituan.md)（CPS S-Ca 签名、入参换算坑）。

 ## 入参

@@ -0,0 +1,18 @@
+# GET /api/v1/savings/battle — 省钱战绩
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SavingsBattleOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `week_saved_cents` | int | 本周已省（分） |
+| `beat_percent` | int | 超过百分之多少用户 |
+| `streak_days` | int | 连续省钱天数 |
+
+## 说明
+「我的」页「省钱战绩」卡数据源。接口已通但无真实业务写入,实际多为 0。
@@ -0,0 +1,29 @@
+# GET /api/v1/savings/records — 省钱明细(游标分页)
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`:`{ items: SavingsRecordOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**SavingsRecordOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 记录 id（也是游标） |
+| `order_amount_cents` | int | 订单金额（分） |
+| `saved_amount_cents` | int | 本单省下（分） |
+| `platform` | string \| null | 平台（美团/饿了么等） |
+| `title` | string \| null | 标题 |
+| `shop_name` | string \| null | 店铺名 |
+| `dishes` | string[] | 菜品列表 |
+| `created_at` | datetime | 时间 |
+
+## 说明
+订单/省钱明细页（`RECORDS`）数据源。
@@ -0,0 +1,18 @@
+# GET /api/v1/savings/summary — 累计帮你省了
+
+> 所属:Savings 组（前缀 `/api/v1/savings`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SavingsSummaryOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `total_saved_cents` | int | 累计省下（分） |
+| `order_count` | int | 累计省钱订单数 |
+| `avg_saved_cents` | int | 平均每单省（分） |
+
+## 说明
+「我的」页「累计帮你省了」卡数据源。当前比价上报未接入,实际多为 0。
@@ -0,0 +1,22 @@
+# POST /api/v1/signin — 执行今日签到
+
+> 所属:Signin 组（前缀 `/api/v1/signin`,本接口 POST 到前缀本身） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SigninResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `coin_awarded` | int | 本次签到发放金币 |
+| `cycle_day` | int | 本次签到落在循环第几天 |
+| `streak` | int | 签到后的连续天数 |
+| `coin_balance` | int | 签到后金币余额 |
+
+## 错误码
+- `409` 今日已签（`already signed today`）
+
+## 说明
+发金币已计入 [wallet-account](./wallet-account.md) 的余额（客户端就地刷新即可,不必另叠）。
@@ -0,0 +1,29 @@
+# GET /api/v1/signin/status — 今日签到状态 + 7 天档位
+
+> 所属:Signin 组（前缀 `/api/v1/signin`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`SigninStatusOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `today_signed` | bool | 今日是否已签 |
+| `consecutive_days` | int | 当前连续签到天数 |
+| `today_cycle_day` | int | 今日处于循环内第几天（1..7） |
+| `today_coin` | int | 今日签到可得金币 |
+| `can_claim` | bool | 今日是否可领（= 未签） |
+| `steps` | SigninStepOut[] | 7 天档位 |
+
+**SigninStepOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `day` | int | 循环内第几天 1..7 |
+| `coin` | int | 该档金币 |
+| `status` | string | `claimed`（已领） / `today`（今日待领） / `locked`（未到） |
+
+## 说明
+福利页签到行 + 签到弹窗 7 档 timeline 数据源。
@@ -0,0 +1,25 @@
+# POST /api/v1/tasks/{task_key}/claim — 领取任务奖励
+
+> 所属:Tasks 组（前缀 `/api/v1/tasks`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参（path）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `task_key` | string | ✅ | 任务标识（见 [tasks-list](./tasks-list.md) 的 `task_key`） |
+
+## 出参
+响应 `200`:`TaskClaimResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `task_key` | string | 任务标识 |
+| `coin_awarded` | int | 本次发放金币 |
+| `coin_balance` | int | 领奖后金币余额 |
+
+## 错误码
+- `404` 未知任务（`unknown task`）
+- `409` 任务已领取（`task already claimed`）
+
+## 说明
+发奖端 gate 由后端把控（如「打开消息提醒」须客户端确认权限已开后才调）。金币已计入余额。
@@ -0,0 +1,20 @@
+# GET /api/v1/tasks — 任务及领取状态
+
+> 所属:Tasks 组（前缀 `/api/v1/tasks`,本接口 GET 前缀本身） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`TaskListOut` = `{ items: TaskOut[] }`
+
+**TaskOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `task_key` | string | 任务标识,如 `enable_notification`（打开消息提醒） |
+| `coin` | int | 完成可得金币 |
+| `claimed` | bool | 是否已领取 |
+
+## 说明
+福利页一次性任务行（如「打开消息提醒」）的状态源。领取走 [tasks-claim](./tasks-claim.md)。
@@ -0,0 +1,18 @@
+# GET /api/v1/wallet/account — 金币 + 现金余额(我的资产)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`CoinAccountOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `coin_balance` | int | 当前金币余额 |
+| `cash_balance_cents` | int | 当前现金余额（分） |
+| `total_coin_earned` | int | 累计赚取金币 |
+
+## 说明
+账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源。
@@ -0,0 +1,28 @@
+# POST /api/v1/wallet/bind-wechat — 微信授权 code 换 openid 并绑定
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | 限流:同 IP ≤10 次/分 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)（code 换 openid / userinfo）。
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `code` | string | ✅ | 微信授权返回的 code（客户端 OAuth 拿到） |
+
+## 出参
+响应 `200`:`BindWechatResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `bound` | bool | 固定 `true` |
+| `wechat_nickname` | string \| null | 微信昵称 |
+| `wechat_avatar_url` | string \| null | 微信头像 URL |
+
+## 错误码
+- `400` code 无效 / 换 openid 失败
+- `409` 该微信已绑定其他账号
+- `503` 微信支付未配置（`wxpay_configured=false`）
+
+## 说明
+后端用 `code` 调微信 `jscode2session`（或 OAuth）换 `openid` 并写入 user。提现前置:必须先绑定。`openid` 全局唯一（DB 唯一约束），一个微信只能绑一个账号。
@@ -0,0 +1,28 @@
+# GET /api/v1/wallet/cash-transactions — 现金流水(游标分页)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`:`{ items: CashTransactionOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**CashTransactionOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 流水 id（也是游标） |
+| `amount_cents` | int | 现金变动（分）,正=兑入 负=提现 |
+| `balance_after_cents` | int | 变动后现金余额（分） |
+| `biz_type` | string | 业务类型（兑换/提现等） |
+| `ref_id` | string \| null | 关联业务 id（如提现单号） |
+| `remark` | string \| null | 备注 |
+| `created_at` | datetime | 时间 |
+
+## 说明
+现金历史页（`CASH_HISTORY`）数据源。
@@ -0,0 +1,28 @@
+# GET /api/v1/wallet/coin-transactions — 金币流水(游标分页)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`:`{ items: CoinTransactionOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**CoinTransactionOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 流水 id（也是游标） |
+| `amount` | int | 金币变动,正=入账 负=出账 |
+| `balance_after` | int | 变动后余额 |
+| `biz_type` | string | 业务类型（签到/任务/兑换等） |
+| `ref_id` | string \| null | 关联业务 id |
+| `remark` | string \| null | 备注 |
+| `created_at` | datetime | 时间 |
+
+## 说明
+金币历史页（`COIN_HISTORY`）数据源。
@@ -0,0 +1,18 @@
+# GET /api/v1/wallet/exchange-info — 金币兑现金 汇率/规则
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:**无**（返回静态配置,不读用户） | [← 返回 API 索引](./README.md)
+
+## 入参
+无。
+
+## 出参
+响应 `200`:`ExchangeInfoOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `coin_per_yuan` | int | 多少金币兑 1 元 |
+| `min_coin` | int | 单次兑换最少金币 |
+| `step_coin` | int | 兑换金币需为该值的整数倍（对齐整分） |
+
+## 说明
+给兑换页展示汇率与规则用。值来自 `app/core/rewards.py`（`COIN_PER_YUAN` / `MIN_EXCHANGE_COIN` / `COIN_PER_CENT`）。
@@ -0,0 +1,26 @@
+# POST /api/v1/wallet/exchange — 金币兑现金
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `coin_amount` | int | ✅（>0） | 要兑换的金币数,须 ≥ `min_coin` 且为 `step_coin` 整数倍 |
+
+## 出参
+响应 `200`:`ExchangeResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `coin_amount` | int | 本次扣除的金币 |
+| `cash_added_cents` | int | 本次兑入的现金（分） |
+| `coin_balance` | int | 兑换后金币余额 |
+| `cash_balance_cents` | int | 兑换后现金余额（分） |
+
+## 错误码
+- `400` `coin_amount` 不满足 ≥ `min_coin` 且为 `step_coin` 整数倍
+- `409` 金币余额不足
+
+## 说明
+兑换规则见 [wallet-exchange-info](./wallet-exchange-info.md)。金币与现金的扣加在同一事务内完成。
@@ -0,0 +1,18 @@
+# POST /api/v1/wallet/unbind-wechat — 解绑微信(清空 openid)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)。
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`UnbindWechatResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `bound` | bool | 固定 `false` |
+
+## 说明
+清空当前用户的 `wechat_openid` / `wechat_nickname` / `wechat_avatar_url`。幂等:未绑定时调用也返回 `bound=false`。解绑后该微信可被其他账号绑定。
@@ -0,0 +1,22 @@
+# GET /api/v1/wallet/withdraw-info — 提现额度 / 绑定状态
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)（提现链路）。
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`WithdrawInfoOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `min_cents` | int | 单次最低提现（分） |
+| `max_cents` | int | 单次最高提现（分） |
+| `wechat_bound` | bool | 是否已绑定微信 |
+| `wechat_nickname` | string \| null | 微信昵称（可能脱敏/空） |
+| `wechat_avatar_url` | string \| null | 微信头像 URL（可能空） |
+
+## 说明
+提现页进入时拉一次:决定展示额度区间、是否需先去绑定微信。额度来自 `rewards.py`（`WITHDRAW_MIN_CENTS` / `WITHDRAW_MAX_CENTS`）。
@@ -0,0 +1,28 @@
+# GET /api/v1/wallet/withdraw-orders — 提现单列表(游标分页)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`:`{ items: WithdrawOrderOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**WithdrawOrderOut**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 单 id（也是游标） |
+| `out_bill_no` | string | 商户提现单号 |
+| `amount_cents` | int | 提现额（分） |
+| `status` | string | `pending` / `success` / `failed` |
+| `wechat_state` | string \| null | 微信侧原始状态 |
+| `fail_reason` | string \| null | 失败原因 |
+| `created_at` | datetime | 发起时间 |
+
+## 说明
+提现记录页数据源。
@@ -0,0 +1,27 @@
+# GET /api/v1/wallet/withdraw/status — 查提现单状态(轮询)
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)（查单 / 撤销转账）。
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `out_bill_no` | string | ✅ | 商户提现单号（[withdraw](./wallet-withdraw.md) 返回的） |
+
+## 出参
+响应 `200`:`WithdrawStatusOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `out_bill_no` | string | 商户提现单号 |
+| `status` | string | `pending` / `success` / `failed` |
+| `wechat_state` | string \| null | 微信侧原始状态 |
+| `amount_cents` | int | 提现额（分） |
+
+## 错误码
+- `404` 提现单不存在（或不属于当前用户）
+
+## 说明
+App 从微信确认页返回后调此接口刷新单状态。**副作用**:若查时仍是 `WAIT_USER_CONFIRM`（用户在确认页放弃），后端会**撤销该单并退回余额**(`cancel_if_unconfirmed=True`)。
@@ -0,0 +1,36 @@
+# POST /api/v1/wallet/withdraw — 发起提现到微信零钱
+
+> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | 限流:同 IP ≤20 次/分 | [← 返回 API 索引](./README.md)
+>
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)（微信 V3 商家转账、签名、实名加密）。
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `amount_cents` | int | ✅（>0） | 提现金额（分）,须落在 `[min_cents, max_cents]` |
+| `user_name` | string | ❌ | 实名（达额时微信商家转账要求,可空） |
+| `out_bill_no` | string | ❌ | **客户端幂等键（商户单号）**:同号重试不重复转账;不传则服务端生成 |
+
+## 出参
+响应 `200`:`WithdrawResultOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `out_bill_no` | string | 商户提现单号（查单用） |
+| `status` | string | `pending` / `success` / `failed` |
+| `wechat_state` | string \| null | 微信侧原始状态 |
+| `amount_cents` | int | 本次提现额（分） |
+| `cash_balance_cents` | int | 提现后现金余额（分） |
+| `package_info` | string \| null | 拉起微信确认页用（`WXOpenBusinessView` requestMerchantTransfer） |
+| `mch_id` | string \| null | 商户号 |
+| `app_id` | string \| null | 微信 AppID |
+
+## 错误码
+- `400` 金额越界 / 未绑定微信
+- `409` 现金余额不足
+- `502` 微信转账调用失败（余额已退回）
+- `503` 微信支付未配置
+
+## 说明
+走微信「商家转账到零钱」V3。先扣余额建单再调微信,转账失败则退回余额。`out_bill_no` 幂等防止网络重试重复打款。返回的 `package_info`/`mch_id`/`app_id` 供 App 拉起微信确认页;确认结果由 [wallet-withdraw-status](./wallet-withdraw-status.md) 轮询。