b2894lxlx/tms-erp-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ 合并金蝶冲销状态回写，拆分独立定时任务并支持分批

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
b2894lxlx
2026-11-04 16:52:23 +08:00
parent e3372d3fbc 014d254295
commit d1562ebb6b
12 changed files with 428 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java
+23
View File
@@ -110,6 +110,11 @@ public class BfiProperties {
*/
private ArResult arResult = new ArResult();
/**
* 金蝶冲销状态回写配置（A102-4/A302-4）
*/
private WriteOffResult writeOffResult = new WriteOffResult();
/**
* 金蝶单据锁定补偿配置
*/
@@ -352,6 +357,24 @@ public class BfiProperties {
private long lockLeaseSeconds = 1800;
}
/**
* 金蝶冲销状态回写配置项（A102-4/A302-4）：定时回写开关、防重键批量查询与结算单批量更新的分批大小，
* 防止单批过大超出金蝶查询接口与批量落库承载能力
*/
@Data
public static class WriteOffResult {
/**
* 冲销状态回写任务开关，默认关闭（安全兜底），由 Nacos 按环境显式开启
*/
private boolean syncEnabled = false;
/**
* 冲销状态批量查询/批量更新分批大小，默认 1000
*/
private int queryBatchSize = 1000;
}
/**
* 金蝶单据锁定补偿配置项
*/
blade-service/blade-transport/src/main/java/org/springblade/transport/constant/KingdeeBfiConstant.java
+6
View File
@@ -171,6 +171,12 @@ public final class KingdeeBfiConstant {
/** 金蝶同步状态：生成失败（推送异常/金蝶返回失败，可重推）。 */
public static final String KINGDEE_STATUS_FAILED = "failed";
/** 金蝶冲销状态：未冲销（旧应付/应收单在金蝶尚未冲销）。 */
public static final String KINGDEE_WRITEOFF_UNWRITTEN = "unwrittenoff";
/** 金蝶冲销状态：已冲销（旧应付/应收单已在金蝶冲销，部分冲销视同已冲销）。 */
public static final String KINGDEE_WRITEOFF_WRITTEN = "writtenoff";
/** 收票单推送状态：未推送（新建单据默认，票池绑定层的 kingdee_status 与此无关）。 */
public static final String RECEIVED_PUSH_UNSYNCED = "unsynced";
blade-service/blade-transport/src/main/java/org/springblade/transport/service/IFormalSettlementService.java
+17
View File
@@ -80,6 +80,23 @@ public interface IFormalSettlementService extends BaseService<FormalSettlement>
String retryKingdeeFailed();
String syncKingdeeArResult();
/**
* 金蝶冲销状态定时回写：扫描已同步金蝶的结算单，按防重键批量查询 A102-4/A302-4 的
* hadwrittenoff（部分冲销视同已冲销），回写冲销状态供结算单列表展示
*
* @return 执行摘要
*/
String syncKingdeeWriteOffResult();
/**
* 单笔刷新金蝶冲销状态（选单预检/重推闸门实时查询后回写，状态未变化不落库）
*
* @param settlementId 正式结算单id
* @param writtenOff 金蝶侧应付/应收单是否已冲销
*/
void refreshKingdeeWriteOff(Long settlementId, boolean writtenOff);
List<FormalSettlementDetailFee> detailFees(Long detailId);
void adjustDetail(PreSettlementDetailAdjustRequest request);
void refreshPaymentSummary(Long settlementId);
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/FormalSettlementServiceImpl.java
+110
View File
@@ -155,6 +155,9 @@ public class FormalSettlementServiceImpl extends BaseServiceImpl<FormalSettlemen
/** 金蝶应收单勾稽结算明细分批查询单次条数上限（in 条件分批，避免单次过滤条件过长） */
private static final int AR_RESULT_DETAIL_QUERY_BATCH = 500;
/** 金蝶冲销状态回写 single-flight 锁键前缀（多副本定时任务与手动触发共用） */
private static final String WRITEOFF_SYNC_LOCK_PREFIX = "transport:formal-settlement:kingdee-writeoff-sync:";
private final FormalSettlementSourceMapper sourceMapper;
private final FormalSettlementSummaryFeeMapper summaryFeeMapper;
private final FormalSettlementPaymentMapper paymentMapper;
@@ -1138,6 +1141,113 @@ public class FormalSettlementServiceImpl extends BaseServiceImpl<FormalSettlemen
return summary;
}
@Override
public String syncKingdeeWriteOffResult() {
return kingdeeSyncLockSupport.runSingleFlight(WRITEOFF_SYNC_LOCK_PREFIX, bfiProperties.getArResult().getLockLeaseSeconds(),
"金蝶冲销状态回写", this::executeWriteOffSync);
}
@Override
public void refreshKingdeeWriteOff(Long settlementId, boolean writtenOff) {
String status = writtenOff ? KingdeeBfiConstant.KINGDEE_WRITEOFF_WRITTEN : KingdeeBfiConstant.KINGDEE_WRITEOFF_UNWRITTEN;
FormalSettlement settlement = getById(settlementId);
// 状态未变化不落库，避免预检反复点击重复更新
if (settlement == null || status.equals(settlement.getKingdeeWriteOffStatus())) {
return;
}
FormalSettlement patch = new FormalSettlement();
patch.setId(settlementId);
patch.setKingdeeWriteOffStatus(status);
patch.setKingdeeWriteOffTime(LocalDateTime.now());
updateById(patch);
log.info("正式结算单[{}]金蝶冲销状态回写：{}", settlement.getFormalSettlementNo(), status);
}
/**
* 金蝶冲销状态回写主体：A102-4/A302-4 批量查询已同步结算单的 hadwrittenoff（部分冲销视同已冲销）
* 并回写冲销状态，由 {@link #syncKingdeeWriteOffResult()} 在分布式锁保护下调用。
* <p>分批与事务口径同 {@link #executeArResultSync()}：结算明细分批 in 查询、远程整批查询消除逐单 N+1，
* 仅回写状态有变化的结算单并 updateBatchById 批量落库；整轮任务不包外层事务，按防重键幂等可重跑。
*
* @return 执行摘要
*/
private String executeWriteOffSync() {
long startMillis = System.currentTimeMillis();
// 已同步金蝶的结算单才在金蝶存在旧应付/应收单，未同步/生成失败不查询（前端展示 '-'）；
// 已冲销为终态不再复查，仅扫未冲销单据（存量 NULL 由 06 脚本回填默认未冲销）
List<FormalSettlement> settlements = list(Wrappers.<FormalSettlement>lambdaQuery()
.eq(FormalSettlement::getKingdeeSyncStatus, KingdeeBfiConstant.KINGDEE_STATUS_SYNCED)
.eq(FormalSettlement::getKingdeeWriteOffStatus, KingdeeBfiConstant.KINGDEE_WRITEOFF_UNWRITTEN)
.orderByAsc(FormalSettlement::getId));
if (Func.isEmpty(settlements)) {
log.info("金蝶冲销状态回写：无待查未冲销结算单");
return "金蝶冲销状态回写：无待查未冲销结算单";
}
log.info("金蝶冲销状态回写：本轮扫描待查未冲销结算单{}笔", settlements.size());
// 结算明细分批一次查全（消除逐单查询 N+1），按结算单 id 分组后按结算类型组装防重键
List<Long> settlementIds = settlements.stream().map(FormalSettlement::getId).toList();
Map<Long, List<FormalSettlementDetail>> detailsBySettlement = new HashMap<>();
kingdeeApBillSyncSupport.batchForeach(settlementIds, AR_RESULT_DETAIL_QUERY_BATCH, batch ->
detailsBySettlement.putAll(detailMapper.selectList(Wrappers.<FormalSettlementDetail>lambdaQuery()
.in(FormalSettlementDetail::getFormalSettlementId, batch)
.eq(FormalSettlementDetail::getIsDeleted, 0)
.orderByAsc(FormalSettlementDetail::getLineNo)).stream()
.collect(Collectors.groupingBy(FormalSettlementDetail::getFormalSettlementId))));
Map<String, FormalSettlement> apSettlementBySrcCode = new LinkedHashMap<>();
Map<String, FormalSettlement> arSettlementBySrcCode = new LinkedHashMap<>();
for (FormalSettlement settlement : settlements) {
List<FormalSettlementDetail> details = detailsBySettlement.getOrDefault(settlement.getId(), List.of());
if (Func.isEmpty(details)) {
continue;
}
if ("receivable".equals(settlement.getSettlementType())) {
String srcCode = kingdeeArBillSyncSupport.arBillSrcCode(settlement, details);
if (Func.isNotBlank(srcCode)) {
arSettlementBySrcCode.putIfAbsent(srcCode, settlement);
}
} else {
String srcCode = kingdeeApBillSyncSupport.apBillSrcCode(settlement, details);
if (Func.isNotBlank(srcCode)) {
apSettlementBySrcCode.putIfAbsent(srcCode, settlement);
}
}
}
// A102-4/A302-4 整批一次查询，冲销状态有变化的才落库（updateBatchById 批量更新，避免逐单 update）
log.info("金蝶冲销状态回写：防重键组装完成，应付{}个、应收{}个，按批次大小{}分批查询",
apSettlementBySrcCode.size(), arSettlementBySrcCode.size(), bfiProperties.getWriteOffResult().getQueryBatchSize());
Map<String, Boolean> apWriteOffFlags = kingdeeApBillSyncSupport.queryApBillWriteOffFlags(new ArrayList<>(apSettlementBySrcCode.keySet()));
Map<String, Boolean> arWriteOffFlags = kingdeeArBillSyncSupport.queryArBillWriteOffFlags(new ArrayList<>(arSettlementBySrcCode.keySet()));
// 金蝶未返回的键按未冲销处理，返回数与组装数差异即金蝶侧查不到单据的规模，留痕便于对账
log.info("金蝶冲销状态批量查询完成：应付键返回{}个、应收键返回{}个，未返回键按未冲销处理",
apWriteOffFlags.size(), arWriteOffFlags.size());
List<FormalSettlement> toUpdateSettlements = new ArrayList<>();
apSettlementBySrcCode.forEach((srcCode, settlement) ->
this.applyWriteOffFlag(settlement, apWriteOffFlags.get(srcCode), toUpdateSettlements));
arSettlementBySrcCode.forEach((srcCode, settlement) ->
this.applyWriteOffFlag(settlement, arWriteOffFlags.get(srcCode), toUpdateSettlements));
if (Func.isNotEmpty(toUpdateSettlements)) {
// 批量落库按同一分批大小拆分，避免单批过大
updateBatchById(toUpdateSettlements, bfiProperties.getWriteOffResult().getQueryBatchSize());
log.info("金蝶冲销状态回写：批量落库完成，本批更新{}笔", toUpdateSettlements.size());
}
String summary = "金蝶冲销状态回写完成：待查未冲销结算单" + (apSettlementBySrcCode.size() + arSettlementBySrcCode.size())
+ "笔，回写" + toUpdateSettlements.size() + "笔";
log.info("{}，耗时{}ms", summary, System.currentTimeMillis() - startMillis);
return summary;
}
/** 应用单笔冲销查询结果：与本地冲销状态不一致时标记更新（查不到金蝶单据按未冲销处理），一致跳过 */
private void applyWriteOffFlag(FormalSettlement settlement, Boolean writtenOff, List<FormalSettlement> toUpdateSettlements) {
String status = Boolean.TRUE.equals(writtenOff) ? KingdeeBfiConstant.KINGDEE_WRITEOFF_WRITTEN : KingdeeBfiConstant.KINGDEE_WRITEOFF_UNWRITTEN;
if (status.equals(settlement.getKingdeeWriteOffStatus())) {
return;
}
settlement.setKingdeeWriteOffStatus(status);
settlement.setKingdeeWriteOffTime(LocalDateTime.now());
toUpdateSettlements.add(settlement);
log.info("金蝶冲销状态回写：正式结算单[{}]，{}", settlement.getFormalSettlementNo(), status);
}
@Override
@Transactional(rollbackFor = Exception.class)
public String applyPayment(FormalSettlementPaymentRequest request) {
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/SettlementAdjustmentServiceImpl.java
+8 -1
View File
@@ -242,10 +242,15 @@ public class SettlementAdjustmentServiceImpl extends BaseServiceImpl<SettlementA
+ "]尚未推送金蝶，请先执行「推送金蝶」");
}
// 冲销硬闸门：仅当金蝶侧原应付/应收单已被冲销（部分冲销放行）才允许以新单号重推，避免重复生成财务单据
if (!this.kingdeeWrittenOff(original)) {
boolean writtenOff = this.kingdeeWrittenOff(original);
// 闸门查询即金蝶实时冲销状态，回写供结算单列表展示（查到未冲销同样回写，拦截提示后列表即同步）
formalSettlementService.refreshKingdeeWriteOff(original.getId(), writtenOff);
if (!writtenOff) {
throw new ServiceException("结算单[" + Func.toStr(original.getFormalSettlementNo())
+ "]的原应付/应收单尚未在金蝶冲销，禁止重推");
}
// 闸门查询即金蝶实时冲销状态，回写供结算单列表展示
formalSettlementService.refreshKingdeeWriteOff(original.getId(), true);
// 幂等：同一原单已克隆过新单则复用（重试从推送步骤续上），避免重复建单
FormalSettlement clone = existingClone(original.getFormalSettlementNo());
if (clone == null) {
@@ -302,6 +307,8 @@ public class SettlementAdjustmentServiceImpl extends BaseServiceImpl<SettlementA
result.put("syncStatus", KingdeeBfiConstant.KINGDEE_STATUS_SYNCED);
try {
boolean writtenOff = this.kingdeeWrittenOff(settlement);
// 预检查询即金蝶实时冲销状态，顺带回写供结算单列表展示
formalSettlementService.refreshKingdeeWriteOff(settlement.getId(), writtenOff);
result.put("writtenOff", writtenOff);
result.put("message", writtenOff
? "该结算单已推送金蝶且旧单已冲销，审批后可直接重新推送新单"
blade-service/blade-transport/src/main/java/org/springblade/transport/support/KingdeeApBillSyncSupport.java
+27 -12
View File
@@ -212,19 +212,34 @@ public class KingdeeApBillSyncSupport {
if (Func.isBlank(awrpSrcCode)) {
return false;
}
BfiApBillQueryDTO param = new BfiApBillQueryDTO();
param.setAwrpSrcCode(List.of(awrpSrcCode));
param.setAwrpSrcSys(bfiProperties.getSrcSys());
for (BfiApBillVO apBill : BfiUtil.queryAllPages(pageNo -> {
param.setPageNo(pageNo);
param.setPageSize(PAY_RESULT_PAGE_SIZE);
return bfiService.queryApBill(param);
})) {
if (awrpSrcCode.equals(apBill.getAwrpSrcCode()) && Boolean.TRUE.equals(apBill.getHadwrittenoff())) {
return true;
return queryApBillWriteOffFlags(List.of(awrpSrcCode)).getOrDefault(awrpSrcCode, Boolean.FALSE);
}
/**
* A102-4 冲销状态批量查询：防重键批量分批查询财务应付单，返回 防重键 -&gt; 是否已冲销
* （hadwrittenoff=true，部分冲销同样视为已冲销；同键多单取或，查不到的键不在结果中即视为未冲销）。
* 定时回写结算单金蝶冲销状态用，整批一次查询消除逐单远程查询 N+1
*
* @param awrpSrcCodes 财务应付单防重键列表
* @return 防重键 -&gt; 是否已冲销
*/
public Map<String, Boolean> queryApBillWriteOffFlags(List<String> awrpSrcCodes) {
Map<String, Boolean> writeOffFlags = new LinkedHashMap<>();
batchForeach(awrpSrcCodes, bfiProperties.getWriteOffResult().getQueryBatchSize(), batch -> {
BfiApBillQueryDTO param = new BfiApBillQueryDTO();
param.setAwrpSrcCode(batch);
param.setAwrpSrcSys(bfiProperties.getSrcSys());
for (BfiApBillVO apBill : BfiUtil.queryAllPages(pageNo -> {
param.setPageNo(pageNo);
param.setPageSize(PAY_RESULT_PAGE_SIZE);
return bfiService.queryApBill(param);
})) {
if (Func.isNotEmpty(apBill.getAwrpSrcCode())) {
writeOffFlags.merge(apBill.getAwrpSrcCode(), Boolean.TRUE.equals(apBill.getHadwrittenoff()), Boolean::logicalOr);
}
}
}
return false;
});
return writeOffFlags;
}
// ==================== A102-2 财务应付单保存 ====================
blade-service/blade-transport/src/main/java/org/springblade/transport/support/KingdeeArBillSyncSupport.java
+27 -12
View File
@@ -150,19 +150,34 @@ public class KingdeeArBillSyncSupport {
if (Func.isBlank(arBillSrcCode)) {
return false;
}
BfiArBillQueryDTO param = new BfiArBillQueryDTO();
param.setAwrpSrcCode(List.of(arBillSrcCode));
param.setAwrpSrcSys(bfiProperties.getSrcSys());
for (BfiArBillVO arBill : BfiUtil.queryAllPages(pageNo -> {
param.setPageNo(pageNo);
param.setPageSize(AR_RESULT_PAGE_SIZE);
return bfiService.queryArBill(param);
})) {
if (arBillSrcCode.equals(arBill.getAwrpSrcCode()) && Boolean.TRUE.equals(arBill.getHadwrittenoff())) {
return true;
return queryArBillWriteOffFlags(List.of(arBillSrcCode)).getOrDefault(arBillSrcCode, Boolean.FALSE);
}
/**
* A302-4 冲销状态批量查询：防重键批量分批查询财务应收单，返回 防重键 -&gt; 是否已冲销
* （hadwrittenoff=true，部分冲销同样视为已冲销；同键多单取或，查不到的键不在结果中即视为未冲销）。
* 定时回写结算单金蝶冲销状态用，整批一次查询消除逐单远程查询 N+1
*
* @param arBillSrcCodes 财务应收单防重键列表
* @return 防重键 -&gt; 是否已冲销
*/
public Map<String, Boolean> queryArBillWriteOffFlags(List<String> arBillSrcCodes) {
Map<String, Boolean> writeOffFlags = new LinkedHashMap<>();
kingdeeApBillSyncSupport.batchForeach(arBillSrcCodes, bfiProperties.getWriteOffResult().getQueryBatchSize(), batch -> {
BfiArBillQueryDTO param = new BfiArBillQueryDTO();
param.setAwrpSrcCode(batch);
param.setAwrpSrcSys(bfiProperties.getSrcSys());
for (BfiArBillVO arBill : BfiUtil.queryAllPages(pageNo -> {
param.setPageNo(pageNo);
param.setPageSize(AR_RESULT_PAGE_SIZE);
return bfiService.queryArBill(param);
})) {
if (Func.isNotEmpty(arBill.getAwrpSrcCode())) {
writeOffFlags.merge(arBill.getAwrpSrcCode(), Boolean.TRUE.equals(arBill.getHadwrittenoff()), Boolean::logicalOr);
}
}
}
return false;
});
return writeOffFlags;
}
// ==================== A302-2 财务应收单保存 ====================
blade-service/blade-transport/src/main/java/org/springblade/transport/task/KingdeeWriteOffResultTask.java
+63
View File
@@ -0,0 +1,63 @@
/**
* BladeX Commercial License Agreement
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
* <p>
* Use of this software is governed by the Commercial License Agreement obtained after purchasing a license from BladeX.
* <p>
* 1. This software is for development use only under a valid license from BladeX.
* <p>
* 2. Redistribution of this software's source code to any third party without a commercial license is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments from this software for such purposes.
* Copyright of this software remains with BladeX.
* <p>
* Using this software signifies agreement to this License, and the software must not be used for illegal purposes.
* <p>
* THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is not liable for any claims arising from secondary or illegal development.
* <p>
* Author: Chill Zhuang (bladejava@qq.com)
*/
package org.springblade.transport.task;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springblade.transport.config.BfiProperties;
import org.springblade.transport.service.IFormalSettlementService;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
/**
* 金蝶冲销状态定时回写任务
* <p>
* A102-4/A302-4 批量查询已同步结算单对应金蝶旧应付/应收单的 hadwrittenoff（部分冲销视同已冲销），
* 回写结算单冲销状态，用于结算单列表展示金蝶旧单是否已冲销。
* 业务逻辑收敛在服务方法（分布式锁 + 分批查询 + 批量落库），便于手动触发联调。
* <p>
* 调度配置（Nacos thirdParty.bfi.writeOffResult.*）：syncEnabled 开关、cron 表达式、queryBatchSize 分批大小。
*
* @author Chill
*/
@Slf4j
@Component
@RefreshScope
@RequiredArgsConstructor
public class KingdeeWriteOffResultTask {
private final IFormalSettlementService formalSettlementService;
private final BfiProperties bfiProperties;
/** 金蝶冲销状态回写调度，默认每10分钟执行一次（分钟位与付款结果回写错峰） */
@Scheduled(cron = "${thirdParty.bfi.writeOffResult.cron:0 4/10 * * * ?}")
public void syncKingdeeWriteOffResult() {
if (!bfiProperties.getWriteOffResult().isSyncEnabled()) {
return;
}
try {
String summary = formalSettlementService.syncKingdeeWriteOffResult();
log.info("定时回写金蝶冲销状态：{}", summary);
} catch (Exception exception) {
log.error("定时回写金蝶冲销状态异常", exception);
}
}
}