1.优化提现接口/api/finance/withdrawCreate

docs/36字花-移动端接口设计草案.md

@@ -428,6 +428,8 @@
   - `status`：int（启用状态，1=启用）
   - `tier_ids`：array（兼容字段；当前固定空数组，表示自动兼容全部充值档位）
 - `withdraw`：object
+  - `pay_channels`：array（提现可选支付渠道，用于 `withdrawCreate` 的 `channel_code`；仅返回后台已启用且服务端已对接出金的渠道）
+    - 每项：`code`（string，渠道代码，小写）、`name`（展示名）、`sort`（排序）
   - `banks`：array（提现银行）
   - `min_ewallet`：string（电子钱包最低提现）
   - `min_bank`：string（银行卡最低提现）
@@ -437,8 +439,11 @@
   - `rate_mode`：string（`fixed` / `live`）
   - `fields`：object（**与 DDPay / `withdrawCreate` 一致**，不由后台「支付/收款配置」开关维护；用于客户端展示必填项）
     - `receive_type_bank_only`：bool（当前固定 `true`，仅支持银行卡出金）
+    - `require_channel_code`：bool（固定 `true`，对应 `channel_code`）
     - `require_receiver_name`：bool（固定 `true`，对应 `receiver_name`）
     - `require_receive_account`：bool（固定 `true`，对应 `receive_account`）
+    - `require_receiver_email`：bool（固定 `true`，对应 `receiver_email`）
+    - `require_receiver_mobile`：bool（固定 `true`，对应 `receiver_mobile`）
     - `require_bank_code`：bool（固定 `true`，对应 `bank_code`）
     - `require_bank_branch`：bool（固定 `false`，`bank_branch` 选填，不传时服务端按 `N/A` 提交 DDPay）
 
@@ -578,12 +583,19 @@
 ### 5.7 提现申请
 - **POST** `/api/finance/withdrawCreate`
 
+说明：
+- **仅支持 DDPay 出金**：`channel_code` 必须为 **`ddpay`**（兼容同义字段 `pay_channel`），且该渠道在收银台配置中为启用状态，否则返回 `code=2004`。
+- 可选渠道列表见 `depositWithdrawConfig` → `withdraw.pay_channels`。
+
 请求参数：
+- `channel_code`：string，必填（支付渠道代码；当前仅支持 `ddpay`；兼容字段 `pay_channel`）
 - `withdraw_coin`：string（含义：申请提现金额，必须 > 0）
 - `receive_account`：string（含义：收款账号；对接 DDPay 出金时对应官方字段 **`receiver_account`**，为收款账户号/手机号，须与银行登记一致）
 - `receive_type`：string（含义：收款类型；当前版本仅支持 `bank`）
 - `idempotency_key`：string（含义：防重复提交提现）
 - `receiver_name`：string（含义：收款账户持有人姓名；`receive_type=bank` 必填，对应官方 **`receiver_name`**，须与银行登记一致）
+- `receiver_email`：string（含义：收款人邮箱，必填，须为合法邮箱格式，最长 255）
+- `receiver_mobile`：string（含义：收款人手机号，必填，5–32 位，仅允许数字与 `+` `-` 空格，至少含 5 位数字）
 - `bank_code`：string（含义：银行代码；`receive_type=bank` 必填。取值来自收银台配置 `withdraw_banks[].code`；服务端会映射为 DDPay 所需的 **`bank[name]`** 银行全称发起出金）
 - `bank_branch`：string（含义：银行支行名称；`receive_type=bank` 可选。官方 **`bank_branch`** 为必填项，若客户端不传则服务端按 **`N/A`** 提交，与 DDPay 文档「若缺失则默认值为 `N/A`」一致）
 
@@ -611,17 +623,18 @@
 - `risk_review_required`：bool（含义：是否命中人工审核）
 
 校验顺序（任一失败即返回对应错误码，不再创建订单）：
-1. 参数完整性与金额合法性（`code=1001`；金额必须为数值且 > 0）
-2. **待审核订单数限制**：同一用户 `status=0`（待审核）的 `withdraw_order` 不得超过 3 笔，否则 `code=2004 Too many pending withdraw orders`，`data` 中回传：
+1. 参数完整性与金额合法性（`code=1001`；含 `channel_code`、`withdraw_coin` 等必填项；金额必须为数值且 > 0）
+2. **支付渠道**：`channel_code` 非 `ddpay` 返回 `code=2004 Withdraw only supports DDPay`；渠道未启用返回 `code=2004 Pay channel not available`
+3. **待审核订单数限制**：同一用户 `status=0`（待审核）的 `withdraw_order` 不得超过 3 笔，否则 `code=2004 Too many pending withdraw orders`，`data` 中回传：
    - `max_pending`：上限值（当前为 `3`）
    - `pending_count`：当前待审核订单数
-3. `coin_balance >= withdraw_coin`，否则 `code=2001 Insufficient balance`
-4. **单笔上限校验**：`withdraw_coin <= max_withdrawable`，否则 `code=2002 Withdraw exceeds available bet flow`，`data` 中回传：
+4. `coin_balance >= withdraw_coin`，否则 `code=2001 Insufficient balance`
+5. **单笔上限校验**：`withdraw_coin <= max_withdrawable`，否则 `code=2002 Withdraw exceeds available bet flow`，`data` 中回传：
    - `max_withdrawable`：**当前允许的单笔最大提现金额**（= `min(coin_balance, max_withdraw_by_flow)`，前端据此提示"最大可提现金额为 XXX"）
    - `coin_balance`、`bet_flow_coin`、`total_withdraw_coin`、`ratio`
    - `max_withdraw_by_flow`：仅按打码量折算的上限（= `max(0, bet_flow_coin / ratio - total_withdraw_coin)`）；`ratio=0` 时为 `null`
-5. 以上全通过后在同一事务内：
-   - `withdraw_order` 写入：`amount` / `fee`（默认 0.5%） / `actual_amount = amount - fee` / `status=0`（待审核） / `channel_id` 取自用户归属渠道快照；同时写入收款字段（`receive_type/receive_account/receiver_name/bank_code/bank_branch`）。
+6. 以上全通过后在同一事务内：
+   - `withdraw_order` 写入：`pay_channel`（= `channel_code`）/ `amount` / `fee`（默认 0.5%） / `actual_amount = amount - fee` / `status=0`（待审核） / `channel_id` 取自用户归属渠道快照；同时写入收款字段（`receive_type/receive_account/receiver_email/receiver_mobile/receiver_name/bank_code/bank_branch`）。
    - `user` 表原子更新：`coin -= withdraw_coin` 且 `total_withdraw_coin += withdraw_coin`（WHERE `coin >= withdraw_coin` 防止并发超额扣减）。
    - `user_wallet_record` 写入 `biz_type=withdraw`、`direction=2`、`amount=withdraw_coin`、`ref_type=withdraw_order`、`idempotency_key=wd_apply_{order_no}`，代表"冻结"动作。
 
@@ -645,6 +658,11 @@
 - `withdraw_coin`：string（含义：申请提现金额，与后台 `withdraw_order.amount` 对齐）
 - `fee_coin`：string（含义：手续费，与后台 `withdraw_order.fee` 对齐）
 - `actual_arrival_coin`：string（含义：实际到账金额 = 申请金额 - 手续费；后台审核调整后会同步刷新）
+- `receive_type`：string（含义：收款类型）
+- `receive_account`：string（含义：收款账号）
+- `pay_channel`：string（含义：支付渠道代码，与 `channel_code` 一致）
+- `receiver_email`：string（含义：收款人邮箱）
+- `receiver_mobile`：string（含义：收款人手机号）
 - `reject_reason`：string/null（含义：拒绝原因，`status=rejected` 时取自 `withdraw_order.remark`，否则为 `null`）
 - `create_time`：int（含义：申请时间）
 - `review_time`：int/null（含义：审核时间戳，未审核为 `null`）