jsowell-charger-web/docs/刷新FLAG.md

需求概述

针对 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