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

Merge branch 'feature/20261027-hcs-bif-all-recBillSync' into feature/20261031-bfi-收票收款改造

Browse Source
This commit is contained in:
刘泉佳
2026-10-31 14:18:14 +08:00
parent 42548e6a35 e1ec74281f
commit f0c551358a
47 changed files with 2262 additions and 1038 deletions
Download Patch File Download Diff File Expand all files Collapse all files
blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/KingdeeReceiptFlow.java
+51 -23
View File
@@ -52,68 +52,96 @@ public class KingdeeReceiptFlow extends TenantEntity {
private static final long serialVersionUID = 1L;
/**
* 金蝶认领公告id（A301-2 返回 id，认领推送 A301-3 必填）
* 金蝶认领公告id（历史 A301-2 同步遗留，A301-1 口径不再使用，恒为空）
*/
@JsonSerialize(using = ToStringSerializer.class)
private Long billId;
/**
* 金蝶付款人id（A301-2 公告对应往来单位 id，认领推送 A301-3 用）
* 金蝶付款人id（历史 A301-2 同步遗留，A301-1 口径不再使用，恒为空）
*/
private String payerId;
/**
* 公告认领状态（A301-2 claimstatus：0未认领/1已认领）
* 公告认领状态（历史 A301-2 同步遗留，A301-1 口径不再使用，恒为空）
*/
private String kingdeeClaimStatus;
/**
* 我已认领（A301-2 claimme）
* 我已认领（历史 A301-2 同步遗留，A301-1 口径不再使用，恒为空）
*/
private Boolean claimMe;
/**
* 未认领金额（A301-2 unclaimamount）
* 未匹配收款金额（A301-1 unmatchamountrec，金蝶参考展示，不参与认领额度）
*/
private BigDecimal unclaimedAmount;
private BigDecimal unmatchAmountRec;
/**
* 手续费（A301-2 fee）
* 已匹配收款金额（A301-1 matchamountrec）
*/
private BigDecimal matchAmountRec;
/**
* 已匹配付款金额（A301-1 matchamountpay）
*/
private BigDecimal matchAmountPay;
/**
* 未匹配付款金额（A301-1 unmatchamountpay）
*/
private BigDecimal unmatchAmountPay;
/**
* 已结算金额（A301-1 settleamount）
*/
private BigDecimal settleAmount;
/**
* 未结算金额（A301-1 unsettleamount）
*/
private BigDecimal unsettleAmount;
/**
* 手续费（A301-1 fee）
*/
private BigDecimal fee;
/**
* 收款人（A301-2 recpayee）
* 收款人（A301-1 收款公司名称 org_name）
*/
private String payeeName;
/**
* 收款通知单号（A301-2 billno）
* 收款人（公司）.编码（A301-1 org_number）
*/
private String orgNumber;
/**
* 核算组织.编码（A301-1 openorg_number）
*/
private String openOrgNumber;
/**
* 金蝶收款单号（A301-1 billno）
*/
private String receiptNoticeNo;
/**
* 付款人名称（A301-2 recviewpayer）
* 付款人名称（A301-1 payername）
*/
private String payerName;
/**
* 收款金额（A301-2 reamount）
* 收款金额（A301-1 actrecamt）
*/
private BigDecimal receiptAmount;
/**
* 对方单位名称（A301-2 oppunit）
* 对方单位名称（A301-1 付款人名称）
*/
private String counterpartyName;
/**
* 对方银行账号（A301-2 oppbanknumber）
* 对方银行账号（A301-1 付款账户 payeracctbanknum）
*/
private String counterpartyAccount;
/**
* 对方开户行（A301-2 oppbank）
* 对方开户行（A301-1 付款银行 payerbankname）
*/
private String counterpartyBank;
/**
* 摘要（A301-2 description）
* 摘要（A301-1 txt_description）
*/
private String summary;
/**
* 交易日期（A301-2 tradetime）
* 交易日期（A301-1 业务日期 bizdate）
*/
private LocalDateTime transactionTime;
/**
* 明细流水号（A301-2 detailid，回退 tradedetailno / bankdetailno，幂等键）
* 明细流水号（收款单号 billno，幂等键；C104-2 按此定位合规侧收款流水）
*/
private String detailSerialNo;
/**
@@ -125,27 +153,27 @@ public class KingdeeReceiptFlow extends TenantEntity {
*/
private String claimStatus;
/**
* 推送状态（none未推送/pushed已推送/failed推送失败；已推送为终态闸门，不允许二次推送）
* 推送状态（none未推送/pushed已推送/failed推送失败；历史 A301-3 推送遗留，A301-1 口径下恒为 none，仅存量的已推送数据保留展示）
*/
private String pushStatus;
/**
* 最近一次推送失败原因（成功后清空）
* 最近一次推送失败原因（历史 A301-3 推送遗留）
*/
private String pushFailReason;
/**
* 首次推送金蝶成功时间
* 首次推送金蝶成功时间（历史 A301-3 推送遗留）
*/
private LocalDateTime pushedTime;
/**
* 金蝶推送来源单据编码（分摊结算单号下划线拼接，推送时生成落库；分摊不变则重试编码不变，A301-1 回写匹配键）
* 金蝶推送来源单据编码（历史 A301-3 推送遗留，A301-1 口径不再生成）
*/
private String awrpSrcCode;
/**
* 金蝶收款单号（推送响应回填 / A301-1 回写推进）
* 金蝶收款单号（A301-1 同步落库 billno）
*/
private String kingdeeBillNo;
/**
* 金蝶回写状态（none未推送/pushed已推送/approved审核通过/received已收款/failed失败）
* 金蝶单据状态（A301-1 billstatus 映射：none未推送/pushed已推送/approved审核通过/received已收款/failed失败，同步时随单据刷新）
*/
private String kingdeeBillStatus;
/**
blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/ReceiptClaimHcsRecord.java
+96
View File
@@ -0,0 +1,96 @@
/**
* 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.pojo.entity;
import com.baomidou.mybatisplus.annotation.TableName;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.EqualsAndHashCode;
import org.springblade.core.tenant.mp.TenantEntity;
import java.io.Serial;
import java.math.BigDecimal;
import java.time.LocalDateTime;
/**
* 收款认领合规推送记录实体类
* <p>
* C107-1 认领记录推送结果落库（认领主单 × 合同一条）：成功持久化合规侧 fdId 供 C107-3 作废引用，
* 失败落推送标记与原因（仅记标记，不做定时重试）。
*
* @author Chill
*/
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("blade_receipt_claim_hcs_record")
@Schema(description = "收款认领合规推送记录")
public class ReceiptClaimHcsRecord extends TenantEntity {
@Serial
private static final long serialVersionUID = 1L;
/**
* 认领主单id
*/
@JsonSerialize(using = ToStringSerializer.class)
private Long receiptClaimId;
/**
* 收款流水id
*/
@JsonSerialize(using = ToStringSerializer.class)
private Long receiptFlowId;
/**
* 合同id
*/
@JsonSerialize(using = ToStringSerializer.class)
private Long contractId;
/**
* 合同编号
*/
private String contractNo;
/**
* 该认领主单分摊到本合同的认领金额
*/
private BigDecimal claimAmount;
/**
* 合规侧认领记录fdId（C107-1 返回，C107-3 作废必填引用）
*/
private String hcsClaimRecordFdId;
/**
* 推送状态（success推送成功/failed推送失败/voided已作废）
*/
private String pushStatus;
/**
* 推送失败原因（成功后清空）
*/
private String failReason;
/**
* 推送成功时间
*/
private LocalDateTime pushedTime;
}
blade-service/blade-transport/src/main/java/org/springblade/transport/config/BfiProperties.java
+11 -33
View File
@@ -71,9 +71,9 @@ public class BfiProperties {
private ReceivedInvoice receivedInvoice = new ReceivedInvoice();
/**
* 收款认领公告查询配置（A301-2）
* 收款流水同步配置（A301-1 收款单查询）
*/
private ClaimAnnounce claimAnnounce = new ClaimAnnounce();
private RecBillSync recBillSync = new RecBillSync();
/**
* 付款结果定时回写配置（A103-2/A103-4，总开关同时控制应收勾稽、开票结果回写）
@@ -85,11 +85,6 @@ public class BfiProperties {
*/
private ReceivedInvoiceResult receivedInvoiceResult = new ReceivedInvoiceResult();
/**
* 收款认领推送配置（A301-3）
*/
private ReceiptClaimPush receiptClaimPush = new ReceiptClaimPush();
/**
* 全票池发票定时同步配置（A801-1）
*/
@@ -197,20 +192,15 @@ public class BfiProperties {
}
/**
* 收款认领公告查询配置项（A301-2）
* 收款流水同步配置项（A301-1 收款单查询）
*/
@Data
public static class ClaimAnnounce {
public static class RecBillSync {
/**
* 查询时间窗口（月数），默认 6（近半年）
* 同步业务日期窗口天数，默认 60
*/
private int months = 6;
/**
* 认领人（claimusers）：配置后公告查询固定使用该值，不再按当前登录用户姓名查询
*/
private String claimusers;
private int days = 60;
}
/**
@@ -257,6 +247,11 @@ public class BfiProperties {
* 回写 single-flight 锁租约秒数，须大于最坏一轮耗时（分批远程查询 + 逐单回写）
*/
private long lockLeaseSeconds = 1800;
/**
* A103-4 付款处理查询业务日期窗口天数，默认 60
*/
private int queryWindowDays = 60;
}
/**
@@ -271,23 +266,6 @@ public class BfiProperties {
private boolean syncEnabled = false;
}
/**
* 收款认领推送配置项（A301-3）
*/
@Data
public static class ReceiptClaimPush {
/**
* 推送任务开关，默认关闭（联调稳定后开启）
*/
private boolean syncEnabled = false;
/**
* 推送 single-flight 锁租约秒数，须大于最坏一轮耗时（逐认领人远程查公告 + 逐条推送）
*/
private long lockLeaseSeconds = 1800;
}
/**
* 全票池发票同步配置项（A801-1）
*/
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/ReceiptClaimRecordController.java
+1 -8
View File
@@ -83,16 +83,9 @@ public class ReceiptClaimRecordController extends BladeController {
@PostMapping("/void")
@ApiOperationSupport(order = 4)
@Operation(summary = "作废认领记录并生成金蝶认领冲单")
@Operation(summary = "作废认领记录（作废后同步合同合规系统）")
public R<Void> voidClaim(@RequestParam Long id) {
receiptClaimRecordService.voidClaim(id);
return R.success("作废成功");
}
@PostMapping("/query-kingdee-result")
@ApiOperationSupport(order = 5)
@Operation(summary = "查询金蝶认领结果（A301-1 收款单查询回写）")
public R<Integer> queryKingdeeResult() {
return R.data(receiptClaimRecordService.refreshKingdeeResult());
}
}
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/ReceiptFlowController.java
+1 -10
View File
@@ -35,7 +35,6 @@ import org.springblade.core.mp.support.Condition;
import org.springblade.core.mp.support.Query;
import org.springblade.core.secure.annotation.PreAuth;
import org.springblade.core.tool.api.R;
import org.springblade.transport.pojo.dto.ReceiptClaimPushResult;
import org.springblade.transport.pojo.dto.ReceiptClaimRequest;
import org.springblade.transport.pojo.vo.ReceiptFlowVO;
import org.springblade.transport.service.IReceiptFlowService;
@@ -95,16 +94,8 @@ public class ReceiptFlowController extends BladeController {
@PostMapping("/sync")
@ApiOperationSupport(order = 5)
@Operation(summary = "手动同步金蝶收款流水（A301-2 收款认领公告查询）")
@Operation(summary = "手动同步金蝶收款流水（A301-1 收款单查询）")
public R<Integer> sync() {
return R.data(receiptFlowService.sync());
}
@PostMapping("/push-kingdee")
@ApiOperationSupport(order = 6)
@Operation(summary = "推送金蝶收款认领（A301-3 收款认领结果推送，仅认领完成流水可推送）")
public R<ReceiptClaimPushResult> pushKingdee(@RequestParam Long flowId) {
ReceiptClaimPushResult result = receiptFlowService.pushClaimToKingdee(flowId);
return result.isSuccess() ? R.data(result) : R.fail(result.getMessage());
}
}
blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/KingdeeReceiptFlowMapper.java
+12
View File
@@ -27,8 +27,11 @@ package org.springblade.transport.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;
import org.springblade.transport.pojo.entity.KingdeeReceiptFlow;
import java.util.List;
/**
* 金蝶收款流水镜像 Mapper 接口
*
@@ -36,4 +39,13 @@ import org.springblade.transport.pojo.entity.KingdeeReceiptFlow;
*/
@Mapper
public interface KingdeeReceiptFlowMapper extends BaseMapper<KingdeeReceiptFlow> {
/**
* 组织管理（blade_dept）中的平台公司金蝶组织编码列表（是否平台公司=是 且 已维护金蝶编码）
*
* @return 平台公司金蝶组织编码
*/
@Select("SELECT kingdee_dept_code FROM blade_dept WHERE is_platform_company = 1 "
+ "AND kingdee_dept_code IS NOT NULL AND kingdee_dept_code != '' AND is_deleted = 0")
List<String> selectPlatformOrgNumbers();
}
blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/ReceiptClaimHcsRecordMapper.java
+39
View File
@@ -0,0 +1,39 @@
/**
* 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.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Mapper;
import org.springblade.transport.pojo.entity.ReceiptClaimHcsRecord;
/**
* 收款认领合规推送记录 Mapper 接口
*
* @author Chill
*/
@Mapper
public interface ReceiptClaimHcsRecordMapper extends BaseMapper<ReceiptClaimHcsRecord> {
}
blade-service/blade-transport/src/main/java/org/springblade/transport/service/IReceiptClaimRecordService.java
-7
View File
@@ -46,11 +46,4 @@ public interface IReceiptClaimRecordService extends BaseService<ReceiptClaim> {
void updateAttachments(ReceiptClaimAttachmentsRequest request);
void voidClaim(Long id);
/**
* A301-1 收款单查询回写认领结果：按来源单据编码匹配金蝶收款单，推进金蝶单据状态
*
* @return 回写条数
*/
int refreshKingdeeResult();
}
blade-service/blade-transport/src/main/java/org/springblade/transport/service/IReceiptFlowService.java
+1 -18
View File
@@ -27,7 +27,6 @@ package org.springblade.transport.service;
import com.baomidou.mybatisplus.core.metadata.IPage;
import org.springblade.core.mp.base.BaseService;
import org.springblade.transport.pojo.dto.ReceiptClaimPushResult;
import org.springblade.transport.pojo.dto.ReceiptClaimRequest;
import org.springblade.transport.pojo.entity.KingdeeReceiptFlow;
import org.springblade.transport.pojo.vo.ReceiptFlowVO;
@@ -53,25 +52,9 @@ public interface IReceiptFlowService extends BaseService<KingdeeReceiptFlow> {
Long claim(ReceiptClaimRequest request);
/**
* 手动同步金蝶收款流水：直连 A301-2 收款认领公告查询，按明细流水号幂等 upsert 收款流水表
* 手动同步金蝶收款流水：直连 A301-1 收款单查询（收款处理查询），按流水分录明细流水号幂等 upsert 收款流水表
*
* @return 本次同步条数
*/
int sync();
/**
* 手动推送金蝶（A301-3 收款认领结果推送）：认领完成且未推送过的流水才可推送，
* 推送前以当前用户姓名重查 A301-2 最新公告对账。与定时任务共用同一推送实现。
*
* @param flowId 收款流水id
* @return 推送结果（失败不抛异常，原因随结果返回）
*/
ReceiptClaimPushResult pushClaimToKingdee(Long flowId);
/**
* 定时推送金蝶：扫描认领完成且未推送过的流水，按认领人姓名分组重查 A301-2 最新公告后逐条推送。
*
* @return 执行摘要
*/
String pushClaimByTask();
}
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/InvoiceReceiptServiceImpl.java
+44 -64
View File
@@ -50,6 +50,7 @@ import org.springblade.thirdparty.bfi.pojo.vo.BfiInvoicePoolVO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiPageVO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiReceivedInvoiceVO;
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.KingdeeAttachmentConstant;
import org.springblade.transport.config.BfiProperties;
@@ -1304,11 +1305,11 @@ public class InvoiceReceiptServiceImpl extends BaseServiceImpl<InvoiceReceiptMap
invoiceTypes.isEmpty() ? "不限制" : invoiceTypes, customerTaxNos != null ? "开启" : "关闭",
POOL_PAGE_SIZE, MAX_POOL_PAGES);
if (invoiceTypes.isEmpty()) {
this.syncWindowSlice(windowStart, windowEnd, null, customerTaxNos, stats);
this.syncPoolWindow(windowStart, windowEnd, null, customerTaxNos, stats);
} else {
// 单值参数拆轮：每个票种编码独立完整切片续扫，互不挤占翻页额度
for (String invoiceType : invoiceTypes) {
this.syncWindowSlice(windowStart, windowEnd, invoiceType, customerTaxNos, stats);
this.syncPoolWindow(windowStart, windowEnd, invoiceType, customerTaxNos, stats);
}
}
String summary = "金蝶全票池同步：翻页" + stats.pageCount + "页切片" + stats.sliceCount + "片拉取"
@@ -1358,72 +1359,51 @@ public class InvoiceReceiptServiceImpl extends BaseServiceImpl<InvoiceReceiptMap
}
/**
* 同步单个时间片 [sliceStart, sliceEnd)：独立翻页拉取（最多 MAX_POOL_PAGES 页），
* 触顶说明该时间片数据 >2.5 万，从中点二分为两片递归续扫（递归深度受时间粒度自然收敛，
* 单片 500 条以内 1 页即短页终止）
* 同步单个票种的时间窗口：翻页与触顶二分续扫统一交给 {@link BfiUtil#forEachWindowSlice}，
* 页级客商单位过滤、镜像批量 upsert、已登记票跟随补绑在页回调中完成
*
* @param sliceStart 切片起点（含）
* @param sliceEnd 切片终点（不含，避免与下一片边界重复拉取）
* @param customerTaxNos 客商发票信息税号集，null 表示客商单位过滤关闭（整轮共享）
* @param stats 整轮统计累加器
* @param windowStart 窗口起点（含）
* @param windowEnd 窗口终点（含）
* @param invoiceType 发票种类编码，null 不限
* @param customerTaxNos 客商发票信息税号集，null 表示客商单位过滤关闭（整轮共享）
* @param stats 整轮统计累加器
*/
private void syncWindowSlice(LocalDateTime sliceStart, LocalDateTime sliceEnd, String invoiceType,
private void syncPoolWindow(LocalDateTime windowStart, LocalDateTime windowEnd, String invoiceType,
Set<String> customerTaxNos, SyncStats stats) {
// 二分收敛保护：切片粒度细到 1 秒仍触顶说明远端异常（同秒 >2.5 万条不可能），不再二分直接记漏
if (!sliceStart.isBefore(sliceEnd)) {
log.error("金蝶全票池同步切片区间为空（{} ~ {}），远端 updateTime 粒度异常，放弃该切片", sliceStart, sliceEnd);
return;
}
boolean truncated = false;
for (int pageNo = 1; pageNo <= MAX_POOL_PAGES; pageNo++) {
List<BfiInvoicePoolVO> rows = this.pullPoolWindowPage(sliceStart, sliceEnd, invoiceType, pageNo);
if (rows.isEmpty()) {
break;
}
stats.pageCount++;
stats.pulledCount += rows.size();
// 客商单位过滤：销/购方税号未同时登记在客商发票信息中的发票不入镜像；
// 短页判定用原始条数，过滤后的空页不能提前终止翻页
stats.sliceCount += BfiUtil.forEachWindowSlice("金蝶全票池同步", windowStart, windowEnd,
POOL_PAGE_SIZE, MAX_POOL_PAGES,
(sliceStart, sliceEnd, pageNo) -> this.pullPoolWindowPage(sliceStart, sliceEnd, invoiceType, pageNo),
rows -> this.handlePoolPage(rows, customerTaxNos, stats));
}
/**
* 票池同步单页处理：客商单位过滤 + 镜像批量 upsert + 已登记票跟随补绑。
* 客商过滤只影响入镜像行数，翻页节奏由 BfiUtil 按原始行数判断，不受过滤影响
*
* @param rows 本页拉取的票池发票（原始行）
* @param customerTaxNos 客商发票信息税号集，null 表示客商单位过滤关闭
* @param stats 整轮统计累加器
*/
private void handlePoolPage(List<BfiInvoicePoolVO> rows, Set<String> customerTaxNos, SyncStats stats) {
stats.pageCount++;
stats.pulledCount += rows.size();
// 客商单位过滤：销/购方税号未同时登记在客商发票信息中的发票不入镜像
if (customerTaxNos != null) {
int rawPageSize = rows.size();
if (customerTaxNos != null) {
rows = rows.stream().filter(row -> this.bothUnitsRegistered(row, customerTaxNos)).toList();
stats.customerFiltered += rawPageSize - rows.size();
}
BatchUpsertResult upsertResult = this.batchUpsertInvoicePool(rows);
stats.created += upsertResult.created();
stats.updated += upsertResult.updated();
stats.mirrorUnchanged += upsertResult.unchanged();
// 已登记票跟随补绑：同页发票号码批量定位登记，绑定关系变更页级事务批量落库
if (!upsertResult.mirrors().isEmpty()) {
RefreshResult refreshResult = this.refreshBoundReceipts(stats.pageCount, upsertResult.mirrors());
stats.bound += refreshResult.bound();
stats.unchanged += refreshResult.unchanged();
stats.failed += refreshResult.failed();
}
// 远程短页：该片到底，正常终止（按原始拉取条数判断，客商过滤不改变翻页节奏）
if (rawPageSize < POOL_PAGE_SIZE) {
stats.sliceCount++;
return;
}
truncated = true;
rows = rows.stream().filter(row -> this.bothUnitsRegistered(row, customerTaxNos)).toList();
stats.customerFiltered += rawPageSize - rows.size();
}
// 触顶：该切片数据超过单查询窗口上限，从中点二分续扫（updateTime 落在中点的行归左片 [start, mid)，
// 右片 [mid, end) 不含 mid，同 updateTime 行整体归左片，不重不漏）
if (truncated) {
LocalDateTime mid = sliceStart.plus(java.time.Duration.between(sliceStart, sliceEnd).dividedBy(2));
if (!mid.isAfter(sliceStart)) {
// 切片已细到不足 1 秒仍满页：理论不可能，防御死递归
log.error("金蝶全票池同步切片 {} ~ {} 已达最小粒度仍满页（>{} 条），该时间片数据异常，跳过",
sliceStart, sliceEnd, MAX_POOL_PAGES * POOL_PAGE_SIZE);
return;
}
log.warn("金蝶全票池同步切片 {} ~ {} 触达翻页保护 {} 页（{} 条），二分续扫 [{} ~ {}) + [{} ~ {})",
sliceStart, sliceEnd, MAX_POOL_PAGES, MAX_POOL_PAGES * POOL_PAGE_SIZE, sliceStart, mid, mid, sliceEnd);
this.syncWindowSlice(sliceStart, mid, invoiceType, customerTaxNos, stats);
this.syncWindowSlice(mid, sliceEnd, invoiceType, customerTaxNos, stats);
return;
BatchUpsertResult upsertResult = this.batchUpsertInvoicePool(rows);
stats.created += upsertResult.created();
stats.updated += upsertResult.updated();
stats.mirrorUnchanged += upsertResult.unchanged();
// 已登记票跟随补绑：同页发票号码批量定位登记，绑定关系变更页级事务批量落库
if (!upsertResult.mirrors().isEmpty()) {
RefreshResult refreshResult = this.refreshBoundReceipts(stats.pageCount, upsertResult.mirrors());
stats.bound += refreshResult.bound();
stats.unchanged += refreshResult.unchanged();
stats.failed += refreshResult.failed();
}
stats.sliceCount++;
}
/**
@@ -1523,7 +1503,7 @@ public class InvoiceReceiptServiceImpl extends BaseServiceImpl<InvoiceReceiptMap
}
/** A801-1 按票池更新时间窗口分页拉取（只认正常票，不推单据使用状态；invoiceType 单值下推，null 不限） */
private List<BfiInvoicePoolVO> pullPoolWindowPage(LocalDateTime windowStart, LocalDateTime windowEnd,
private BfiPageVO<BfiInvoicePoolVO> pullPoolWindowPage(LocalDateTime windowStart, LocalDateTime windowEnd,
String invoiceType, int pageNo) {
BfiInvoicePoolQueryDataDTO data = new BfiInvoicePoolQueryDataDTO();
data.setPageNo(pageNo);
@@ -1536,7 +1516,7 @@ public class InvoiceReceiptServiceImpl extends BaseServiceImpl<InvoiceReceiptMap
param.setQueryParam(data);
BfiPageVO<BfiInvoicePoolVO> poolPage = bfiService.queryInvoicePool(param);
log.info("金蝶全票池同步 第{}页拉取 {} 条", pageNo, poolPage.getRows() == null ? 0 : poolPage.getRows().size());
return poolPage.getRows() == null ? List.of() : poolPage.getRows();
return poolPage;
}
/**
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/PaymentApplicationServiceImpl.java
+5 -3
View File
@@ -1185,15 +1185,17 @@ public class PaymentApplicationServiceImpl extends BaseServiceImpl<PaymentApplic
}
/**
* A103-4 分页查询：按付款人（公司）编码 + 最近1个月业务日期窗口（接口限制不超过1个月），自动翻页
* A103-4 分页查询：按付款人（公司）编码 + 业务日期窗口，自动翻页
* <p>
* 窗口天数取 Nacos thirdParty.bfi.payResult.queryWindowDays（默认 60）
*
* @param orgNumber 付款人（公司）编码
* @return 付款处理单列表
*/
private List<BfiPayBillVO> queryPayBillPages(String orgNumber) {
LocalDate endDate = LocalDate.now();
// 业务日期窗口控制在不超过1个月
LocalDate beginDate = endDate.minusMonths(1).plusDays(1);
int windowDays = Math.max(bfiProperties.getPayResult().getQueryWindowDays(), 1);
LocalDate beginDate = endDate.minusDays(windowDays);
BfiPayBillQueryDTO param = new BfiPayBillQueryDTO();
param.setOrgNumber(List.of(orgNumber));
param.setBeginBizdate(beginDate.format(DateTimeFormatter.ISO_LOCAL_DATE));
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/ReceiptClaimRecordServiceImpl.java
+15 -145
View File
@@ -33,12 +33,6 @@ import org.springblade.core.log.exception.ServiceException;
import org.springblade.core.mp.base.BaseServiceImpl;
import org.springblade.core.secure.utils.AuthUtil;
import org.springblade.core.tool.utils.Func;
import org.springblade.thirdparty.bfi.constant.BfiConstant;
import org.springblade.thirdparty.bfi.pojo.dto.BfiRecBillQueryDTO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiRecBillVO;
import org.springblade.thirdparty.bfi.service.IBfiService;
import org.springblade.thirdparty.bfi.util.BfiUtil;
import org.springblade.transport.constant.KingdeeBfiConstant;
import org.springblade.transport.mapper.FormalSettlementMapper;
import org.springblade.transport.mapper.KingdeeReceiptFlowMapper;
import org.springblade.transport.mapper.ReceiptClaimMapper;
@@ -53,20 +47,21 @@ import org.springblade.transport.pojo.entity.ReceiptFlowRecord;
import org.springblade.transport.pojo.vo.ReceiptClaimRecordVO;
import org.springblade.transport.service.IReceiptClaimRecordService;
import org.springblade.transport.service.IFormalSettlementService;
import org.springblade.transport.support.hcs.HcsClaimSyncSupport;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.support.TransactionSynchronization;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Comparator;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
import java.util.function.Function;
import java.util.stream.Collectors;
@@ -84,21 +79,13 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
private static final String CLAIMED = "claimed";
private static final String VOIDED = "voided";
private static final String APPROVED = "approved";
/**
* A301-1 收款单查询回看窗口天数（金蝶约束业务日期范围不可超过1个月）
*/
private static final int RESULT_WINDOW_DAYS = 30;
/**
* A301-1 收款单查询分页大小
*/
private static final int RESULT_PAGE_SIZE = 200;
private final ReceiptClaimSettlementMapper claimSettlementMapper;
private final IFormalSettlementService formalSettlementService;
private final KingdeeReceiptFlowMapper receiptFlowMapper;
private final FormalSettlementMapper formalSettlementMapper;
private final ReceiptFlowRecordMapper recordMapper;
private final IBfiService bfiService;
private final HcsClaimSyncSupport hcsClaimSyncSupport;
@Override
public IPage<ReceiptClaimRecordVO> selectPage(IPage<ReceiptClaimRecordVO> page,
@@ -203,10 +190,6 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
if (flow == null || Objects.equals(flow.getIsDeleted(), 1)) {
throw new ServiceException("关联收款流水不存在");
}
// 已推送金蝶的认领不允许作废：金蝶收款单已生成，冲销/调整由人工在金蝶处置
if (KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_PUSHED.equals(flow.getPushStatus())) {
throw new ServiceException("该认领已推送金蝶，不允许作废，请在金蝶侧人工处置");
}
List<ReceiptClaimSettlement> relations = claimSettlementMapper.selectList(
Wrappers.<ReceiptClaimSettlement>lambdaQuery()
@@ -256,9 +239,8 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
flow.setClaimStatus(amountClaimStatus(flowClaimedAfter, claimCeiling(flow)));
receiptFlowMapper.updateById(flow);
// 作废不生成金蝶认领冲单：金蝶单号/状态保留原值（未推送为空，已推送为真实收款单信息），
// 金蝶侧冲销/红冲由人工处置；冲单逻辑后续迭代如需恢复，放开下行调用即可
// String kingdeeBillNo = buildKingdeeBillNo(claim.getId());
// 作废不生成金蝶认领冲单：金蝶单号/状态保留原值（金蝶收款单已在 A301-1 同步落库），
// 金蝶侧冲销/红冲由人工处置
claim.setClaimStatus(VOIDED);
claim.setVoidedBy(AuthUtil.getUserId());
claim.setVoidedByName(Func.isEmpty(AuthUtil.getUserName()) ? claim.getClaimerName()
@@ -278,108 +260,14 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
: AuthUtil.getUserName());
operationRecord.setContent("作废认领，回退认领金额 " + money(claim.getClaimAmount()));
recordMapper.insert(operationRecord);
}
/**
* A301-1 收款单查询回写认领结果：按来源单据编码匹配金蝶收款单，推进流水金蝶回写状态
* <p>
* 回写口径：A301-1 契约本身不支持按来源单号过滤，故按近 30 天业务日期窗口全量翻页后，
* 以金蝶收款单 sourcebillnumber == 流水 awrp_src_code（A301-3 推送时按流水生成、重试复用）在本地匹配；
* 仅推进金蝶回写状态与补登收款单号，不改本地认领金额/分摊；名下未作废认领主单冗余展示字段级联刷新。
*
* @return 回写条数
*/
@Override
public int refreshKingdeeResult() {
List<KingdeeReceiptFlow> pending = receiptFlowMapper.selectList(
Wrappers.<KingdeeReceiptFlow>lambdaQuery()
.eq(KingdeeReceiptFlow::getPushStatus, KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_PUSHED)
.in(KingdeeReceiptFlow::getKingdeeBillStatus,
List.of(KingdeeBfiConstant.KINGDEE_STATUS_PUSHED, APPROVED))
.eq(KingdeeReceiptFlow::getStatus, 1)
.orderByAsc(KingdeeReceiptFlow::getId));
if (pending.isEmpty()) {
log.info("金蝶认领结果回写：无待回写流水（已推送/已审核且未终态）");
return 0;
}
Set<String> srcCodes = pending.stream()
.map(KingdeeReceiptFlow::getAwrpSrcCode)
.filter(Func::isNotEmpty)
.collect(Collectors.toSet());
if (srcCodes.isEmpty()) {
return 0;
}
log.info("金蝶认领结果回写：待回写流水 {} 条", pending.size());
LocalDate end = LocalDate.now();
LocalDate begin = end.minusDays(RESULT_WINDOW_DAYS);
long start = System.currentTimeMillis();
log.info("调用BFI接口 收款单查询开始，业务日期窗口 {} ~ {}", begin, end);
List<BfiRecBillVO> rows = BfiUtil.queryAllPages(pageNo -> {
BfiRecBillQueryDTO dto = new BfiRecBillQueryDTO();
dto.setPageNo(pageNo);
dto.setPageSize(RESULT_PAGE_SIZE);
dto.setBeginBizdate(begin.format(DateTimeFormatter.ISO_LOCAL_DATE));
dto.setEndBizdate(end.format(DateTimeFormatter.ISO_LOCAL_DATE));
return bfiService.queryRecBill(dto);
// 作废事务提交后同步合规 C107-3（fdStatus=1 已作废，失败仅记日志不回滚作废）
TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
@Override
public void afterCommit() {
hcsClaimSyncSupport.voidClaimToHcs(claim.getId());
}
});
log.info("调用BFI接口 收款单查询结束 耗时：{}ms，拉取 {} 条", System.currentTimeMillis() - start, rows.size());
// 窗口内收款单按 sourcebillnumber 匹配待回写来源编码，同键多单取首条
Map<String, BfiRecBillVO> matched = rows.stream()
.filter(row -> Func.isNotEmpty(row.getSourcebillnumber()))
.filter(row -> srcCodes.contains(row.getSourcebillnumber()))
.collect(Collectors.toMap(BfiRecBillVO::getSourcebillnumber, Function.identity(),
(first, second) -> first, HashMap::new));
int updated = 0;
for (KingdeeReceiptFlow flow : pending) {
BfiRecBillVO bill = matched.get(flow.getAwrpSrcCode());
if (bill == null) {
// 窗口内未查到：金蝶回单延迟/状态未同步，不改状态，由下次回写或人工处置兜底
continue;
}
// 推送成功时金蝶收款单号先以来源编码占位（A301-3 响应 number 为空，取回执 keys.awrp_src_code），
// 回写命中后以金蝶真实收款单号覆盖
if (Func.isNotEmpty(bill.getBillno())) {
flow.setKingdeeBillNo(bill.getBillno());
}
flow.setKingdeeBillStatus(billStatusOf(bill.getBillstatus()));
receiptFlowMapper.updateById(flow);
// 级联刷新名下未作废认领主单的冗余展示字段
baseMapper.update(null, Wrappers.<ReceiptClaim>lambdaUpdate()
.eq(ReceiptClaim::getReceiptFlowId, flow.getId())
.eq(ReceiptClaim::getClaimStatus, CLAIMED)
.set(ReceiptClaim::getKingdeeBillNo, flow.getKingdeeBillNo())
.set(ReceiptClaim::getKingdeeBillStatus, flow.getKingdeeBillStatus()));
updated++;
log.info("金蝶认领结果回写 flowId：{}，awrpSrcCode：{}，金蝶收款单号：{}，状态：{} → {}",
flow.getId(), flow.getAwrpSrcCode(), bill.getBillno(), bill.getBillstatus(),
flow.getKingdeeBillStatus());
}
log.info("金蝶认领结果回写完成：匹配 {} 条，更新 {} 条", matched.size(), updated);
return updated;
}
/**
* 金蝶收款单单据状态 → 本地认领金蝶状态
*
* @param billStatus 金蝶 billstatus（A暂存/B已提交/C已审核/D已收款/G已退单）
* @return 本地状态
*/
private String billStatusOf(String billStatus) {
if (BfiConstant.BILL_STATUS_RECEIVED.equals(billStatus)) {
return KingdeeBfiConstant.KINGDEE_STATUS_RECEIVED;
}
if (BfiConstant.BILL_STATUS_AUDITED.equals(billStatus)) {
return APPROVED;
}
if (BfiConstant.BILL_STATUS_DRAFT.equals(billStatus)
|| BfiConstant.BILL_STATUS_SUBMITTED.equals(billStatus)) {
return KingdeeBfiConstant.KINGDEE_STATUS_PUSHED;
}
// 其余状态（含 G 已退单）按处理失败回收，提示人工在金蝶核查
log.warn("金蝶收款单状态[{}]未匹配映射，认领回写按 failed 处理", billStatus);
return KingdeeBfiConstant.KINGDEE_STATUS_FAILED;
}
private void fillStatusNames(ReceiptClaimRecordVO record) {
@@ -399,17 +287,6 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
return VOIDED.equals(claimStatus) ? VOIDED : CLAIMED;
}
/**
* 生成本地金蝶认领冲单号（KDCX + 时间戳 + 认领id尾号6位）。
* 当前作废流程不生成冲单（调用点已注释保留），后续迭代接金蝶冲销时放开即可。
*/
@SuppressWarnings("unused")
private String buildKingdeeBillNo(Long claimId) {
String time = DateTimeFormatter.ofPattern("yyyyMMddHHmmss").format(LocalDateTime.now());
String suffix = String.valueOf(claimId);
return "KDCX" + time + suffix.substring(Math.max(0, suffix.length() - 6));
}
/**
* 累计认领金额 → 流水认领状态：对照可认领上限判定（与收款流水侧口径一致）
*/
@@ -421,18 +298,11 @@ public class ReceiptClaimRecordServiceImpl extends BaseServiceImpl<ReceiptClaimM
}
/**
* 可认领上限：公告未认领金额与收款金额取较小正值（与收款流水侧口径一致）
* 可认领上限：收款金额（A301-1 actrecamt，与收款流水侧口径一致）。
* 认领只登记本地，额度由本地累计认领控制，金蝶未匹配金额不参与。
*/
private BigDecimal claimCeiling(KingdeeReceiptFlow flow) {
BigDecimal unclaimed = money(flow.getUnclaimedAmount());
BigDecimal receipt = money(flow.getReceiptAmount());
if (receipt.compareTo(BigDecimal.ZERO) <= 0) {
return unclaimed;
}
if (unclaimed.compareTo(BigDecimal.ZERO) <= 0) {
return unclaimed;
}
return unclaimed.min(receipt);
return money(flow.getReceiptAmount());
}
private String amountStatus(BigDecimal paidAmount, BigDecimal settlementAmount) {
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/ReceiptFlowServiceImpl.java
+294 -554
View File
@@ -38,12 +38,9 @@ import org.springblade.core.tool.utils.Func;
import org.springblade.system.cache.SysCache;
import org.springblade.system.cache.UserCache;
import org.springblade.system.pojo.entity.Dept;
import org.springblade.thirdparty.bfi.pojo.dto.BfiClaimAnnounceQueryDTO;
import org.springblade.thirdparty.bfi.pojo.dto.BfiClaimPushDTO;
import org.springblade.thirdparty.bfi.pojo.dto.BfiClaimPushEntryDTO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiBillSaveResultItemVO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiBillSaveResultVO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiClaimAnnounceVO;
import org.springblade.thirdparty.bfi.pojo.dto.BfiRecBillQueryDTO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiPageVO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiRecBillVO;
import org.springblade.thirdparty.bfi.service.IBfiService;
import org.springblade.thirdparty.bfi.util.BfiUtil;
import org.springblade.transport.config.BfiProperties;
@@ -53,7 +50,6 @@ import org.springblade.transport.mapper.KingdeeReceiptFlowMapper;
import org.springblade.transport.mapper.ReceiptClaimMapper;
import org.springblade.transport.mapper.ReceiptClaimSettlementMapper;
import org.springblade.transport.mapper.ReceiptFlowRecordMapper;
import org.springblade.transport.pojo.dto.ReceiptClaimPushResult;
import org.springblade.transport.pojo.dto.ReceiptClaimRequest;
import org.springblade.transport.pojo.entity.FormalSettlement;
import org.springblade.transport.pojo.entity.KingdeeReceiptFlow;
@@ -63,12 +59,13 @@ import org.springblade.transport.pojo.entity.ReceiptFlowRecord;
import org.springblade.transport.pojo.vo.ReceiptFlowVO;
import org.springblade.transport.service.IFormalSettlementService;
import org.springblade.transport.service.IReceiptFlowService;
import org.springblade.transport.support.KingdeeSyncLockSupport;
import org.springblade.transport.support.TransportBusinessSupport;
import org.springblade.transport.support.hcs.HcsClaimSyncSupport;
import org.springblade.transport.wrapper.ReceiptFlowWrapper;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.support.TransactionSynchronization;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import org.springframework.transaction.support.TransactionTemplate;
import java.math.BigDecimal;
@@ -77,7 +74,6 @@ import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
@@ -109,18 +105,23 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
// 应收款
private static final String RECEIVABLE = "receivable";
/**
* A301-2 认领公告同步分页大小
* A301-1 收款单查询分页大小
*/
private static final int SYNC_PAGE_SIZE = 200;
/**
* A301-2 交易时间格式
* 同步分批入库批次大小：累计满一批即独立事务入库，避免全量驻留内存
*/
private static final int SYNC_BATCH_SIZE = 5000;
/**
* A301-1 单片翻页最大页数保护（200条/页 × 500页）：触顶说明该时间片数据超过单查询窗口上限，
* 由 BfiUtil 二分切片续扫保证尾部不漏
*/
private static final int SYNC_MAX_PAGES = 500;
/**
* A301-1 业务日期时间格式（请求参数与返回 bizdate 均为 yyyy-MM-dd HH:mm:ss）
*/
private static final DateTimeFormatter BFI_DATE_TIME_FORMATTER =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/**
* 定时推送收款认领 single-flight 锁键前缀（多副本定时任务共用）
*/
private static final String RECEIPT_CLAIM_PUSH_LOCK_PREFIX = "transport:receipt-flow:kingdee-claim-push:";
private final ReceiptClaimMapper claimMapper;
private final ReceiptClaimSettlementMapper claimSettlementMapper;
@@ -130,7 +131,6 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
private final IBfiService bfiService;
private final BfiProperties bfiProperties;
private final TransactionTemplate transactionTemplate;
private final KingdeeSyncLockSupport kingdeeSyncLockSupport;
private final HcsClaimSyncSupport hcsClaimSyncSupport;
@Override
@@ -316,9 +316,6 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
// 收款流水
KingdeeReceiptFlow flow = lockedFlow(request.getFlowId());
if (flow.getBillId() == null) {
throw new ServiceException("认领公告id缺失，请先手动同步金蝶收款流水");
}
// 结算单id → 分摊金额
Map<Long, BigDecimal> allocationMap = allocationMap(request.getSettlements());
// 结算单id列表（升序）
@@ -347,10 +344,7 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
allocatedTotal = allocatedTotal.add(allocated);
}
// 认领上限：公告未认领金额与收款金额取较小值（避免未认领金额异常偏大导致无法认领完成）
if (flow.getUnclaimedAmount() == null) {
throw new ServiceException("公告未认领金额缺失，请先手动同步金蝶收款流水");
}
// 认领上限：收款金额（认领只登记本地，额度由本地累计认领控制，金蝶侧匹配状态不参与）
BigDecimal claimCeiling = claimCeiling(flow);
if (claimCeiling.compareTo(BigDecimal.ZERO) <= 0) {
throw new ServiceException("该流水可认领金额为0，无需认领");
@@ -386,8 +380,9 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
claim.setRemark(trimToNull(request.getRemark()));
// 认领状态
claim.setClaimStatus(CLAIMED);
// 金蝶回写状态（待推送）
claim.setKingdeeBillStatus(KingdeeBfiConstant.RECEIPT_CLAIM_BILL_NONE);
// 金蝶收款单号/状态（冗余展示：A301-1 同步落库的单据信息）
claim.setKingdeeBillNo(flow.getKingdeeBillNo());
claim.setKingdeeBillStatus(flow.getKingdeeBillStatus());
claimMapper.insert(claim);
for (FormalSettlement settlement : settlements) {
@@ -436,149 +431,241 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
record(flow.getId(), claim.getId(), "claim", "认领收款流水", fromStatus, toStatus,
allocatedTotal, "关联" + settlements.size() + "张应收正式结算单");
// 认领只登记本地，不推送金蝶；推送由定时任务/手动按钮在认领完成后触发
// 认领只登记本地，不推送金蝶；事务提交后按认领主单推送合同合规（C103-9/C107-1/C108-1，失败仅落标记）
TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
@Override
public void afterCommit() {
hcsClaimSyncSupport.pushClaimToHcs(claim.getId());
}
});
return claim.getId();
}
/**
* 手动同步金蝶收款流水：直连 A301-1 收款单查询，收款单主单粒度、以金蝶收款单号为幂等键 upsert；
* 数据量大，时间窗口二分切片续扫（BfiUtil.forEachWindowSlice）：单片触顶自动二分续扫，
* 总覆盖不受单查询窗口上限约束，尾部不漏；累计满一批（5000 条流水行）即独立事务入库一批，
* 不全量驻留内存
*
* @return 本次同步条数（新增+更新）
*/
@Override
@Transactional(rollbackFor = Exception.class)
public int sync() {
String claimusers = UserCache.getUserRealName(AuthUtil.getUserId());
if (Func.isEmpty(claimusers)) {
throw new ServiceException("当前用户无姓名，无法同步金蝶认领公告");
int days = bfiProperties.getRecBillSync().getDays();
LocalDate endDate = LocalDate.now();
LocalDate startDate = endDate.minusDays(days);
// 金蝶 A301-1 仅接受带时分秒的日期参数，传纯日期会报 bos.filterSqlBuilder 时区时间格式错误
LocalDateTime windowStart = startDate.atStartOfDay();
LocalDateTime windowEnd = endDate.atTime(23, 59, 59);
log.info("收款流水同步开始，业务日期窗口：{} ~ {}（近{}天）",
windowStart.format(BFI_DATE_TIME_FORMATTER), windowEnd.format(BFI_DATE_TIME_FORMATTER), days);
long start = System.currentTimeMillis();
// 同步口径：按业务日期窗口拉取金蝶收款单（收款处理），以金蝶明细流水号为幂等键 upsert 收款流水表；
// 本地已认领金额/状态（claimedAmount/claimStatus）由认领、作废驱动，不被同步顺带覆盖，
// 未匹配收款金额单独存 unmatch_amount_rec，仅作金蝶参考展示，不参与认领额度。
// 按组织过滤：组织管理（blade_dept）中平台公司（是否平台公司=是）且已维护金蝶编码的组织
List<String> orgNumbers = baseMapper.selectPlatformOrgNumbers();
if (Func.isEmpty(orgNumbers)) {
throw new ServiceException("组织管理中未维护平台公司金蝶编码，无法同步金蝶收款流水，请先检查组织数据");
}
List<BfiClaimAnnounceVO> announces = queryClaimAnnounces(claimusers);
if (announces.isEmpty()) {
record(null, null, "sync", "手动同步流水", null, null, BigDecimal.ZERO,
"金蝶认领公告未查询到数据");
return 0;
log.info("收款流水同步按组织过滤，组织编码：{}", orgNumbers);
RecBillSyncState state = new RecBillSyncState();
state.sliceCount += BfiUtil.forEachWindowSlice("收款流水同步", windowStart, windowEnd,
SYNC_PAGE_SIZE, SYNC_MAX_PAGES,
(sliceStart, sliceEnd, pageNo) -> this.pullRecBillPage(sliceStart, sliceEnd, orgNumbers, pageNo),
rows -> this.handleRecBillPage(rows, state));
// 尾批不足 SYNC_BATCH_SIZE 的剩余入库
if (!state.pending.isEmpty()) {
state.batchNo++;
state.totalCount += this.syncBatch(state.batchNo, state.pending);
state.pending.clear();
state.batchSerials.clear();
}
if (state.pullCount == 0) {
this.record(null, null, "sync", "手动同步流水", null, null, BigDecimal.ZERO,
"金蝶收款单未查询到数据");
} else if (state.totalCount == 0) {
this.record(null, null, "sync", "手动同步流水", null, null, BigDecimal.ZERO,
"金蝶收款单无有效数据");
}
log.info("金蝶收款流水同步完成，翻页{}页切片{}片，拉取收款单 {} 张，新增/更新 {} 条，跳过 {} 条，"
+ "分 {} 批入库，耗时 {}ms",
state.pageCount, state.sliceCount, state.pullCount, state.totalCount, state.skippedCount,
state.batchNo, System.currentTimeMillis() - start);
return state.totalCount;
}
// 同步口径：A301-2 按参与认领用户（当前登录用户真实姓名）拉取全量认领公告，
// 以金蝶明细流水号为幂等键 upsert 收款流水表；本地已认领金额/状态（claimedAmount/claimStatus）
// 由认领、作废驱动，不被公告顺带覆盖，公告侧状态单独存 kingdee_claim_status/unclaimed_amount。
/**
* A301-1 按业务日期时间片分页拉取（组织编码过滤整轮共享，切片起止由 BfiUtil 二分传入）
*
* @param sliceStart 切片起点（含）
* @param sliceEnd 切片终点（含）
* @param orgNumbers 平台公司组织编码集
* @param pageNo 页码，从 1 开始
* @return 分页结果
*/
private BfiPageVO<BfiRecBillVO> pullRecBillPage(LocalDateTime sliceStart, LocalDateTime sliceEnd,
List<String> orgNumbers, int pageNo) {
BfiRecBillQueryDTO queryDTO = new BfiRecBillQueryDTO();
queryDTO.setPageNo(pageNo);
queryDTO.setPageSize(SYNC_PAGE_SIZE);
queryDTO.setBeginBizdate(sliceStart.format(BFI_DATE_TIME_FORMATTER));
queryDTO.setEndBizdate(sliceEnd.format(BFI_DATE_TIME_FORMATTER));
queryDTO.setOrgNumber(orgNumbers);
return bfiService.queryRecBill(queryDTO);
}
// 第一遍：数据校验与过滤，收集有效的 detailSerialNo
log.info("收款流水同步开始数据校验，共 {} 条认领公告", announces.size());
Map<String, BfiClaimAnnounceVO> validAnnounces = new LinkedHashMap<>();
int skippedCount = 0;
for (BfiClaimAnnounceVO announce : announces) {
// 明细流水号优先级：detailid > tradedetailno > bankdetailno
String detailSerialNo = firstNonBlank(announce.getDetailid(),
announce.getTradedetailno(), announce.getBankdetailno());
/**
* A301-1 单页数据处理：收款单主单粒度逐行校验入缓冲，累计满一批即独立事务入库。
* 切片边界同秒的收款单可能在相邻两片各拉一次，按批内收款单号去重幂等跳过，不重不漏
*
* @param rows 本页拉取的收款单
* @param state 整轮同步状态（待入库缓冲与统计累加）
*/
private void handleRecBillPage(List<BfiRecBillVO> rows, RecBillSyncState state) {
state.pageCount++;
state.pullCount += rows.size();
for (BfiRecBillVO recBill : rows) {
// 主单粒度：一张收款单一条流水，不展开流水分录；明细流水号取收款单号（幂等键，C104-2 按此定位合规流水）
String detailSerialNo = trimToEmpty(recBill.getBillno());
if (Func.isEmpty(detailSerialNo)) {
log.warn("收款流水同步跳过：认领公告[{}]缺少明细流水号", announce.getBillno());
skippedCount++;
log.warn("收款流水同步跳过：收款单缺少单号");
state.skippedCount++;
continue;
}
detailSerialNo = detailSerialNo.trim();
if (validAnnounces.containsKey(detailSerialNo)) {
throw new ServiceException("明细流水号" + detailSerialNo + "重复");
if (!state.batchSerials.add(detailSerialNo)) {
// 切片边界重复拉取或同批脏数据重复单号，幂等跳过（upsert 本就按单号幂等）
log.warn("收款流水同步跳过：收款单[{}]本批已拉取，跳过重复处理", detailSerialNo);
state.skippedCount++;
continue;
}
BigDecimal receiptAmount = money(announce.getReamount());
// 收款金额取主单 actrecamt（金蝶收款金额口径）
BigDecimal receiptAmount = money(recBill.getActrecamt());
if (receiptAmount.compareTo(BigDecimal.ZERO) <= 0) {
log.warn("收款流水同步跳过：认领公告[{}]收款金额为空或小于0", announce.getBillno());
skippedCount++;
// log.warn("收款流水同步跳过：收款单[{}]收款金额（actrecamt）为空或小于0", recBill.getBillno());
state.skippedCount++;
continue;
}
validAnnounces.put(detailSerialNo, announce);
}
log.info("收款流水数据校验完成：有效 {} 条，跳过 {} 条", validAnnounces.size(), skippedCount);
if (validAnnounces.isEmpty()) {
log.info("收款流水同步无有效数据，记录操作日志后返回");
record(null, null, "sync", "手动同步流水", null, null, BigDecimal.ZERO,
"金蝶认领公告无有效数据");
return 0;
}
// 批量查询已存在的记录（FOR UPDATE 防并发）
log.info("收款流水同步开始批量查询已存在记录，查询条件：detailSerialNo IN {} 条", validAnnounces.size());
List<KingdeeReceiptFlow> existingEntities = baseMapper.selectList(
Wrappers.<KingdeeReceiptFlow>lambdaQuery()
.in(KingdeeReceiptFlow::getDetailSerialNo, validAnnounces.keySet())
.last("FOR UPDATE")
);
Map<String, KingdeeReceiptFlow> existingMap = existingEntities.stream()
.collect(Collectors.toMap(KingdeeReceiptFlow::getDetailSerialNo, e -> e));
log.info("收款流水批量查询完成：已存在 {} 条，待新增 {} 条",
existingEntities.size(), validAnnounces.size() - existingEntities.size());
// 第二遍：构建新增和更新列表
log.info("收款流水同步开始构建新增/更新列表");
List<KingdeeReceiptFlow> toInsert = new ArrayList<>();
List<KingdeeReceiptFlow> toUpdate = new ArrayList<>();
int createdCount = 0;
int updatedCount = 0;
for (Map.Entry<String, BfiClaimAnnounceVO> entry : validAnnounces.entrySet()) {
String detailSerialNo = entry.getKey();
BfiClaimAnnounceVO announce = entry.getValue();
BigDecimal receiptAmount = money(announce.getReamount());
// 判断是新增还是更新
KingdeeReceiptFlow existing = existingMap.get(detailSerialNo);
boolean created = (existing == null);
KingdeeReceiptFlow entity;
if (created) {
// 新增：初始化本地认领金额和状态
entity = new KingdeeReceiptFlow();
entity.setClaimedAmount(BigDecimal.ZERO.setScale(2, RoundingMode.HALF_UP));
entity.setClaimStatus(UNCLAIMED);
} else {
// 更新：保留本地已认领金额和状态
entity = existing;
}
// 复制公告数据到实体（不覆盖本地认领字段）
copyAnnounceRow(entity, announce, detailSerialNo, receiptAmount);
// 根据本地累计认领金额与可认领上限重新计算认领状态
entity.setClaimStatus(amountClaimStatus(money(entity.getClaimedAmount()),
claimCeiling(entity)));
if (created) {
toInsert.add(entity);
createdCount++;
} else {
toUpdate.add(entity);
updatedCount++;
state.pending.add(new BfiRecBillRow(recBill, detailSerialNo, receiptAmount));
if (state.pending.size() >= SYNC_BATCH_SIZE) {
state.batchNo++;
state.totalCount += this.syncBatch(state.batchNo, state.pending);
state.pending.clear();
state.batchSerials.clear();
}
}
log.info("收款流水列表构建完成：待新增 {} 条，待更新 {} 条", createdCount, updatedCount);
}
// 批量插入和更新
if (!toInsert.isEmpty()) {
log.info("收款流水同步开始批量插入 {} 条", toInsert.size());
saveBatch(toInsert);
log.info("收款流水批量插入完成");
}
if (!toUpdate.isEmpty()) {
log.info("收款流水同步开始批量更新 {} 条", toUpdate.size());
updateBatchById(toUpdate);
log.info("收款流水批量更新完成");
}
/**
* 单批入库（独立事务）：批内 FOR UPDATE 防并发，按明细流水号 upsert，操作日志批量落库
*
* @param batchNo 批次号（日志用）
* @param rows 本批流水行
* @return 本批新增+更新条数
*/
private int syncBatch(int batchNo, List<BfiRecBillRow> rows) {
Integer count = transactionTemplate.execute(status -> {
// 批量查询已存在的记录（FOR UPDATE 防并发）
Map<String, KingdeeReceiptFlow> existingMap = baseMapper.selectList(
Wrappers.<KingdeeReceiptFlow>lambdaQuery()
.in(KingdeeReceiptFlow::getDetailSerialNo,
rows.stream().map(BfiRecBillRow::detailSerialNo).toList())
.last("FOR UPDATE"))
.stream().collect(Collectors.toMap(KingdeeReceiptFlow::getDetailSerialNo, e -> e));
List<KingdeeReceiptFlow> toInsert = new ArrayList<>();
List<KingdeeReceiptFlow> toUpdate = new ArrayList<>();
for (BfiRecBillRow row : rows) {
KingdeeReceiptFlow existing = existingMap.get(row.detailSerialNo());
boolean created = (existing == null);
KingdeeReceiptFlow entity;
if (created) {
// 新增：初始化本地认领金额和状态
entity = new KingdeeReceiptFlow();
entity.setClaimedAmount(BigDecimal.ZERO.setScale(2, RoundingMode.HALF_UP));
entity.setClaimStatus(UNCLAIMED);
} else {
// 更新：保留本地已认领金额和状态
entity = existing;
}
// 复制收款单数据到实体（不覆盖本地认领字段）
copyRecBillRow(entity, row);
// 根据本地累计认领金额与可认领上限重新计算认领状态
entity.setClaimStatus(amountClaimStatus(money(entity.getClaimedAmount()),
claimCeiling(entity)));
if (created) {
toInsert.add(entity);
} else {
toUpdate.add(entity);
}
}
if (!toInsert.isEmpty()) {
saveBatch(toInsert);
}
if (!toUpdate.isEmpty()) {
updateBatchById(toUpdate);
}
// 记录操作日志（批量插入，避免逐行 N+1）
List<ReceiptFlowRecord> records = new ArrayList<>(toInsert.size() + toUpdate.size());
for (KingdeeReceiptFlow entity : toInsert) {
records.add(buildRecord(entity.getId(), null, "sync", "新增金蝶收款流水",
entity.getClaimStatus(), entity.getClaimStatus(), BigDecimal.ZERO, entity.getDetailSerialNo()));
}
for (KingdeeReceiptFlow entity : toUpdate) {
records.add(buildRecord(entity.getId(), null, "sync", "更新金蝶收款流水",
entity.getClaimStatus(), entity.getClaimStatus(), BigDecimal.ZERO, entity.getDetailSerialNo()));
}
if (!records.isEmpty()) {
Db.saveBatch(records);
}
return toInsert.size() + toUpdate.size();
});
log.info("收款流水同步第 {} 批入库完成，本批 {} 条", batchNo, count == null ? 0 : count);
return count == null ? 0 : count;
}
// 记录操作日志（批量插入，避免逐行 N+1）
log.info("收款流水同步开始记录操作日志，共 {} 条", toInsert.size() + toUpdate.size());
List<ReceiptFlowRecord> records = new ArrayList<>(toInsert.size() + toUpdate.size());
for (KingdeeReceiptFlow entity : toInsert) {
records.add(buildRecord(entity.getId(), null, "sync", "新增金蝶收款流水",
entity.getClaimStatus(), entity.getClaimStatus(), BigDecimal.ZERO, entity.getDetailSerialNo()));
}
for (KingdeeReceiptFlow entity : toUpdate) {
records.add(buildRecord(entity.getId(), null, "sync", "更新金蝶收款流水",
entity.getClaimStatus(), entity.getClaimStatus(), BigDecimal.ZERO, entity.getDetailSerialNo()));
}
if (!records.isEmpty()) {
Db.saveBatch(records);
}
log.info("收款流水操作日志记录完成");
/**
* A301-1 收款单查询返回的收款单 + 流水分录展开行（同步过程传递用）
*/
private record BfiRecBillRow(BfiRecBillVO recBill,
String detailSerialNo, BigDecimal receiptAmount) {
}
log.info("金蝶收款流水同步完成 claimusers：{}，拉取 {} 条，新增 {} 条，更新 {} 条",
claimusers, announces.size(), createdCount, updatedCount);
return createdCount + updatedCount;
/**
* 收款流水整轮同步状态：待入库缓冲与统计累加（各切片共享，结束进日志摘要）
*/
private static final class RecBillSyncState {
/**
* 待入库缓冲：累计满 SYNC_BATCH_SIZE 即入库一批并清空
*/
final List<BfiRecBillRow> pending = new ArrayList<>();
/**
* 批内收款单号去重（含切片边界重复拉取）
*/
final Set<String> batchSerials = new HashSet<>();
/**
* A301-1 原始拉取收款单张数
*/
int pullCount;
/**
* 跳过条数（缺单号/金额异常/重复拉取）
*/
int skippedCount;
/**
* 新增+更新条数
*/
int totalCount;
/**
* 已入库批次数
*/
int batchNo;
/**
* 实际处理的翻页总页数
*/
int pageCount;
/**
* 实际处理的切片数
*/
int sliceCount;
}
private Map<String, Object> candidateRow(FormalSettlement settlement, BigDecimal claimedAmount) {
@@ -724,19 +811,12 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
}
/**
* 可认领上限：公告未认领金额与收款金额取较小正值。
* 主口径仍为 A301-2 公告未认领金额；与收款金额取 min，避免未认领金额异常偏大导致无法进入「认领完成」。
* 可认领上限：收款金额（A301-1 actrecamt）。
* 认领只登记本地并推合同合规，与金蝶侧收款单匹配（核销）状态无关；
* 金蝶未匹配收款金额（unmatchamountrec）仅作参考展示，不参与额度控制。
*/
private BigDecimal claimCeiling(KingdeeReceiptFlow flow) {
BigDecimal unclaimed = money(flow.getUnclaimedAmount());
BigDecimal receipt = money(flow.getReceiptAmount());
if (receipt.compareTo(BigDecimal.ZERO) <= 0) {
return unclaimed;
}
if (unclaimed.compareTo(BigDecimal.ZERO) <= 0) {
return unclaimed;
}
return unclaimed.min(receipt);
return money(flow.getReceiptAmount());
}
private Long toLong(Object value) {
@@ -774,405 +854,72 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
}
/**
* 手动推送金蝶（A301-3 收款认领结果推送）
* <p>
* 仅认领完成且未推送过的流水可推送；推送前以当前用户姓名重查 A301-2 最新公告对账。
* 推送失败不抛异常跨事务边界（保证失败状态落库），原因随结果对象返回。
* A301-1 收款单 → 收款流水表字段拷贝（仅覆盖金蝶侧来源字段，不覆盖本地认领金额与状态）。
* 金蝶匹配/结算金额原样落库仅作参考，不参与认领额度控制。
*/
@Override
public ReceiptClaimPushResult pushClaimToKingdee(Long flowId) {
if (flowId == null) {
throw new ServiceException("收款流水ID不能为空");
}
KingdeeReceiptFlow flow = existing(flowId);
if (flow.getBillId() == null) {
return ReceiptClaimPushResult.fail("认领公告id缺失，请先手动同步金蝶收款流水");
}
String claimusers = UserCache.getUserRealName(AuthUtil.getUserId());
if (Func.isEmpty(claimusers)) {
throw new ServiceException("当前用户无姓名，无法推送金蝶收款认领");
}
// 推送前对账：以当前用户身份重查 A301-2 拿最新公告（手动推送者须在公告认领范围内）
BfiClaimAnnounceVO announce = queryClaimAnnounces(claimusers).stream()
.filter(item -> flow.getBillId().equals(item.getId()))
.findFirst().orElse(null);
if (announce == null) {
return ReceiptClaimPushResult.fail("金蝶侧未查询到该认领公告，当前用户可能不在公告认领范围内，请重新同步后重试");
}
return pushClaimLocked(flow.getId(), announce);
}
/**
* 定时推送金蝶：扫描认领完成且未推送过的流水，按认领人姓名分组重查 A301-2 最新公告后逐条推送。
* 多副本部署下由 single-flight 分布式锁保证同一轮全局最多一份在跑，已有轮次进行中则本轮跳过。
*
* @return 执行摘要
*/
@Override
public String pushClaimByTask() {
return kingdeeSyncLockSupport.runSingleFlight(RECEIPT_CLAIM_PUSH_LOCK_PREFIX, bfiProperties.getReceiptClaimPush().getLockLeaseSeconds(),
"定时推送收款认领", this::executeReceiptClaimPush);
}
/**
* 定时推送收款认领主体：按认领人姓名串行处理——
* 先重查该认领人的 A301-2 最新公告并推完其名下全部流水，再到下一个认领人。
* A301-2 的 claimusers 必填且为单个用户姓名，定时任务无登录人上下文，
* 故按认领人逐人查询公告，按公告id（bill_id）匹配流水。
* 单条流水推送失败独立消化，不影响同批其他流水。
*
* @return 执行摘要
*/
private String executeReceiptClaimPush() {
List<KingdeeReceiptFlow> candidates = list(Wrappers.<KingdeeReceiptFlow>lambdaQuery()
.isNotNull(KingdeeReceiptFlow::getBillId)
.in(KingdeeReceiptFlow::getPushStatus, List.of(
KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_NONE, KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_FAILED))
.eq(KingdeeReceiptFlow::getClaimStatus, CLAIMED)
.eq(KingdeeReceiptFlow::getStatus, 1)
.orderByAsc(KingdeeReceiptFlow::getId));
if (candidates.isEmpty()) {
return "无待推送流水";
}
Map<Long, KingdeeReceiptFlow> candidateById = candidates.stream()
.collect(Collectors.toMap(KingdeeReceiptFlow::getId, Function.identity(),
(first, second) -> first, LinkedHashMap::new));
// 认领人 → 其有效认领的流水id
Map<String, Set<Long>> claimedFlowIdsByClaimer = claimMapper.selectList(
Wrappers.<ReceiptClaim>lambdaQuery()
.in(ReceiptClaim::getReceiptFlowId, candidateById.keySet())
.eq(ReceiptClaim::getClaimStatus, CLAIMED)).stream()
.filter(claim -> Func.isNotEmpty(claim.getClaimerName()) && claim.getReceiptFlowId() != null)
.collect(Collectors.groupingBy(ReceiptClaim::getClaimerName,
Collectors.mapping(ReceiptClaim::getReceiptFlowId, Collectors.toSet())));
if (claimedFlowIdsByClaimer.isEmpty()) {
return "待推送流水 " + candidates.size() + " 条，但无有效认领人，跳过";
}
int successCount = 0;
int failedCount = 0;
int skippedCount = 0;
// 本轮已推送成功的流水：同一流水被多个认领人认领时，只在首个覆盖它的认领人处推送一次
Set<Long> pushedFlowIds = new HashSet<>();
// 按认领人逐人串行：查该认领人公告 → 推完其名下流水 → 下一个认领人
for (String claimerName : claimedFlowIdsByClaimer.keySet().stream().sorted().toList()) {
Set<Long> claimerFlowIds = claimedFlowIdsByClaimer.get(claimerName);
List<KingdeeReceiptFlow> claimerFlows = candidateById.values().stream()
.filter(flow -> claimerFlowIds.contains(flow.getId()))
.filter(flow -> !pushedFlowIds.contains(flow.getId()))
.toList();
if (claimerFlows.isEmpty()) {
continue;
}
// 该认领人的公告一次查询，按公告id归集
Map<Long, BfiClaimAnnounceVO> announceByBillId = new HashMap<>();
try {
for (BfiClaimAnnounceVO announce : queryClaimAnnounces(claimerName)) {
if (announce.getId() != null) {
announceByBillId.putIfAbsent(announce.getId(), announce);
}
}
} catch (Exception exception) {
log.error("定时推送收款认领：认领人[{}]公告查询失败，其名下流水全部跳过", claimerName, exception);
skippedCount += claimerFlows.size();
continue;
}
for (KingdeeReceiptFlow flow : claimerFlows) {
BfiClaimAnnounceVO announce = announceByBillId.get(flow.getBillId());
if (announce == null) {
skippedCount++;
log.info("定时推送收款认领：认领人[{}]流水[{}]未在公告查询结果中命中，跳过",
claimerName, flow.getId());
continue;
}
try {
ReceiptClaimPushResult result = pushClaimLocked(flow.getId(), announce);
if (result.isSuccess()) {
successCount++;
pushedFlowIds.add(flow.getId());
} else {
failedCount++;
}
} catch (Exception exception) {
failedCount++;
log.error("定时推送收款认领：认领人[{}]流水[{}]推送异常", claimerName, flow.getId(), exception);
}
}
}
String summary = "扫描 " + candidates.size() + " 条，推送成功 " + successCount
+ " 条，推送失败 " + failedCount + " 条，公告未命中跳过 " + skippedCount + " 条";
log.info("定时推送收款认领完成：{}", summary);
return summary;
}
/**
* 事务内推送：流水行锁覆盖闸门校验、对账、推送与状态落库全过程，
* 防定时任务与手动按钮并发对同一流水双推；
* 推送成功后触发合同合规认领链推送（C103-9/C107-1/C108-1，事务提交后执行，失败不影响金蝶推送结果）
*/
private ReceiptClaimPushResult pushClaimLocked(Long flowId, BfiClaimAnnounceVO announce) {
ReceiptClaimPushResult result = transactionTemplate.execute(status -> doPushClaimToKingdee(flowId, announce));
if (result != null && result.isSuccess()) {
hcsClaimSyncSupport.pushClaimToHcs(flowId);
}
return result;
}
/**
* 推送单条流水：静态闸门 → 最新公告对账 → 按流水归集分摊行推送 → 成败状态落库
*/
private ReceiptClaimPushResult doPushClaimToKingdee(Long flowId, BfiClaimAnnounceVO announce) {
KingdeeReceiptFlow flow = lockedFlow(flowId);
if (flow.getBillId() == null) {
return ReceiptClaimPushResult.fail("认领公告id缺失，请先手动同步金蝶收款流水");
}
// 终态闸门：已推送流水不允许二次推送（作废重认领使等式再满足也不推，金蝶侧人工处置）
if (KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_PUSHED.equals(flow.getPushStatus())) {
return ReceiptClaimPushResult.fail("该流水已推送金蝶，不允许重复推送");
}
// 推送前对账：以最新公告刷新公告侧未认领金额并重算认领状态（快照落库，页面口径同步修正）
flow.setUnclaimedAmount(money(announce.getUnclaimamount()));
flow.setKingdeeClaimStatus(trimToNull(announce.getClaimstatus()));
flow.setClaimMe(announce.getClaimme());
BigDecimal claimedTotal = flowClaimedAmount(flow.getId());
flow.setClaimedAmount(claimedTotal);
BigDecimal claimCeiling = claimCeiling(flow);
String claimStatus = amountClaimStatus(claimedTotal, claimCeiling);
flow.setClaimStatus(claimStatus);
updateById(flow);
if (!CLAIMED.equals(claimStatus)) {
return ReceiptClaimPushResult.fail("累计认领金额（" + claimedTotal + "）与可认领上限（"
+ claimCeiling + "）不一致，不满足推送条件");
}
// 分录取该流水全部有效分摊行（结算单id升序，跨认领主单归集）
List<ReceiptClaimSettlement> allocations = claimSettlementMapper.selectList(
Wrappers.<ReceiptClaimSettlement>lambdaQuery()
.eq(ReceiptClaimSettlement::getReceiptFlowId, flow.getId())
.eq(ReceiptClaimSettlement::getStatus, 1)
.eq(ReceiptClaimSettlement::getIsDeleted, 0)
.orderByAsc(ReceiptClaimSettlement::getFormalSettlementId));
if (allocations.isEmpty()) {
return ReceiptClaimPushResult.fail("该流水无有效认领分摊，无法推送");
}
// 核心单据编号取第一张结算单同步金蝶回写的星瀚内码（应收/应付单金蝶id），TMS本地id金蝶无法识别
FormalSettlement firstSettlement = formalSettlementMapper.selectById(allocations.get(0).getFormalSettlementId());
if (firstSettlement == null || Func.isBlank(firstSettlement.getKingdeeBillId())) {
return ReceiptClaimPushResult.fail("结算单" + allocations.get(0).getFormalSettlementNo()
+ "未同步金蝶（缺少金蝶单据id），不满足推送条件");
}
// 推送来源编码：分摊结算单号下划线拼接（A301-3 契约口径；分摊不变则重试编码不变，
// 金蝶按 awrp_src_sys + awrp_src_code 幂等防重试双单）
String awrpSrcCode = allocations.stream()
.map(ReceiptClaimSettlement::getFormalSettlementNo)
.filter(Func::isNotEmpty)
.distinct()
.collect(Collectors.joining("_"));
flow.setAwrpSrcCode(awrpSrcCode);
BfiClaimPushDTO param = buildClaimPushDTO(flow, claimedTotal, allocations, firstSettlement.getKingdeeBillId());
log.info("调用BFI接口 收款认领结果推送开始 flowId：{}，billId：{}，awrpSrcCode：{}，分摊明细 {} 行，认领金额 {}",
flow.getId(), flow.getBillId(), flow.getAwrpSrcCode(), allocations.size(), claimedTotal);
try {
BfiBillSaveResultVO result = bfiService.pushClaimResult(param);
return applyClaimPushSuccess(flow, extractClaimPushBillNo(result));
} catch (Exception exception) {
return applyClaimPushFailure(flow, exception);
}
}
/**
* A301-3 推送报文组装：billid=公告id，单条分录、金额=全部未推送金额（一笔流水一张金蝶收款单），
* 核心单据编号=第一张结算单的金蝶单据id（星瀚内码）
*/
private BfiClaimPushDTO buildClaimPushDTO(KingdeeReceiptFlow flow, BigDecimal claimedTotal,
List<ReceiptClaimSettlement> allocations, String coreBillId) {
BfiClaimPushDTO param = new BfiClaimPushDTO();
// 【必填】认领公告id
param.setBillid(flow.getBillId());
// 【必填】来源系统编码
param.setAwrpSrcSys(bfiProperties.getSrcSys());
// 【必填】来源系统单据编码（分摊结算单号下划线拼接）
param.setAwrpSrcCode(flow.getAwrpSrcCode());
// 【必填】收款类型.编码
param.setRecpaytypeNumber(KingdeeBfiConstant.BFI_CLAIM_REC_PAY_TYPE);
// 【必填】付款人类型
param.setPaymenttype(KingdeeBfiConstant.BFI_CLAIM_PAYMENT_TYPE);
// 【必填】付款人名称
param.setRecviewpayer(flow.getPayerName());
// 【必填】付款人id
param.setRecpayer(flow.getPayerId());
// 【必填】单据体分录：仅一条，应收金额=全部未推送金额（累计有效认领）
BfiClaimPushEntryDTO entry = new BfiClaimPushEntryDTO();
// 【必填】应收金额（全部未推送金额）
entry.setEReceivableamt(claimedTotal);
// 分录行序号（第一张结算单id，分摊已按结算单id升序，多张取最小）
entry.setSeq(allocations.get(0).getFormalSettlementId());
// 核心单据类型
// entry.setECorebilltype(KingdeeBfiConstant.BFI_CLAIM_CORE_BILL_TYPE);
// 核心单据编号（第一张结算单的金蝶单据id，星瀚内码）
entry.setECorebillno(coreBillId);
param.setEntryentity(List.of(entry));
return param;
}
/**
* 解析 A301-3 推送结果：全项成功返回单据号，否则抛出汇总错误文本（由失败路径落库）。
* 成功响应的 number 为空，金蝶收款单号取回执 keys 中的 awrp_src_code（来源编码）。
*/
private String extractClaimPushBillNo(BfiBillSaveResultVO result) {
if (result == null || result.getResult() == null || result.getResult().isEmpty()) {
throw new ServiceException("金蝶认领结果推送失败，返回结果为空");
}
List<BfiBillSaveResultItemVO> items = result.getResult();
boolean allSuccess = items.stream().allMatch(item -> Boolean.TRUE.equals(item.getBillStatus()));
if (!allSuccess) {
String errorText = items.stream()
.map(BfiBillSaveResultItemVO::getErrorText)
.filter(text -> !text.isEmpty())
.collect(Collectors.joining("；"));
throw new ServiceException("金蝶认领结果推送失败"
+ (errorText.isEmpty() ? "" : "：" + errorText));
}
return items.stream()
.map(this::claimPushBillNoOf)
.filter(Func::isNotEmpty)
.findFirst().orElse(null);
}
/**
* 单项推送结果 → 单据号：A301-3 成功响应 number 为空，取回执键值中的 awrp_src_code
*/
private String claimPushBillNoOf(BfiBillSaveResultItemVO item) {
if (Func.isNotEmpty(item.getNumber())) {
return item.getNumber();
}
return item.getKeys() == null ? null : item.getKeys().get("awrp_src_code");
}
/**
* 推送成功：流水置已推送并回填金蝶收款单号，级联刷新名下未作废认领主单的冗余展示字段
*/
private ReceiptClaimPushResult applyClaimPushSuccess(KingdeeReceiptFlow flow, String kingdeeBillNo) {
log.info("调用BFI接口 收款认领结果推送成功 flowId：{}，金蝶收款单号：{}",
flow.getId(), Func.isEmpty(kingdeeBillNo) ? "响应未返回" : kingdeeBillNo);
flow.setPushStatus(KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_PUSHED);
flow.setPushedTime(LocalDateTime.now());
flow.setKingdeeBillNo(kingdeeBillNo);
flow.setKingdeeBillStatus(KingdeeBfiConstant.KINGDEE_STATUS_PUSHED);
// 失败原因需显式置空（实体 update 忽略 null 字段，走 lambdaUpdate）
this.update(Wrappers.<KingdeeReceiptFlow>lambdaUpdate()
.eq(KingdeeReceiptFlow::getId, flow.getId())
.set(KingdeeReceiptFlow::getPushStatus, flow.getPushStatus())
.set(KingdeeReceiptFlow::getPushFailReason, null)
.set(KingdeeReceiptFlow::getPushedTime, flow.getPushedTime())
.set(KingdeeReceiptFlow::getAwrpSrcCode, flow.getAwrpSrcCode())
.set(KingdeeReceiptFlow::getKingdeeBillNo, kingdeeBillNo)
.set(KingdeeReceiptFlow::getKingdeeBillStatus, flow.getKingdeeBillStatus()));
// 级联刷新名下未作废认领主单的冗余展示字段
claimMapper.update(null, Wrappers.<ReceiptClaim>lambdaUpdate()
.eq(ReceiptClaim::getReceiptFlowId, flow.getId())
.eq(ReceiptClaim::getClaimStatus, CLAIMED)
.set(ReceiptClaim::getKingdeeBillNo, kingdeeBillNo)
.set(ReceiptClaim::getKingdeeBillStatus, KingdeeBfiConstant.KINGDEE_STATUS_PUSHED));
record(flow.getId(), null, "push", "推送金蝶收款认领", CLAIMED, CLAIMED, flow.getClaimedAmount(),
"金蝶收款单号：" + (Func.isEmpty(kingdeeBillNo) ? "响应未返回" : kingdeeBillNo));
return ReceiptClaimPushResult.success(kingdeeBillNo);
}
/**
* 推送失败：流水置推送失败并记录原因，本地认领数据保留，可重新推送（重试复用同一来源编码）
*/
private ReceiptClaimPushResult applyClaimPushFailure(KingdeeReceiptFlow flow, Exception exception) {
String reason = Func.isEmpty(exception.getMessage())
? exception.getClass().getSimpleName() : exception.getMessage();
reason = truncateText(reason, 1000);
log.error("调用BFI接口 收款认领结果推送失败 flowId：{}，billId：{}，awrpSrcCode：{}",
flow.getId(), flow.getBillId(), flow.getAwrpSrcCode(), exception);
this.update(Wrappers.<KingdeeReceiptFlow>lambdaUpdate()
.eq(KingdeeReceiptFlow::getId, flow.getId())
.set(KingdeeReceiptFlow::getPushStatus, KingdeeBfiConstant.RECEIPT_CLAIM_PUSH_FAILED)
.set(KingdeeReceiptFlow::getPushFailReason, reason)
.set(KingdeeReceiptFlow::getAwrpSrcCode, flow.getAwrpSrcCode()));
record(flow.getId(), null, "push", "推送金蝶收款认领", CLAIMED, CLAIMED, flow.getClaimedAmount(),
"推送失败：" + truncateText(reason, 200));
return ReceiptClaimPushResult.fail("金蝶认领结果推送失败：" + reason);
}
/**
* A301-2 收款认领公告查询：按认领人姓名全量翻页，时间窗口取 Nacos 配置（默认近半年）。
* 认领公告同步、手动推送对账与定时任务对账共用。
*/
private List<BfiClaimAnnounceVO> queryClaimAnnounces(String claimusers) {
int months = bfiProperties.getClaimAnnounce().getMonths();
// 认领人直接取 Nacos 配置值
String effectiveClaimusers = bfiProperties.getClaimAnnounce().getClaimusers();
LocalDateTime endDate = LocalDateTime.now();
LocalDateTime startDate = endDate.minusMonths(months);
long start = System.currentTimeMillis();
log.info("调用BFI接口 收款认领公告查询开始 claimusers：{}，时间窗口：{} ~ {}（近{}个月）",
effectiveClaimusers, startDate.format(BFI_DATE_TIME_FORMATTER), endDate.format(BFI_DATE_TIME_FORMATTER), months);
BfiClaimAnnounceQueryDTO queryDTO = new BfiClaimAnnounceQueryDTO();
queryDTO.setClaimusers(effectiveClaimusers);
queryDTO.setModifytimeS(startDate.format(BFI_DATE_TIME_FORMATTER));
queryDTO.setModifytimeE(endDate.format(BFI_DATE_TIME_FORMATTER));
queryDTO.setPageSize(SYNC_PAGE_SIZE);
List<BfiClaimAnnounceVO> announces = BfiUtil.queryAllPages(pageNo -> {
queryDTO.setPageNo(pageNo);
return bfiService.queryClaimAnnounce(queryDTO);
});
log.info("调用BFI接口 收款认领公告查询结束 claimusers：{}，耗时：{}ms，拉取 {} 条",
effectiveClaimusers, System.currentTimeMillis() - start, announces.size());
return announces;
}
/**
* A301-2 认领公告 → 收款流水表字段拷贝（仅覆盖金蝶侧来源字段，不覆盖本地认领金额与状态）
*/
private void copyAnnounceRow(KingdeeReceiptFlow target, BfiClaimAnnounceVO source,
String detailSerialNo, BigDecimal receiptAmount) {
// 金蝶认领公告id
target.setBillId(source.getId());
// 收款通知单号
private void copyRecBillRow(KingdeeReceiptFlow target, BfiRecBillRow row) {
BfiRecBillVO source = row.recBill();
// 金蝶收款单号（既是收款通知单号也是金蝶单据号）
target.setReceiptNoticeNo(trimToEmpty(source.getBillno()));
// 付款人名称（取自对方户名）
target.setPayerName(trimToEmpty(source.getOppunit()));
// 付款人id（取自对方账号）
target.setPayerId(trimToEmpty(source.getOppbanknumber()));
// 收款人
target.setPayeeName(trimToNull(source.getRecpayee()));
// 收款金额
target.setReceiptAmount(receiptAmount);
// 对方单位名称
target.setCounterpartyName(trimToEmpty(source.getOppunit()));
// 对方银行账号
target.setCounterpartyAccount(trimToEmpty(source.getOppbanknumber()));
// 对方开户行
target.setCounterpartyBank(trimToEmpty(source.getOppbank()));
target.setKingdeeBillNo(trimToNull(source.getBillno()));
// 金蝶回写状态随单据状态同步刷新
target.setKingdeeBillStatus(billStatusOf(source.getBillstatus()));
// 付款人名称
target.setPayerName(trimToEmpty(source.getPayername()));
// 收款人（收款公司名称）
target.setPayeeName(trimToNull(source.getOrgName()));
// 收款人（公司）.编码
target.setOrgNumber(trimToNull(source.getOrgNumber()));
// 核算组织.编码
target.setOpenOrgNumber(trimToNull(source.getOpenorgNumber()));
// 收款金额（主单 actrecamt）
target.setReceiptAmount(row.receiptAmount());
// 对方单位名称（取付款人名称）
target.setCounterpartyName(trimToEmpty(source.getPayername()));
// 对方银行账号（付款账户）
target.setCounterpartyAccount(trimToEmpty(source.getPayeracctbanknum()));
// 对方开户行（付款银行）
target.setCounterpartyBank(trimToEmpty(source.getPayerbankname()));
// 摘要
target.setSummary(trimToNull(source.getDescription()));
// 交易日期
target.setTransactionTime(parseDateTime(source.getTradetime()));
target.setSummary(trimToNull(source.getTxtDescription()));
// 交易日期（业务日期）
target.setTransactionTime(parseDateTime(source.getBizdate()));
// 明细流水号
target.setDetailSerialNo(detailSerialNo);
// 未认领金额
target.setUnclaimedAmount(money(source.getUnclaimamount()));
target.setDetailSerialNo(row.detailSerialNo());
// 未匹配收款金额（金蝶参考展示，不参与认领额度）
target.setUnmatchAmountRec(money(source.getUnmatchamountrec()));
// 已匹配收款金额 / 已匹配付款金额 / 未匹配付款金额
target.setMatchAmountRec(money(source.getMatchamountrec()));
target.setMatchAmountPay(money(source.getMatchamountpay()));
target.setUnmatchAmountPay(money(source.getUnmatchamountpay()));
// 已结算金额 / 未结算金额
target.setSettleAmount(money(source.getSettleamount()));
target.setUnsettleAmount(money(source.getUnsettleamount()));
// 手续费
target.setFee(source.getFee() == null ? null : source.getFee().setScale(2, RoundingMode.HALF_UP));
// 公告认领状态
target.setKingdeeClaimStatus(trimToNull(source.getClaimstatus()));
// 我已认领
target.setClaimMe(source.getClaimme());
// 来源更新时间
target.setSourceUpdatedTime(target.getTransactionTime() == null
? LocalDateTime.now() : target.getTransactionTime());
target.setSourceUpdatedTime(LocalDateTime.now());
}
private String firstNonBlank(String... values) {
for (String value : values) {
if (Func.isNotEmpty(value)) {
return value.trim();
}
/**
* A301-1 单据状态 → 本地金蝶回写状态（同步时随单据刷新）
*
* @param billStatus 金蝶 billstatus（A暂存/B已提交/C已审核/D已收款/G已退单）
* @return 本地状态
*/
private String billStatusOf(String billStatus) {
if ("D".equals(billStatus)) {
return KingdeeBfiConstant.KINGDEE_STATUS_RECEIVED;
}
return null;
if ("C".equals(billStatus)) {
return APPROVED;
}
if ("A".equals(billStatus) || "B".equals(billStatus)) {
return KingdeeBfiConstant.KINGDEE_STATUS_PUSHED;
}
// 其余状态（含 G 已退单/E 变更中）按处理失败记录，提示人工在金蝶核查
log.warn("金蝶收款单单据状态[{}]未匹配映射，同步按 failed 处理", billStatus);
return KingdeeBfiConstant.KINGDEE_STATUS_FAILED;
}
private LocalDateTime parseDateTime(String value) {
@@ -1237,13 +984,6 @@ public class ReceiptFlowServiceImpl extends BaseServiceImpl<KingdeeReceiptFlowMa
}
}
private String truncateText(String value, int maxLength) {
if (value == null || value.length() <= maxLength) {
return value;
}
return value.substring(0, maxLength);
}
private void record(Long flowId, Long claimId, String actionType, String actionName,
String fromStatus, String toStatus, BigDecimal operationAmount, String content) {
recordMapper.insert(buildRecord(flowId, claimId, actionType, actionName,
blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsClaimSyncSupport.java
+209 -67
View File
@@ -11,8 +11,8 @@
* 2. Redistribution of this software's source code to any third party
* is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments
* from this software for their own commercial purposes.
* 3. Licensees may copyright their own code but cannot use segments of this software
* for their own commercial purposes.
* <p>
* Using this software signifies agreement to this license agreement and terms of use,
* and you expressly agree to be bound by the terms of use of this software.
@@ -33,17 +33,24 @@ import org.springblade.core.tool.utils.StringUtil;
import org.springblade.hcs.config.HcsProperties;
import org.springblade.hcs.dto.HcsClaimRecordAddDTO;
import org.springblade.hcs.dto.HcsCollectionFlowVO;
import org.springblade.hcs.dto.HcsFormSaveVO;
import org.springblade.hcs.dto.HcsIdVO;
import org.springblade.hcs.dto.HcsMechanismsDTO;
import org.springblade.hcs.dto.HcsPageQueryDTO;
import org.springblade.hcs.dto.HcsPageVO;
import org.springblade.hcs.dto.HcsPerfRecordFormDataDTO;
import org.springblade.hcs.dto.HcsPerfRecordPropsDTO;
import org.springblade.hcs.dto.HcsPerfRecordSaveDTO;
import org.springblade.hcs.dto.HcsRefVO;
import org.springblade.hcs.dto.HcsResult;
import org.springblade.hcs.dto.HcsUserRefVO;
import org.springblade.hcs.exception.HcsException;
import org.springblade.hcs.feign.IHcsClient;
import org.springblade.transport.constant.HcsSyncConstant;
import org.springblade.transport.mapper.ContractManageMapper;
import org.springblade.transport.mapper.FormalSettlementMapper;
import org.springblade.transport.mapper.KingdeeReceiptFlowMapper;
import org.springblade.transport.mapper.ReceiptClaimHcsRecordMapper;
import org.springblade.transport.mapper.ReceiptClaimMapper;
import org.springblade.transport.mapper.ReceiptClaimSettlementMapper;
import org.springblade.transport.pojo.entity.ContractManage;
@@ -51,12 +58,14 @@ import org.springblade.transport.pojo.entity.FormalSettlement;
import org.springblade.transport.pojo.entity.HcsContractExeStage;
import org.springblade.transport.pojo.entity.KingdeeReceiptFlow;
import org.springblade.transport.pojo.entity.ReceiptClaim;
import org.springblade.transport.pojo.entity.ReceiptClaimHcsRecord;
import org.springblade.transport.pojo.entity.ReceiptClaimSettlement;
import org.springblade.transport.service.IContractExeStageService;
import org.springframework.stereotype.Component;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.util.LinkedHashMap;
import java.util.List;
@@ -67,13 +76,14 @@ import java.util.stream.Collectors;
/**
* HCS 收款认领链推送编排支撑组件（C103-9 更新履约计划 + C107-1 认领记录 + C108-1 履约流水）
* <p>
* 触发点：金蝶认领推送（A301-3）成功之后（手动按钮与定时任务共用钩子）。
* 触发点：收款流水认领事务提交后按认领主单推送（作废认领事务提交后推 C107-3 作废同步）。
* 开关复用既有配置（不单独新增）：exe-stage.sync-enabled 门禁 C103-9/C107-1（与合同链履约计划同步同开关），
* perf-record.sync-enabled 门禁 C108-1（与付款链履约记录同步同开关）。
* 编排顺序：先 C103-9（认领金额累加到收款履约计划行并重推，C107-1/C108-1 引用其返回的阶段ID），
* 再按「认领主单 × 合同」推 C107-1（合规流水ID 经 C104-2 按明细流水号定位），最后按合同推 C108-1 履约流水。
* 再按「认领主单 × 合同」推 C107-1（合规流水ID 经 C104-2 按明细流水号定位，返回 fdId 落库
* blade_receipt_claim_hcs_record 供作废 C107-3 引用），最后按合同推 C108-1 履约流水。
* 合同未推送合规（hcs_fd_id 空）时仅累加计划行金额，随合同链路首推。
* 推送失败仅记日志不回滚金蝶推送结果（单合同失败不影响其余合同）。
* 推送失败仅落失败标记与日志，不回滚认领主流程（单合同失败不影响其余合同，不做定时重试）。
*
* @author Chill
*/
@@ -86,60 +96,80 @@ public class HcsClaimSyncSupport {
* 认领完成状态（与 ReceiptFlowServiceImpl.CLAIMED 同值）
*/
private static final String CLAIMED = "claimed";
/**
* 推送状态：推送成功
*/
private static final String PUSH_SUCCESS = "success";
/**
* 推送状态：推送失败（仅记标记，不做定时重试）
*/
private static final String PUSH_FAILED = "failed";
/**
* 推送状态：已作废（C107-3 同步成功）
*/
private static final String PUSH_VOIDED = "voided";
/**
* 认领记录状态：已认领
*/
private static final int CLAIM_STATUS_CLAIMED = 0;
/**
* 认领记录状态：已作废
*/
private static final int CLAIM_STATUS_VOIDED = 1;
private final IHcsClient hcsClient;
private final HcsProperties hcsProperties;
private final KingdeeReceiptFlowMapper receiptFlowMapper;
private final ReceiptClaimMapper claimMapper;
private final ReceiptClaimSettlementMapper claimSettlementMapper;
private final ReceiptClaimHcsRecordMapper claimHcsRecordMapper;
private final FormalSettlementMapper formalSettlementMapper;
private final ContractManageMapper contractManageMapper;
private final IContractExeStageService contractExeStageService;
private final HcsExeStageSyncSupport hcsExeStageSyncSupport;
private final HcsPerfRecordAddSupport hcsPerfRecordAddSupport;
/**
* 金蝶认领推送成功后推送合同合规（C103-9 → C107-1 → C108-1）
* 认领事务提交后推送合同合规（C103-9 → C107-1 → C108-1，按认领主单维度）
* <p>
* 复用既有开关：exe-stage.sync-enabled（履约计划同步）门禁 C103-9/C107-1，
* perf-record.sync-enabled（履约记录同步）门禁 C108-1；开关关闭或推送异常均静默返回，
* 不影响金蝶认领推送主流程与事务。
* 不影响认领主流程与事务。
*
* @param flowId 收款流水ID
* @param claimId 认领主单ID
*/
public void pushClaimToHcs(Long flowId) {
public void pushClaimToHcs(Long claimId) {
if (!hcsProperties.getExeStage().isSyncEnabled()) {
return;
}
try {
doPushClaimToHcs(flowId);
doPushClaimToHcs(claimId);
} catch (Exception exception) {
log.error("HCS收款认领链推送异常 flowId：{}", flowId, exception);
log.error("HCS收款认领链推送异常 claimId：{}", claimId, exception);
}
}
/**
* 推送主体：归集有效认领分摊（按合同分组）→ 逐合同推送（单合同失败不影响其余合同）
* 推送主体：归集本认领主单有效分摊（按合同分组）→ 逐合同推送（单合同失败不影响其余合同）
*/
private void doPushClaimToHcs(Long flowId) {
KingdeeReceiptFlow flow = receiptFlowMapper.selectById(flowId);
private void doPushClaimToHcs(Long claimId) {
ReceiptClaim claim = claimMapper.selectById(claimId);
if (claim == null || !CLAIMED.equals(claim.getClaimStatus())) {
log.info("HCS收款认领链推送跳过：认领主单不存在或已作废 claimId={}", claimId);
return;
}
KingdeeReceiptFlow flow = receiptFlowMapper.selectById(claim.getReceiptFlowId());
if (flow == null) {
log.warn("HCS收款认领链推送跳过：收款流水不存在 claimId={}，flowId={}", claimId, claim.getReceiptFlowId());
return;
}
// 未作废认领主单（作废认领不同步合规）
List<ReceiptClaim> claims = claimMapper.selectList(Wrappers.<ReceiptClaim>lambdaQuery()
.eq(ReceiptClaim::getReceiptFlowId, flowId)
.eq(ReceiptClaim::getClaimStatus, CLAIMED));
if (claims.isEmpty()) {
return;
}
// 有效分摊行（作废时已置 status=0）
// 本认领主单有效分摊行（作废时已置 status=0）
List<ReceiptClaimSettlement> allocations = claimSettlementMapper.selectList(
Wrappers.<ReceiptClaimSettlement>lambdaQuery()
.eq(ReceiptClaimSettlement::getReceiptFlowId, flowId)
.eq(ReceiptClaimSettlement::getReceiptClaimId, claimId)
.eq(ReceiptClaimSettlement::getStatus, 1)
.eq(ReceiptClaimSettlement::getIsDeleted, 0));
if (allocations.isEmpty()) {
log.info("HCS收款认领链推送跳过：认领主单无有效分摊 claimId={}", claimId);
return;
}
// 结算单批量定位合同（一次 IN 查询，避免逐行 N+1）
@@ -147,20 +177,18 @@ public class HcsClaimSyncSupport {
allocations.stream().map(ReceiptClaimSettlement::getFormalSettlementId)
.filter(Objects::nonNull).distinct().toList()).stream()
.collect(Collectors.toMap(FormalSettlement::getId, item -> item, (first, second) -> first));
// 合同id → 认领主单id → 分摊金额
Map<Long, Map<Long, BigDecimal>> amountByContractByClaim = new LinkedHashMap<>();
// 合同id → 本认领主单分摊金额
Map<Long, BigDecimal> amountByContract = new LinkedHashMap<>();
for (ReceiptClaimSettlement allocation : allocations) {
FormalSettlement settlement = settlements.get(allocation.getFormalSettlementId());
if (settlement == null || settlement.getContractId() == null
|| allocation.getReceiptClaimId() == null || allocation.getAllocatedReceiptAmount() == null) {
|| allocation.getAllocatedReceiptAmount() == null) {
continue;
}
amountByContractByClaim
.computeIfAbsent(settlement.getContractId(), key -> new LinkedHashMap<>())
.merge(allocation.getReceiptClaimId(), allocation.getAllocatedReceiptAmount(), BigDecimal::add);
amountByContract.merge(settlement.getContractId(), allocation.getAllocatedReceiptAmount(), BigDecimal::add);
}
if (amountByContractByClaim.isEmpty()) {
log.info("HCS收款认领链推送跳过：分摊行未关联合同 flowId={}", flowId);
if (amountByContract.isEmpty()) {
log.info("HCS收款认领链推送跳过：分摊行未关联合同 claimId={}，flowId={}", claimId, flow.getId());
return;
}
// 合规侧收款流水ID（C107-1 必填引用，一次定位全部合同共用；定位失败仅跳过 C107-1，不阻塞履约计划更新）
@@ -168,47 +196,47 @@ public class HcsClaimSyncSupport {
try {
hcsCollectionFlowId = locateHcsCollectionFlowId(flow);
} catch (Exception exception) {
log.error("HCS收款流水定位失败 flowId：{}，跳过C107-1认领记录推送", flowId, exception);
log.error("HCS收款流水定位失败 flowId：{}，跳过C107-1认领记录推送", flow.getId(), exception);
}
for (Map.Entry<Long, Map<Long, BigDecimal>> contractEntry : amountByContractByClaim.entrySet()) {
for (Map.Entry<Long, BigDecimal> contractEntry : amountByContract.entrySet()) {
try {
pushOneContract(flow, claims, contractEntry.getKey(), contractEntry.getValue(), hcsCollectionFlowId);
pushOneContract(flow, claim, contractEntry.getKey(), contractEntry.getValue(), hcsCollectionFlowId);
} catch (Exception exception) {
log.error("HCS收款认领链推送失败 flowId：{}，contractId：{}", flowId, contractEntry.getKey(), exception);
log.error("HCS收款认领链推送失败 claimId：{}，flowId：{}，contractId：{}",
claimId, flow.getId(), contractEntry.getKey(), exception);
}
}
}
/**
* 推送单个合同：① C103-9 更新履约计划（认领金额累加重推）→ ② C107-1 认领记录（按认领主单分组）→ ③ C108-1 履约流水
* 推送单个合同：① C103-9 更新履约计划（认领金额累加重推）→ ② C107-1 认领记录（结果落库）→ ③ C108-1 履约流水
*/
private void pushOneContract(KingdeeReceiptFlow flow, List<ReceiptClaim> claims, Long contractId,
Map<Long, BigDecimal> amountByClaim, String hcsCollectionFlowId) {
private void pushOneContract(KingdeeReceiptFlow flow, ReceiptClaim claim, Long contractId,
BigDecimal claimAmount, String hcsCollectionFlowId) {
ContractManage contractManage = contractManageMapper.selectById(contractId);
if (contractManage == null) {
log.warn("HCS收款认领链推送跳过：合同不存在 contractId={}", contractId);
return;
}
BigDecimal claimedTotal = amountByClaim.values().stream().reduce(BigDecimal.ZERO, BigDecimal::add);
// ① C103-9 更新合同履约计划：认领金额累加到收款计划行；已同步行置 update 凭阶段ID 重推
contractExeStageService.accumulateClaimedAmountOnPush(contractId, claimedTotal);
contractExeStageService.accumulateClaimedAmountOnPush(contractId, claimAmount);
HcsContractExeStage stageRow = contractExeStageService.findCollectionStageRow(contractId, HcsSyncConstant.FUND_NATURE_PROGRESS);
if (StringUtil.isNotBlank(contractManage.getHcsFdId())) {
// 行级重推（无待同步行返回提示，不视为失败）；合同未推送合规时随合同链路首推
hcsExeStageSyncSupport.syncExeStages(contractManage);
}
// ② C107-1 认领记录：按「认领主单 × 合同」推送，金额为该认领主单分摊到本合同的金额
// ② C107-1 认领记录：本认领主单分摊到本合同的金额，返回 fdId 落库供 C107-3 作废引用
if (StringUtil.isBlank(hcsCollectionFlowId)) {
log.warn("HCS认领记录推送跳过：未定位到合规收款流水 flowId={}，detailSerialNo={}", flow.getId(), flow.getDetailSerialNo());
log.warn("HCS认领记录推送跳过：未定位到合规收款流水 claimId={}，flowId={}，detailSerialNo={}",
claim.getId(), flow.getId(), flow.getDetailSerialNo());
saveClaimHcsRecord(claim, flow, contractManage, claimAmount, null, PUSH_FAILED, "C104-2未定位到合规收款流水");
} else {
Map<Long, ReceiptClaim> claimsById = claims.stream()
.collect(Collectors.toMap(ReceiptClaim::getId, item -> item, (first, second) -> first));
for (Map.Entry<Long, BigDecimal> claimEntry : amountByClaim.entrySet()) {
pushClaimRecord(flow, claimsById.get(claimEntry.getKey()), contractManage, stageRow, claimEntry.getValue(), hcsCollectionFlowId);
}
String claimRecordFdId = pushClaimRecord(flow, claim, contractManage, stageRow, claimAmount, hcsCollectionFlowId);
saveClaimHcsRecord(claim, flow, contractManage, claimAmount, claimRecordFdId,
StringUtil.isBlank(claimRecordFdId) ? PUSH_FAILED : PUSH_SUCCESS, null);
}
// ③ C108-1 履约流水：按合同一条（开关 perf-record.sync-enabled，与付款链履约记录同步同开关），
// 须已推送合规且存在已同步收款计划行（fd_plan_id 必填）；履约日期为收款流水交易日期
// 须已推送合规且存在已同步收款计划行（fd_plan_id 必填）
if (!hcsProperties.getPerfRecord().isSyncEnabled()) {
log.info("HCS履约流水推送跳过：履约记录同步开关未开启 contractNo={}", contractManage.getContractNo());
return;
@@ -221,16 +249,18 @@ public class HcsClaimSyncSupport {
log.info("HCS履约流水推送跳过：无已同步收款履约计划行 contractNo={}", contractManage.getContractNo());
return;
}
pushPerfRecord(flow, contractManage, stageRow, claimedTotal);
pushPerfRecord(flow, contractManage, stageRow, claimAmount, claim.getClaimDate());
}
/**
* C107-1 认领记录推送（单认领主单 × 单合同）
*
* @return 合规侧认领记录 fdId（响应未返回返回 null）
*/
private void pushClaimRecord(KingdeeReceiptFlow flow, ReceiptClaim claim, ContractManage contractManage,
HcsContractExeStage stageRow, BigDecimal claimAmount, String hcsCollectionFlowId) {
if (claim == null || claimAmount == null || claimAmount.signum() <= 0) {
return;
private String pushClaimRecord(KingdeeReceiptFlow flow, ReceiptClaim claim, ContractManage contractManage,
HcsContractExeStage stageRow, BigDecimal claimAmount, String hcsCollectionFlowId) {
if (claimAmount == null || claimAmount.signum() <= 0) {
return null;
}
HcsClaimRecordAddDTO param = new HcsClaimRecordAddDTO();
// 【必填】收款流水引用（合规侧流水ID，C104-2 按明细流水号定位）
@@ -259,7 +289,7 @@ public class HcsClaimSyncSupport {
param.setFdClaimDate(toMillis(claim.getClaimDate()));
param.setFdRemark(claim.getRemark());
// 状态 0=已认领（仅推送未作废认领）
param.setFdStatus(0);
param.setFdStatus(CLAIM_STATUS_CLAIMED);
log.info("HCS认领记录推送开始 flowId：{}，claimId：{}，contractNo：{}，认领金额 {}",
flow.getId(), claim.getId(), contractManage.getContractNo(), claimAmount);
HcsResult<HcsIdVO> result = hcsClient.claimRecordAdd(param);
@@ -267,25 +297,137 @@ public class HcsClaimSyncSupport {
log.error("HCS认领记录推送失败响应：{}，claimId={}", result == null ? "无响应" : String.format("msg=%s, traceId=%s", result.getMsg(), result.getTraceId()), claim.getId());
throw new HcsException("C107-1 认领记录推送失败：" + (result == null ? "响应为空" : result.getMsg()));
}
// shortcut: C107-1 返回 fdId 未持久化（认领作废同步 C107-3 未实现，重推会重复）；需作废联动时先落库
String claimRecordFdId = result.getData() == null ? null : result.getData().getFdId();
log.info("HCS认领记录推送成功 flowId：{}，claimId：{}，contractNo：{}，claimRecordFdId：{}",
flow.getId(), claim.getId(), contractManage.getContractNo(),
result.getData() == null ? "响应未返回" : result.getData().getFdId());
StringUtil.isBlank(claimRecordFdId) ? "响应未返回" : claimRecordFdId);
return claimRecordFdId;
}
/**
* C108-1 履约流水推送（单合同一条：申请金额=实际金额=该合同累计认领金额，履约日期=收款流水交易日期）
* C107-1 推送结果落库（认领主单 × 合同一条）：成功持久化合规 fdId，失败落标记与原因
*/
private void saveClaimHcsRecord(ReceiptClaim claim, KingdeeReceiptFlow flow, ContractManage contractManage,
BigDecimal claimAmount, String claimRecordFdId, String pushStatus, String failReason) {
ReceiptClaimHcsRecord record = new ReceiptClaimHcsRecord();
record.setReceiptClaimId(claim.getId());
record.setReceiptFlowId(flow.getId());
record.setContractId(contractManage.getId());
record.setContractNo(contractManage.getContractNo());
record.setClaimAmount(claimAmount);
record.setHcsClaimRecordFdId(claimRecordFdId);
record.setPushStatus(pushStatus);
record.setFailReason(failReason);
record.setPushedTime(PUSH_SUCCESS.equals(pushStatus) ? LocalDateTime.now() : null);
claimHcsRecordMapper.insert(record);
}
/**
* 认领作废事务提交后同步合规 C107-3（修改认领记录 fdStatus=1 已作废）
* <p>
* 仅同步本认领主单推送成功的合规记录；单条失败独立记日志，不影响其余合同。
* 作废失败时本地记录保持 success（合规侧仍为已认领），需人工在合规侧处置。
*
* @param claimId 认领主单ID
*/
public void voidClaimToHcs(Long claimId) {
if (!hcsProperties.getExeStage().isSyncEnabled()) {
return;
}
try {
List<ReceiptClaimHcsRecord> records = claimHcsRecordMapper.selectList(
Wrappers.<ReceiptClaimHcsRecord>lambdaQuery()
.eq(ReceiptClaimHcsRecord::getReceiptClaimId, claimId)
.eq(ReceiptClaimHcsRecord::getPushStatus, PUSH_SUCCESS));
if (records.isEmpty()) {
log.info("HCS认领作废同步跳过：无推送成功的合规认领记录 claimId={}", claimId);
return;
}
for (ReceiptClaimHcsRecord record : records) {
try {
voidOneClaimRecord(record);
} catch (Exception exception) {
log.error("HCS认领作废同步失败 claimId：{}，recordId：{}，hcsFdId：{}",
claimId, record.getId(), record.getHcsClaimRecordFdId(), exception);
}
}
} catch (Exception exception) {
log.error("HCS认领作废同步异常 claimId：{}", claimId, exception);
}
}
/**
* C107-3 单条作废：fdId 必填，fdStatus=1 已作废；成功后本地记录置 voided
*/
private void voidOneClaimRecord(ReceiptClaimHcsRecord record) {
HcsClaimRecordAddDTO param = new HcsClaimRecordAddDTO();
// 【必填】合规侧认领记录ID（C107-1 推送成功时落库）
param.setFdId(record.getHcsClaimRecordFdId());
// 状态 1=已作废
param.setFdStatus(CLAIM_STATUS_VOIDED);
log.info("HCS认领作废同步开始 claimId：{}，contractNo：{}，hcsFdId：{}",
record.getReceiptClaimId(), record.getContractNo(), record.getHcsClaimRecordFdId());
HcsResult<HcsIdVO> result = hcsClient.claimRecordUpdate(param);
if (result == null || !result.isSuccess()) {
throw new HcsException("C107-3 认领作废同步失败：" + (result == null ? "响应为空" : result.getMsg()));
}
// 本地推送记录置已作废
claimHcsRecordMapper.update(null, Wrappers.<ReceiptClaimHcsRecord>lambdaUpdate()
.eq(ReceiptClaimHcsRecord::getId, record.getId())
.set(ReceiptClaimHcsRecord::getPushStatus, PUSH_VOIDED));
log.info("HCS认领作废同步成功 claimId：{}，contractNo：{}，hcsFdId：{}",
record.getReceiptClaimId(), record.getContractNo(), record.getHcsClaimRecordFdId());
}
/**
* C108-1 履约流水推送（单合同一条：申请金额=实际金额=本次认领分摊金额）
*/
private void pushPerfRecord(KingdeeReceiptFlow flow, ContractManage contractManage,
HcsContractExeStage stageRow, BigDecimal claimedTotal) {
// 履约日期：交易日期（需求口径），交易时间为空兜底当天
LocalDate perfDate = flow.getTransactionTime() != null ? flow.getTransactionTime().toLocalDate() : LocalDate.now();
String perfFdId = hcsPerfRecordAddSupport.pushPerfRecordAdd(contractManage, stageRow,
firstNonBlank(flow.getReceiptNoticeNo(), flow.getDetailSerialNo()), claimedTotal, toMillis(perfDate),
HcsSyncConstant.PERF_TYPE_COLLECTION, flow.getKingdeeBillNo(), flow.getId(),
"收款履约-" + firstNonBlank(flow.getReceiptNoticeNo(), flow.getDetailSerialNo()));
// shortcut: 履约流水 fdId 未持久化（认领链无 C108-2 更新场景，重推会重复）；需推进实际金额更新时先落库
log.info("HCS履约流水新建完成 flowId：{}，contractNo：{}，perfFdId：{}", flow.getId(), contractManage.getContractNo(), perfFdId);
HcsContractExeStage stageRow, BigDecimal claimAmount, LocalDate planDate) {
// 表单模板ID（配置 perf-record.xform-id，环境值 §9-U9，未配置不传）
String xformId = StringUtil.isBlank(hcsProperties.getPerfRecord().getXformId()) ? null : hcsProperties.getPerfRecord().getXformId();
HcsPerfRecordPropsDTO props = new HcsPerfRecordPropsDTO();
// 【必填】申请编号：收款通知单号，兜底明细流水号
props.setFdApplyNo(firstNonBlank(flow.getReceiptNoticeNo(), flow.getDetailSerialNo()));
// 申请金额 / 实际金额：本次认领分摊金额
props.setFdApplyAmount(claimAmount.toPlainString());
props.setFdFactAmount(claimAmount.toPlainString());
// 【必填】履约日期：认领日期（毫秒时间戳）
props.setFdPlanDate(toMillis(planDate));
// 履约类型：收款
props.setFdPalnType(HcsSyncConstant.PERFORM_TYPE_COLLECTION);
// 履约性质：收款计划行款项性质
props.setFdProperty(stageRow.getFundNature());
// 履约计划id / 来源履约计划项ID：收款计划行合规阶段ID（HCS 只认自己的阶段ID）
props.setFdId(stageRow.getHcsStageFdId());
props.setFdPlanId(stageRow.getHcsStageFdId());
// 金蝶单据号：金蝶收款单号（A301-1 同步落库）
props.setFdJdDocNo(flow.getKingdeeBillNo());
// 【必填】合同ID：HCS 合同ID
props.setFdContractId(contractManage.getHcsFdId());
// 业务ID：TMS 收款流水ID（溯源）
props.setFdBusinessId(String.valueOf(flow.getId()));
props.setFdCreateTime(System.currentTimeMillis());
props.setFdXformId(xformId);
HcsPerfRecordFormDataDTO formData = new HcsPerfRecordFormDataDTO();
formData.setFdXformId(xformId);
formData.setDynamicProps(props);
// 机制数据（C108-1 必填）：认领附件暂不转传，传空列表
HcsMechanismsDTO mechanisms = new HcsMechanismsDTO();
mechanisms.setAttachment(List.of());
HcsPerfRecordSaveDTO param = new HcsPerfRecordSaveDTO();
param.setCurUser(HcsUserRefVO.ofLoginName(hcsProperties.getOperatorLoginName()));
param.setFormData(formData);
param.setMechanisms(mechanisms);
log.info("HCS履约流水新建开始 flowId：{}，contractNo：{}，认领金额 {}", flow.getId(), contractManage.getContractNo(), claimAmount);
HcsResult<HcsFormSaveVO> result = hcsClient.perfRecordAdd(param);
if (result == null || !result.isSuccess() || result.getData() == null || StringUtil.isBlank(result.getData().getFdId())) {
log.error("HCS履约流水新建失败响应：{}，contractNo={}", result == null ? "无响应" : String.format("msg=%s, traceId=%s", result.getMsg(), result.getTraceId()), contractManage.getContractNo());
throw new HcsException("C108-1 履约流水新建失败：" + (result == null ? "响应为空" : result.getMsg()));
}
// shortcut: 履约流水 fdId 未持久化（认领链无 C108-2 更新场景）；需推进实际金额更新时先落库
log.info("HCS履约流水新建成功 flowId：{}，contractNo：{}，perfFdId：{}",
flow.getId(), contractManage.getContractNo(), result.getData().getFdId());
}
/**
blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsPaymentSyncSupport.java
+13 -18
View File
@@ -50,7 +50,7 @@ import java.util.List;
/**
* HCS 付款链推送编排支撑组件（结算付款特批 C106-3/4 + 履约计划重推 C103-9 + 履约记录 C108-1/2 + 特批结果推送接收，设计文档 §5.0/§5.3/§5.5/§5.6）
* <p>
* 编排顺序：特批（提交时高风险/黑名单须特批附件或额度超额标记 need 时发起）→ 履约计划重推（付款审批款项金额累加行）→ 履约记录（金蝶实际付款后新建/分期推进更新）。
* 编排顺序：特批（提交时高风险/黑名单须特批附件或额度超额标记 need 时发起）→ 金蝶实际付款门禁（未付款时履约计划与履约记录均不推送）→ 履约计划重推（付款审批累加款项金额行，金蝶付款后随链重推）→ 履约记录（金蝶实际付款后新建/分期推进更新）。
* 特批通过后不推履约数据：履约计划与履约记录统一在各业务环节推送（付款=金蝶实际付款后，收款/开票/收票各自环节）。
* 特批审核期间（need/pushing/processing）仅发起/等待 C106，不推送履约计划与履约记录；驳回不产生履约数据。
* 特批流程ID 与履约记录ID 在各自 Support 内即时持久化；整体同步状态（hcs_sync_status）由本组件统一回写。
@@ -78,7 +78,7 @@ public class HcsPaymentSyncSupport {
private final ApplicationEventPublisher eventPublisher;
/**
* 推送付款申请到 HCS：特批（need 时发起 C106-3 后挂起）→ 履约计划重推（C103-9 款项金额累加行）→ 履约记录（金蝶实际付款后新建/更新）→ 回填整体同步状态
* 推送付款申请到 HCS：特批（need 时发起 C106-3 后挂起）→ 金蝶实际付款门禁（未付款时整体跳过，付款回写后重新置待同步触发推送）→ 履约计划重推（C103-9 款项金额累加行）→ 履约记录（C108-1 新建/C108-2 更新）→ 回填整体同步状态
*
* @param payment 付款申请单（approvalStatus=approved）
* @return 推送结果描述
@@ -104,8 +104,16 @@ public class HcsPaymentSyncSupport {
markSynced(payment, message);
return message;
}
// ② 履约计划重推（C103-9 行级更新）：付款审批通过累加款项金额置 row_op=update 的计划行，
// 凭已存合规阶段ID 重推；独立于履约记录开关，推送失败抛出由付款链置 failed 重试兜底
// ② 金蝶实际付款门禁：履约计划与履约记录均待金蝶实际付款后推送（需求口径：金蝶付款成功后再推给合同系统）——
// 审批通过仅本地累加计划金额置待同步，此处不重推；未付款时整体照常回写，
// 付款回写推进（applyPayApplyResult）重新置待同步后由扫描任务触发本推送
if (payment.getPaidAmount() == null || payment.getPaidAmount().signum() <= 0) {
String message = "金蝶未实际付款，待付款后推送履约计划与履约记录";
markSynced(payment, message);
return message;
}
// ③ 履约计划重推（C103-9 行级更新）：付款审批通过累加款项金额置 row_op=update 的计划行，
// 凭已存合规阶段ID 重推；推送失败抛出由付款链置 failed 重试兜底
if (hcsProperties.getExeStage().isSyncEnabled()) {
String stageResult = this.pushExeStageUpdate(payment);
if (StringUtil.isNotBlank(stageResult)) {
@@ -115,24 +123,11 @@ public class HcsPaymentSyncSupport {
result.append(stageResult);
}
}
// ③ 履约记录：金蝶实际付款后推送（需求口径：金蝶实际付款了再推给合同系统）——
// 首次回写实际付款走 C108-1 新建，分期付款推进（paidAmount 变化置待同步）走 C108-2 更新；
// 未实际付款时跳过（整体状态照常回写，付款回写时重新置待同步触发推送）
// ④ 履约记录：首次回写实际付款走 C108-1 新建，分期付款推进（paidAmount 变化置待同步）走 C108-2 更新
if (!hcsProperties.getPerfRecord().isSyncEnabled()) {
markSynced(payment, result.toString());
return result.toString();
}
if (payment.getPaidAmount() == null || payment.getPaidAmount().signum() <= 0) {
if (result.length() > 0) {
result.append("；");
}
result.append("金蝶未实际付款，待付款后推送履约记录");
markSynced(payment, result.toString());
return result.toString();
}
if (result.length() > 0) {
result.append("；");
}
result.append(hcsPerfRecordSyncSupport.pushPerfRecord(payment));
markSynced(payment, result.toString());
return result.toString();
blade-service/blade-transport/src/main/java/org/springblade/transport/task/ReceiptClaimPushTask.java
-67
View File
@@ -1,67 +0,0 @@
/**
* 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
* is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments
* from this software for their own commercial purposes.
* <p>
* Using this software signifies agreement to this license agreement and terms of use,
* and you expressly agree to be bound by the terms of use of this software.
* <p>
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* <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.IReceiptFlowService;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
/**
* 收款认领推送金蝶定时任务（A301-3 收款认领结果推送）
* <p>
* 认领动作只在本地登记，本任务扫描「认领完成且未推送过」的收款流水自动推送金蝶，
* 与收款流水页「推送金蝶」手动按钮共用同一服务方法（推送前按认领人重查 A301-2 最新公告对账）。
* 单条流水推送失败独立消化、可重试，不影响同批其他流水。
* <p>
* 调度配置（Nacos thirdParty.bfi.receiptClaimPush.*）：syncEnabled 开关、cron 表达式。
*
* @author Chill
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class ReceiptClaimPushTask {
private final IReceiptFlowService receiptFlowService;
private final BfiProperties bfiProperties;
/** 收款认领推送调度，默认每10分钟执行一次 */
@Scheduled(cron = "${thirdParty.bfi.receiptClaimPush.cron:0 4/10 * * * ?}")
public void pushClaimToKingdee() {
if (!bfiProperties.getReceiptClaimPush().isSyncEnabled()) {
return;
}
try {
String summary = receiptFlowService.pushClaimByTask();
log.info("定时推送收款认领：{}", summary);
} catch (Exception exception) {
log.error("定时推送收款认领异常", exception);
}
}
}
blade-service/blade-transport/src/main/java/org/springblade/transport/wrapper/ReceiptFlowWrapper.java
+2 -7
View File
@@ -70,15 +70,10 @@ public class ReceiptFlowWrapper extends BaseEntityWrapper<KingdeeReceiptFlow, Re
case "failed" -> "处理失败";
default -> "未推送";
});
// 剩余可认领金额 = 可认领上限 − 累计认领金额（上限取公告未认领与收款金额较小值）
BigDecimal unclaimedAmount = money(entity.getUnclaimedAmount());
// 剩余可认领金额 = 收款金额 − 累计认领金额（认领只登记本地，额度由本地累计认领控制）
BigDecimal receiptAmount = money(entity.getReceiptAmount());
BigDecimal claimCeiling = unclaimedAmount;
if (receiptAmount.compareTo(BigDecimal.ZERO) > 0 && unclaimedAmount.compareTo(BigDecimal.ZERO) > 0) {
claimCeiling = unclaimedAmount.min(receiptAmount);
}
BigDecimal claimedAmount = money(entity.getClaimedAmount());
vo.setRemainingAmount(claimCeiling.subtract(claimedAmount).max(BigDecimal.ZERO));
vo.setRemainingAmount(receiptAmount.subtract(claimedAmount).max(BigDecimal.ZERO));
vo.setCreateUserName(UserCache.getUserRealName(entity.getCreateUser()));
vo.setUpdateUserName(UserCache.getUserRealName(entity.getUpdateUser()));
return vo;
blade-third-party-api/blade-bfi-api/src/main/java/org/springblade/thirdparty/bfi/feign/IBfiClient.java
Vendored
+4 -1
View File
@@ -213,6 +213,9 @@ public interface IBfiClient {
/**
* A103-4 付款处理查询
* <p>
* 注意：开始业务日期的请求参数名以金蝶契约为准，为 {@code beigin_bizdate}（并非 begin_bizdate），
* 传错会被忽略并返回「参数【beigin_bizdate】必填」。
*
* @param accessToken 访问令牌，通过 getToken 获取
* @param pageNo 页码，从1开始
@@ -227,7 +230,7 @@ public interface IBfiClient {
BfiResultVO<BfiPageVO<BfiPayBillVO>> payBillQuery(@RequestHeader(BfiConstant.HEADER_ACCESS_TOKEN) String accessToken,
@RequestParam("pageNo") Integer pageNo,
@RequestParam("pageSize") Integer pageSize,
@RequestParam("begin_bizdate") String beginBizdate,
@RequestParam("beigin_bizdate") String beginBizdate,
@RequestParam("end_bizdate") String endBizdate,
@RequestParam(value = "billno", required = false) List<String> billno,
@RequestParam("org_number") List<String> orgNumber);
blade-third-party-api/blade-bfi-api/src/main/java/org/springblade/thirdparty/bfi/pojo/dto/BfiPayBillQueryDTO.java
Vendored
+2 -1
View File
@@ -51,7 +51,8 @@ public class BfiPayBillQueryDTO implements Serializable {
*/
private Integer pageSize;
/**
* 开始业务日期，格式：yyyy-MM-dd，限定时间范围不可超过1个月
* 开始业务日期，格式：yyyy-MM-dd，限定时间范围不可超过1个月；
* 请求参数名为 beigin_bizdate（金蝶契约拼写如此，非 begin_bizdate）
*/
private String beginBizdate;
/**
blade-third-party-api/blade-bfi-api/src/main/java/org/springblade/thirdparty/bfi/pojo/dto/BfiRecBillQueryDTO.java
Vendored
+4 -3
View File
@@ -38,7 +38,7 @@ import java.util.List;
* <p>
* 请求示例：
* <pre>{@code
* GET /ierp/kapi/v2/awrp/cas/cas_recbill/queryRecBill?begin_bizdate=2021-09-08&end_bizdate=2026-09-08&org_number=01.01.20.02.04.01&pageSize=10&pageNo=1
* GET /ierp/kapi/v2/awrp/cas/cas_recbill/queryRecBill?begin_bizdate=2021-09-08 00:00:00&end_bizdate=2026-09-08 23:59:59&org_number=01.01.20.02.04.01&pageSize=10&pageNo=1
* }</pre>
*
* @author Chill
@@ -57,12 +57,13 @@ public class BfiRecBillQueryDTO implements Serializable {
*/
private Integer pageSize;
/**
* 【必填】开始业务日期，格式：yyyy-MM-dd，限定时间范围不可超过1个月
* 【必填】开始业务日期，格式：yyyy-MM-dd HH:mm:ss，窗口天数由调用方控制；
* 传纯日期 yyyy-MM-dd 会被金蝶拒绝（bos.filterSqlBuilder 时间格式错误）
*/
@JsonProperty("begin_bizdate")
private String beginBizdate;
/**
* 【必填】结束业务日期，格式：yyyy-MM-dd
* 【必填】结束业务日期，格式：yyyy-MM-dd HH:mm:ss
*/
@JsonProperty("end_bizdate")
private String endBizdate;
blade-third-party-api/blade-bfi-api/src/main/java/org/springblade/thirdparty/bfi/service/IBfiService.java
Vendored
+1 -1
View File
@@ -287,7 +287,7 @@ public interface IBfiService {
/**
* A301-1 收款单查询（收款处理查询）
*
* @param param 查询参数，业务日期范围不可超过1个月
* @param param 查询参数，业务日期格式 yyyy-MM-dd HH:mm:ss，窗口天数由调用方控制
* @return 收款处理分页数据
*/
BfiPageVO<BfiRecBillVO> queryRecBill(BfiRecBillQueryDTO param);
blade-third-party-api/blade-bfi-api/src/main/java/org/springblade/thirdparty/bfi/util/BfiUtil.java
Vendored
+169
View File
@@ -25,15 +25,19 @@
*/
package org.springblade.thirdparty.bfi.util;
import lombok.extern.slf4j.Slf4j;
import org.springblade.core.tool.utils.DateUtil;
import org.springblade.core.tool.utils.Func;
import org.springblade.thirdparty.bfi.pojo.dto.BfiBaseDTO;
import org.springblade.thirdparty.bfi.pojo.vo.BfiPageVO;
import java.time.Duration;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.UUID;
import java.util.function.Consumer;
import java.util.function.IntFunction;
/**
@@ -44,6 +48,7 @@ import java.util.function.IntFunction;
*
* @author Chill
*/
@Slf4j
public class BfiUtil {
/**
@@ -56,6 +61,11 @@ public class BfiUtil {
*/
public static final int DEFAULT_MAX_PAGES = 50;
/**
* 按 totalCount 推导总页数时的兜底最大页数，仅防金蝶侧返回异常导致死循环
*/
public static final int DEFAULT_TOTAL_MAX_PAGES = 500;
private BfiUtil() {
}
@@ -139,4 +149,163 @@ public class BfiUtil {
}
return rows;
}
/**
* BFI 分页查询通用翻页：按首页返回的 totalCount 推导总页数，自动翻页汇总全量数据行
* <p>
* 与 {@link #queryAllPages(IntFunction)} 的区别：总页数由 totalCount 决定，固定页数仅作兜底，
* 适合业务日期窗口较长、数据量可能超过固定页数上限的查询场景；达到兜底上限或未取满 totalCount 时打印告警，避免静默截断
*
* @param pageFetcher 页码 -> 分页结果，lambda 内负责设置页码（必要时含页大小）并调用接口
* @param <T> 数据行类型
* @return 全量数据行
*/
public static <T> List<T> queryAllPagesByTotal(IntFunction<BfiPageVO<T>> pageFetcher) {
return queryAllPagesByTotal(pageFetcher, DEFAULT_TOTAL_MAX_PAGES);
}
/**
* BFI 分页查询通用翻页：按首页返回的 totalCount 推导总页数，自动翻页汇总全量数据行
* <p>
* 终止条件：返回页为空、数据行为空、lastPage=true、数据行不满一页（按返回 pageSize 判断）、取满推导出的总页数
* <p>
* totalCount 缺失或非正数时退化为 {@link #queryAllPages(IntFunction, int)} 的固定页数上限逻辑
*
* @param pageFetcher 页码 -> 分页结果，lambda 内负责设置页码（必要时含页大小）并调用接口
* @param maxPages 兜底最大页数，防止金蝶侧 totalCount/lastPage 返回异常时死循环
* @param <T> 数据行类型
* @return 全量数据行
*/
public static <T> List<T> queryAllPagesByTotal(IntFunction<BfiPageVO<T>> pageFetcher, int maxPages) {
List<T> rows = new ArrayList<>();
int totalPages = maxPages;
Integer totalCount = null;
for (int pageNo = 1; pageNo <= totalPages; pageNo++) {
BfiPageVO<T> page = pageFetcher.apply(pageNo);
if (page == null || Func.isEmpty(page.getRows())) {
return rows;
}
rows.addAll(page.getRows());
if (pageNo == 1) {
totalCount = page.getTotalCount();
totalPages = resolveTotalPages(page, maxPages);
}
if (Boolean.TRUE.equals(page.getLastPage())) {
return rows;
}
if (page.getPageSize() != null && page.getRows().size() < page.getPageSize()) {
return rows;
}
}
if (totalCount != null && rows.size() < totalCount) {
log.warn("BFI分页查询未取满，totalCount={}，已汇总 {} 条，可能存在数据截断", totalCount, rows.size());
}
return rows;
}
/**
* 按首页 totalCount 与 pageSize 推导总页数，超过兜底上限时按上限截断并告警
*
* @param page 首页分页结果
* @param maxPages 兜底最大页数
* @return 总页数
*/
private static int resolveTotalPages(BfiPageVO<?> page, int maxPages) {
Integer totalCount = page.getTotalCount();
Integer pageSize = page.getPageSize();
if (totalCount == null || totalCount <= 0 || pageSize == null || pageSize <= 0) {
return maxPages;
}
int totalPages = (totalCount + pageSize - 1) / pageSize;
if (totalPages > maxPages) {
log.warn("BFI分页查询需要 {} 页（totalCount={}），超过兜底上限 {} 页，超出部分将被截断", totalPages, totalCount, maxPages);
return maxPages;
}
return totalPages;
}
/**
* BFI 时间窗口二分切片续扫翻页，逐页回调处理，窗口数据超过单查询翻页上限时尾部不漏同步
* <p>
* 适用按时间窗口增量同步且数据量可能超过单查询翻页上限的场景
* （A801-1 票池同步按 updateTime、A301-1 收款单同步按业务日期）：
* <pre>{@code
* int sliceCount = BfiUtil.forEachWindowSlice("金蝶全票池同步", windowStart, windowEnd,
* PAGE_SIZE, MAX_PAGES,
* (sliceStart, sliceEnd, pageNo) -> {
* data.setUpdateTime(sliceStart.format(FORMATTER));
* data.setUpdateTimeEnd(sliceEnd.format(FORMATTER));
* data.setPageNo(pageNo);
* data.setPageSize(PAGE_SIZE);
* return bfiService.queryInvoicePool(param);
* },
* rows -> batchUpsert(rows));
* }</pre>
* <p>
* 单片独立翻页（最多 maxPages 页）：空页或末页不满一页即该片到底；触达页数保护说明该时间片
* 数据超过单查询窗口上限（maxPages × pageSize），从中点二分为 [start, mid] + [mid, end] 两片递归续扫，
* 总覆盖不受单查询上限约束。切片边界同刻度的数据可能在相邻两片各拉一次，pageHandler 必须幂等；
* 切片细到不足 1 秒仍满页视为远端异常，告警跳过防御死递归。
* 终止只认空页与短页，不依赖 lastPage（末页不满一页天然触发短页终止，lastPage 异常提前终止反而漏拉）
*
* @param bizName 业务名称（日志前缀）
* @param windowStart 窗口起点（含）
* @param windowEnd 窗口终点（含）
* @param pageSize 分页大小（须与 pageFetcher 内实际设置的页大小一致）
* @param maxPages 单片最大页数保护
* @param pageFetcher 时间片起止 + 页码 → 分页结果，lambda 内负责设置时间窗口与页码并调用接口
* @param pageHandler 单页数据行处理（过滤、upsert、统计等），必须幂等
* @param <T> 数据行类型
* @return 实际处理完的切片数（含空片，异常跳过的不计）
*/
public static <T> int forEachWindowSlice(String bizName, LocalDateTime windowStart, LocalDateTime windowEnd,
int pageSize, int maxPages, WindowPageFetcher<T> pageFetcher, Consumer<List<T>> pageHandler) {
// 二分收敛保护：切片区间为空说明时间粒度异常，放弃该片
if (!windowStart.isBefore(windowEnd)) {
log.error("{}切片区间为空（{} ~ {}），时间粒度异常，放弃该切片", bizName, windowStart, windowEnd);
return 0;
}
for (int pageNo = 1; pageNo <= maxPages; pageNo++) {
BfiPageVO<T> page = pageFetcher.fetch(windowStart, windowEnd, pageNo);
List<T> rows = page == null || page.getRows() == null ? List.of() : page.getRows();
if (rows.isEmpty()) {
return 1;
}
pageHandler.accept(rows);
// 短页：该片到底，正常终止（不依赖 lastPage，末页不满一页天然触发）
if (rows.size() < pageSize) {
return 1;
}
}
// 触顶：该时间片数据超过单查询窗口上限，从中点二分续扫（边界同刻度数据由 pageHandler 幂等兜底）
LocalDateTime mid = windowStart.plus(Duration.between(windowStart, windowEnd).dividedBy(2));
if (!mid.isAfter(windowStart)) {
log.error("{}切片 {} ~ {} 已达最小粒度仍满页（>{} 条），该时间片数据异常，跳过",
bizName, windowStart, windowEnd, (long) maxPages * pageSize);
return 0;
}
log.warn("{}切片 {} ~ {} 触达单片翻页保护 {} 页（>{} 条），二分续扫 [{} ~ {}] + [{} ~ {}]",
bizName, windowStart, windowEnd, maxPages, (long) maxPages * pageSize, windowStart, mid, mid, windowEnd);
return forEachWindowSlice(bizName, windowStart, mid, pageSize, maxPages, pageFetcher, pageHandler)
+ forEachWindowSlice(bizName, mid, windowEnd, pageSize, maxPages, pageFetcher, pageHandler);
}
/**
* 时间窗口切片翻页取数函数：按切片起止时间 + 页码拉取一页数据
*
* @param <T> 数据行类型
*/
@FunctionalInterface
public interface WindowPageFetcher<T> {
/**
* 拉取单个时间片的一页数据
*
* @param sliceStart 切片起点（含）
* @param sliceEnd 切片终点（含）
* @param pageNo 页码，从 1 开始
* @return 分页结果
*/
BfiPageVO<T> fetch(LocalDateTime sliceStart, LocalDateTime sliceEnd, int pageNo);
}
}
blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/dto/HcsClaimRecordAddDTO.java
+4
View File
@@ -47,6 +47,10 @@ import java.math.BigDecimal;
public class HcsClaimRecordAddDTO implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
/**
* 认领记录ID（C107-1 新增不传，C107-3 修改时必填，作废传 fdStatus=1）
*/
private String fdId;
/**
* 收款流水（fdId 必填，为合规系统流水ID）
*/
blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/feign/IHcsClient.java
+10
View File
@@ -108,6 +108,7 @@ public interface IHcsClient {
String INVOICE_REG_ADD_URL = "${thirdParty.hcs.invoiceRegAddUrl:/openapi/eop-data/eopDataInvoiceRegistrationOpen/add}";
String INVOICE_REG_UPDATE_URL = "${thirdParty.hcs.invoiceRegUpdateUrl:/openapi/eop-data/eopDataInvoiceRegistrationOpen/update}";
String CLAIM_RECORD_ADD_URL = "${thirdParty.hcs.claimRecordAddUrl:/openapi/eop-data/eopDataCollectionFlowClaimRecordOpen/add}";
String CLAIM_RECORD_UPDATE_URL = "${thirdParty.hcs.claimRecordUpdateUrl:/openapi/eop-data/eopDataCollectionFlowClaimRecordOpen/update}";
String COLLECTION_FLOW_LIST_URL = "${thirdParty.hcs.collectionFlowListUrl:/openapi/eop-data/eopDataCollectionFlowOpen/list}";
/**
@@ -341,6 +342,15 @@ public interface IHcsClient {
@PostMapping(CLAIM_RECORD_ADD_URL)
HcsResult<HcsIdVO> claimRecordAdd(@RequestBody HcsClaimRecordAddDTO param);
/**
* C107-3 修改认领记录（fdId 必填；作废认领传 fdStatus=1）
*
* @param param 请求参数（入参同新增，仅 fdId 必填）
* @return 修改认领记录 fdId
*/
@PostMapping(CLAIM_RECORD_UPDATE_URL)
HcsResult<HcsIdVO> claimRecordUpdate(@RequestBody HcsClaimRecordAddDTO param);
/**
* C104-2 查询收款流水列表（认领记录推送前按明细流水号定位合规侧收款流水ID）
*
doc/docs/hcs合同/2026-10-29-履约计划与履约记录四场景业务说明（业务人员版）.md
+289
View File
@@ -0,0 +1,289 @@
# 履约计划与履约记录业务说明（付款 / 开票 / 收票 / 收款）
> 适用对象：合同、结算、付款、开票、收票相关业务人员
> 更新日期：2026-10-29
> 用途：说明 TMS 与合同合规系统之间「履约计划」「履约记录」是怎么产生、什么时候产生、先后顺序和注意事项。
---
## 一、先看懂三个概念
| 概念 | 通俗理解 | 举例 |
| --- | --- | --- |
| **合同** | 业务发生的前提 | 与承运商签的运输合同、与客户签的运输服务合同 |
| **履约计划** | 合同约定的**收付款计划台账**（打算收/付多少钱、什么时候收/付） | 合同约定进度款 100 万，分几次结算 |
| **履约记录** | 计划实际执行的**流水**（真正付了、收了、开了票、收了票） | 本次实际付款 30 万、本次认领收款 20 万 |
一句话记住：**计划是“打算”，记录是“实际发生”**。先有计划，才有记录；记录必须挂在某一条计划下面。
---
## 二、总体流程
```
合同审批通过
↓
生成 / 确认履约计划（付款计划、收款计划）
↓
合同与计划推送到合规系统（合规侧生成对应的计划编号）
↓
业务实际发生：付款 / 收款 / 开票 / 收票
↓
系统自动生成履约记录，回传合规系统
```
关键顺序：
1. **合同先推合规**；
2. **履约计划再推合规**；
3. **计划推送成功后，履约记录才能生成**。
如果合同还没推合规，或者计划还没推成功，记录会暂时生成不了，等前面的步骤完成后自动补上（收款场景除外，见第六节）。
---
## 三、履约计划是怎么来的
### 3.1 计划从哪来
| 来源 | 说明 |
| --- | --- |
| 合同里维护「履约规则」 | 业务人员在合同页签里填写付款/收款计划行 |
| 合同审批通过自动生成 | 合同没有维护计划行时，系统自动补一条默认计划：承运商合同生成付款计划，客户合同生成收款计划 |
| 业务发生自动累加 | 付款审批通过、收款认领后，计划金额自动累加 |
### 3.2 计划金额什么时候变
| 业务动作 | 计划金额变化 |
| --- | --- |
| 付款申请**审批通过** | 对应付款计划的金额 += 本次申请金额（本地记账，**金蝶实际付款后**才同步到合规） |
| 收款流水**认领完成** | 对应收款计划的金额 += 本次认领分摊金额 |
请注意：
- 计划金额是**“已批准 / 已认领”的口径**，不是实际到账/实付口径；
- 实际付了多少、收了多少，看履约记录；
- 付款计划只在款项性质一致时累加（预付款不会加到进度款计划上）；
- 同一合同多次付款、多次认领，计划金额会持续累加。
### 3.3 计划的修改
- 合同审批通过后，已推送成功的计划行再修改，系统会自动重新推送合规；
- 删除已推送的计划行，会在合规侧同步删除（不能直接物理删除）；
- 新增的计划行随下一次推送一起补到合规。
---
## 四、四个场景的履约记录
### 4.1 付款履约记录
**什么时候产生：金蝶实际付款之后。**
业务过程：
```
付款申请审批通过
→ 本地累加计划金额（暂不同步合规），不产生履约付款记录
→ 推送金蝶付款申请
金蝶完成实际付款
→ 系统回写实付金额
→ 计划金额同步到合规 + 生成履约付款记录
```
业务要点：
| 项目 | 说明 |
| --- | --- |
| 生成条数 | 一张付款申请对应一条；**分次付款不新增，只更新同一条的实际金额** |
| 金额 | 申请金额 + 实际付款金额 |
| 日期 | 付款申请日期 |
| 附件 | 付款场景会把付款附件一并传到合规 |
| 特批 | 需要特批的付款，特批通过后也不会立刻生成记录，仍要等金蝶实际付款 |
> 常见误区：付款审批通过后就去合规找履约付款记录——此时还没有，属于正常现象，金蝶付款后才会出现（付款计划金额的累加同样是金蝶实际付款后才同步到合规）。
---
### 4.2 收款履约记录
**什么时候产生：收款流水认领完成之后。**
业务过程：
```
收款流水到账并同步到 TMS
→ 业务人员做认领（分摊到应收结算单）
→ 认领提交后，系统自动：
① 更新该合同的收款计划金额
② 推送认领记录到合规
③ 生成收款履约记录
```
业务要点：
| 项目 | 说明 |
| --- | --- |
| 生成条数 | 每完成一次认领，按涉及的合同各生成一条 |
| 金额 | **本次认领分摊到该合同的金额**（不是合同累计认领金额） |
| 日期 | 认领日期 |
| 作废 | 认领作废只会在合规侧把认领记录置为作废，**不会冲回计划金额，也不会冲回已生成的履约记录** |
> 注意：收款链路的推送失败**不会自动重试**，如合规侧没有数据，请联系系统管理员排查。
---
### 4.3 开票履约记录
**什么时候产生：金蝶开票完成、发票回到 TMS 之后。**
业务过程：
```
开票申请审批通过
→ 推送金蝶开票
→ 推送合规开票登记（此时还没有发票日期）
金蝶完成开票
→ 系统回写发票信息（每张发票一条）
→ 按每张发票生成履约开票记录
```
业务要点：
| 项目 | 说明 |
| --- | --- |
| 生成条数 | **每张发票一条**；一张开票申请开多张发票，就会生成多条 |
| 金额 | 发票价税合计 |
| 日期 | 发票的开票日期 |
| 标题 | `开票履约-发票号`，可在合规侧按此检索 |
| 失败处理 | 合同或计划条件不满足时暂不生成，系统自动重试，条件满足后补上 |
---
### 4.4 收票履约记录
**什么时候产生：收票单成功推送合规之后。**
业务过程：
```
收票登记审批通过
→ 推送金蝶收票单
→ 推送合规收票单（C109）
→ 推送成功后，按收票单里的每条结算信息生成履约收票记录
```
业务要点：
| 项目 | 说明 |
| --- | --- |
| 生成条数 | **每条结算信息（分摊行）一条**；一张收票单分摊到多张结算单就会生成多条 |
| 金额 | 分摊到该结算单的收票金额 |
| 日期 | 收票单的发票日期 |
| 标题 | `收票履约-发票号-结算单号` |
| 失败处理 | 收票单还没成功推合规时暂不生成，等收票单推送成功后自动补上 |
---
### 4.5 四场景速查
| 场景 | 什么时候出现 | 生成条数 | 金额口径 | 日期口径 |
| --- | --- | --- | --- | --- |
| 付款 | 金蝶实际付款后 | 一张付款申请一条（分期更新同一条） | 申请金额 / 实付金额 | 申请日期 |
| 收款 | 认领提交后 | 每次认领 × 每个合同一条 | 本次认领分摊金额 | 认领日期 |
| 开票 | 金蝶开票完成后 | 每张发票一条 | 发票价税合计 | 发票开票日期 |
| 收票 | 收票单推合规成功后 | 每条结算分摊行一条 | 分摊收票金额 | 发票日期 |
---
## 五、合规侧怎么核对
在合规系统履约记录列表中，按标题前缀检索最快：
| 场景 | 标题前缀 |
| --- | --- |
| 付款 | `付款履约-` |
| 收款 | `收款履约-` |
| 开票 | `开票履约-` |
| 收票 | `收票履约-` |
核对时重点看四项：**合同是否正确、金额是否正确、日期口径是否符合上表、条数是否与业务动作匹配**。
---
## 六、异常与重试
| 场景 | 推送失败后是否自动重试 | 业务需要做什么 |
| --- | --- | --- |
| 付款 | 是，系统定时自动重试 | 一般无需处理；长期失败联系管理员 |
| 开票 | 是，系统定时自动重试 | 确认金蝶是否已开票完成；长期失败联系管理员 |
| 收票 | 是，系统定时自动重试 | 先确认收票单是否已成功推送合规 |
| 收款 | **否** | 联系系统管理员手动排查处理 |
常见“暂时生成不了”的原因：
1. 合同还没推送合规；
2. 履约计划还没推送成功（没有可关联的计划）；
3. 对应单据还没审批通过；
4. 收票单还没成功推送合规；
5. 金蝶还没实际付款 / 还没完成开票。
前四类在条件满足后会自动补推，不需要重复操作单据。
---
## 七、作废、驳回与变更
| 业务动作 | 对合规履约数据的影响 |
| --- | --- |
| 付款审批驳回 | 不产生履约付款记录 |
| 付款需要特批 | 特批期间不产生履约数据；特批通过后也要等金蝶实际付款 |
| 付款申请作废 | 当前**不会冲回**已累加的计划金额，也不会冲回履约付款记录 |
| 收款认领作废 | 合规侧认领记录作废；**计划金额与收款履约记录不冲回** |
| 合同变更审批通过 | 计划行随变更重新推送合规，已生成的履约记录不受影响 |
> 如业务上需要“作废后金额必须回退”，请单独提需求或在合规侧人工调整，不能依赖当前自动链路。
---
## 八、常见问题（FAQ）
**1. 合同刚审批通过，合规为什么没有履约记录？**
正常。此时只有履约计划，记录要等业务实际发生（付款、收款、开票、收票）后才生成。
**2. 付款已经审批通过了，合规为什么没有付款履约记录？**
正常。付款履约记录以**金蝶实际付款**为准，审批通过只更新计划金额。
**3. 同一笔付款分两次支付，合规会出现两条记录吗？**
不会。一张付款申请对应一条记录，第二次付款更新实际金额。
**4. 同一笔收款分多次认领，合规会出现几条？**
每次认领都会生成一条（按涉及合同分别生成），金额为本次分摊金额。
**5. 一张开票申请开了多张发票，合规有几条？**
每张发票一条。
**6. 收票单有多条结算信息，合规有几条？**
每条结算信息一条。
**7. 合规侧一条记录都没有，先查什么？**
按顺序确认：合同是否已推合规 → 履约计划是否已推成功 → 单据是否已审批通过 →（开票）金蝶是否已开票完成 →（收票）收票单是否已推合规。收款链路不会自动重试，需联系管理员。
**8. 计划金额和履约记录金额为什么对不上？**
两者口径不同：计划金额是“已批准/已认领”的累计口径，履约记录是“本次实际发生”的口径。付款场景下，计划看申请金额，记录看实付金额。
**9. 作废后合规金额为什么没变？**
当前作废不回冲计划金额和履约记录，需要在合规侧人工处理或单独提需求。
---
## 附录：业务名称与合规接口对照（供对接同学参考）
| 业务名称 | 合规接口 |
| --- | --- |
| 合同推送 | C103-1 / C103-11 |
| 履约计划推送 | C103-9 |
| 付款履约记录 新建 / 更新 | C108-1 / C108-2 |
| 收款认领记录 新增 / 作废 | C107-1 / C107-3 |
| 开票登记 | C111 |
| 收票单推送 | C109 |
doc/docs/hcs合同/2026-10-29-履约计划与履约记录四场景实现逻辑（付款-开票-收票-收款）.md
+317
View File
@@ -0,0 +1,317 @@
# 履约计划与履约记录四场景实现逻辑（付款 / 开票 / 收票 / 收款）
> 日期：2026-10-29
> 范围：`tms-api` blade-transport 中 TMS ↔ 合同合规系统（HCS）的「履约计划」（C103-9）与「履约记录」（C108-1/2）。
> 目标：只讲清**逻辑、流程、先后顺序**，不展开代码细节。
---
## 0. 总览
一句话：**履约计划是合同资金的“计划行”，履约记录是这些计划行的“实际发生流水”**。计划先行（先拿到 HCS 阶段ID），记录才能引用它；四个业务场景（付款/收款/开票/收票）各自在“业务真正发生”的时点产生一条或多条履约记录。
### 0.1 全景顺序
```
合同审批通过
└─ 建默认履约计划行 → 推合同 C103-1（拿合同 hcs_fd_id）
└─ 推履约计划 C103-9（拿计划 hcs_exeplan_id + 每行 hcs_stage_fd_id）
├─ 付款：审批通过 → 计划金额本地累加（不推合规） → 金蝶实际付款 → C103-9 重推 + C108-1/C108-2
├─ 收款：认领提交 → 计划金额累加 → C107-1 → C108-1
├─ 开票：金蝶开票完成、发票落库 → C111 登记 → 每张发票 C108-1
└─ 收票：收票单推合规 C109 成功 → 每条结算分摊行 C108-1
```
### 0.2 四条链的关键先后关系
| 场景 | 前一条链必须先完成 | 履约记录产生时点 | 记录粒度 |
| --- | --- | --- | --- |
| 付款 | C103-1 拿到 `hcs_fd_id`；C103-9 计划行拿到 `hcs_stage_fd_id` | **金蝶实际付款后**（`paidAmount>0` 且金额推进） | 付款申请单（1 张单 1 条，分期走更新） |
| 收款 | 同上，且收款计划行已同步 | **认领事务提交后** | 认领主单 × 合同（每次认领各 1 条） |
| 开票 | 合同/收款计划行已同步；金蝶 A303-5 发票已落库 | **金蝶开票完成后** | 每张发票 1 条 |
| 收票 | 合同/付款计划行已同步；**C109 收票单已推合规成功** | **C109 推送成功后** | 每条结算分摊行 1 条 |
---
## 1. 两个对象与 ID 链
| 对象 | TMS 落点 | HCS 接口 | 作用 |
| --- | --- | --- | --- |
| 履约计划行 | `blade_contract_exe_stage`（`HcsContractExeStage`） | C103-9 行级 add/update/delete | 合同维度的付款/收款资金计划 |
| 履约记录 | 各业务表上的 `hcs_perf_fd_id` | C108-1 新建 / C108-2 更新 | 计划的实际执行流水 |
必须持久化的 ID 链（后面所有推送都依赖它）：
```
blade_contract_manage.hcs_fd_id 合规合同ID（C103-1）
blade_contract_manage.hcs_exeplan_id 合规履约计划ID（C103-9）
blade_contract_exe_stage.hcs_stage_fd_id 合规阶段ID（C103-9 按行回填，= C108 的 fd_plan_id）
blade_payment_application.hcs_perf_fd_id 付款履约记录ID（C108-1 返回）
blade_invoice_application_invoice.hcs_perf_fd_id 开票履约记录ID
blade_invoice_receipt_settlement.hcs_perf_fd_id 收票履约记录ID
blade_receipt_claim_hcs_record.hcs_claim_record_fd_id C107-1 认领记录ID（供 C107-3 作废）
```
`fd_plan_id` 在 C108 接口中**必填**，只能取 HCS 自己返回的 `hcs_stage_fd_id`。因此没有已同步计划行时，履约记录一律推不出去，只能失败重试，等合同链把计划补推成功后自愈。
---
## 2. 履约计划（C103-9）
### 2.1 计划行从哪来
| 入口 | 行为 |
| --- | --- |
| 合同表单「履约规则」页签维护（`ContractExeStageServiceImpl#submitRows/removeRow`） | 新行 → `row_op=add`；已同步行编辑 → `update`；已同步行删除 → 软删 + `delete` 标记（不能物理删，delete 要凭阶段ID 上报） |
| 合同审批通过（`createDefaultRowOnApprove`） | 无任何计划行时自动建默认行：承运商合同=付款/进度款，客户合同=收款/进度款；同时把该合同所有未拿到阶段ID 的行统一置 `add` |
| 付款审批通过（`accumulatePaidAmountOnApprove`） | 按付款类型映射款项性质（正式结算=进度款，其余=预付款），对**精确匹配**该款项性质的已同步付款行，原子累加 `fund_amount += 申请金额`，并置 `update + unsynced` |
| 收款认领（`accumulateClaimedAmountOnPush`） | 取收款/进度款计划行（无进度款则兜底首条已同步收款行），累加本次分摊到该合同的认领金额，置 `update + unsynced` |
要点：
- 金额累加只发生在“审批通过/认领提交”，**不是**在实际收付款时；因此计划金额反映的是“已批准/已认领的计划口径”，履约记录才反映实际发生额。
- 付款累加严格要求款项性质一致，匹配不到就跳过，避免预付款计进进度款；收款累加允许兜底行。
- 已同步行靠 `hcs_stage_fd_id` 重推；未同步行保持 `add`，随合同链首推（首次推送即携带累加后的金额）。
### 2.2 同步逻辑（`HcsExeStageSyncSupport#syncExeStages`）
1. 前置：合同必须有 `hcs_fd_id`。
2. 取该合同所有 `row_op <> 'none'` 的行；删除行已软删，用原生 SQL 绕过逻辑删除才能取到。
3. 整体操作类型：`hcs_exeplan_id` 为空 → `add`（首次），否则 `update`。
4. 行级：`add` 行带 `fdUniqueId=TMS行ID`（重试稳定）；`update/delete` 行必须带 `fdId=hcs_stage_fd_id`。
5. 响应回填：回填 `hcs_exeplan_id`、逐行回填 `hcs_stage_fd_id`，清 `row_op`、置 `synced`；`add` 行没匹配到阶段ID → 置 `failed`，下轮重试。
### 2.3 三个触发入口（谁调 C103-9）
| 入口 | 位置 | 门禁 | 说明 |
| --- | --- | --- | --- |
| 合同链 | `HcsContractSyncSupport#pushContract` 第⑤步 | `exe-stage.sync-enabled` | 合同起草/更新成功后、特批挂起前同步计划 |
| 付款链 | `HcsPaymentSyncSupport#pushPayment` 第③步 | `exe-stage.sync-enabled` | **金蝶实际付款门禁通过后**重推计划（审批通过仅本地累加金额不推送），再推履约记录 |
| 收款链 | `HcsClaimSyncSupport#pushOneContract` 第①步 | `exe-stage.sync-enabled` | 先累加并重推计划，再推 C107-1/C108-1 |
> 合同还没推合规时，计划行只做本地标记/累加，不报错，等合同链首推时一并带上。
---
## 3. 履约记录（C108）
### 3.1 公共前置与公共字段
所有场景的 C108-1 都要求：
- 合同已推合规（`hcs_fd_id` 非空）；
- 存在已同步计划行（`hcs_stage_fd_id` 非空）：付款/收票取**付款**计划行，收款/开票取**收款**计划行；
- `perf-record.sync-enabled` 开启；
- `fd_plan_id`/`fd_id` = 计划行 `hcs_stage_fd_id`，`fd_property` = 计划行款项性质。
四个场景的差异主要在：**触发时点、粒度、金额、履约日期、类型、幂等键**。
### 3.2 付款（`HcsPaymentSyncSupport` + `HcsPerfRecordSyncSupport`）
```
付款申请审批通过
→ hcs_sync_status=unsynced；计划金额本地累加（row_op=update，不推合规）
→ 即时推送/扫描：paidAmount=0 → 履约计划与履约记录均不推送
（提示“金蝶未实际付款”），整体仍置 synced
金蝶实际付款 → A103-2 回写（applyPayApplyResult）
→ paidAmount 首次>0 或金额变化 → hcs_sync_status=unsynced
→ 扫描付款任务：先 C103-9 重推累加金额的计划行
无 hcs_perf_fd_id → C108-1 新建，返回 fdId 立即落库
有 hcs_perf_fd_id → C108-2 更新（分期付款推进实际金额）
```
- 金额：申请金额=`appliedAmount`，实际金额=`paidAmount`。
- 日期：申请日期（`applyDate`）。
- 类型：`付款`。
- 幂等：单据粒度，`hcs_perf_fd_id` 决定新建还是更新；金额不变不会重复触发。
- 附件：仅付款场景保留附件转传（C103-2 → `fd_plan_att`），其余场景传空列表。
- 特批：`need` 发起 C106-3 后挂起；特批通过后**不补推任何履约数据**，只恢复审批并补推金蝶；驳回不产生履约数据。
### 3.3 收款（`HcsClaimSyncSupport`）
```
认领登记（只登记本地，不推金蝶）
→ 事务提交后 afterCommit → pushClaimToHcs(claimId)
① 按“本次分摊到该合同”的金额累加收款计划行 → C103-9 重推
② C107-1 认领记录（认领主单 × 合同一条，金额=本次分摊额）
③ C108-1 履约流水（同一粒度：认领主单 × 合同一条）
```
- 触发点：**认领事务提交后**，不是金蝶回调。
- 前置：`exe-stage.sync-enabled` 为整条链总门禁；C108-1 另受 `perf-record.sync-enabled` 门禁。
- 定位合规流水：C104-2 按明细流水号查出合规收款流水ID；查不到只跳过 C107-1，不影响计划更新。
- 金额：本次认领分摊到该合同的金额（申请金额=实际金额）。
- 日期：认领日期（当前代码 `claim.claimDate`）。
- 类型：当前代码传的是 `collection`（见第 6 节差异说明）。
- 幂等/重试：事件驱动、**无定时重试**；C108-1 返回的 fdId 未落库（无 C108-2 场景），失败只记日志。
- 作废：只推 C107-3 把 C107-1 记录置为已作废；**不回冲计划金额、不回冲履约记录**。
### 3.4 开票（`HcsInvoicePerfSyncSupport`）
```
开票申请审批通过 → 推金蝶 A303-1 → 推合规 C111 开票登记（票据日期为空）
金蝶开票完成 → A303-5 回写：发票逐张落库；申请单置 invoiced + hcs_sync_status=unsynced
扫描开票任务（同一轮）：
① C111 推送/回填票据日期
② 履约开票记录：扫描 hcs_perf_fd_id 为空且未超重试上限的发票
申请单须审批通过
合同回溯：开票申请 → 应收结算关联 → 正式结算单 → 合同
每张发票一条 C108-1
```
- 金额：发票价税合计 `invoiceAmount`。
- 日期：发票完成开票日期 `invoiceDate`。
- 类型：`开票`。
- 申请编号：发票号；标题：`开票履约-{发票号}`。
- 幂等：发票粒度，`hcs_perf_fd_id` 非空即跳过；失败 `retry+1` + 原因，下轮补偿，超上限人工处理。
- 合同回溯不到、无已同步收款计划行 → 记失败原因，等条件满足后自愈。
### 3.5 收票（`HcsReceiptPerfSyncSupport`）
```
收票单审批通过 → 推金蝶收票单（A303-2 + A302-6）
扫描收票任务（同一轮）：
① C109 收票单推送合规 → 成功置 hcs_sync_status=synced
② 履约收票记录：扫描 hcs_perf_fd_id 为空且未超重试上限的分摊行
所属收票单须审批通过且 hcs_sync_status=synced（C109 必须先成功）
合同回溯：分摊行 → 正式结算单 → 合同
每条结算分摊行一条 C108-1
```
- 金额：分摊收票金额 `allocatedInvoiceAmount`，为空兜底结算金额。
- 日期：收票单发票日期 `invoiceDate`。
- 类型：`收票`；关联**付款**计划行。
- 申请编号：`{发票号}-{结算单号}`；标题：`收票履约-{申请编号}`。
- 幂等：分摊行粒度，`hcs_perf_fd_id` 非空跳过；C109 未成功时记“尚未推送合规”，成功后下轮自动补偿。
### 3.6 四场景对照
| 维度 | 付款 | 收款 | 开票 | 收票 |
| --- | --- | --- | --- | --- |
| 触发时点 | 金蝶实际付款回写后 | 认领事务提交后 | 金蝶开票完成、发票落库后 | C109 推送成功后 |
| 粒度 | 付款申请单 | 认领主单 × 合同 | 每张发票 | 每条结算分摊行 |
| 申请金额 | 申请金额 | 本次分摊金额 | 发票价税合计 | 分摊收票金额 |
| 实际金额 | 实付金额 | 同申请金额 | 同申请金额 | 同申请金额 |
| 履约日期 | 申请日期 | 认领日期 | 发票开票日期 | 发票日期 |
| 类型 | 付款 | collection（现状） | 开票 | 收票 |
| 计划行 | 付款（按款项性质） | 收款（进度款优先） | 收款（进度款优先） | 付款（进度款优先） |
| 幂等键 | `hcs_perf_fd_id`（可更新） | 无（每次认领新建） | `hcs_perf_fd_id` | `hcs_perf_fd_id` |
| 失败重试 | 定时扫描 | 无 | 定时扫描 | 定时扫描 |
| 更新接口 | C108-2 支持 | 不支持 | 不支持 | 不支持 |
---
## 4. 端到端时序（先后顺序）
### 4.1 计划必须先于记录
```mermaid
sequenceDiagram
participant C as 合同
participant H as HCS
participant B as 业务单据(付款/认领/发票/收票)
C->>H: C103-1 合同起草
H-->>C: hcs_fd_id
C->>H: C103-9 履约计划（add）
H-->>C: hcs_exeplan_id + 每行 hcs_stage_fd_id
Note over C,H: 阶段ID 落库后，下面四条链才有 fd_plan_id
B->>H: C108-1 履约记录（fd_plan_id=阶段ID）
```
### 4.2 付款链
```mermaid
sequenceDiagram
participant P as 付款申请
participant H as HCS
participant K as 金蝶
P->>P: 审批通过：计划金额+=申请金额
P->>H: C103-9 重推计划
P->>P: paidAmount=0，跳过 C108
K-->>P: 实际付款回写（paidAmount 变化）
P->>H: C108-1（首次）/ C108-2（分期）
```
### 4.3 收款链
```mermaid
sequenceDiagram
participant U as 认领
participant H as HCS
U->>U: 认领登记（本地）
U->>H: ① C103-9 累加收款计划并重推
U->>H: ② C104-2 定位合规流水 → C107-1 认领记录
U->>H: ③ C108-1 履约流水（本次分摊金额）
```
### 4.4 开票 / 收票（任务内顺序）
```
开票任务：C111 开票登记 → 发票逐张 C108-1（同一轮）
收票任务：C109 收票单 → 分摊行逐条 C108-1（同一轮，C109 必须先成功）
```
---
## 5. 定时任务与开关
| 任务 | 默认 cron | 内容 |
| --- | --- | --- |
| contract | `0 1/5 * * * ?` | C103-1/C103-11 → C103-9 |
| payment | `0 2/5 * * * ?` | C106 特批 →（金蝶实际付款后）C103-9 → C108-1/2 |
| invoice-application | `0 3/5 * * * ?` | C111 → 履约开票 C108-1 |
| invoice-receipt | `0 4/5 * * * ?` | C109 → 履约收票 C108-1 |
| 收款 | 无独立任务 | 认领事务提交后事件驱动 |
| 配置（`thirdParty.hcs.*`） | 作用 | 默认 |
| --- | --- | --- |
| `exe-stage.sync-enabled` | C103-9 总开关；同时门禁整条收款链 | true |
| `perf-record.sync-enabled` | 四场景履约记录总开关 | false |
| `perf-record.xform-id` | C108 表单模板ID | 空 |
| `push.payment/invoice-application/invoice-receipt.sync-enabled` | 各任务开关 | false |
| `push.max-retry` / `push.batch-size` | 重试上限 / 单轮批量 | 5 / 配置值 |
| `attachment.transfer-enabled` | 付款履约记录附件转传 | true |
手动入口：`POST /hcs/sync/{bizType}` 批量扫描一轮（开票/收票为组合动作，含履约记录）；`POST /hcs/sync/{bizType}/{id}` 单条重推（仅主单据，不覆盖发票/分摊行粒度）。
---
## 6. 当前实现与设计文档的差异（重要）
以下为代码实际情况，与《2026-10-27 履约计划与履约记录逻辑与流程梳理》《2026-10-28 C108 履约记录四场景推送改造流程梳理》存在出入，落地时以本节为准：
| 点 | 设计文档口径 | 当前代码 |
| --- | --- | --- |
| 收款触发 | 金蝶认领推送 A301-3 成功后 | **认领事务提交后**（认领只登记本地，不推金蝶） |
| 收款履约日期 | 收款流水交易日期 `transaction_time` | **认领日期 `claimDate`**（提交 `4a76e65b` 回退了该调整） |
| 收款履约类型 | 中文「收款」 | **`collection`**（`PERFORM_TYPE_COLLECTION`，未使用 `PERF_TYPE_COLLECTION`） |
| 收款金额 | 该合同累计认领金额 | **本次认领分摊到该合同的金额** |
| 收款组装 | 复用 `HcsPerfRecordAddSupport` | **仍为 `HcsClaimSyncSupport` 内部独立组装** |
| 付款链 C103-9 门禁 | 不受 `exe-stage` 开关限制 | **受 `exe-stage.sync-enabled` 控制** |
| 收款链 fdId | 需落库以支持后续更新 | **未落库**（无 C108-2 场景） |
| 付款作废 / 认领作废 | — | 均不回冲计划金额与履约记录（认领仅 C107-3 作废） |
建议：若确认收款需按「交易日期 + 中文类型 + 通用组件」口径，应把 `HcsClaimSyncSupport#pushPerfRecord` 切到 `HcsPerfRecordAddSupport`，并同步修正日期与类型常量；否则应同步更新设计文档，避免联调口径不一致。
---
## 7. 代码索引
| 职责 | 类 / 方法 |
| --- | --- |
| 计划行维护、差异标记、金额累加、默认行 | `ContractExeStageServiceImpl`：`submitRows` / `removeRow` / `accumulatePaidAmountOnApprove` / `accumulateClaimedAmountOnPush` / `createDefaultRowOnApprove` / `findPaymentStageRow` / `findCollectionStageRow` |
| C103-9 同步与回填 | `HcsExeStageSyncSupport#syncExeStages` |
| 付款链编排 | `HcsPaymentSyncSupport#pushPayment` |
| 付款履约记录 C108-1/2 | `HcsPerfRecordSyncSupport#pushPerfRecord` |
| 收款链编排 | `HcsClaimSyncSupport#pushClaimToHcs` / `#pushOneContract` / `#pushPerfRecord` / `#voidClaimToHcs` |
| C108-1 通用组件（开票/收票共用） | `HcsPerfRecordAddSupport#pushPerfRecordAdd` |
| 开票履约记录 | `HcsInvoicePerfSyncSupport#pushUnsyncedInvoicePerfRecords` |
| 收票履约记录 | `HcsReceiptPerfSyncSupport#pushUnsyncedReceiptPerfRecords` |
| 定时任务编排 | `HcsPushTask`：`pushHcsPayment` / `syncHcsInvoiceApplications` / `syncHcsInvoiceReceipts` |
| 审批即时推送 | `HcsImmediatePushSupport#pushPaymentAndWait / pushPaymentAfterCommit` |
| 金蝶实付回写触发 | `PaymentApplicationServiceImpl#applyPayApplyResult` |
| 认领事务提交触发 | `ReceiptFlowServiceImpl`（`afterCommit` → `pushClaimToHcs`） |
| 常量与映射 | `HcsSyncConstant`（`PERF_TYPE_*`、`PERFORM_TYPE_*`、`FUND_NATURE_*`、`fundNatureOfPayment`） |
doc/docs/业务流程/2026-10-16-收款流水多次认领与作废口径梳理.md
+11 -6
View File
@@ -2,6 +2,11 @@
> 日期：2026-10-16
> 范围：`tms-api` blade-transport 收款流水认领、认领记录模块；`tms-erp-web` 认领记录页面
>
> **口径变更提示（2026-10-29）**：文中"公告未认领金额 `unclaimed_amount` / A301-2 口径"已废止，见
> [2026-10-29-收款流水菜单改造](./2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）.md)。
> 现认领上限为**收款金额 `receipt_amount`（A301-1 `actrecamt`）**，`remaining_amount = max(收款金额 − 累计认领金额, 0)`；
> 金蝶未匹配金额 `unmatch_amount_rec` 仅作参考展示，不参与额度控制。认领/作废/多次认领的其余口径不变。
---
@@ -45,10 +50,10 @@ blade_kingdee_receipt_flow（收款流水 / 认领通知单，1）
1. 锁定流水（通知单）与所选结算单。
2. 校验两条累计上限：
- 每张结算单：已有累计认领 + 本次分摊 ≤ 结算总应收含税金额；
- 流水：已有累计认领（`flowClaimedAmount`，只算未作废记录）+ 本次总额 ≤ 公告未认领金额（`unclaimed_amount`，A301-2 口径）。
- 流水：已有累计认领（`flowClaimedAmount`，只算未作废记录）+ 本次总额 ≤ 收款金额（`receipt_amount`，A301-1 口径；2026-10-29 前为公告未认领金额）。
3. **插入一条** `ReceiptClaim` 主单：`claim_amount` = 本次分摊总额，`claim_status = claimed`。
4. 按所选结算单逐张**插入 N 条** `ReceiptClaimSettlement` 分摊明细。
5. 累加流水 `claimed_amount`，按累计值重算流水状态（< 未认领金额 → partial，= → claimed）。
5. 累加流水 `claimed_amount`，按累计值重算流水状态（< 收款金额 → partial，≥ 收款金额 → claimed）。
6. 只登记本地，不推送金蝶；推送由定时任务/手动按钮触发。
所以：**同一通知单第二次认领是再插一条新主单**，不存在"找已有主单合并金额"的逻辑；校验全部按"未作废记录累计"实时计算，天然支持多次认领。
@@ -69,17 +74,17 @@ canClaim(row) {
2. **剩余可认领金额 > 0**：`remainingAmount` 由后端 `ReceiptFlowWrapper` 统一计算：
```
remainingAmount = max(公告未认领金额 unclaimed_amount − 累计认领金额 claimed_amount, 0)
remainingAmount = max(收款金额 receipt_amount − 累计认领金额 claimed_amount, 0)
```
按认领状态换算：
| 流水认领状态 | remainingAmount | 认领按钮 |
| --- | --- | --- |
| unclaimed 未认领（公告金额 > 0） | = 公告未认领金额 > 0 | 显示 |
| unclaimed 未认领（收款金额 > 0） | = 收款金额 > 0 | 显示 |
| partial 部分认领 | > 0 | 显示 |
| claimed 认领完成 | = 0（累计 ≥ 公告金额） | **不显示** |
| 公告未认领金额为 0 的流水 | = 0 | **不显示** |
| claimed 认领完成 | = 0（累计 ≥ 收款金额） | **不显示** |
| 收款金额为 0 或缺失的流水 | = 0 | **不显示** |
| 无 `receipt_flow_claim` 权限 | — | **不显示** |
即：**按钮显隐只看金额余额与权限，不看认领状态字段本身**；`claimed` 状态的行因为剩余额度为 0 自然不显示按钮。按钮不显示且不满足"推送金蝶"条件时，操作列显示"-"。
doc/docs/业务流程/2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/01-结算调整单列表-金蝶状态与推送入口.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

doc/docs/业务流程/2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/02-新增调整单-回带结算单信息与费用明细.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

doc/docs/业务流程/2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/03-新增调整单-选单后金蝶冲销预检提示.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

doc/docs/业务流程/2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/04-重新推送-高危二次确认.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 111 KiB

doc/docs/业务流程/2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.md
+8
View File
@@ -20,6 +20,8 @@
> 全程交互使用中文。
![结算调整单列表：审批通过的调整单统一一个入口，未同步显示「推送金蝶」、已同步显示「重新推送（高危）」；列表带「金蝶单据状态 / 金蝶单据号」列](./2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/01-结算调整单列表-金蝶状态与推送入口.png)
## 2. 名词与接口速查
| 代号 | 含义 |
@@ -119,6 +121,8 @@
- 排除收付完成/尾款等不可调整（`adjustableFormalSettlement`，约 295）；
- 保存时自动回带客商、调整类型、合同、原结算金额等。
![新增结算调整单：选定关联结算单后自动回带客商、结算单类型、合同、原结算金额，并带出原单费用明细供录入调整金额](./2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/02-新增调整单-回带结算单信息与费用明细.png)
### 6.2 选单后金蝶冲销预检（新增，软提示）
选定关联结算单号、回带信息后，前端调后端**预检接口**：
@@ -134,6 +138,8 @@
- **降级**：金蝶查询超时/不可用/接口异常时，预检返回"未校验"，**不阻断**建单与回带，由后续审批分流与重推闸门兜底。
- 预检结果**只用于提示**，不作为后续环节的结论缓存：审批（操作 2）、重推（操作 3）各自按**当下**状态重新判定。
![选单后金蝶冲销预检：该结算单已推送金蝶且旧单尚未冲销时的醒目提示，仅为软提示，不阻断建单](./2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/03-新增调整单-选单后金蝶冲销预检提示.png)
> 为什么不把硬拦截放在选单：冲销是金蝶侧**不可逆/需人工撤销**的对外操作，而审批只是 TMS 内部决策。若选单即要求已冲销，会出现"旧单已冲销、调整单却被驳回/删除"的**应付单空档**（详见第 13 节）。
## 7. 操作 2｜审批通过
@@ -179,6 +185,8 @@
7. **原单收尾**：标记 `adjustStatus='已调整'` + 旧锁记录置 `unlocked`；追加重推变更记录。业务字段不动。
8. **失败处理**：新单 `kingdeeSyncStatus=failed` + 失败原因，支持复用 `retryKingdeeFailed` 重试（重试即从第 4 步继续，克隆已存在则跳过，注意幂等）。
![重新推送（高危）：点击后先弹高危二次确认，确认金蝶旧应付/应收单已由财务手工冲销后才真正生成新单](./2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.assets/04-重新推送-高危二次确认.png)
## 9. 关键机制
### 9.1 防重键与新单号
doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.assets/01-结算调整单列表-各状态操作入口.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB

doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.assets/02-新增调整单-选单回带与费用录入.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 79 KiB

doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.assets/03-新增调整单-金蝶冲销预检提示.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.assets/04-提交审批二次确认.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 104 KiB

doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.assets/05-重新推送-高危二次确认.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 111 KiB

doc/docs/业务流程/2026-10-17-结算调整单操作流程说明（分场景）.md
+39 -2
View File
@@ -34,7 +34,34 @@
- 审批中：只能"通过"或"驳回"。
- 审批通过：终态，只剩金蝶推送相关操作。
### 2.2 各状态下的按钮
### 2.2 总体流程图
```
调整单审批通过
│
原结算单金蝶状态
┌───────────────────┴────────────────────┐
▼ ▼
未推送（场景 A） 已推送（场景 B）
① 调整回写原结算单 ① 原结算单业务数据【零改动】
② 原单追加变更记录 ② 原单仅追加 1 条变更记录
③ 调整单 → 审批通过 ③ 调整单 → 审批通过
④ 自动推送金蝶 ④ 提示：请财务在金蝶手工冲销旧单
（应付/应收单 + 落锁 + 附件） 【财务在金蝶手工冲销旧单】
⑤ 回填「已同步 + 金蝶单据号」 点「重新推送（高危）」并二次确认
↓ ① 校验调整单已审批通过
金蝶应付/应收单（含调整金额） ② 旧单必须已冲销，否则拒绝
③ 克隆新正式结算单（应用调整）
④ 用新单号推金蝶 → 全新应付/应收单
⑤ 新单落锁 + 附件
⑥ 调整单改挂新单 + 回填金蝶单据号
⑦ 原单标「已调整」+ 旧锁解锁
⑧ 推送失败置「生成失败」，可重试
↓
金蝶【全新】应付/应收单（旧单已冲销）
```
### 2.3 各状态下的按钮
| 状态 | 可用操作 | 说明 |
|---|---|---|
@@ -43,7 +70,9 @@
| 审批中 | 通过 / 驳回 | 审批人操作 |
| 审批通过 | 推送金蝶 / 重新推送（合一按钮）| 按金蝶状态自动分流，高危确认 |
### 2.3 金蝶同步状态（调整单上的展示字段）
![结算调整单列表：草稿行显示「查看 / 编辑 / 删除 / 提交」，审批通过行只剩「查看」与推送类操作；金蝶状态为「已同步」时按钮变为红色的「重新推送（高危）」，未同步时为「推送金蝶」](./2026-10-17-结算调整单操作流程说明（分场景）.assets/01-结算调整单列表-各状态操作入口.png)
### 2.4 金蝶同步状态（调整单上的展示字段）
| 状态 | 含义 |
|---|---|
@@ -67,6 +96,10 @@
> 预检只是提示，不拦人；真正的拦截在"重新推送"那一步。填单时必须至少录入一条调整费用，否则无法提交。
![新增调整单：选定关联正式结算单后自动回带客商、结算单类型、合同、原结算金额，并带出原单费用明细供录入调整金额](./2026-10-17-结算调整单操作流程说明（分场景）.assets/02-新增调整单-选单回带与费用录入.png)
![选单后的金蝶冲销预检：该结算单已推送金蝶且旧单未冲销时，顶部弹出醒目提示"审批通过后需先由财务在金蝶完成冲销，才能重新推送"，但建单不受影响](./2026-10-17-结算调整单操作流程说明（分场景）.assets/03-新增调整单-金蝶冲销预检提示.png)
### 3.2 保存草稿 / 编辑 / 删除
- 草稿和已驳回的单可反复编辑；删除仅限草稿，删除后单号作废、不留痕迹。
@@ -77,6 +110,8 @@
- 草稿 / 已驳回 → 审批中，进入审批人的待办。
- 提交后单据锁定，提交人不能再改。
![提交审批：草稿行点「提交」后需二次确认，确认后单据进入审批中并锁定](./2026-10-17-结算调整单操作流程说明（分场景）.assets/04-提交审批二次确认.png)
### 3.4 审批通过 ★ 核心分流点
审批人点"通过"后，系统按**原结算单是否推送过金蝶**自动走两条完全不同的路（见第四、五节场景 A / B）：
@@ -102,6 +137,8 @@
按钮点击均有高危二次确认弹窗。
![重新推送（高危）：确认金蝶旧应付/应收单已由财务手工冲销后才继续，系统将克隆新单并生成全新应付/应收单](./2026-10-17-结算调整单操作流程说明（分场景）.assets/05-重新推送-高危二次确认.png)
---
## 四、分场景流程
doc/docs/业务流程/2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）.md
+201
View File
@@ -0,0 +1,201 @@
# 收款流水菜单改造：数据源 A301-2 改 A301-1，认领只登记本地并推送合同合规（C107-1 / C107-3）
> 日期：2026-10-29
> 范围：tms-api（blade-transport、blade-hcs-api、blade-transport-api）+ tms-erp-web（收款流水 / 认领记录页面）
> 关联文档：
> - [2026-09-24-收款认领金蝶全链路业务流程（A301-2公告同步-A301-3认领推送-A301-1收款单回写）](./2026-09-24-收款认领金蝶全链路业务流程（A301-2公告同步-A301-3认领推送-A301-1收款单回写）.md)（本改造后 A301-3 链路整体下线）
> - [2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理](../hcs合同/2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理.md)（触发点由 A301-3 成功后改为认领事务提交后）
---
## 1. 需求与决策结论
收款流水菜单做两点改造：
1. **数据源改为 A301-1 收款单查询**（原 A301-2 收款认领公告查询下线）；
2. **认领动作只做本地认领记录 + 推送合同合规系统**（原 A301-3 推送金蝶链路整体下线，合规推送链保持 C103-9 + C107-1 + C108-1 全链）。
已确认的业务决策：
| # | 决策点 | 结论 |
| --- | --- | --- |
| 1 | 认领上限口径 | **收款金额 `receipt_amount`（A301-1 `actrecamt`）**。原定 `unmatchamountrec` 与收款金额取 min，因金蝶侧财务先核销导致大量收款单未匹配金额为 0、TMS 永久无法认领，2026-10-29 修正：认领只登记本地，额度由本地累计认领控制，`unmatchamountrec` 仅参考展示 |
| 2 | 合规推送范围 | **C103-9（履约计划金额累加）、C107-1（认领记录）、C108-1（履约流水）全保留** |
| 3 | C107-1 推送失败补偿 | **不做定时重试，只落推送标记**（blade_receipt_claim_hcs_record.push_status = failed + 失败原因） |
| 4 | 认领作废 | **需要 C107-3 作废同步**（fdStatus=1），C107-1 返回的合规 fdId 必须落库 |
| 5 | 同步可见范围 | A301-1 无认领人维度，**全公司流水均进入页面，可接受** |
---
## 2. 现状与目标链路对比
```
【现状】
A301-2 认领公告同步（按认领人姓名拉取）
→ blade_kingdee_receipt_flow 落库（幂等键 detail_serial_no）
→ 页面认领（只登记本地）
→ A301-3 推送金蝶（手动按钮 + 10分钟定时任务，推送前重查 A301-2 对账）
→ A301-3 成功后推合规链（C103-9 → C107-1 → C108-1）
→ A301-1 按 awrp_src_code 回写金蝶单据状态（refreshKingdeeResult）
【目标】
A301-1 收款单查询（业务日期窗口取 `thirdParty.bfi.recBillSync.days`，默认 60 天，全量）
→ blade_kingdee_receipt_flow 落库（幂等键 detail_serial_no，金蝶单号/状态随同步刷新）
→ 页面认领（只登记本地）
→ 认领事务提交后按认领主单推合规链（C103-9 → C107-1 → C108-1，C107-1 结果落库标记）
→ 认领作废事务提交后推 C107-3（fdStatus=1 已作废）
→ （A301-3 推送、awrp_src_code、A301-1 回写、定时任务、推送按钮全部下线）
```
关键变化：
- 金蝶收款单在认领前就已存在（A301-1 即金蝶收款处理单），因此**金蝶收款单号 / 单据状态随同步直接落库**，不再依赖推送回填与回写推进；
- 合规推送触发点从「A301-3 推送成功后（流水级）」改为「认领事务提交后（认领主单级）」，继续认领时每次认领各自推送一次，累计金额口径不变。
---
## 3. 后端改造明细（tms-api）
### 3.1 HCS Feign（blade-third-party-api/blade-hcs-api）
| 文件 | 改动 |
| --- | --- |
| `IHcsClient` | 新增 `CLAIM_RECORD_UPDATE_URL`（`/openapi/eop-data/eopDataCollectionFlowClaimRecordOpen/update`）与 `claimRecordUpdate` 方法（C107-3 修改认领记录） |
| `HcsClaimRecordAddDTO` | 新增 `fdId` 字段：C107-1 新增不传，C107-3 修改必填（作废传 fdStatus=1），一个 DTO 复用两个接口 |
### 3.2 收款流水同步：A301-2 → A301-1
`ReceiptFlowServiceImpl#sync()` 重写，`BfiUtil.queryAllPagesByTotal`（按 totalCount 推导总页数，兜底 500 页）+ `bfiService.queryRecBill` 全量翻页（pageSize 200），请求参数 `begin_bizdate` / `end_bizdate`（窗口天数取 Nacos `thirdParty.bfi.recBillSync.days`，默认 60）。
**字段映射（A301-1 → blade_kingdee_receipt_flow）**：
| 流水表字段 | A301-1 来源 | 说明 |
| --- | --- | --- |
| receipt_notice_no / kingdee_bill_no | `billno` | 金蝶收款单号（两处同值） |
| kingdee_bill_status | `billstatus` 映射 | A/B已提交→pushed、C已审核→approved、D已收款→received、其余（含G退单）→failed |
| detail_serial_no | 主单 `billno` | 明细流水号=收款单号，**幂等键**；主单粒度，一张收款单一条流水，不展开流水分录 |
| receipt_amount | 主单 `actrecamt` | 收款金额（金蝶收款金额口径） |
| unmatch_amount_rec | `unmatchamountrec` | 未匹配收款金额（金蝶参考展示，**不参与认领额度**；原列名 unclaimed_amount 已改名） |
| match_amount_rec | `matchamountrec` | 已匹配收款金额 |
| match_amount_pay | `matchamountpay` | 已匹配付款金额 |
| unmatch_amount_pay | `unmatchamountpay` | 未匹配付款金额 |
| settle_amount | `settleamount` | 已结算金额 |
| unsettle_amount | `unsettleamount` | 未结算金额 |
| payer_name / counterparty_name | `payername` | 付款人名称 |
| payee_name | `org_name` | 收款人（收款公司名称） |
| org_number | `org_number` | 收款人（公司）.编码 |
| open_org_number | `openorg_number` | 核算组织.编码 |
| counterparty_account | `payeracctbanknum` | 付款账户 |
| counterparty_bank | `payerbankname` | 付款银行 |
| summary | `txt_description` | 摘要 |
| transaction_time | `bizdate` | 业务日期 |
| fee | `fee` | 手续费 |
| source_updated_time | 同步时间 | — |
| bill_id / payer_id / kingdee_claim_status / claim_me | — | **废弃不再写入**（历史 A301-2 专属字段，列保留兼容存量） |
| push_status / push_fail_reason / pushed_time / awrp_src_code | — | **不再写入**（A301-3 下线；存量已推送数据保留展示） |
同步保持原有框架：明细流水号重复抛异常、金额 ≤0 跳过、FOR UPDATE 批量防并发、按幂等键 upsert、批量操作日志；本地认领字段（claimed_amount / claim_status）不被同步覆盖，认领后状态按「累计认领 vs 收款金额」重算。
### 3.3 认领与合规推送链
`ReceiptFlowServiceImpl#claim()`：
- 删除「认领公告id缺失」「公告未认领金额缺失」拦截（A301-1 无公告概念）；
- 认领上限：`claimCeiling = receipt_amount`（收款金额 `actrecamt`，金蝶未匹配金额不参与额度控制）；
- 认领主单冗余展示字段直取流水：`kingdeeBillNo` / `kingdeeBillStatus`（金蝶单据认领前已存在）；
- 事务提交后（`TransactionSynchronizationManager.afterCommit`）按**认领主单**触发 `HcsClaimSyncSupport#pushClaimToHcs(claimId)`，失败仅落标记不影响认领。
`HcsClaimSyncSupport` 重写（编排顺序不变、触发维度改变）：
1. 归集**本认领主单**有效分摊行 → 按合同分组金额；
2. C104-2 按明细流水号定位合规侧收款流水 ID（一次定位全部合同共用）；
3. 逐合同：C103-9 履约计划金额累加重推 → C107-1 认领记录（返回 fdId）→ C108-1 履约流水；
4. **C107-1 结果落库** `blade_receipt_claim_hcs_record`（认领主单×合同一条）：成功持久化合规 fdId（供 C107-3 引用），失败落 failed + 原因（只记标记，无定时重试）；
5. C108-1 的申请编号兜底、金蝶单据号（fd_jd_doc_no）取流水 `kingdee_bill_no`（A301-1 同步落库），金额改为本次认领分摊金额。
开关复用既有配置：`exe-stage.sync-enabled` 门禁 C103-9/C107-1，`perf-record.sync-enabled` 门禁 C108-1。
### 3.4 认领作废：C107-3 同步
`ReceiptClaimRecordServiceImpl#voidClaim()`：
- 删除「已推送金蝶不允许作废」拦截（不再有 TMS→金蝶推送，作废只回退本地 + 同步合规）；
- 事务提交后按认领主单推 C107-3：查 `blade_receipt_claim_hcs_record` 中 push_status=success 的记录，逐条 `claimRecordUpdate(fdId, fdStatus=1)`，成功后本地记录置 voided；单条失败独立记日志不回滚作废，合规侧需人工处置。
### 3.5 A301-3 链路整体下线
| 项 | 处置 |
| --- | --- |
| `pushClaimToKingdee` / `pushClaimByTask` / `executeReceiptClaimPush` / `pushClaimLocked` / `doPushClaimToKingdee` / `buildClaimPushDTO` / `extractClaimPushBillNo` / `applyClaimPushSuccess` / `applyClaimPushFailure` | 删除（ReceiptFlowServiceImpl） |
| `ReceiptClaimPushTask`（10 分钟定时推送） | 文件删除 |
| `ReceiptFlowController` `/push-kingdee` 端点 | 删除 |
| `refreshKingdeeResult`（A301-1 按 awrp_src_code 回写）+ `/receipt-claim-record/query-kingdee-result` 端点 | 删除（A301-1 已是数据源，状态随同步刷新） |
| `awrpSrcCode` 生成逻辑 | 删除 |
| `BfiProperties` | `claimAnnounce` / `receiptClaimPush` 配置类删除，新增 `RecBillSync`（`days` 默认 30） |
| `KingdeeReceiptFlow` 实体 | 字段注释更新为 A301-1 口径（bill_id 等标注废弃） |
### 3.6 新增表
`blade_receipt_claim_hcs_record`（收款认领合规推送记录，DDL 见 `doc/sql/transport/lqj/20261028/01_blade_receipt_claim_hcs_record_20261028.sql`）：
| 字段 | 说明 |
| --- | --- |
| receipt_claim_id / receipt_flow_id | 认领主单 / 收款流水 |
| contract_id / contract_no | 合同 |
| claim_amount | 本认领主单分摊到本合同的金额 |
| hcs_claim_record_fd_id | 合规侧认领记录 fdId（C107-1 返回，C107-3 必填引用） |
| push_status | success 推送成功 / failed 推送失败 / voided 已作废 |
| fail_reason / pushed_time | 失败原因 / 成功时间 |
---
## 4. 前端改造明细（tms-erp-web）
| 页面 / 文件 | 改动 |
| --- | --- |
| `views/payment/receipt-flow.vue` | 删「推送金蝶」操作按钮及 `canPush`/`handlePush`；删搜索「推送状态」；详情删「推送状态」「推送失败原因」，「金蝶未认领金额」→「未匹配金额」；同步提示改为"收款流水" |
| `views/payment/receipt-claim-record.vue` | 删「查询金蝶认领结果」按钮；删搜索「推送状态」；作废按钮去掉 `pushStatus !== 'pushed'` 限制；作废确认提示增加"同步作废合同合规系统认领记录" |
| `views/payment/receipt-flow-form.vue` / `receipt-flow-batch-form.vue` | 「认领通知单」→「收款单号」；「金蝶未认领金额」→「未匹配金额」；校验提示"公告未认领金额"→"未匹配金额" |
| `views/payment/receipt-claim-record-form.vue` | 「认领通知单」→「收款单号」 |
| `views/settlement/components/formal-settlement-editor.vue` | 认领列表列「认领通知单」→「收款单号」 |
| `api/payment/receiptFlow.js` | 删 `pushKingdee`、`pushStatusOptions` |
| `api/payment/receiptClaimRecord.js` | 删 `queryKingdeeResult`、`pushStatusOptions` |
| `option/payment/receiptFlow.js` | 删「公告状态」「推送状态」「推送失败原因」「金蝶收款单号」（与单号列重复）列；「认领通知单」→「收款单号」、「付款金额」→「收款金额」、「金蝶未认领金额」→「未匹配金额」 |
| `option/payment/receiptClaimRecord.js` | 「认领通知单」→「收款单号」、「付款金额」→「收款金额」 |
菜单按钮权限提示：`receipt_flow_push` 权限码随按钮下线，可在菜单配置中清理。
---
## 5. 配置与存量数据
**Nacos（thirdParty.bfi.*）**：
- 新增（可选）：`recBillSync.days`，默认 60（A301-1 业务日期窗口天数）；
- 可清理：`claimAnnounce.*`、`receiptClaimPush.*`（代码已不再读取）。
**存量数据**：
- A301-2 时代同步的流水（bill_id、kingdee_claim_status、claim_me 有值）与新口径并存，页面不再展示这些列；历史 push_status=pushed / awrp_src_code 仅保留展示，不再参与任何闸门；
- 明细流水号为全链唯一衔接键：A301-1 `bei_detailid` ≈ A301-2 `detailid` ≈ 合规 C104-2 `fdDetailSerialNumber`，同源同值时新旧数据 upsert 自然衔接。
---
## 6. 风险与待验证项
| # | 项 | 说明 | 等级 |
| --- | --- | --- | --- |
| 1 | **明细流水号同源性** | A301-1 `bei_detailid` 必须与原 A301-2 `detailid`、合规侧 `fdDetailSerialNumber` 同值，否则 C104-2 定位失败 → C107-1 全部跳过（仅记日志/落失败标记）。需联调拿真实报文核对 | 高 |
| 2 | 认领额度与金蝶匹配解耦 | 上限改用收款金额后，金蝶侧已匹配（核销）的收款单同样可认领并推合规；金蝶匹配状态变化不影响 TMS 已认领额度（按 `claimed_amount` 本地累计）。原 `unmatchamountrec` 口径下 797 条流水有 704 条额度为 0，需求无法闭环 | 中 |
| 3 | 合规履约计划金额不回退 | C103-9 认领时累加，作废仅同步 C107-3，不回退履约计划行金额（与改造前口径一致，未新增回退逻辑） | 中 |
| 4 | 全公司可见范围 | A301-1 按组织/日期拉全量，不再按认领人过滤，页面数据范围扩大（业务已确认可接受） | 低 |
| 5 | C107-1 失败无自动重试 | 仅落 failed 标记与原因，需人工在合规侧核对补录（业务已确认） | 低 |
## 7. 验证清单（交由测试/联调执行）
1. 手动同步：A301-1 拉取、流水按 infoentry 展开、重复明细流水号拦截、金额/单号/状态落库正确；
2. 认领：上限按收款金额控制、认领完成状态判定、合规链推送成功后 `blade_receipt_claim_hcs_record` 有 success 记录且 fdId 非空；
3. 继续认领：第二次认领各自推送一次 C107-1/C108-1，C103-9 累计金额正确；
4. 作废：本地回退 + C107-3 同步、记录置 voided；无合规记录（推送失败）时作废静默跳过；
5. 合规开关关闭（exe-stage/perf-record sync-enabled=false）时认领/作废主流程不受影响；
6. 回归：认领记录页、结算单收款汇总刷新、认领人筛选。
doc/docs/业务流程/2026-10-29-收款流水认领操作流程（收款金额本地额度·单条批量与作废）.md
+254
View File
@@ -0,0 +1,254 @@
# 收款流水认领操作流程（收款金额本地额度 · 单条/批量/作废）
> 日期：2026-10-29
> 范围：`tms-api` blade-transport 收款流水（同步、认领、认领记录）+ `tms-erp-web` 收款流水 / 认领记录页面
> 关联文档：
> - [2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）](./2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）.md)（改造设计与字段映射）
> - [2026-10-16-收款流水多次认领与作废口径梳理](./2026-10-16-收款流水多次认领与作废口径梳理.md)（多次认领、逐条作废口径）
---
## 0. 一页速览
| 项 | 内容 |
| --- | --- |
| 菜单入口 | 首付款管理 → **收款流水**（`/payment/receipt-flow`）、**认领记录**（`/payment/receipt-claim-record`） |
| 数据来源 | 金蝶 A301-1 收款单查询（收款处理单），**手动同步**触发，无定时任务 |
| 流水粒度 | 一张金蝶收款单 = 一条流水（`detail_serial_no` = 收款单号，幂等键） |
| 可认领上限 | **收款金额 `receipt_amount`（金蝶 `actrecamt`）** |
| 剩余可认领 | `max(收款金额 − 已认领金额 claimed_amount, 0)` |
| 未匹配金额 | 金蝶 `unmatchamountrec`，**仅参考展示，不参与额度控制** |
| 认领动作 | 只登记本地（认领主单 + 结算单分摊），**不推金蝶** |
| 合规推送 | 认领事务提交后推 C103-9 → C107-1 → C108-1；作废推 C107-3 |
| 状态 | `unclaimed` 未认领 / `partial` 部分认领 / `claimed` 认领完成 |
---
## 1. 角色与权限
| 操作 | 权限码 | 说明 |
| --- | --- | --- |
| 查看收款流水 | `receipt_flow_view` | 菜单权限 `receipt_flow` |
| 认领 / 批量认领 | `receipt_flow_claim` | 无此权限时操作列显示 `-`，顶部无「批量认领」按钮 |
| 手动同步流水 | `receipt_flow_sync` | 无此权限时顶部无「手动同步流水」按钮 |
| 查看认领记录 | `receipt_claim_record` | **只显示当前登录人自己的认领记录** |
| 作废认领记录 | `receipt_claim_record_void` | 仅本人、且状态为「已认领」的记录可作废 |
管理员（`admin`）默认直通按钮权限判断；认领记录页的数据范围仍按当前登录人过滤，管理员也只能看到自己做的认领。
---
## 2. 流程总览
```
【金蝶】A301-1 收款单
│ ① 手动同步（可按窗口重复执行，幂等）
▼
【TMS】收款流水列表（blade_kingdee_receipt_flow）
│ ② 勾选/单条 → 选择应收正式结算单 → 填分摊金额
▼
【TMS】认领（blade_receipt_claim + blade_receipt_claim_settlement）
│ ③ 更新流水累计认领金额/状态、刷新结算单收款汇总
│ ④ 事务提交后推合规：C103-9 → C107-1 → C108-1（失败只落标记）
▼
合规侧认领记录（C107-1 返回 fdId 落库）
│ ⑤ 需要撤销时在「认领记录」页作废
▼
本地回退金额 + 推 C107-3（fdStatus=1 已作废）
```
---
## 3. 场景一：同步收款流水
**入口**：收款流水页顶部「手动同步流水」。
**前置条件**：组织管理中已维护“是否平台公司 = 是”且已填金蝶编码的组织，否则直接报错「组织管理中未维护平台公司金蝶编码，无法同步金蝶收款流水，请先检查组织数据」。
**动作**：
1. 按业务日期窗口取数：结束日期 = 当天，开始日期 = 当天 − `thirdParty.bfi.recBillSync.days`（默认 60 天），起止时间格式 `yyyy-MM-dd HH:mm:ss`；
2. 按上述组织编码过滤，全量翻页拉取（pageSize 200，兜底 500 页，结束条件为末页/不满一页）；
3. 以收款单号去重，按幂等键 upsert：新增初始化 `claimed_amount = 0`、`claim_status = unclaimed`；已存在只更新金蝶来源字段，**不覆盖本地认领金额与状态**；
4. 收款金额 ≤ 0 的收款单跳过；
5. 每批 5000 条独立事务入库，并写同步操作日志。
**结果提示**：「流水同步完成，共同步 N 条收款流水」，列表自动刷新。
**注意**：
- 同步窗口从今天倒推，历史更早的单据不会进入；需要更早数据时调整 Nacos `thirdParty.bfi.recBillSync.days` 后重新同步（该配置支持热更新）。
- 金蝶侧改动（金额、状态、匹配/结算金额）每次同步都会刷新；**TMS 已认领金额与状态不受影响**，但状态会按新的收款金额重算。
---
## 4. 场景二：单条认领
### 4.1 入口与显示条件
列表操作列「认领」需同时满足：
1. 有 `receipt_flow_claim` 权限（admin 直通）；
2. 剩余可认领金额 > 0（即收款金额 > 累计已认领金额）。
不满足时操作列显示 `-`。列表列「未匹配金额」为金蝶口径参考值，**该列为 0 不影响认领**。
### 4.2 操作步骤
1. 点「认领」进入认领页面，顶部只读展示：收款单号、付款人、收款金额、交易时间、对方户名/开户行/账号、明细流水号、已认领金额、未匹配金额（金蝶参考）、剩余可认领金额、摘要、认领人、认领日期、认领人部门；
2. 点「关联结算单」选择器，弹窗按结算单号/项目/合同搜索：
- 候选范围：应收类型 + 已审批通过 + 有效状态 + 该结算单自身仍有剩余可认领金额；
- 多选时必须**同一项目、同一组织、同付款方、同收款方**，否则提示「关联结算单必须属于同一项目、组织及收付款方」；
3. 在「结算信息」明细中逐张填写「分摊收款金额」：
- 单张结算单分摊上限 = 结算总金额 − 已认领收款金额；
- 本次分摊合计必须 ≤ 当前页面的「剩余可认领金额」；
4. 维护附件（可选）、备注（≤200 字）；
5. 点「确认」。
### 4.3 确认后系统做了什么
| 步骤 | 内容 |
| --- | --- |
| 1 | 行锁流水与所选结算单，防止并发超额 |
| 2 | 校验：每张结算单「已认领 + 本次分摊 ≤ 结算总金额」；流水「已认领 + 本次分摊 ≤ 收款金额」 |
| 3 | 插入 1 条认领主单 `blade_receipt_claim`（`claim_amount` = 本次分摊合计） |
| 4 | 按结算单插入 N 条分摊 `blade_receipt_claim_settlement`（记录认领前已认领金额、本次分摊金额） |
| 5 | 刷新各结算单收款汇总；流水 `claimed_amount` 累加，重算 `claim_status`（0 → unclaimed，< 收款金额 → partial，≥ 收款金额 → claimed） |
| 6 | 写流水操作记录（认领动作、金额、关联结算单数） |
| 7 | **事务提交后**按认领主单推合规：C103-9（履约计划金额累加）→ C107-1（认领记录，返回 fdId 落库）→ C108-1（履约流水）；任一步失败只落 `blade_receipt_claim_hcs_record` 失败标记，不回滚认领 |
| 8 | 返回收款流水列表，提示「认领成功」 |
> 合规开关关闭（`exe-stage.sync-enabled` / `perf-record.sync-enabled`）时，认领主流程不受影响，只是不推合规。
---
## 5. 场景三：批量认领
**入口**：列表勾选多条流水 → 顶部「批量认领」（需 `receipt_flow_claim` 权限）。
**前置校验**：所选流水的**付款人 + 对方账号必须完全一致**，否则提示「批量认领所选流水的付款人、对方账号必须一致」。
**操作步骤**：
1. 进入「批量认领收款流水」页面，顶部明细列出所选流水（收款单号、收款金额、已认领金额、未匹配金额、剩余可认领金额、摘要）；
2. 选择关联应收结算单（候选规则同单条认领，多选同样要求同项目/组织/收付款方）；
3. 在「结算单 × 流水」分摊矩阵中逐格填写金额：
- 单格上限 = min(该结算单剩余可认领 − 该结算单其它格已填, 该流水剩余可认领 − 该流水其它格已填)；
4. 附件、备注同单条认领；
5. 点「确认」。
**提交逻辑**：
- 先校验结算单维度（累计分摊 ≤ 结算单剩余）与流水维度（累计分摊 ≤ 流水剩余可认领）；
- 按流水逐条提交认领：**每条流水生成一条认领主单**，各自推一次合规（C103-9 累计金额按各次认领累加）；
- 分摊为 0 的格子不提交；全部为 0 时提示「没有需要入库的分摊收款金额」；
- 全部成功提示「批量认领成功，共 N 条流水」并返回列表。
> 批量提交是逐条循环调用认领接口，非单一事务：中途某条失败时，之前的流水已认领成功，需要按提示逐条核查（可在「认领记录」页确认已成功的部分）。
---
## 6. 场景四：部分认领与继续认领
1. 首次分摊合计小于收款金额 → 流水状态变「部分认领」（`partial`），剩余可认领金额 = 收款金额 − 累计已认领；
2. 再次点「认领」进入页面时，会**自动预填本流水历史关联且仍有剩余可认领金额的结算单**（分摊金额默认 0，需重新填写）；
3. 每次认领都是一条新的认领主单，合规侧每次各推一次 C107-1/C108-1，C103-9 按合同累计；
4. 累计达到收款金额 → 状态「认领完成」，操作列不再显示「认领」。
---
## 7. 场景五：作废认领记录
**入口**：认领记录页（仅本人记录）→ 操作列「作废」（需 `receipt_claim_record_void`，且记录状态为「已认领」）。
**操作**：点击后二次确认，提示「作废后将回退本次认领金额，并同步作废合同合规系统认领记录」。
**作废后系统做了什么**：
| 步骤 | 内容 |
| --- | --- |
| 1 | 行锁认领主单、收款流水、关联结算单 |
| 2 | 本次认领的分摊行批量置为无效（`status = 0`） |
| 3 | 刷新关联结算单收款汇总 |
| 4 | 流水 `claimed_amount` 回退本次认领金额（不小于 0），并按收款金额重算状态（可能回到 unclaimed / partial） |
| 5 | 认领主单置「已作废」，记录作废人、作废时间与操作日志 |
| 6 | 事务提交后逐条推 C107-3（按落库 fdId 传 `fdStatus=1`），成功记录置 `voided`；单条失败只记日志，**不回滚作废**，需人工在合规侧处置 |
**注意**：
- 已作废记录不可重复作废；
- 作废不生成金蝶冲销单，金蝶收款单本身不受影响（金蝶侧红冲由财务人工处置）；
- 认领记录允许本人维护附件（`/receipt-claim-record/attachments`）。
---
## 8. 状态与金额口径
### 8.1 流水认领状态
| 状态 | 含义 | 判定 |
| --- | --- | --- |
| `unclaimed` 未认领 | 尚未认领 | 累计认领金额 = 0 |
| `partial` 部分认领 | 已认领一部分 | 0 < 累计认领金额 < 收款金额 |
| `claimed` 认领完成 | 额度用尽 | 累计认领金额 ≥ 收款金额 |
### 8.2 关键金额
| 金额 | 来源/公式 | 用途 |
| --- | --- | --- |
| 收款金额 `receipt_amount` | A301-1 `actrecamt` | 认领上限 |
| 已认领金额 `claimed_amount` | 本地认领累加（作废回退） | 已用额度 |
| 剩余可认领金额 `remainingAmount` | `max(收款金额 − 已认领金额, 0)` | 按钮显隐、前置校验 |
| 未匹配金额 `unmatch_amount_rec` | A301-1 `unmatchamountrec` | 金蝶参考展示，**不参与校验** |
| 结算单剩余可认领 | 结算总金额 − 该结算单已认领收款金额 | 分摊上限（结算单维度） |
### 8.3 金蝶单据状态（随同步刷新）
| `billstatus` | 本地 `kingdee_bill_status` | 页面展示 |
| --- | --- | --- |
| A 暂存 / B 已提交 | `pushed` | 已推送 |
| C 已审核 | `approved` | 审核通过 |
| D 已收款 | `received` | 已收款 |
| G 已退单 / E 变更中 / 其它 | `failed` | 处理失败（需人工在金蝶核查） |
---
## 9. 常见提示与处置
| 提示 | 原因 | 处置 |
| --- | --- | --- |
| 操作列显示 `-` | 无 `receipt_flow_claim` 权限，或已认领完成（剩余可认领 = 0） | 配权限；或确认是否已全额认领 |
| 「该流水可认领金额为0，无需认领」 | 收款金额 ≤ 0（数据异常，正常同步已跳过此类单据） | 核查金蝶收款单金额 |
| 「累计认领金额不能超过可认领上限，剩余可认领 X」 | 分摊合计超过剩余可认领 | 按提示减少分摊 |
| 前端「累计认领金额不能超过剩余可认领金额」 | 同上，前端预校验拦截 | 同上 |
| 「结算单XXX的累计认领金额不能超过结算总应收含税金额」 | 单张结算单分摊超过其剩余 | 调整该结算单分摊 |
| 「关联结算单必须属于同一项目、组织及收付款方」 | 多选结算单不一致 | 重新选择同项目同收付款方的结算单 |
| 「批量认领所选流水的付款人、对方账号必须一致」 | 勾选流水不属于同一付款账户 | 拆分批次 |
| 「组织管理中未维护平台公司金蝶编码…」 | 同步前置缺失 | 维护组织金蝶编码后再同步 |
| 未匹配金额为 0 但可以认领 | 金蝶侧财务已核销，属正常 | 忽略该列，按剩余可认领操作 |
| 认领记录页看不到某条记录 | 只显示当前登录人自己的记录 | 由本人查看/作废，或到结算单认领明细核查 |
| 合规推送失败 | C103-9/C107-1/C108-1 返回异常 | 查 `blade_receipt_claim_hcs_record` 失败原因，人工在合规侧补录（无自动重试） |
---
## 10. 与 2026-10-29 之前的差异
| 项 | 改造前 | 现在 |
| --- | --- | --- |
| 数据源 | A301-2 收款认领公告 | A301-1 收款单查询 |
| 认领上限 | `min(未匹配收款金额, 收款金额)` | **收款金额** |
| 未匹配金额的作用 | 决定是否可认领（大量单据为 0 → 无法认领） | 仅参考展示 |
| 认领后 | A301-3 推金蝶（手动/定时） | 只登记本地 + 推合规，金蝶不写 |
| 推送失败 | 定时重试 | 只落失败标记，人工处理 |
---
## 11. 操作自查清单
1. 同步后列表条数、收款单号、收款金额、金蝶状态与金蝶一致；
2. 剩余可认领金额 = 收款金额 − 已认领金额，且列表/详情/认领页三处一致；
3. 单条认领：分摊合计 = 收款金额 → 状态「认领完成」，按钮消失；小于 → 「部分认领」；
4. 继续认领：剩余额度正确、历史结算单预填、合规侧新增一条认领记录；
5. 批量认领：同一付款账户多流水一次提交，各自生成认领记录；
6. 作废：金额回退、状态回退、合规侧记录变为已作废（`blade_receipt_claim_hcs_record.push_status = voided`）；
7. 超额场景（流水维度、结算单维度）均被拦截并给出可读提示。
doc/nacos/blade-dev.yaml
+6
View File
@@ -184,12 +184,18 @@ thirdParty:
exratetable: ${BFI_PAY_APPLY_EXRATE_TABLE:01}
# 外部单据类型
srcType: ${BFI_PAY_APPLY_SRC_TYPE:0KzXs}
# 收款流水同步配置（A301-1 收款单查询）
recBillSync:
# 业务日期窗口天数
days: ${BFI_RECBILL_SYNC_DAYS:60}
# 金蝶付款结果定时回写（A103-2 付款申请单查询 / A103-4 付款处理查询）
payResult:
# 回写任务开关
syncEnabled: ${BFI_PAY_RESULT_SYNC_ENABLED:true}
# 调度 cron，默认每10分钟
cron: ${BFI_PAY_RESULT_CRON:0 */10 * * * ?}
# A103-4 付款处理查询业务日期窗口天数
queryWindowDays: ${BFI_PAY_RESULT_QUERY_WINDOW_DAYS:60}
# 收款认领公告查询配置（A301-2）
claimAnnounce:
# 查询时间窗口（月数）
doc/nacos/blade-prod.yaml
+6
View File
@@ -133,12 +133,18 @@ thirdParty:
exratetable: ${BFI_PAY_APPLY_EXRATE_TABLE:01}
# 外部单据类型
srcType: ${BFI_PAY_APPLY_SRC_TYPE:0KzXs}
# 收款流水同步配置（A301-1 收款单查询）
recBillSync:
# 业务日期窗口天数
days: ${BFI_RECBILL_SYNC_DAYS:60}
# 金蝶付款结果定时回写（A103-2 付款申请单查询 / A103-4 付款处理查询）
payResult:
# 回写任务开关
syncEnabled: ${BFI_PAY_RESULT_SYNC_ENABLED:true}
# 调度 cron，默认每10分钟
cron: ${BFI_PAY_RESULT_CRON:0 */10 * * * ?}
# A103-4 付款处理查询业务日期窗口天数
queryWindowDays: ${BFI_PAY_RESULT_QUERY_WINDOW_DAYS:60}
# 收款认领推送金蝶定时任务（A301-3 收款认领结果推送）
receiptClaimPush:
# 推送任务开关，默认关闭（联调稳定后开启）
doc/nacos/third-party-api.yaml
+6
View File
@@ -86,12 +86,18 @@ thirdParty:
exratetable: ${BFI_PAY_APPLY_EXRATE_TABLE:01}
# 外部单据类型
srcType: ${BFI_PAY_APPLY_SRC_TYPE:0KzXs}
# 收款流水同步配置（A301-1 收款单查询）
recBillSync:
# 业务日期窗口天数
days: ${BFI_RECBILL_SYNC_DAYS:60}
# 金蝶付款结果定时回写（A103-2 付款申请单查询 / A103-4 付款处理查询）
payResult:
# 回写任务开关
syncEnabled: ${BFI_PAY_RESULT_SYNC_ENABLED:false}
# 调度 cron，默认每10分钟
cron: ${BFI_PAY_RESULT_CRON:0 1/10 * * * ?}
# A103-4 付款处理查询业务日期窗口天数
queryWindowDays: ${BFI_PAY_RESULT_QUERY_WINDOW_DAYS:60}
# 金蝶收票单结果定时回写（A801-3 异常回收/指定补偿/单号补登）
receivedInvoiceResult:
doc/sql/transport/lqj/20261028/01_blade_receipt_claim_hcs_record_20261028.sql
+27
View File
@@ -0,0 +1,27 @@
-- 收款认领合规推送记录表：C107-1 认领记录推送结果落库（认领主单 × 合同一条）
-- 成功持久化合规侧 fdId 供认领作废 C107-3 引用；失败落推送标记与原因（仅记标记，不做定时重试）
-- 配套改造：收款流水菜单数据源 A301-2 → A301-1，认领事务提交后推送合规链（C103-9/C107-1/C108-1）
CREATE TABLE IF NOT EXISTS `blade_receipt_claim_hcs_record` (
`id` bigint NOT NULL COMMENT '主键',
`tenant_id` varchar(12) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT '000000' COMMENT '租户ID',
`receipt_claim_id` bigint NOT NULL COMMENT '认领主单id',
`receipt_flow_id` bigint NOT NULL COMMENT '收款流水id',
`contract_id` bigint DEFAULT NULL COMMENT '合同id',
`contract_no` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '合同编号',
`claim_amount` decimal(19, 2) DEFAULT NULL COMMENT '该认领主单分摊到本合同的认领金额',
`hcs_claim_record_fd_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '合规侧认领记录fdId（C107-1返回，C107-3作废必填引用）',
`push_status` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '推送状态（success推送成功/failed推送失败/voided已作废）',
`fail_reason` varchar(1000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '推送失败原因（成功后清空）',
`pushed_time` datetime DEFAULT NULL COMMENT '推送成功时间',
`create_user` bigint DEFAULT NULL COMMENT '创建人',
`create_dept` bigint DEFAULT NULL COMMENT '创建部门',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_user` bigint DEFAULT NULL COMMENT '修改人',
`update_time` datetime DEFAULT NULL COMMENT '修改时间',
`status` int DEFAULT NULL COMMENT '状态',
`is_deleted` int DEFAULT 0 COMMENT '是否已删除',
PRIMARY KEY (`id`),
KEY `idx_receipt_claim_id` (`receipt_claim_id`),
KEY `idx_receipt_flow_id` (`receipt_flow_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='收款认领合规推送记录表';
doc/sql/transport/lqj/20261029/01_blade_kingdee_receipt_flow_org_fields_20261029.sql
+28
View File
@@ -0,0 +1,28 @@
-- 收款流水表增加金蝶收款单组织/公司编码字段（A301-1 收款单查询同步落库）
-- openorg_number 核算组织.编码、org_number 收款人（公司）.编码；org_name 已由 payee_name 承载不加列
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `org_number` varchar(50) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT ''收款人（公司）.编码（A301-1 org_number）'' AFTER `payee_name`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'org_number'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `open_org_number` varchar(50) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT ''核算组织.编码（A301-1 openorg_number）'' AFTER `org_number`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'open_org_number'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
doc/sql/transport/lqj/20261029/02_blade_kingdee_receipt_flow_match_settle_amounts_20261029.sql
+67
View File
@@ -0,0 +1,67 @@
-- 收款流水表增加金蝶收款单匹配/结算金额字段（A301-1 收款单查询同步落库）
-- unmatchamountrec 未匹配收款金额已由 unclaimed_amount 承载，不重复加列
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `match_amount_rec` decimal(19, 2) DEFAULT NULL COMMENT ''已匹配收款金额（A301-1 matchamountrec）'' AFTER `unclaimed_amount`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'match_amount_rec'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `match_amount_pay` decimal(19, 2) DEFAULT NULL COMMENT ''已匹配付款金额（A301-1 matchamountpay）'' AFTER `match_amount_rec`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'match_amount_pay'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `unmatch_amount_pay` decimal(19, 2) DEFAULT NULL COMMENT ''未匹配付款金额（A301-1 unmatchamountpay）'' AFTER `match_amount_pay`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'unmatch_amount_pay'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `settle_amount` decimal(19, 2) DEFAULT NULL COMMENT ''已结算金额（A301-1 settleamount）'' AFTER `unmatch_amount_pay`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'settle_amount'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
SET @ddl_sql = (
SELECT IF(COUNT(*) = 0,
'ALTER TABLE `blade_kingdee_receipt_flow` ADD COLUMN `unsettle_amount` decimal(19, 2) DEFAULT NULL COMMENT ''未结算金额（A301-1 unsettleamount）'' AFTER `settle_amount`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'unsettle_amount'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;
doc/sql/transport/lqj/20261029/03_blade_kingdee_receipt_flow_unmatch_amount_rec_rename_20261029.sql
+15
View File
@@ -0,0 +1,15 @@
-- 收款流水表未匹配收款金额列改名：unclaimed_amount（A301-2 公告未认领金额遗留列名）
-- → unmatch_amount_rec（与 A301-1 字段口径及其他匹配金额列命名统一）
SET @ddl_sql = (
SELECT IF(COUNT(*) = 1,
'ALTER TABLE `blade_kingdee_receipt_flow` RENAME COLUMN `unclaimed_amount` TO `unmatch_amount_rec`',
'SELECT 1')
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'blade_kingdee_receipt_flow'
AND COLUMN_NAME = 'unclaimed_amount'
);
PREPARE ddl_stmt FROM @ddl_sql;
EXECUTE ddl_stmt;
DEALLOCATE PREPARE ddl_stmt;