feat: 履约记录类型fd_paln_type按四场景传中文值（付款/收款/开票/收票）

2026-10-28 19:43:37 +08:00
parent 830acee00e
commit adbc87e2e4
6 changed files with 38 additions and 14 deletions
@@ -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 = "收票";
+
 	/**
 	 * 款项性质：进度款
 	 */
@@ -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);
@@ -60,7 +60,7 @@ import java.util.stream.Collectors;
 * <p>
 * 粒度：金蝶回写的每张发票（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);
 	}
@@ -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）
@@ -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);
 	}
@@ -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` 为空的历史发票会被补推，如需排除请手工回填标记）。