| | |
|---|
| | | |
|---|
| | | 目的：后端生成斗拱微信小程序支付或支付宝支付请求，避免前端直接拼接支付参数。 |
|---|
| | | 操作：`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 五分钟。 |
|---|
| | | 影响范围：游客端 `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` 验签；验签失败返回 `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` 等字段。 |
|---|
| | | 操作：`DouGongNotifyController` 接收 `/base/dougong/**` 和 `/api/base/dougong/**`，回调路径免 Token，校验 `sign` 和 `resp_data`，使用 `HUIFU_RSA_PUBLIC_KEY` 验签；支付回调继续校验商户号、支付金额和交易状态。 |
|---|
| | | 影响范围：影响 `/base/dougong/pay-notify`、`/api/base/dougong/pay-notify` 以及对应的退款、提现回调路径。 |
|---|
| | | 验证：安全配置已放行 `/base/dougong/**` 和 `/api/base/dougong/**`；回调成功时日志会记录 `req_seq_id`、`org_req_seq_id`、`trans_stat`。 |
|---|
| | | 注意：只有 `trans_stat=S` 的验签成功回调才会把订单从 `PENDING_PAYMENT` 更新为 `PENDING_ACCEPT`；重复回调不会重复派单，金额不一致或商户号不匹配返回 `FAIL`。 |
|---|
| | | |
|---|
| | | ## 4. 退款处理 |
|---|
| | | |
|---|
| | |
|---|
| | | 验证：斗拱返回体应包含提现受理结果；最终到账状态以 `/base/dougong/encashment` 回调为准。 |
|---|
| | | 注意：当前工具只负责调用斗拱，导游余额扣减和提现单状态变更必须放到业务服务中做幂等处理。 |
|---|
| | | |
|---|
| | | ## 6. 后续落地 |
|---|
| | | ## 6. 联调要求 |
|---|
| | | |
|---|
| | | 目的：把斗拱工具真正接入本项目订单和资金模型。 |
|---|
| | | 操作：下一步需要新增“创建斗拱支付订单”和“支付回调确认订单”服务，并在回调中按 `req_seq_id` 查本地订单。 |
|---|
| | | 影响范围：涉及 `MiniTourOrderCommandService.confirmPayment`、`TourOrder` 支付字段、退款字段、导游收益和财务流水。 |
|---|
| | | 验证：支付成功回调后订单只能从 `PENDING_PAYMENT` 流转到 `PENDING_ACCEPT`，重复回调不应重复入账或重复派单。 |
|---|
| | | 注意：在回调落库完成前，不要把斗拱支付创建接口直接暴露为“支付成功”接口。 |
|---|
| | | 目的：确保真实小程序支付和公网异步通知可以闭环。 |
|---|
| | | 操作：配置微信小程序 AppID 与汇付商户绑定关系，并将 `HUIFU_CALLBACK_PATH` 设置为汇付可访问的 HTTPS 域名根地址。 |
|---|
| | | 影响范围：支付回调地址为 `{HUIFU_CALLBACK_PATH}/base/dougong/pay-notify`。 |
|---|
| | | 验证：执行数据库迁移后，在微信开发者工具或真机拉起支付；支付成功后确认订单状态由回调更新，并检查相同回调重复发送不会重复派单。 |
|---|
| | | 注意：联调环境不得使用生产金额和生产用户，正式上线前需要验证支付超时、用户取消、重复回调、金额不一致和错误签名场景。 |
|---|
