feat: HCS付款申请数据层与零埋点接线（特批字段组/履约记录ID字段/审批与付款推进置待同步）

2026-09-27 23:38:55 +08:00
parent d147ef8209
commit 594773d7c7
5 changed files with 129 additions and 0 deletions
@@ -33,6 +33,7 @@ import org.springblade.core.tenant.mp.TenantEntity;
 import java.io.Serial;
 import java.math.BigDecimal;
 import java.time.LocalDate;
+import java.time.LocalDateTime;

 /** 付款申请实体。 @author Chill */
@Data
@@ -120,4 +121,26 @@ public class PaymentApplication extends TenantEntity {
 	private String attachmentsJson;
 	/** 备注 */
 	private String remark;
+	/** 合规系统单据ID（fdId） */
+	private String hcsFdId;
+	/** 合规同步状态：unsynced 待同步 / synced 已同步 / failed 同步失败 */
+	private String hcsSyncStatus;
+	/** 合规推送失败重试次数 */
+	private Integer hcsRetryCount;
+	/** 合规最近同步时间 */
+	private LocalDateTime hcsSyncTime;
+	/** 合规最近同步结果信息/失败原因 */
+	private String hcsSyncMsg;
+	/** 额度校验结果：pass 通过 / over 超额（C106-1） */
+	private String hcsCreditStatus;
+	/** 额度校验说明（超额原因 fdMessage） */
+	private String hcsCreditMsg;
+	/** 额度校验时间 */
+	private LocalDateTime hcsCreditTime;
+	/** 结算付款特批流程ID（C106-3 返回，C106-4 必传） */
+	private String hcsSpecFdId;
+	/** 特批状态：none/need/pushing/processing/approved/rejected */
+	private String hcsSpecStatus;
+	/** 履约记录ID（C108-1 返回，C108-2 更新必传） */
+	private String hcsPerfFdId;
 }
@@ -59,6 +59,11 @@ public final class HcsSyncConstant {
 	 */
 	public static final String BIZ_TYPE_CONTRACT = "contract";

+	/**
+	 * 推送业务类型：付款申请（C106 特批 / C108 履约记录）
+	 */
+	public static final String BIZ_TYPE_PAYMENT = "payment";
+
 	/**
 	 * 校验类型：客商风险（C101-1）
 	 */
@@ -84,6 +89,50 @@ public final class HcsSyncConstant {
 	 */
 	public static final String CHECK_RESULT_SKIP = "skip";

+	// ==================== 额度校验结果（C106-1，D15） ====================
+
+	/**
+	 * 额度校验通过
+	 */
+	public static final String CREDIT_STATUS_PASS = "pass";
+
+	/**
+	 * 额度校验超额（不拦截提交，转入特批链路）
+	 */
+	public static final String CREDIT_STATUS_OVER = "over";
+
+	// ==================== 特批状态（hcs_spec_status，D15） ====================
+
+	/**
+	 * 特批状态：无需特批
+	 */
+	public static final String SPEC_STATUS_NONE = "none";
+
+	/**
+	 * 特批状态：待特批（额度超额标记，扫描任务据此发起 C106-3）
+	 */
+	public static final String SPEC_STATUS_NEED = "need";
+
+	/**
+	 * 特批状态：发起中
+	 */
+	public static final String SPEC_STATUS_PUSHING = "pushing";
+
+	/**
+	 * 特批状态：特批中（C106-3 已发起，结果人工确认，§9-U1）
+	 */
+	public static final String SPEC_STATUS_PROCESSING = "processing";
+
+	/**
+	 * 特批状态：特批通过（人工确认）
+	 */
+	public static final String SPEC_STATUS_APPROVED = "approved";
+
+	/**
+	 * 特批状态：特批驳回（人工确认）
+	 */
+	public static final String SPEC_STATUS_REJECTED = "rejected";
+
 	// ==================== Redis 缓存 key（照 BFI blade:third: 前缀惯例） ====================

 	/**
@@ -426,6 +426,8 @@ public final class MkProcessBizHandlers {
 			entity.setApprovalStatus("approved");
 			entity.setCurrentNode("审核通过");
 			entity.setCurrentProcessor(MkProcessNodeHelper.text(processorName, "系统"));
+			// HCS 推送零埋点：MK 审批回调仅置待同步状态，与 /approve 入口收敛于同一权威状态（ADR-0001）
+			entity.setHcsSyncStatus(HcsSyncConstant.HCS_STATUS_UNSYNCED);
 			return service.updateById(entity);
 		}

@@ -47,6 +47,7 @@ import org.springblade.thirdparty.bfi.pojo.vo.BfiPayApplyVO;
 import org.springblade.thirdparty.bfi.pojo.vo.BfiPayBillVO;
 import org.springblade.thirdparty.bfi.service.IBfiService;
 import org.springblade.thirdparty.bfi.util.BfiUtil;
+import org.springblade.transport.constant.HcsSyncConstant;
 import org.springblade.transport.constant.KingdeeBfiConstant;
 import org.springblade.transport.constant.TransportBusiConstant;
 import org.springblade.transport.mapper.BillLedgerMapper;
@@ -350,6 +351,8 @@ private final CustomerReceiptAccountMapper receiptAccountMapper;
 		if (!TransportBusiConstant.REVIEWING.equals(entity.getApprovalStatus())) throw new ServiceException("仅审批中的付款申请允许审核");
 		if (isBillPayment(entity.getPaymentMethod())) useBillBalance(entity);
 		entity.setApprovalStatus(TransportBusiConstant.APPROVED); entity.setCurrentNode("审批通过"); entity.setCurrentProcessor(AuthUtil.getUserName());
+		// HCS 推送零埋点：审批通过仅置待同步状态，扫描任务据此推特批（如需）与履约记录（ADR-0001）
+		entity.setHcsSyncStatus(HcsSyncConstant.HCS_STATUS_UNSYNCED);
 		updateById(entity);
 		refreshFormalSettlement(entity);
 	}
@@ -611,6 +614,10 @@ private final CustomerReceiptAccountMapper receiptAccountMapper;
 		} else if (KingdeeBfiConstant.KINGDEE_STATUS_PAID.equals(kingdeeStatus)) {
 			entity.setPaidAmount(money(entity.getAppliedAmount()).setScale(2, RoundingMode.HALF_UP));
 		}
+		// HCS 履约记录推进：实际付款变化后置待同步，扫描任务凭 hcs_perf_fd_id 走 C108-2 更新（D11）
+		if (entity.getHcsPerfFdId() != null) {
+			entity.setHcsSyncStatus(HcsSyncConstant.HCS_STATUS_UNSYNCED);
+		}
 		updateById(entity);
 		if (KingdeeBfiConstant.KINGDEE_STATUS_PAID.equals(kingdeeStatus)) {
 			// 付款完成：联动履约付款数据（预结算预付记录、正式结算付款记录）
@@ -0,0 +1,48 @@
+-- 桂物合同合规系统（HCS）接入：付款申请特批字段组与履约记录字段（设计文档 §4，P3）。
+-- blade_payment_application 追加额度校验结果、特批流程ID/状态、履约记录ID 字段。
+-- 通过 information_schema 判断字段是否存在，可重复执行。
+SET @db_name = DATABASE();
+
+-- ==================== blade_payment_application 扩展字段（C106-1 结果、C106-3/4 特批、C108 履约记录） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_credit_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_credit_status varchar(16) DEFAULT NULL COMMENT ''额度校验结果 pass=通过/over=超额（C106-1）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_credit_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_credit_msg varchar(512) DEFAULT NULL COMMENT ''额度校验说明（超额原因 fdMessage）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_credit_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_credit_time datetime DEFAULT NULL COMMENT ''额度校验时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_spec_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_spec_fd_id varchar(64) DEFAULT NULL COMMENT ''结算付款特批流程ID（C106-3 返回，C106-4 必传）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_spec_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_spec_status varchar(16) DEFAULT ''none'' COMMENT ''特批状态 none/need/pushing/processing/approved/rejected'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_perf_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_perf_fd_id varchar(64) DEFAULT NULL COMMENT ''履约记录ID（C108-1 返回，C108-2 更新必传）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;