# 斗拱支付接入备注

## 1. 配置接入

目的：让斗拱商户配置从运行环境注入，避免源码硬编码商户号、私钥和公钥。  
操作：通过 `HuiFuProperties` 读取 `huifu.*`，配置项在 `application.yml` 中映射到 `HUIFU_PRODUCT_ID`、`HUIFU_SYS_ID`、`HUIFU_RSA_PRIVATE_KEY`、`HUIFU_RSA_PUBLIC_KEY`、`HUIFU_ID`、`HUIFU_UPPER_HUIFU_ID`、`HUIFU_CALLBACK_PATH`。  
影响范围：影响所有斗拱接口调用，包括支付创建、退款、提现、分账、进件和回调验签。  
验证：执行 `mvn -DskipTests compile`，确认配置类能正常编译；运行环境需要确认这些环境变量非空。  
注意：生产密钥必须通过环境变量或安全配置中心注入，不能提交到 Git。

## 2. 支付创建

目的：后端生成斗拱微信小程序支付或支付宝支付请求，避免前端直接拼接支付参数。  
操作：`DouGongPayUtil` 统一生成 `req_seq_id`、`req_date`、`notify_url`、`trans_amt`，再按斗拱要求生成 RSA 签名并请求 `/v4/trade/payment/create`。  
影响范围：游客端 `PUT /api/mini/orders/{id}/pay` 只创建支付参数，不再直接修改订单状态；小程序使用返回参数调用 `uni.requestPayment`。
验证：调用 `wxPayOrder` 后应拿到斗拱 `pay_info`；同一订单的成功支付参数会按 `req_seq_id` 在 Redis 缓存五分钟，防止重复创建支付请求。
注意：创建支付订单不等于本地订单已支付，本地订单状态必须等斗拱回调验签成功后再更新。

## 3. 回调验签

目的：确保支付、退款、提现回调确实来自斗拱平台，防止伪造回调修改本地订单或资金状态。  
操作：`DouGongNotifyController` 接收 `/base/dougong/**`，校验 `sign` 和 `resp_data`，使用 `HUIFU_RSA_PUBLIC_KEY` 验签；支付回调继续校验商户号、支付金额和交易状态。
影响范围：影响 `/base/dougong/pay-notify`、`/base/dougong/refund-logistics`、`/base/dougong/refund-crosscity`、`/base/dougong/encashment`。  
验证：安全配置已放行 `/base/dougong/**`；回调成功时日志会记录 `req_seq_id`、`org_req_seq_id`、`trans_stat`。  
注意：只有 `trans_stat=S` 的验签成功回调才会把订单从 `PENDING_PAYMENT` 更新为 `PENDING_ACCEPT`；重复回调不会重复派单，金额不一致或商户号不匹配返回 `FAIL`。

## 4. 退款处理

目的：通过斗拱发起原路退款，并保留退款回调用于最终确认。  
操作：`DouGongRefundBiz.refund` 组装 `req_seq_id`、`org_req_date`、`org_req_seq_id`、`ord_amt` 和退款回调地址。  
影响范围：影响订单取消、自动退款、后台退款等后续退款链路。  
验证：请求斗拱退款接口后应返回 `resp_code` 和 `resp_desc`；最终退款成功以退款回调 `trans_stat=S` 为准。  
注意：退款请求成功只代表斗拱受理，不能立即把本地退款状态当作最终成功。

## 5. 提现处理

目的：支持导游电子账户余额提现到绑定银行卡。  
操作：`DouGongWithdrawBiz.encashment` 组装提现金额、提现方汇付 ID、取现卡序列号、D1 到账类型和提现回调地址，并按完整报文签名。  
影响范围：影响导游余额、提现单审核、财务流水和提现回调处理。  
验证：斗拱返回体应包含提现受理结果；最终到账状态以 `/base/dougong/encashment` 回调为准。  
注意：当前工具只负责调用斗拱，导游余额扣减和提现单状态变更必须放到业务服务中做幂等处理。

## 6. 联调要求

目的：确保真实小程序支付和公网异步通知可以闭环。
操作：配置微信小程序 AppID 与汇付商户绑定关系，并将 `HUIFU_CALLBACK_PATH` 设置为汇付可访问的 HTTPS 域名根地址。
影响范围：支付回调地址为 `{HUIFU_CALLBACK_PATH}/base/dougong/pay-notify`。
验证：执行数据库迁移后，在微信开发者工具或真机拉起支付；支付成功后确认订单状态由回调更新，并检查相同回调重复发送不会重复派单。
注意：联调环境不得使用生产金额和生产用户，正式上线前需要验证支付超时、用户取消、重复回调、金额不一致和错误签名场景。