优化斗鱼充值

2026-08-13 21:43:27 +08:00
parent 902e669614
commit 0bf69c1240
19 changed files with 450 additions and 266 deletions
@@ -16,22 +16,22 @@
 - 商户账户查询 `userInfoV2`；
 - 环境变量配置和请求、响应格式校验。

-嵌套的 `recharge_arg`、`ext_arg` 在签名中使用稳定的紧凑 JSON 字符串。该序列化方式需要供应商联调确认；若其服务端使用其他规则，应在 `FishFinRechargeClient._sign_value` 中按确认规则调整。
+新版订单文档规定：`recharge_arg`、`ext_arg` 都是 JSON 字符串，不是 JSON 数组或对象。客户端以紧凑 JSON 文本发送并将该文本原样参与签名。

 ## 已确认商品

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

-创建订单只会发送文档示例中的必填字段和 UID 对应的 `recharge_arg`；空 `notify_url` 与未约定的 `ext_arg` 不会发送或参与签名。`ext_arg` 仅在供应商明确约定 `skuid`、`skuname` 等字段后才可启用。
+创建订单使用新版必填字段 `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` 幂等更新任务。

 ## 接入前待供应商确认

 1. API 网关基地址（文档只给出相对路径）。
 2. `AppKey` 的实际传输位置与字段名。当前协议示例只签名并发送 `app_id`，客户端不会猜测发送 `AppKey`。
-3. `queryOrderV2` 所需的订单标识字段名（商户单号、供应商单号或两者）。
-4. 创建订单完整字段和 `recharge_arg` 模板，尤其是鱼翅商品 `product_id`、价格、数量含义，以及是否必须传 `ext_arg`。
-5. `recharge_arg` / `ext_arg` 的嵌套签名序列化规则，以及请求与响应是否必须验签。
-6. 回调地址、回调重试与回调验签规则；生产接入应持久化商户订单号并实现幂等处理。
+3. 鱼翅商品 `product_id`、`pay_amount`、`buy_num` 的最终业务约束，以及是否必须传 `ext_arg`。
+4. 回调地址的公网可达性与回调重试策略。

 ## 运行时配置

@@ -42,6 +42,7 @@ 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
 ```