diff --git a/docs/刷新FLAG.md b/docs/刷新FLAG.md new file mode 100644 index 000000000..91da65cdf --- /dev/null +++ b/docs/刷新FLAG.md @@ -0,0 +1,203 @@ +## 需求概述 + +针对 `adapay_unsplit_record` 表中的未分账/未退款记录，通过调用汇付（Adapay）API 查询最新的退款和分账数据，与本地数据库对比更新，并重新计算 `refund_flag` 和 `split_flag` 标识，确保数据一致性。 + +--- + +## 数据模型 + +### adapay_unsplit_record 表（核心字段） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int | 主键 | +| `payment_id` | varchar | 汇付支付对象ID（交易流水号） | +| `order_code` | varchar | 订单编号 | +| `order_no` | varchar | 交易订单号（汇付侧） | +| `merchant_code` | varchar | 商户号 | +| `pay_time` | datetime | 支付时间 | +| `pay_amount` | decimal | 交易订单金额（支付金额） | +| `settle_amount` | decimal | 结算金额（应分账金额，从订单表同步） | +| `confirmed_split_amount` | decimal | 已确认分账金额（汇付实际已分账） | +| `refund_amount` | decimal | 已撤销金额（汇付实际已退款） | +| `due_refund_amount` | decimal | 应退金额（从订单表同步） | +| `payment_revoke_amount` | decimal | 支付确认撤销金额（分账后又撤销） | +| `remaining_split_amount` | decimal | 剩余未分账金额 | +| `pile_type` | varchar | 桩类型（EV / eBike） | +| **`refund_flag`** | varchar | **退款标识**（SUCCESS / PROCESSING / FAILED） | +| **`split_flag`** | varchar | **分账标识**（SUCCESS / PROCESSING / FAILED） | +| `update_time` | datetime | 更新时间 | + +> 实体类：`jsowell-pile/.../domain/AdapayUnsplitRecord.java` +> 表只记录通过汇付支付的订单，`refund_flag` 和 `split_flag` 用于标识退款和分账是否已处理完成。 + +--- + +## 汇付 API 查询（延时结算模式） + +> 所有订单均采用延时结算模式，无需处理实时结算模式。 + +### 需要调用的 API + +| API | 方法 | 用途 | +|-----|------|------| +| 查询支付撤销对象列表 | `queryPaymentReverse(paymentId, wechatAppId)` | 获取已撤销/已退款金额 | +| 查询支付确认对象列表 | `queryPaymentConfirmList(dto)` | 获取已确认分账金额、预留分账金额、剩余未分账金额 | +| 查询支付对象详情 | `queryPaymentDetail(paymentId, wechatAppId)` | 获取支付对象完整信息 | + +> 服务类：`jsowell-pile/.../adapay/service/AdapayService.java` + +### API 返回的关键数据 + +**支付撤销 API 返回（延时模式退款用）：** +- `reverse_amt`：撤销金额（即退款金额） +- `trans_status`：交易状态（pending / succeeded / failed） + +**支付确认列表 API 返回：** +- `confirmed_amt`：已确认分账金额 +- `reserved_amt`：预留中金额（已发起但未确认） +- 各分账对象的 `div_members`：分账成员及金额 + +--- + +## 处理流程 + +### 整体流程 + +``` +取得 paymentId + │ + ├─ 1. 调用汇付 API 查询最新数据 + │ ├─ 查询支付撤销/退款 → 获取实际已退款金额 + │ └─ 查询支付确认列表 → 获取实际已分账金额 + │ + ├─ 2. 与本地数据库对比更新 + │ ├─ 对比 due_refund_amount（应退） vs refund_amount（实退） + │ ├─ 对比 settle_amount（应分） vs confirmed_split_amount（实分） + │ └─ 不一致则更新对应字段 + │ + └─ 3. 重新计算 refund_flag 和 split_flag + ├─ 退款标识：实际退款 >= 应退金额 → SUCCESS + ├─ 分账标识：实际分账 >= 应分金额 → SUCCESS + └─ 未达预期则标记 PROCESSING 或 FAILED +``` + +### 详细步骤 + +#### 步骤 1：查询汇付最新数据 + +1. **获取退款数据**：调用 `queryPaymentReverse`，查询该 `paymentId` 下所有支付撤销记录，汇总成功状态的撤销金额作为已退款金额 +2. **获取分账数据**：调用 `queryPaymentConfirmList`，获取所有分账确认对象的已确认金额和预留金额 +3. **获取剩余未分账金额**：`pay_amount - due_refund_amount - max(confirmed_amt) - max(reserved_amt)` + +#### 步骤 2：对比更新本地数据 + +| 对比项 | 本地字段 | 汇付数据源 | 更新字段 | +|--------|----------|------------|----------| +| 应退金额 | `due_refund_amount` | 订单表 `refund_amount` | `due_refund_amount` | +| 已退款金额 | `refund_amount` | 汇付退款/撤销 API汇总 | `refund_amount` | +| 结算金额 | `settle_amount` | 订单表 `settle_amount` | `settle_amount` | +| 已分账金额 | `confirmed_split_amount` | 汇付分账API汇总 | `confirmed_split_amount` | +| 剩余未分账金额 | `remaining_split_amount` | 计算得出 | `remaining_split_amount` | + +> 仅在有差异时才更新，减少不必要的写库操作。 + +#### 步骤 3：计算 flag 标识 + +**flag 状态值：** + +| 值 | 含义 | +|----|------| +| `SUCCESS` | 处理完成（实际金额 >= 预期金额 或 预期金额 <= 0） | +| `PROCESSING` | 处理中（已受理金额 >= 预期金额，但实际成功金额不足） | +| `FAILED` | 处理失败（已受理金额 < 预期金额） | + +**退款标识计算：** +``` +expected = due_refund_amount（应退金额） +success = 汇付实际成功退款金额 +accepted = 汇付已受理退款金额（成功 + 处理中） + +if expected <= 0 或 success >= expected → SUCCESS +else if accepted >= expected → PROCESSING +else → FAILED +``` + +**分账标识计算：** +``` +expected = pay_amount - due_refund_amount（预期应分账金额） +success = 汇付实际已确认分账金额 +accepted = confirmed + reserved（已确认 + 预留中） + +if expected <= 0 或 success >= expected → SUCCESS +else if accepted >= expected → PROCESSING +else → FAILED +``` + +--- + +## 相关代码索引 + +### 核心实现 + +| 功能 | 文件路径 | +|------|---------| +| **flag 刷新主逻辑** | `jsowell-quartz/.../service/impl/AdapayUnsplitRecordHandleServiceImpl.java` | +| 方法 `refreshUnsplitRecordHandleFlag()` | 第 532 行 — 核心刷新方法，查询汇付并对比更新 | +| 方法 `calculateHandleFlag()` | 第 686 行 — flag 计算逻辑 | +| 方法 `checkRefundAmount()` | 第 641 行 — 退款金额核对 | +| 方法 `checkSplitAmount()` | 第 653 行 — 分账金额核对 | +| 方法 `getRefundedAmount()` | 第 781 行 — 获取汇总退款金额 | + +### 汇付 API 调用 + +| 功能 | 文件路径 | +|------|---------| +| **AdapayService** | `jsowell-pile/.../adapay/service/AdapayService.java` | +| 查询支付撤销 | `queryPaymentReverse()` 第 1333 行 | +| 查询退款列表 | `queryPaymentRefund()` 第 1417 行 | +| 查询支付确认列表 | `queryPaymentConfirmList()` 第 1435 行 | +| 查询支付详情 | `queryPaymentDetail()` 第 1351 行 | + +### 数据层 + +| 功能 | 文件路径 | +|------|---------| +| **实体类** | `jsowell-pile/.../domain/AdapayUnsplitRecord.java` | +| **Mapper XML** | `jsowell-pile/src/main/resources/mapper/pile/AdapayUnsplitRecordMapper.xml` | +| **Service 接口** | `jsowell-pile/.../service/AdapayUnsplitRecordService.java` | +| **VO 对象** | `jsowell-pile/.../vo/AdapayUnsplitRecordVO.java` | + +### 定时任务入口 + +| 任务 | 文件路径 | 方法 | +|------|---------|------| +| 刷新 flag | `jsowell-quartz/.../task/JsowellTask.java` | — | +| 处理未结算订单 | `AdapayUnsplitRecordHandleServiceImpl.java` | `processUnSettledOrder()` | +| 补齐缺失字段 | `AdapayUnsplitRecordHandleServiceImpl.java` | `completeAdapayUnsplitRecordFields()` | + +### 订单退款服务 + +| 功能 | 文件路径 | +|------|---------| +| 汇付退款 | `jsowell-pile/.../service/impl/OrderBasicInfoServiceImpl.java` → `refundOrderWithAdapay()` | +| 退款信息查询 | `OrderBasicInfoServiceImpl.java` → `getOrderRefundInfoList()` | + +--- + +## 注意事项 + +1. **统一模式**：所有订单均为延时结算模式，退款通过 `queryPaymentReverse`（支付撤销）处理，分账通过 `queryPaymentConfirmList` / `createPaymentConfirmRequest` 处理 +2. **触发时机**：该流程通常在定时任务中批量执行，也可针对单个 `paymentId` 手动触发 +3. **幂等性**：通过 `insertOrUpdateSelective` 保证更新幂等，重复执行不会产生脏数据 +4. **分账前置条件**：有应退金额时，必须先确认退款足额成功才能继续分账 +5. **金额精度**：所有金额计算使用 `BigDecimal`，保留 2 位小数，四舍五入 +6. **API 限流**：批量处理时注意汇付 API 调用频率限制 + +--- + +## 汇付 API 文档 + +- 查询支付撤销对象列表：https://docs.adapay.tech/api/trade.html#id76 +- 查询支付确认对象列表：https://docs.adapay.tech/api/trade.html#id62 +- 汇付开发文档首页：https://docs.adapay.tech/api/introduce.html diff --git a/jsowell-admin/src/test/java/PaymentTestController.java b/jsowell-admin/src/test/java/PaymentTestController.java index dfe391efe..b2b7bab8f 100644 --- a/jsowell-admin/src/test/java/PaymentTestController.java +++ b/jsowell-admin/src/test/java/PaymentTestController.java @@ -166,7 +166,9 @@ public class PaymentTestController { public void refreshAdapayUnsplitRecordHandleFlagTest() { String startTime = "2025-01-11 06:51:00"; String endTime = "2026-01-29 09:28:00"; - adapayUnsplitRecordHandleService.refreshAdapayUnsplitRecordHandleFlag(startTime, endTime, wechatAppId1, null); + // adapayUnsplitRecordHandleService.refreshAdapayUnsplitRecordHandleFlag(startTime, endTime, wechatAppId1, null); + + adapayUnsplitRecordHandleService.syncAndRefreshFlagsFromAdapay(startTime, endTime, wechatAppId1, null); } /** @@ -174,8 +176,8 @@ public class PaymentTestController { */ @Test public void refreshAdapayUnsplitRecordHandleFlagTestV2() { - String paymentId = "002212025100717133810821564090057555968"; - adapayUnsplitRecordHandleService.refreshAdapayUnsplitRecordHandleFlag(paymentId, wechatAppId1); + String paymentId = "002212025100511252110820751665557659648"; + adapayUnsplitRecordHandleService.syncAndRefreshFlagsFromAdapay(paymentId, wechatAppId1); } /** diff --git a/jsowell-quartz/src/main/java/com/jsowell/quartz/service/AdapayUnsplitRecordHandleService.java b/jsowell-quartz/src/main/java/com/jsowell/quartz/service/AdapayUnsplitRecordHandleService.java index a2094918d..e4f2de2da 100644 --- a/jsowell-quartz/src/main/java/com/jsowell/quartz/service/AdapayUnsplitRecordHandleService.java +++ b/jsowell-quartz/src/main/java/com/jsowell/quartz/service/AdapayUnsplitRecordHandleService.java @@ -17,4 +17,8 @@ public interface AdapayUnsplitRecordHandleService { int refreshAdapayUnsplitRecordHandleFlag(String startTime, String endTime, String wechatAppId, Integer pageSize); void processUnSettledOrder(); + + int syncAndRefreshFlagsFromAdapay(String paymentId, String wechatAppId); + + int syncAndRefreshFlagsFromAdapay(String startTime, String endTime, String wechatAppId, Integer pageSize); } diff --git a/jsowell-quartz/src/main/java/com/jsowell/quartz/service/impl/AdapayUnsplitRecordHandleServiceImpl.java b/jsowell-quartz/src/main/java/com/jsowell/quartz/service/impl/AdapayUnsplitRecordHandleServiceImpl.java index 6c8f7af55..2ab8938f2 100644 --- a/jsowell-quartz/src/main/java/com/jsowell/quartz/service/impl/AdapayUnsplitRecordHandleServiceImpl.java +++ b/jsowell-quartz/src/main/java/com/jsowell/quartz/service/impl/AdapayUnsplitRecordHandleServiceImpl.java @@ -7,6 +7,7 @@ import com.jsowell.adapay.common.PaymentConfirmInfo; import com.jsowell.adapay.dto.PaymentConfirmParam; import com.jsowell.adapay.dto.QueryPaymentConfirmDTO; import com.jsowell.adapay.response.PaymentConfirmResponse; +import com.jsowell.adapay.response.PaymentReverseResponse; import com.jsowell.adapay.response.QueryPaymentConfirmDetailResponse; import com.jsowell.adapay.service.AdapayService; import com.jsowell.common.YouDianUtils; @@ -265,6 +266,231 @@ public class AdapayUnsplitRecordHandleServiceImpl implements AdapayUnsplitRecord return updatedCount; } + @Override + public int syncAndRefreshFlagsFromAdapay(String paymentId, String wechatAppId) { + if (StringUtils.isBlank(paymentId)) { + return 0; + } + List list = adapayUnsplitRecordService.selectByPaymentIds(Lists.newArrayList(paymentId)); + if (CollectionUtils.isEmpty(list)) { + log.warn("同步刷新未分账记录失败，记录不存在, paymentId:{}", paymentId); + return 0; + } + String appId = StringUtils.isBlank(wechatAppId) ? Constants.DEFAULT_APP_ID : wechatAppId; + return doSyncAndRefresh(list.get(0), appId) ? 1 : 0; + } + + @Override + public int syncAndRefreshFlagsFromAdapay(String startTime, String endTime, String wechatAppId, Integer pageSize) { + int size = pageSize == null || pageSize <= 0 ? 1000 : pageSize; + int pageNum = 1; + int updatedCount = 0; + String appId = StringUtils.isBlank(wechatAppId) ? Constants.DEFAULT_APP_ID : wechatAppId; + + while (true) { + PageUtils.startPage(pageNum, size); + List list = adapayUnsplitRecordService.queryUnsplitOrders(startTime, endTime); + if (CollectionUtils.isEmpty(list)) { + break; + } + + int batchUpdated = 0; + for (AdapayUnsplitRecord record : list) { + if (doSyncAndRefresh(record, appId)) { + batchUpdated++; + } + } + updatedCount += batchUpdated; + + if (list.size() < size) { + break; + } + pageNum++; + } + + log.info("同步刷新未分账记录完成, startTime:{}, endTime:{}, 更新:{}条", startTime, endTime, updatedCount); + return updatedCount; + } + + private boolean doSyncAndRefresh(AdapayUnsplitRecord record, String wechatAppId) { + if (record == null || StringUtils.isBlank(record.getPaymentId())) { + return false; + } + + String paymentId = record.getPaymentId(); + String orderCode = record.getOrderCode(); + if (StringUtils.isBlank(orderCode)) { + orderCode = extractOrderCode(record.getOrderNo()); + if (StringUtils.isNotBlank(orderCode)) { + record.setOrderCode(orderCode); + } + } + + boolean needUpdate = false; + + RefundAmountResult refundResult = queryRefundAmountFromAdapay(paymentId, wechatAppId); + SplitAmountResult splitResult = querySplitAmountFromAdapay(paymentId, wechatAppId); + + if (StringUtils.isNotBlank(orderCode)) { + OrderBasicInfo orderBasicInfo = orderBasicInfoService.getOrderInfoByOrderCode(orderCode); + if (orderBasicInfo != null) { + BigDecimal orderDueRefund = defaultAmount(orderBasicInfo.getRefundAmount()); + if (!isSameAmount(record.getDueRefundAmount(), orderDueRefund)) { + record.setDueRefundAmount(orderDueRefund); + needUpdate = true; + } + BigDecimal orderSettle = defaultAmount(orderBasicInfo.getSettleAmount()); + if (!isSameAmount(record.getSettleAmount(), orderSettle)) { + record.setSettleAmount(orderSettle); + needUpdate = true; + } + String pileType = YouDianUtils.isEBikePileSn(orderBasicInfo.getPileSn()) ? "eBike" : "EV"; + if (!StringUtils.equals(record.getPileType(), pileType)) { + record.setPileType(pileType); + needUpdate = true; + } + } + } + + if (!isSameAmount(record.getRefundAmount(), refundResult.refundedAmount)) { + record.setRefundAmount(refundResult.refundedAmount); + needUpdate = true; + } + if (!isSameAmount(record.getConfirmedSplitAmount(), splitResult.confirmedSplitAmount)) { + record.setConfirmedSplitAmount(splitResult.confirmedSplitAmount); + needUpdate = true; + } + BigDecimal remaining = calculateRemainingSplitAmount( + defaultAmount(record.getPayAmount()), + defaultAmount(record.getDueRefundAmount()), + splitResult.confirmedSplitAmount, + splitResult.reservedSplitAmount); + if (!isSameAmount(record.getRemainingSplitAmount(), remaining)) { + record.setRemainingSplitAmount(remaining); + needUpdate = true; + } + + BigDecimal dueRefundAmount = defaultAmount(record.getDueRefundAmount()); + String refundFlag = calculateHandleFlag(dueRefundAmount, refundResult.refundedAmount, refundResult.acceptedRefundAmount); + if (!StringUtils.equals(record.getRefundFlag(), refundFlag)) { + record.setRefundFlag(refundFlag); + needUpdate = true; + } + + BigDecimal expectedSplitAmount = defaultAmount(record.getPayAmount()).subtract(dueRefundAmount) + .setScale(2, BigDecimal.ROUND_HALF_UP); + if (expectedSplitAmount.compareTo(BigDecimal.ZERO) < 0) { + expectedSplitAmount = BigDecimal.ZERO; + } + BigDecimal acceptedSplitAmount = splitResult.confirmedSplitAmount.add(splitResult.reservedSplitAmount); + String splitFlag = calculateHandleFlag(expectedSplitAmount, splitResult.confirmedSplitAmount, acceptedSplitAmount); + if (!StringUtils.equals(record.getSplitFlag(), splitFlag)) { + record.setSplitFlag(splitFlag); + needUpdate = true; + } + + if (needUpdate) { + record.setUpdateTime(DateUtils.getNowDate()); + adapayUnsplitRecordService.insertOrUpdateSelective(record); + log.info("同步刷新未分账记录, paymentId:{}, orderCode:{}, dueRefundAmount:{}, refundedAmount:{}, " + + "expectedSplitAmount:{}, confirmedSplitAmount:{}, remainingSplitAmount:{}, refundFlag:{}, splitFlag:{}", + paymentId, orderCode, dueRefundAmount, refundResult.refundedAmount, + expectedSplitAmount, splitResult.confirmedSplitAmount, remaining, refundFlag, splitFlag); + return true; + } + return false; + } + + private RefundAmountResult queryRefundAmountFromAdapay(String paymentId, String wechatAppId) { + try { + List reverses = + adapayService.queryPaymentReverse(paymentId, wechatAppId); + if (CollectionUtils.isEmpty(reverses)) { + return new RefundAmountResult(BigDecimal.ZERO, BigDecimal.ZERO); + } + BigDecimal refundedAmount = BigDecimal.ZERO; + BigDecimal acceptedRefundAmount = BigDecimal.ZERO; + for (PaymentReverseResponse reverse : reverses) { + if (reverse == null) { + continue; + } + BigDecimal amt = parseAmount(reverse.getReverse_amt()); + acceptedRefundAmount = acceptedRefundAmount.add(amt); + if (reverse.isSuccess()) { + refundedAmount = refundedAmount.add(amt); + } + } + return new RefundAmountResult( + refundedAmount.setScale(2, BigDecimal.ROUND_HALF_UP), + acceptedRefundAmount.setScale(2, BigDecimal.ROUND_HALF_UP)); + } catch (Exception e) { + log.warn("查询汇付支付撤销金额异常, paymentId:{}", paymentId, e); + return new RefundAmountResult(BigDecimal.ZERO, BigDecimal.ZERO); + } + } + + private SplitAmountResult querySplitAmountFromAdapay(String paymentId, String wechatAppId) { + try { + QueryPaymentConfirmDTO dto = new QueryPaymentConfirmDTO(); + dto.setWechatAppId(wechatAppId); + dto.setPaymentId(paymentId); + QueryPaymentConfirmDetailResponse response = adapayService.queryPaymentConfirmList(dto); + if (response == null || CollectionUtils.isEmpty(response.getPaymentConfirms())) { + return new SplitAmountResult(BigDecimal.ZERO, BigDecimal.ZERO); + } + BigDecimal maxConfirmedAmount = BigDecimal.ZERO; + BigDecimal maxReservedAmount = BigDecimal.ZERO; + for (PaymentConfirmInfo confirm : response.getPaymentConfirms()) { + if (confirm == null) { + continue; + } + BigDecimal confirmedAmount = parseAmount(confirm.getConfirmedAmt()); + BigDecimal reservedAmount = parseAmount(confirm.getReservedAmt()); + if (confirmedAmount.compareTo(maxConfirmedAmount) > 0) { + maxConfirmedAmount = confirmedAmount; + } + if (reservedAmount.compareTo(maxReservedAmount) > 0) { + maxReservedAmount = reservedAmount; + } + } + return new SplitAmountResult( + maxConfirmedAmount.setScale(2, BigDecimal.ROUND_HALF_UP), + maxReservedAmount.setScale(2, BigDecimal.ROUND_HALF_UP)); + } catch (Exception e) { + log.warn("查询汇付支付确认金额异常, paymentId:{}", paymentId, e); + return new SplitAmountResult(BigDecimal.ZERO, BigDecimal.ZERO); + } + } + + private BigDecimal calculateRemainingSplitAmount(BigDecimal payAmount, BigDecimal dueRefundAmount, + BigDecimal confirmedSplitAmount, BigDecimal reservedSplitAmount) { + BigDecimal remaining = payAmount.subtract(dueRefundAmount) + .subtract(confirmedSplitAmount) + .subtract(reservedSplitAmount); + return remaining.compareTo(BigDecimal.ZERO) > 0 + ? remaining.setScale(2, BigDecimal.ROUND_HALF_UP) : BigDecimal.ZERO; + } + + private static class RefundAmountResult { + final BigDecimal refundedAmount; + final BigDecimal acceptedRefundAmount; + + RefundAmountResult(BigDecimal refundedAmount, BigDecimal acceptedRefundAmount) { + this.refundedAmount = refundedAmount == null ? BigDecimal.ZERO : refundedAmount; + this.acceptedRefundAmount = acceptedRefundAmount == null ? BigDecimal.ZERO : acceptedRefundAmount; + } + } + + private static class SplitAmountResult { + final BigDecimal confirmedSplitAmount; + final BigDecimal reservedSplitAmount; + + SplitAmountResult(BigDecimal confirmedSplitAmount, BigDecimal reservedSplitAmount) { + this.confirmedSplitAmount = confirmedSplitAmount == null ? BigDecimal.ZERO : confirmedSplitAmount; + this.reservedSplitAmount = reservedSplitAmount == null ? BigDecimal.ZERO : reservedSplitAmount; + } + } + /** * V1方法，获取退款金额与结算金额 */