49 lines
2.9 KiB
Markdown
49 lines
2.9 KiB
Markdown
# 鱼翅直充接入分析
|
||
|
||
## 与现有扫码充值的关系
|
||
|
||
当前项目的 `create_gold_qr` 调用斗鱼 `https://cz.douyu.com/m/gold/getQrCode`，返回 `pay_url`，由用户微信扫码付款；到账通过斗鱼余额接口轮询确认。
|
||
|
||
本目录文档描述的是第三方供应商的直充订单协议：商户创建订单后，由供应商处理充值，调用方通过查询订单或异步通知得到最终状态。它不能替换为现有二维码支付接口，也不应复用现有的扫码支付轮询逻辑。
|
||
|
||
## 已完成的 API 基础层
|
||
|
||
`core/douyu/recharge_api.py` 提供：
|
||
|
||
- MD5 签名、响应签名校验辅助方法；
|
||
- 创建订单 `createOrderV2`；
|
||
- 查询订单 `queryOrderV2`；
|
||
- 商户账户查询 `userInfoV2`；
|
||
- 环境变量配置和请求、响应格式校验。
|
||
|
||
嵌套的 `recharge_arg`、`ext_arg` 在签名中使用稳定的紧凑 JSON 字符串。该序列化方式需要供应商联调确认；若其服务端使用其他规则，应在 `FishFinRechargeClient._sign_value` 中按确认规则调整。
|
||
|
||
## 已确认商品
|
||
|
||
供应商商品列表中，鱼翅商品为“鱼翅-1元”：`goodsNo=111570`、单份供货成本 `0.993`。项目将它作为 API 渠道的默认商品参数。用户在工作台填写的充值面值同时传为 `buy_num` 与 `customer_price`，例如填写 `10` 会为每个勾选账号创建 `buy_num=10`、`customer_price=10` 的订单；整数金额以 JSON 整数发送，例如 `1` 而不是 `1.0`。供货成本不参与下单金额。
|
||
|
||
创建订单只会发送文档示例中的必填字段和 UID 对应的 `recharge_arg`；空 `notify_url` 与未约定的 `ext_arg` 不会发送或参与签名。`ext_arg` 仅在供应商明确约定 `skuid`、`skuname` 等字段后才可启用。
|
||
|
||
## 接入前待供应商确认
|
||
|
||
1. API 网关基地址（文档只给出相对路径）。
|
||
2. `AppKey` 的实际传输位置与字段名。当前协议示例只签名并发送 `app_id`，客户端不会猜测发送 `AppKey`。
|
||
3. `queryOrderV2` 所需的订单标识字段名（商户单号、供应商单号或两者）。
|
||
4. 创建订单完整字段和 `recharge_arg` 模板，尤其是鱼翅商品 `product_id`、价格、数量含义，以及是否必须传 `ext_arg`。
|
||
5. `recharge_arg` / `ext_arg` 的嵌套签名序列化规则，以及请求与响应是否必须验签。
|
||
6. 回调地址、回调重试与回调验签规则；生产接入应持久化商户订单号并实现幂等处理。
|
||
|
||
## 运行时配置
|
||
|
||
在 `.env` 中设置以下变量，凭据不应写入源码、数据库或前端响应：
|
||
|
||
```dotenv
|
||
FISH_FIN_RECHARGE_BASE_URL=https://supplier.example
|
||
FISH_FIN_RECHARGE_APP_ID=
|
||
FISH_FIN_RECHARGE_APP_KEY=
|
||
FISH_FIN_RECHARGE_APP_SECRET=
|
||
FISH_FIN_RECHARGE_TIMEOUT=20
|
||
```
|
||
|
||
确认上述信息后，下一步是在后台增加订单表、受权限保护的创建/查询接口、回调幂等处理，再将工作台的“充值鱼翅”从扫码路径显式分流为“扫码支付”和“供应商直充”两种方式。
|