From e24314d6cbe75158394577d7551f71f6e13cfef8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com>
Date: Thu, 15 Oct 2026 03:21:33 +0800
Subject: [PATCH] =?UTF-8?q?:feat:=20=E6=96=B0=E5=A2=9E=E9=87=91=E8=9D=B6?=
 =?UTF-8?q?=E5=8D=95=E6=8D=AE=E9=94=81=E5=AE=9A=E8=A7=A3=E9=94=81=E6=80=BB?=
 =?UTF-8?q?=E5=BC=80=E5=85=B3=EF=BC=88billLock.enabled=EF=BC=8C=E6=8E=A7?=
 =?UTF-8?q?=E5=88=B6=E6=8E=A8=E9=80=81=E9=94=81=E5=8D=95/=E8=A7=A3?=
 =?UTF-8?q?=E9=94=81=E5=9B=9E=E8=B0=83/=E8=A1=A5=E5=81=BF=E9=87=8D?=
 =?UTF-8?q?=E9=94=81=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../transport/config/BfiProperties.java           |  8 ++++++++
 .../service/impl/KingdeeBillLockServiceImpl.java  | 15 +++++++++++++++
 doc/nacos/third-party-api.yaml                    |  2 ++
 3 files changed, 25 insertions(+)

diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java
index ecc40f74..f2e38a9d 100644
--- a/blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java
+++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java
@@ -372,6 +372,14 @@ public class BfiProperties {
 	@Data
 	public static class BillLock {
 
+		/**
+		 * 锁定/解锁总开关（thirdParty.bfi.billLock.enabled）：推送后锁定 lockBusiData、
+		 * 金蝶解锁回调 unLockNotifyBusiData、锁定补偿重锁三处共用；
+		 * 默认开启保持既有锁定行为，Nacos 置 false 一键停用
+		 * （推送后不再锁单、解锁回调只应答不处理、补偿跳过），存量锁记录守卫（不可编辑校验）不受影响
+		 */
+		private boolean enabled = true;
+
 		/**
 		 * 锁定补偿开关，默认关闭（安全兜底）
 		 */
diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/KingdeeBillLockServiceImpl.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/KingdeeBillLockServiceImpl.java
index d3982a09..97ee28db 100644
--- a/blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/KingdeeBillLockServiceImpl.java
+++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/KingdeeBillLockServiceImpl.java
@@ -73,6 +73,11 @@ public class KingdeeBillLockServiceImpl extends ServiceImpl<KingdeeBillLockMappe
 
 	@Override
 	public String lockAfterPush(String sourceBillType, Long sourceBillId, String sourceBillNo, String targetBillType, List<String> targetBillNos) {
+		// 总开关关闭：不落锁记录、不调 lockBusiData，返回 null 不影响推送主流程
+		if (!bfiProperties.getBillLock().isEnabled()) {
+			log.info("金蝶单据锁定总开关关闭，跳过锁定：源单[{}:{}]", sourceBillType, sourceBillNo);
+			return null;
+		}
 		if (Func.isEmpty(targetBillNos)) {
 			return null;
 		}
@@ -145,6 +150,12 @@ public class KingdeeBillLockServiceImpl extends ServiceImpl<KingdeeBillLockMappe
 	@Override
 	@Transactional(rollbackFor = Exception.class)
 	public int onUnlockNotify(BfiBillLockDTO param) {
+		// 总开关关闭：只应答不处理（返回 0 与「未匹配」同构，金蝶侧不会触发重试）
+		if (!bfiProperties.getBillLock().isEnabled()) {
+			log.warn("金蝶单据锁定总开关关闭，跳过解锁回调处理：operationType={}，targetBillNo={}",
+				param == null ? null : param.getOperationType(), param == null ? null : param.getTargetBillNo());
+			return 0;
+		}
 		if (param == null || !KingdeeLockConstant.SYSTEM_XH.equals(param.getSourceSystem())
 			|| !KingdeeLockConstant.SYSTEM_WLTMS.equals(param.getTargetSystem())
 			|| !KingdeeLockConstant.ACTION_UNLOCK.equals(param.getLockAction())) {
@@ -265,6 +276,10 @@ public class KingdeeBillLockServiceImpl extends ServiceImpl<KingdeeBillLockMappe
 	 */
 	@Override
 	public String retryFailedLocks() {
+		// 总开关关闭：定时任务与手动补偿一并跳过
+		if (!bfiProperties.getBillLock().isEnabled()) {
+			return "金蝶单据锁定总开关关闭，跳过补偿";
+		}
 		List<KingdeeBillLock> failedList = this.list(Wrappers.<KingdeeBillLock>lambdaQuery()
 			.eq(KingdeeBillLock::getLockStatus, KingdeeLockConstant.STATUS_FAILED)
 			.lt(KingdeeBillLock::getTryCount, KingdeeLockConstant.RETRY_MAX_COUNT));
diff --git a/doc/nacos/third-party-api.yaml b/doc/nacos/third-party-api.yaml
index 3dfeb2f3..caa5f604 100644
--- a/doc/nacos/third-party-api.yaml
+++ b/doc/nacos/third-party-api.yaml
@@ -96,6 +96,8 @@ thirdParty:
       lockLeaseSeconds: ${BFI_RECEIPT_CLAIM_PUSH_LOCK_LEASE_SECONDS:1800}
     # 金蝶单据锁定定时补偿
     billLock:
+      # 锁定/解锁总开关（推送后锁定+解锁回调+补偿重锁共用），默认开启保持既有行为
+      enabled: ${BFI_BILL_LOCK_ENABLED:true}
       # 锁定补偿开关，默认关闭（安全兜底）
       retryEnabled: ${BFI_BILL_LOCK_RETRY_ENABLED:false}
       # 补偿调度 cron，默认每5分钟（:02 起步，错峰避让其他金蝶任务）