WonderableAI/shaguabijia-app-server
11
0
Fork 0
Code Issues Pull Requests 13 Actions Packages Projects Releases Wiki Activity

@

Browse Source 
docs: reorganize api docs into categorized subdirectories and fill missing docs

- Categorize 77 existing api docs into 16 business-domain subdirectories
  (auth/ad/wallet/coupon/compare/savings/signin/tasks/invite/user/
   device/platform/intent/meituan/other) plus admin/ and internal/
- Split admin/ into 7 sub-resource subdirectories (auth/users/wallet/
  withdraws/feedbacks/admins/ad) with 4 single-file docs at root
- Create 21 new docs covering 28 previously undocumented endpoints:
  ad/watch-report, wallet/transfer-auth (3 endpoints), coupon/session+
  stats+completed-today+prompt (7), invite/me+invitees+bind+landing-track,
  user/onboarding (2), platform/flags+ad-config+app-version,
  intent/step+precoupon/step, analytics/events, order/report,
  report/submit+records, feedback/config+records, trace/finalize
- Add mock request/response JSON examples to all new docs
- Create docs/README.md with full category index for LLM navigation
- Update docs/api/README.md: fix all links, add new endpoint rows,
  replace "no doc" markers with actual links
- Fix back-navigation links (./README.md -> ../README.md or
  ../../README.md) in all moved files
@
This commit is contained in:
guke
2026-07-03 14:56:50 +08:00
parent ee132aa93b
commit b23335d5fb
102 changed files with 2418 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/wallet/wallet-account.md
+18
View File
@@ -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 | 累计赚取金币 |
## 说明
账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源。
docs/api/wallet/wallet-bind-wechat.md
+28
View File
@@ -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 唯一约束），一个微信只能绑一个账号。
docs/api/wallet/wallet-cash-transactions.md
+28
View File
@@ -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`）数据源。
docs/api/wallet/wallet-coin-transactions.md
+28
View File
@@ -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`）数据源。
docs/api/wallet/wallet-exchange-info.md
+18
View File
@@ -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`）。
docs/api/wallet/wallet-exchange.md
+26
View File
@@ -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)。金币与现金的扣加在同一事务内完成。
docs/api/wallet/wallet-transfer-auth.md
+108
View File
@@ -0,0 +1,108 @@
# 免确认收款授权（transfer-auth 族）
> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:全部 Bearer | [← 返回 API 索引](../README.md)
>
> 集成实现:见 [integrations/wxpay](../../integrations/wxpay.md)（微信 V3 免确认收款授权）。
开启一次后，后续提现走免确认转账直接到账，不再跳微信确认。绑定 openid 是前提。
---
## POST /transfer-auth — 开启免确认到账
申请免确认授权，返回拉起微信授权页的 `package_info`。
### 入参
无（`user_id` 从 JWT 取）。
### 出参
响应 `200`:`TransferAuthResultOut`
| 字段 | 类型 | 说明 |
|---|---|---|
| `already_active` | bool | 是否已是开启状态（无需再授权） |
| `package_info` | string \| null | 拉起微信授权页的 package；已开启时为空 |
| `mch_id` | string \| null | 商户号 |
| `app_id` | string \| null | 微信 AppID |
Mock 出参（首次申请）:
```json
{
"already_active": false,
"package_info": "affirmTransferAuth|{\"mchId\":\"1234567890\",\"appId\":\"wxabc123\",\"package\":\"affirm_biz_123\"}",
"mch_id": "1234567890",
"app_id": "wxabc123"
}
```
Mock 出参（已开启，无需重复授权）:
```json
{
"already_active": true,
"package_info": null,
"mch_id": "1234567890",
"app_id": "wxabc123"
}
```
### 错误码
- `400` 未绑定微信
- `502` 微信授权接口调用失败
- `503` 微信支付授权未配置
---
## GET /transfer-auth/status — 查免确认授权状态
从微信授权页返回后轮询。
### 入参
无（`user_id` 从 JWT 取）。
### 出参
响应 `200`:`TransferAuthStatusOut`
| 字段 | 类型 | 说明 |
|---|---|---|
| `state` | string | `none`（未开启）/ `pending`（待确认）/ `active`（已开启）/ `closed`（已关闭） |
| `enabled` | bool | 是否已开启免确认到账 |
Mock 出参:
```json
{
"state": "active",
"enabled": true
}
```
---
## POST /transfer-auth/close — 关闭免确认到账
解除授权，恢复每次提现跳微信确认。
### 入参
无（`user_id` 从 JWT 取）。
### 出参
响应 `200`:`TransferAuthStatusOut`（同上）
Mock 出参:
```json
{
"state": "closed",
"enabled": false
}
```
---
## 错误码（通用）
- `401` 未鉴权 / token 失效
- `503` 微信支付授权未配置
docs/api/wallet/wallet-unbind-wechat.md
+28
View File
@@ -0,0 +1,28 @@
# POST /api/v1/wallet/unbind-wechat — 解绑微信(清空 openid)
> 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
>
> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)。
## 入参
请求体 `UnbindWechatRequest`（**可选**:旧客户端可不带 body,等价 `force=false`）:
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `force` | bool | `false` | 跳过「有待审核提现」二次确认,强制解绑。首次解绑传 `false`;命中 `needs_confirm` 后用户确认,再带 `true` 调一次才真解绑 |
## 出参
响应 `200`:`UnbindWechatResultOut`
| 字段 | 类型 | 说明 |
|---|---|---|
| `bound` | bool | 解绑成功为 `false`;命中二次确认(本次未解绑)时为当前真实绑定态(通常 `true`) |
| `needs_confirm` | bool | `true` = 有待审核提现且未 `force`,**本次未解绑**,客户端应弹确认弹窗 |
| `message` | string \| null | `needs_confirm=true` 时的提示文案,直接展示给用户 |
## 说明
清空当前用户的 `wechat_openid` / `wechat_nickname` / `wechat_avatar_url`。幂等:未绑定时调用也返回 `bound=false`。解绑后该微信可被其他账号绑定。
**有待审核提现时的二次确认**:用户有 `reviewing`(待审核)状态的提现单且未带 `force=true` 时,**首次解绑被拦下**——不清 openid,返回 `bound`(真实绑定态)+ `needs_confirm=true` + `message`。客户端据此弹确认弹窗,用户确认后带 `force=true` 再调一次即放行解绑。
> 只拦 `reviewing`:这类单还没打款,用户确认解绑(`force=true`)时**立即退回现金余额**(写 `withdraw_refund` 流水、单子置终态),后台不再挂单、不必等管理员审核。`pending`(打款在途)单转账已发起、解绑影响不到、照常打款到微信,故**不拦**。
docs/api/wallet/wallet-withdraw-info.md
+22
View File
@@ -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`）。
docs/api/wallet/wallet-withdraw-orders.md
+28
View File
@@ -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 | 发起时间 |
## 说明
提现记录页数据源。
docs/api/wallet/wallet-withdraw-status.md
+27
View File
@@ -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`)。
docs/api/wallet/wallet-withdraw.md
+36
View File
@@ -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) 轮询。