- * 触发点：金蝶认领推送（A301-3）成功之后（手动按钮与定时任务共用钩子），开关 thirdParty.hcs.claim.sync-enabled。 + * 触发点：金蝶认领推送（A301-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 履约流水。 * 合同未推送合规（hcs_fd_id 空）时仅累加计划行金额，随合同链路首推。 @@ -104,12 +106,14 @@ public class HcsClaimSyncSupport { /** * 金蝶认领推送成功后推送合同合规（C103-9 → C107-1 → C108-1） *
- * 开关关闭或推送异常均静默返回，不影响金蝶认领推送主流程与事务。 + * 复用既有开关：exe-stage.sync-enabled（履约计划同步）门禁 C103-9/C107-1， + * perf-record.sync-enabled（履约记录同步）门禁 C108-1；开关关闭或推送异常均静默返回， + * 不影响金蝶认领推送主流程与事务。 * * @param flowId 收款流水ID */ public void pushClaimToHcs(Long flowId) { - if (!hcsProperties.getClaim().isSyncEnabled()) { + if (!hcsProperties.getExeStage().isSyncEnabled()) { return; } try { @@ -208,7 +212,12 @@ public class HcsClaimSyncSupport { pushClaimRecord(flow, claimsById.get(claimEntry.getKey()), contractManage, stageRow, claimEntry.getValue(), hcsCollectionFlowId); } } - // ③ C108-1 履约流水：按合同一条，须已推送合规且存在已同步收款计划行（fd_plan_id 必填） + // ③ C108-1 履约流水：按合同一条（开关 perf-record.sync-enabled，与付款链履约记录同步同开关）， + // 须已推送合规且存在已同步收款计划行（fd_plan_id 必填） + if (!hcsProperties.getPerfRecord().isSyncEnabled()) { + log.info("HCS履约流水推送跳过：履约记录同步开关未开启 contractNo={}", contractManage.getContractNo()); + return; + } if (StringUtil.isBlank(contractManage.getHcsFdId())) { log.info("HCS履约流水推送跳过：合同尚未推送合规 contractNo={}", contractManage.getContractNo()); return; diff --git a/blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/config/HcsProperties.java b/blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/config/HcsProperties.java index 919b333f..5e0ca285 100644 --- a/blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/config/HcsProperties.java +++ b/blade-third-party-api/blade-hcs-api/src/main/java/org/springblade/hcs/config/HcsProperties.java @@ -124,10 +124,6 @@ public class HcsProperties { * 收票单（C109）配置 */ private ReceiptBill receiptBill = new ReceiptBill(); - /** - * 收款认领链（C103-9 更新履约计划 + C107-1 认领记录 + C108-1 履约流水）配置 - */ - private Claim claim = new Claim(); /** * 附件转传（C103-2）配置 */ @@ -326,14 +322,6 @@ public class HcsProperties { private String xformId = ""; } - @Data - public static class Claim { - /** - * 收款认领链同步开关（金蝶认领推送 A301-3 成功后推 C103-9/C107-1/C108-1，默认关） - */ - private boolean syncEnabled = false; - } - @Data public static class Attachment { /** diff --git a/doc/docs/hcs合同/2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理.md b/doc/docs/hcs合同/2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理.md index 553257f6..47071b63 100644 --- a/doc/docs/hcs合同/2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理.md +++ b/doc/docs/hcs合同/2026-10-22-收款认领推送金蝶完成后同步合同合规系统（C103-9履约计划-C107-1认领记录-C108-1履约流水）业务流程梳理.md @@ -1,6 +1,6 @@ # 收款认领推送金蝶完成后同步合同合规系统（C103-9 履约计划 + C107-1 认领记录 + C108-1 履约流水）业务流程梳理 -> 需求：金蝶认领推送（A301-3）完成后，把认领记录推送给合同合规系统（HCS）——① C103-9 更新合同履约计划（认领金额累加到收款计划行并重推）；② C107-1 新增认领记录；③ C108-1 新增履约流水。整体做一个开关。 +> 需求：金蝶认领推送（A301-3）完成后，把认领记录推送给合同合规系统（HCS）——① C103-9 更新合同履约计划（认领金额累加到收款计划行并重推）；② C107-1 新增认领记录；③ C108-1 新增履约流水。开关复用既有配置（exe-stage / perf-record），不单独新增。 > 关键口径：C107-1 的 `fdCollectionFlow.fdId` 为**合规系统自己的收款流水ID**（非 TMS 本地主键），经 C104-2 按明细流水号定位（合规侧流水由合规自 ERP 同步，与 TMS A301-2 镜像同源）；C107-1/C108-1 引用的履约项ID 均为 C103-9 返回的阶段ID（hcs_stage_fd_id）。 > 代码改动日期：2026-10-22，`mvn compile` 通过。 @@ -11,7 +11,7 @@ | # | 规则 | 说明 | | --- | --- | --- | | 1 | 触发点唯一：A301-3 推送成功之后 | 挂在 `pushClaimLocked`（金蝶认领推送事务模板）返回成功后执行，手动「推送金蝶」按钮与定时任务两条路共用；金蝶推送事务已提交，合规推送失败不影响金蝶推送结果 | -| 2 | 总开关 | `thirdParty.hcs.claim.sync-enabled`（`HcsProperties.claim.syncEnabled`，默认 false），关闭时整个认领链不执行、零开销 | +| 2 | 开关复用既有配置（不新增） | `exe-stage.sync-enabled`（履约计划同步，与合同链 C103-9 同开关）门禁 C103-9/C107-1；`perf-record.sync-enabled`（履约记录同步，与付款链 C108 同开关）门禁 C108-1。exe-stage 关闭时整个认领链不执行、零开销 | | 3 | 按合同分组推送 | 有效认领分摊行（`blade_receipt_claim_settlement` status=1 且未删）经结算单 `contract_id` 归集，逐合同推送；**单合同失败不影响其余合同** | | 4 | 编排顺序：C103-9 → C107-1 → C108-1 | 先更新履约计划（认领金额累加重推），因为 C107-1 的 `fdExePlanStageId` 与 C108-1 的 `fd_plan_id` 都引用 C103-9 返回的阶段ID（与付款链 C103-9→C108 同口径） | | 5 | 认领金额累加口径 | `coalesce(fund_amount, 0) + 认领金额` 原子累加到收款计划行（防并发丢更新）；已同步行置 `row_op=update` 凭阶段ID 重推 C103-9，未同步行保持 `add` 待合同链路首推（首推即携带累加后金额）——与付款审批累加逻辑完全对称 | @@ -35,13 +35,13 @@ ▼ A301-3 推送成功（push_status=pushed、回填金蝶收款单号）★事务已提交 ▼ -HCS 收款认领链（开关 thirdParty.hcs.claim.sync-enabled，失败仅日志） +HCS 收款认领链（开关 exe-stage.sync-enabled 门禁 C103-9/C107-1、perf-record.sync-enabled 门禁 C108-1，失败仅日志） ├─① 归集：有效分摊行 × 结算单 → 按合同分组（合同id → 认领主单id → 金额） └─② 逐合同推送（单合同失败 continue 下一合同） ├─ C103-9 更新履约计划：认领金额累加收款计划行 → 已同步行重推 ├─ C104-2 定位合规收款流水ID（明细流水号精确匹配，一次定位全程共用；失败仅跳过 C107-1） ├─ C107-1 认领记录 × N（按「认领主单 × 合同」分组，每组合一条） - └─ C108-1 履约流水 × 1（按合同一条：金额=该合同累计认领金额） + └─ C108-1 履约流水 × 1（perf-record 开关开启时；须有已同步收款计划行提供 fd_plan_id） ``` ### 2.2 代码视角（HcsClaimSyncSupport.pushClaimToHcs） @@ -52,7 +52,7 @@ ReceiptFlowServiceImpl.pushClaimLocked(flowId, announce) │ result.isSuccess() ? ▼ yes hcsClaimSyncSupport.pushClaimToHcs(flowId) - ├─ 开关关闭 → return（静默） + ├─ exe-stage.sync-enabled 关闭 → return（静默，整个认领链不执行） ├─ try doPushClaimToHcs(flowId) catch → log.error（不外抛） │ ├─ 查询数据（流水重读 + 认领主单 claimed + 分摊行 status=1/is_deleted=0） @@ -67,7 +67,7 @@ hcsClaimSyncSupport.pushClaimToHcs(flowId) │ └─ 行已同步 → row_op=update + unsynced（"收款认领金额累加，待重推C103-9"） ├─ 合同已推送合规（hcs_fd_id 非空）→ syncExeStages 重推 C103-9（无待同步行返回提示非失败） ├─ C107-1 × 认领主单数：claimRecordAdd（流水引用+合同+阶段ID+认领人+金额+日期+备注，fdStatus=0） - └─ C108-1 × 1：perfRecordAdd（须有已同步收款计划行提供 fd_plan_id，否则跳过） + └─ C108-1 × 1：perfRecordAdd（perf-record 开关开启时；须有已同步收款计划行提供 fd_plan_id，否则跳过） ``` --- @@ -126,9 +126,9 @@ hcsClaimSyncSupport.pushClaimToHcs(flowId) | `feign/IHcsClient.java` | 新增 C104-2 `collectionFlowList` 与路径常量 | | `dto/HcsCollectionFlowVO.java`（新增） | C104-2 分页行出参 | | `dto/HcsPerfRecordPropsDTO.java` | 补充 `fd_plan_id`（fd_plan_id）、`fdJdDocNo`（fd_jd_doc_no）——接口文档新版必填/新增字段 | -| `config/HcsProperties.java` | 新增 `Claim` 配置节（`claim.syncEnabled`，默认 false） | +| `config/HcsProperties.java` | 无改动（认领链复用既有 `exe-stage` / `perf-record` 开关，未新增配置项） | | `service/IContractExeStageService.java` + Impl | 新增 `findCollectionStageRow`（progress 精确匹配→首条收款行兜底）与 `accumulateClaimedAmountOnPush`（原子累加+标记重推） | -| `doc/nacos/third-party-api.yaml`、`blade-dev.yaml` | hcs 节点新增 `claim.sync-enabled` 配置样例 | +| `doc/nacos/third-party-api.yaml`、`blade-dev.yaml` | 无改动（复用既有 exe-stage / perf-record 开关，未新增配置项） | > 无数据库表结构变更、无新增定时任务、无新增页面。 @@ -144,17 +144,22 @@ hcsClaimSyncSupport.pushClaimToHcs(flowId) | 2 | 合同下有**已同步**收款履约计划行（performType=collection，优先 progress） | 金额不累加、C107-1 不带履约项、C108-1 跳过 | | 3 | 合规侧已存在同明细流水号的收款流水（合规自 ERP 同步） | C104-2 查不到 → 仅 C107-1 跳过 | | 4 | HCS 配置可用（baseUrl/鉴权头/xform-id 等，与付款链共用） | 对应接口失败，error 日志留痕 | +| 5 | 开关：`exe-stage.sync-enabled=true`（C108-1 另需 `perf-record.sync-enabled=true`） | exe-stage 关→整链不执行；perf-record 关→仅跳过 C108-1 | -### 5.2 开关配置（Nacos `third-party-api.yaml` / 环境覆盖） +### 5.2 开关配置（复用既有配置，无新增配置项） ```yaml thirdParty: hcs: - claim: - sync-enabled: ${HCS_CLAIM_SYNC_ENABLED:false} # 默认关，联调/灰度后打开 + # 履约规则行级同步开关：门禁认领链 C103-9 更新履约计划 + C107-1 认领记录（当前环境已开） + exe-stage: + sync-enabled: ${HCS_EXE_STAGE_SYNC_ENABLED:true} + # 履约记录同步开关：门禁认领链 C108-1 履约流水（一期暂不对接，默认关） + perf-record: + sync-enabled: ${HCS_PERF_RECORD_SYNC_ENABLED:false} ``` -代码内配置键为 `third-party.hcs.claim.sync-enabled`（横线小写），YAML 驼峰 `thirdParty.hcs.claim.*` 经宽松绑定等价生效，与既有 hcs 配置同节点。 +与合同链 C103-9、付款链 C108 共用同一开关，语义一致：exe-stage 开=履约计划同步对接；perf-record 开=履约记录同步对接。代码内配置键为 `third-party.hcs.exe-stage.sync-enabled` / `third-party.hcs.perf-record.sync-enabled`（横线小写），YAML 驼峰经宽松绑定等价生效。 ### 5.3 业务操作步骤 diff --git a/doc/nacos/blade-dev.yaml b/doc/nacos/blade-dev.yaml index 67ad9acd..571180d4 100644 --- a/doc/nacos/blade-dev.yaml +++ b/doc/nacos/blade-dev.yaml @@ -327,10 +327,6 @@ thirdParty: sync-enabled: ${HCS_PERF_RECORD_SYNC_ENABLED:false} # 表单模板ID（fd_xform_id，环境相关值，§9-U9 待合规方提供） xform-id: ${HCS_PERF_RECORD_XFORM_ID:} - # 收款认领链（金蝶认领推送成功后：C103-9 更新履约计划 + C107-1 认领记录 + C108-1 履约流水） - claim: - # 认领链同步总开关（默认关，对接后打开） - sync-enabled: ${HCS_CLAIM_SYNC_ENABLED:false} # 附件转传（C103-2） attachment: # 附件转传总开关 diff --git a/doc/nacos/third-party-api.yaml b/doc/nacos/third-party-api.yaml index 201d6ddc..8ca005cc 100644 --- a/doc/nacos/third-party-api.yaml +++ b/doc/nacos/third-party-api.yaml @@ -250,10 +250,6 @@ thirdParty: sync-enabled: ${HCS_PERF_RECORD_SYNC_ENABLED:false} # 表单模板ID（fd_xform_id，环境相关值，§9-U9 待合规方提供） xform-id: ${HCS_PERF_RECORD_XFORM_ID:} - # 收款认领链（金蝶认领推送成功后：C103-9 更新履约计划 + C107-1 认领记录 + C108-1 履约流水） - claim: - # 认领链同步总开关（默认关，对接后打开） - sync-enabled: ${HCS_CLAIM_SYNC_ENABLED:false} # 附件转传（C103-2） attachment: # 附件转传总开关