# 斗拱支付接入备注

## 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`。  
影响范围：影响后续小程序订单从 `PENDING_PAYMENT` 进入真实支付流程，但当前还没有替换 `MiniTourOrderCommandService.confirmPayment` 的本地确认逻辑。  
验证：调用 `wxPayOrder` 或 `aliPayOrder` 后应拿到斗拱返回体和本地追加的 `req_seq_id`；微信支付响应会额外缓存到 Redis 五分钟。  
注意：创建支付订单不等于本地订单已支付，本地订单状态必须等斗拱回调验签成功后再更新。

## 3. 回调验签

目的：确保支付、退款、提现回调确实来自斗拱平台，防止伪造回调修改本地订单或资金状态。  
操作：`DouGongNotifyController` 接收 `/base/dougong/**`，校验 `sign` 和 `resp_data`，使用 `HUIFU_RSA_PUBLIC_KEY` 验签；验签失败返回 `FAIL`。  
影响范围：影响 `/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`。  
注意：当前回调只记录日志，后续要按 `req_seq_id` 做幂等落库，更新 `tour_order.payment_order_no`、`tour_order.status`、`tour_order.payment_time` 等字段。

## 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. 后续落地

目的：把斗拱工具真正接入本项目订单和资金模型。  
操作：下一步需要新增“创建斗拱支付订单”和“支付回调确认订单”服务，并在回调中按 `req_seq_id` 查本地订单。  
影响范围：涉及 `MiniTourOrderCommandService.confirmPayment`、`TourOrder` 支付字段、退款字段、导游收益和财务流水。  
验证：支付成功回调后订单只能从 `PENDING_PAYMENT` 流转到 `PENDING_ACCEPT`，重复回调不应重复入账或重复派单。  
注意：在回调落库完成前，不要把斗拱支付创建接口直接暴露为“支付成功”接口。