鱼翅直充接入分析

与现有扫码充值的关系

当前项目的 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 等字段后才可启用。

接入前待供应商确认

API 网关基地址（文档只给出相对路径）。
AppKey 的实际传输位置与字段名。当前协议示例只签名并发送 app_id，客户端不会猜测发送 AppKey。
queryOrderV2 所需的订单标识字段名（商户单号、供应商单号或两者）。
创建订单完整字段和 recharge_arg 模板，尤其是鱼翅商品 product_id、价格、数量含义，以及是否必须传 ext_arg。
recharge_arg / 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_TIMEOUT=20

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

2.9 KiB Raw Blame History Unescape Escape