diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/constant/HcsSyncConstant.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/constant/HcsSyncConstant.java index bf786eaf..13069ebd 100644 --- a/blade-service/blade-transport/src/main/java/org/springblade/transport/constant/HcsSyncConstant.java +++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/constant/HcsSyncConstant.java @@ -250,15 +250,37 @@ public final class HcsSyncConstant { public static final String ROW_OP_DELETE = "delete"; /** - * 履约类型：付款 + * 履约类型：付款（C103-9 履约计划行） */ public static final String PERFORM_TYPE_PAYMENT = "payment"; /** - * 履约类型：收款 + * 履约类型：收款（C103-9 履约计划行） */ public static final String PERFORM_TYPE_COLLECTION = "collection"; + // ==================== 履约记录类型（C108 fd_paln_type，按四场景传中文） ==================== + + /** + * 履约记录类型：付款 + */ + public static final String PERF_TYPE_PAYMENT = "付款"; + + /** + * 履约记录类型：收款 + */ + public static final String PERF_TYPE_COLLECTION = "收款"; + + /** + * 履约记录类型：开票 + */ + public static final String PERF_TYPE_INVOICE = "开票"; + + /** + * 履约记录类型：收票 + */ + public static final String PERF_TYPE_INVOICE_RECEIPT = "收票"; + /** * 款项性质：进度款 */ diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsClaimSyncSupport.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsClaimSyncSupport.java index ea242d5c..8577b62d 100644 --- a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsClaimSyncSupport.java +++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsClaimSyncSupport.java @@ -282,7 +282,7 @@ public class HcsClaimSyncSupport { 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.PERFORM_TYPE_COLLECTION, flow.getKingdeeBillNo(), flow.getId(), + 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); diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsInvoicePerfSyncSupport.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsInvoicePerfSyncSupport.java index a831adcc..00ed9b2f 100644 --- a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsInvoicePerfSyncSupport.java +++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsInvoicePerfSyncSupport.java @@ -60,7 +60,7 @@ import java.util.stream.Collectors; *

* 粒度：金蝶回写的每张发票（blade_invoice_application_invoice）对应一条履约开票记录； * 触发：A303-5 开票结果回写落库发票后，随开票登记扫描任务（HcsPushTask invoice-application）推送； - * 履约日期为发票完成开票日期（invoice_date），履约类型 collection（收款方向，关联合同收款履约计划行）； + * 履约日期为发票完成开票日期（invoice_date），履约类型「开票」（关联合同收款履约计划行）； * 合同经应收结算链路回溯（开票申请 → 应收结算关联 → 正式结算单合同，同 C111 §9-U10 口径）； * 幂等凭 hcs_perf_fd_id（非空跳过），失败置重试计数与原因由下轮扫描自动补偿。 * @@ -139,7 +139,7 @@ public class HcsInvoicePerfSyncSupport { BigDecimal amount = invoice.getInvoiceAmount() == null ? BigDecimal.ZERO : invoice.getInvoiceAmount(); String perfFdId = hcsPerfRecordAddSupport.pushPerfRecordAdd(contractManage, stageRow, invoice.getInvoiceNo(), amount, toMillis(invoice.getInvoiceDate()), - HcsSyncConstant.PERFORM_TYPE_COLLECTION, invoice.getSerialNo(), invoice.getId(), + HcsSyncConstant.PERF_TYPE_INVOICE, invoice.getSerialNo(), invoice.getId(), "开票履约-" + invoice.getInvoiceNo()); markSynced(invoice, perfFdId); } diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsPerfRecordSyncSupport.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsPerfRecordSyncSupport.java index 54e14846..9d2c3a32 100644 --- a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsPerfRecordSyncSupport.java +++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsPerfRecordSyncSupport.java @@ -163,8 +163,8 @@ public class HcsPerfRecordSyncSupport { props.setFdApplyNo(payment.getPaymentNo()); // 【必填】计划日期：applyDate（毫秒时间戳） props.setFdPlanDate(toMillis(payment.getApplyDate())); - // 计划类型：paymentType（原文拼写 fd_paln_type 必须沿用） - props.setFdPalnType(payment.getPaymentType()); + // 计划类型：履约记录类型按场景传中文「付款」（原文拼写 fd_paln_type 必须沿用） + props.setFdPalnType(HcsSyncConstant.PERF_TYPE_PAYMENT); // 性质：款项性质取关联履约计划行的款项性质 props.setFdProperty(stageRow.getFundNature()); // 履约计划id / 来源履约计划项ID：履约计划行合规阶段ID（HCS 只认自己的阶段ID） diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsReceiptPerfSyncSupport.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsReceiptPerfSyncSupport.java index 96e37fde..13d2bddc 100644 --- a/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsReceiptPerfSyncSupport.java +++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/support/hcs/HcsReceiptPerfSyncSupport.java @@ -59,7 +59,7 @@ import java.util.stream.Collectors; * 粒度：收票登记结算单分摊行（blade_invoice_receipt_settlement）对应一条履约收票记录； * 触发：收票单推送合规（C109）成功后，随收票单扫描任务（HcsPushTask invoice-receipt）推送， * 扫描范围限定所属收票单 hcs_sync_status=synced（C109 已推送），失败下轮自动补偿； - * 履约日期为发票日期（收票单 invoice_date），履约类型 payment（付款方向，关联合同付款履约计划行）； + * 履约日期为发票日期（收票单 invoice_date），履约类型「收票」（关联合同付款履约计划行）； * 合同经应付结算链路回溯（结算分摊行 → 正式结算单合同）； * 幂等凭 hcs_perf_fd_id（非空跳过），失败置重试计数与原因由下轮扫描自动补偿。 * @@ -153,7 +153,7 @@ public class HcsReceiptPerfSyncSupport { String applyNo = receipt.getInvoiceNo() + "-" + (settlementNo == null ? "" : settlementNo); String perfFdId = hcsPerfRecordAddSupport.pushPerfRecordAdd(contractManage, stageRow, applyNo, amount, toMillis(receipt.getInvoiceDate()), - HcsSyncConstant.PERFORM_TYPE_PAYMENT, receipt.getKingdeeReceivedInvoiceNo(), settlementLine.getId(), + HcsSyncConstant.PERF_TYPE_INVOICE_RECEIPT, receipt.getKingdeeReceivedInvoiceNo(), settlementLine.getId(), "收票履约-" + applyNo); markSynced(settlementLine, perfFdId); } diff --git a/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md b/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md index f85fd850..d60a406c 100644 --- a/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md +++ b/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md @@ -12,10 +12,12 @@ C108-1（履约记录新建）、C108-2（履约记录更新）两个接口需 | # | 场景 | 对应 TMS 数据 | 推送时机 | 履约日期（fd_plan_date） | 履约类型（fd_paln_type） | |---|------|--------------|----------|------------------------|------------------------| -| 1 | 履约收款记录 | 收款认领记录（收款流水 × 认领分摊） | 金蝶认领推送（A301-3）成功后 | **交易日期**（收款流水 `transaction_time`） | collection（收款） | -| 2 | 履约付款记录 | 付款申请（含实际付款金额） | **金蝶实际付款后**（付款结果回写推进） | 申请日期（计划日期口径，维持原样） | payment（付款） | -| 3 | 履约开票记录 | 开票申请的金蝶回写发票（每张发票一条） | **金蝶开票完成后**（A303-5 发票落库后） | **发票完成开票日期**（`invoice_date`） | collection（收款） | -| 4 | 履约收票记录 | 收票单的每条结算信息（分摊行，每条一条） | 收票单推送合规（C109）成功后 | **发票日期**（收票单 `invoice_date`） | payment（付款） | +| 1 | 履约收款记录 | 收款认领记录（收款流水 × 认领分摊） | 金蝶认领推送（A301-3）成功后 | **交易日期**（收款流水 `transaction_time`） | 收款 | +| 2 | 履约付款记录 | 付款申请（含实际付款金额） | **金蝶实际付款后**（付款结果回写推进） | 申请日期（计划日期口径，维持原样） | 付款 | +| 3 | 履约开票记录 | 开票申请的金蝶回写发票（每张发票一条） | **金蝶开票完成后**（A303-5 发票落库后） | **发票完成开票日期**（`invoice_date`） | 开票 | +| 4 | 履约收票记录 | 收票单的每条结算信息（分摊行，每条一条） | 收票单推送合规（C109）成功后 | **发票日期**（收票单 `invoice_date`） | 收票 | + +> `fd_paln_type` 按四场景分别传中文值：**付款 / 收款 / 开票 / 收票**（常量 `HcsSyncConstant.PERF_TYPE_*`）；C103-9 履约计划行的履约类型仍传 `payment`/`collection`，两者互不影响。 本次确认的业务口径调整：**履约付款记录由「审批通过即新建」改为「金蝶实际付款后才新建」**。 @@ -256,7 +258,7 @@ HcsPushTask 开票任务（每5分钟）： ## 9. 联调注意事项与风险 -1. **fd_paln_type / 款项性质口径**：开票=collection+收款进度款计划行、收票=payment+付款进度款计划行，为按履约计划行方向推定的口径，需与合规侧确认。 +1. **fd_paln_type 口径（已确认）**：履约记录类型按四场景传中文——付款 / 收款 / 开票 / 收票；款项性质仍取关联履约计划行（progress），如合规侧字典要求编码（如 4141 样例）联调时调整常量即可。 2. **C108-1 无服务端判重键**：新三场景极端情况下「推送超时但远端已成功」的重试可能在合同系统产生重复记录（与既有 C107-1 同风险）；开票/收票有本地 fdId 幂等只能防"确认成功后"的重复，不能防"未知结果"的重试。 3. **收票履约依赖 C109 先推**：收票单未推送合规（或推送失败）时分摊行记失败原因等待，C109 成功后下轮自动补偿。 4. **存量数据**：改造前已按「审批通过即新建」推送过履约付款记录的单据（已有 `hcs_perf_fd_id`），后续金额推进仍走 C108-2，行为兼容；开票/收票新场景上线后只会处理新落库数据（`hcs_perf_fd_id` 为空的历史发票会被补推，如需排除请手工回填标记）。