鱼翅直充接入分析

与现有扫码充值的关系

当前项目的 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 字符串，不是 JSON 数组或对象。客户端以紧凑 JSON 文本发送并将该文本原样参与签名。

已确认商品

供应商商品列表中，鱼翅商品为“鱼翅-1元”：goodsNo=111570、单份供货成本 0.993。项目将它作为 API 渠道的默认商品参数。用户在工作台填写的充值面值同时传为 buy_num 与 pay_amount，例如填写 10 会为每个勾选账号创建 buy_num=10、pay_amount=10、order_type=0 的直充订单；整数金额以 JSON 整数发送，例如 1 而不是 1.0。供货成本不参与下单金额。

创建订单使用新版必填字段 product_id、buy_num、pay_amount、out_order_id、order_type，其中 out_order_id 是稳定的 DYGF{任务ID}。UID 通过 JSON 字符串 recharge_arg 传递。空 notify_url 与未约定的 ext_arg 不会发送或参与签名。ext_arg 仅在供应商明确约定 skuid、skuname 等字段后才可启用。

查询订单使用 GET queryOrderV2?out_order_id=...。服务端会轮询该订单号；如果设置 FISH_FIN_RECHARGE_NOTIFY_URL，也会发送回调地址至供应商。回调地址为 /api/douyu/supplier-recharge/callback，仅接受通过 POST 签名验证的回调并按 out_order_id 幂等更新任务。

接入前待供应商确认

API 网关基地址（文档只给出相对路径）。
AppKey 的实际传输位置与字段名。当前协议示例只签名并发送 app_id，客户端不会猜测发送 AppKey。
鱼翅商品 product_id、pay_amount、buy_num 的最终业务约束，以及是否必须传 ext_arg。
回调地址的公网可达性与回调重试策略。

运行时配置

在 .env 中设置以下变量，凭据不应写入源码、数据库或前端响应：

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_NOTIFY_URL=https://your-domain.example/api/douyu/supplier-recharge/callback
FISH_FIN_RECHARGE_TIMEOUT=20

确认上述信息后，下一步是在后台增加订单表、受权限保护的创建/查询接口、回调幂等处理，再将工作台的“充值鱼翅”从扫码路径显式分流为“扫码支付”和“供应商直充”两种方式。

3.1 KiB Raw Blame History Unescape Escape