From 30ba7c6b3a1e275e99f83787e1773f779e146976 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com> Date: Wed, 28 Oct 2026 19:31:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9EC108=E5=B1=A5?= =?UTF-8?q?=E7=BA=A6=E8=AE=B0=E5=BD=95=E5=9B=9B=E5=9C=BA=E6=99=AF=E6=8E=A8?= =?UTF-8?q?=E9=80=81=E6=94=B9=E9=80=A0=E4=B8=8E=E9=AA=8C=E8=AF=81=E6=8C=87?= =?UTF-8?q?=E5=BC=95=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...四场景推送改造流程梳理（收款-付款-开票-收票）.md | 263 ++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md diff --git a/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md b/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md new file mode 100644 index 00000000..f85fd850 --- /dev/null +++ b/doc/docs/hcs合同/2026-10-28-C108履约记录四场景推送改造流程梳理（收款-付款-开票-收票）.md @@ -0,0 +1,263 @@ +# C108 履约记录四场景推送改造流程梳理（收款/付款/开票/收票） + +> 日期：2026-10-28 +> 范围：`tms-api` blade-transport HCS 推送链路；合同系统（HCS）接口 C108-1 履约记录新建 / C108-2 履约记录更新 +> 关联文档：《2026-10-27-履约计划与履约记录逻辑与流程梳理》（改造前基线） + +--- + +## 1. 需求口径 + +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（付款） | + +本次确认的业务口径调整：**履约付款记录由「审批通过即新建」改为「金蝶实际付款后才新建」**。 + +--- + +## 2. 总览：改造前后对照 + +| 场景 | 改造前 | 改造后 | +|------|--------|--------| +| 收款 | 已实现（C108-1），履约日期=最近认领日期 | 履约日期改为交易日期；组装逻辑收敛到通用组件 | +| 付款 | 审批通过即 C108-1 新建，实际付款后 C108-2 更新 | 未实际付款不推送；首次实际付款 C108-1 新建；分期付款推进 C108-2 更新 | +| 开票 | 无（仅 C111 开票登记） | 新增：金蝶回写发票逐张推 C108-1，发票粒度幂等+重试 | +| 收票 | 无（仅 C109 收票单） | 新增：每条结算分摊行推 C108-1，分摊行粒度幂等+重试，且限 C109 已推送 | + +--- + +## 3. 通用机制 + +### 3.1 接口与字段 + +- C108-1：`IHcsClient.perfRecordAdd`，返回 `fdId`（履约记录ID，**必须持久化**，C108-2 更新必传） +- C108-2：`IHcsClient.perfRecordUpdate`，`formData.fdId` 必填，响应无 data，`success=true` 即成功 +- `fd_plan_id`（履约计划id）接口必填：取合同**已同步的履约计划行合规阶段ID**（`blade_contract_exe_stage.hcs_stage_fd_id`）；无已同步计划行时抛出重试，合同链路首推 C103-9 后下轮自愈 +- `fd_paln_type` 为接口文档原文拼写（plan 笔误），必须沿用；取值 `payment` / `collection` +- 机制数据（附件）C108-1 必填：新三场景（收款/开票/收票）无附件传空列表；付款场景保留附件转传逻辑 + +### 3.2 开关 + +统一复用 `thirdParty.hcs.perf-record.sync-enabled`（默认关，灰度打开），无新增配置： +- 收款：门禁 C108-1（C103-9/C107-1 仍由 `exe-stage.sync-enabled` 门禁） +- 付款：门禁 C108-1/C108-2 +- 开票/收票：门禁各自扫描任务，且随宿主任务（invoice-application / invoice-receipt）的 `sync-enabled` 一起生效 + +### 3.3 幂等与重试模式 + +- **付款**：单据粒度，`blade_payment_application.hcs_perf_fd_id` + `hcs_sync_status`（unsynced/synced/failed）+ `hcs_retry_count`，随 HcsPushTask 付款任务扫描重试 +- **开票**：发票粒度，`blade_invoice_application_invoice.hcs_perf_fd_id`（非空即已推，扫描跳过）+ `hcs_perf_retry_count` / `hcs_perf_sync_msg`，失败下轮自动补偿，超上限人工 +- **收票**：分摊行粒度，`blade_invoice_receipt_settlement.hcs_perf_fd_id` + 同上两列；扫描范围限定所属收票单 C109 已推送（`hcs_sync_status=synced`） +- **收款**：认领链事件驱动（金蝶认领推送成功后内联），fdId 暂不落库（shortcut：认领链无 C108-2 场景，重推会重复，需作废联动时先落库） + +### 3.4 通用组件 + +新增 `HcsPerfRecordAddSupport`（transport/support/hcs）：收敛收款/开票/收票三场景的 C108-1 组装与推送（申请金额=实际金额、fd_plan_id 校验、标题、溯源字段），入参：合同、履约计划行、申请编号、金额、履约日期、履约类型、金蝶单据号、业务ID、标题。 +付款场景因含 C108-2 推进与附件转传，保留原 `HcsPerfRecordSyncSupport`。 + +--- + +## 4. 各场景流程明细 + +### 4.1 履约收款记录（对应认领记录） + +``` +认领操作 → 收款流水推送金蝶（A301-3）成功 + → HcsClaimSyncSupport.pushClaimToHcs(flowId) + ① C103-9 认领金额累加收款履约计划行并重推 + ② C107-1 认领记录（按「认领主单 × 合同」分组，金额为分摊到该合同的金额） + ③ C108-1 履约流水（按合同一条） ← 本次改造点 +``` + +- 履约日期：**收款流水交易日期** `blade_kingdee_receipt_flow.transaction_time`（原为最近认领日期，空时兜底当天） +- 申请编号：收款通知单号，兜底明细流水号 +- 申请金额 = 实际金额 = 该合同累计认领金额 +- fd_jd_doc_no：A301-3 返回的金蝶收款单号；fd_business_id：收款流水ID +- 标题：`收款履约-{通知单号}` +- 前置门禁：合同已推送合规（hcs_fd_id 非空）、存在已同步收款计划行，不满足仅记日志跳过 + +### 4.2 履约付款记录（对应付款记录，金蝶实际付款了再推） + +``` +付款申请审批通过（特批通过后） + → HCS 推送链：C106-3 特批（如需）→ C103-9 履约计划重推 + → C108 履约记录环节：paidAmount 为空/0 → 跳过（提示"金蝶未实际付款，待付款后推送履约记录"）★改 + 整体状态照常置 synced + +金蝶实际付款 → 定时任务 A103-2 付款结果回写（applyPayApplyResult） + → paidAmount 首次 >0 或金额变化 → hcs_sync_status 置 unsynced ★改（原仅在有 fdId 时置） + → HcsPushTask 付款任务下轮扫描 → pushPayment + 无 hcs_perf_fd_id → C108-1 新建（申请金额 + 实际金额）→ fdId 回填 hcs_perf_fd_id + 有 hcs_perf_fd_id → C108-2 更新（分期付款推进实际金额） +``` + +- 触发数据源：A103-2 分录 `e_paidamt` 汇总（分录缺失且已付款时兜底申请全额） +- 履约日期：申请日期（fd_plan_date 计划日期口径不变）；C108-2 仅在金额推进时触发，`paying` 状态每轮回写金额不变不再重复推送 +- 标题：`付款履约-{付款申请单号}`；fd_jd_doc_no：金蝶付款申请单号 + +### 4.3 履约开票记录（对应开票申请，金蝶开票完成后推送） + +``` +开票申请审批通过 → 推金蝶（A303-1）→ 推合规 C111 开票登记（票据日期空） +金蝶开票完成 → 定时任务 A303-5 开票结果回写（executeInvoiceResultSync） + → 发票逐张落库 blade_invoice_application_invoice + → 申请单置 kingdeeStatus=invoiced + hcs_sync_status=unsynced（触发 C111-3 回填票据日期） + +HcsPushTask 开票任务（每5分钟）： + ① pushUnsyncedInvoiceApplications：C111 开票登记推送/回填 + ② HcsInvoicePerfSyncSupport.pushUnsyncedInvoicePerfRecords ★新增 + 扫描 hcs_perf_fd_id IS NULL 且重试未超限的发票 + → 批量装配：申请单（须审批通过）→ 应收结算关联 → 正式结算单合同 → 收款履约计划行 + → 每张发票一条 C108-1：金额=发票价税合计，履约日期=发票完成开票日期 + → 成功回填 hcs_perf_fd_id；失败 retry+1 记 hcs_perf_sync_msg 下轮补偿 +``` + +- 申请编号：发票号；fd_jd_doc_no：金蝶开票申请单编号（serialNo）；fd_business_id：发票记录ID +- 标题：`开票履约-{发票号}` +- 合同回溯不到（无应收结算关联/合同）→ 记失败原因，下轮重试（同 C111 §9-U10 口径） + +### 4.4 履约收票记录（对应收票单每条结算信息） + +``` +收票登记审批通过 + → 推金蝶收票单（A303-2 + A302-6） + → HcsPushTask 收票任务（每5分钟）： + ① pushUnsyncedInvoiceReceipts：C109 收票单推送合规 + ② HcsReceiptPerfSyncSupport.pushUnsyncedReceiptPerfRecords ★新增 + 扫描 hcs_perf_fd_id IS NULL 且重试未超限的分摊行， + 且所属收票单 hcs_sync_status=synced（C109 已推送）+ 审批通过 + → 每条结算信息一条 C108-1：金额=分摊收票金额（兜底结算金额）， + 履约日期=收票单发票日期，履约类型 payment，关联合同付款履约计划行 + → 成功回填 hcs_perf_fd_id；失败 retry+1 记 hcs_perf_sync_msg 下轮补偿 +``` + +- 申请编号：`{发票号}-{结算单号}`（同一发票分摊多结算单时逐条可区分）；标题：`收票履约-{发票号}-{结算单号}` +- fd_jd_doc_no：金蝶收票单号（`kingdee_received_invoice_no`）；fd_business_id：分摊行ID +- 合同回溯：分摊行 → 正式结算单 → contractId + +--- + +## 5. 定时任务编排（改造后） + +| 任务 | cron（默认） | 内容 | +|------|-------------|------| +| 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（分摊行粒度）** | +| （收款无独立任务） | 事件驱动 | 金蝶认领推送（A301-3）成功后内联：C103-9 → C107-1 → C108-1 | + +--- + +## 6. 数据库变更 + +`doc/sql/transport/blade_invoice_application_invoice_perf_20261028.sql`、`blade_invoice_receipt_settlement_perf_20261028.sql`： + +- `blade_invoice_application_invoice` 加 `hcs_perf_fd_id varchar(64)` / `hcs_perf_retry_count int` / `hcs_perf_sync_msg varchar(512)` +- `blade_invoice_receipt_settlement` 加同三列 + +--- + +## 7. 关键代码位置 + +| 文件 | 说明 | +|------|------| +| `support/hcs/HcsPerfRecordAddSupport.java` | ★新增 通用 C108-1 组件（收款/开票/收票共用） | +| `support/hcs/HcsInvoicePerfSyncSupport.java` | ★新增 履约开票记录扫描推送 | +| `support/hcs/HcsReceiptPerfSyncSupport.java` | ★新增 履约收票记录扫描推送 | +| `support/hcs/HcsClaimSyncSupport.java` | 改：履约日期→交易日期；组装改调通用组件 | +| `support/hcs/HcsPaymentSyncSupport.java` | 改：C108 环节增加「金蝶实际付款」门禁 | +| `service/impl/PaymentApplicationServiceImpl.java` | 改：实际付款推进置 unsynced（不再要求已有 fdId；金额不变不重复触发） | +| `task/HcsPushTask.java` | 改：开票/收票任务追加履约记录推送；组合方法改 public 供手动批量入口复用 | +| `controller/HcsSyncController.java` | 改：`POST /hcs/sync/invoice-application|invoice-receipt` 批量入口改走组合方法（手动触发也推履约记录） | +| `pojo/entity/InvoiceApplicationInvoice.java`、`InvoiceReceiptSettlement.java` | 改：加 3 个 hcs_perf_* 字段 | + +--- + +## 8. 验证指引 + +### 8.1 前置准备 + +1. **执行 SQL**：`doc/sql/transport/blade_invoice_application_invoice_perf_20261028.sql`、`blade_invoice_receipt_settlement_perf_20261028.sql`（两表各加 3 列）。 +2. **编译**：`mvn clean compile -DskipTests -pl blade-service/blade-transport -am`（已验证通过）。 +3. **Nacos 开关**（`third-party-api.yaml` / 环境配置）： + - `thirdParty.hcs.perf-record.sync-enabled: true`（履约记录总开关，四场景共用，默认关） + - 宿主任务开关：`thirdParty.hcs.push.payment.sync-enabled`、`thirdParty.hcs.push.invoice-application.sync-enabled`、`thirdParty.hcs.push.invoice-receipt.sync-enabled`（定时任务与手动批量共用） + - 收款链另需 `thirdParty.hcs.exe-stage.sync-enabled: true`（门禁 C103-9/C107-1） + - 环境项照旧：`thirdParty.hcs.base-url/authorization/key-auth`、`perf-record.xform-id` +4. **基础数据**：合同已推送合规（`blade_contract_manage.hcs_fd_id` 非空）且存在已同步履约计划行（`blade_contract_exe_stage.hcs_stage_fd_id` 非空，收款场景需收款行、付款/收票需付款行、开票需收款行）——`fd_plan_id` 必填来源，无则推送记失败等待合同链路首推后自愈。 + +### 8.2 手动触发入口（联调不等定时任务） + +| 动作 | 接口 | +|------|------| +| 认领推送金蝶（收款链触发点） | `POST /receipt-flow/push-kingdee` | +| 付款结果回写（A103-2/A103-4） | `POST /payment-application/sync-kingdee-result` | +| 开票结果回写（A303-5 发票落库） | `POST /invoice-application/sync-kingdee-invoice-result` | +| 收票单推送金蝶（A303-2+A302-6） | `POST /invoice-receipt/push-kingdee` | +| HCS 批量扫描一轮（含履约记录） | `POST /hcs/sync/payment`、`/hcs/sync/invoice-application`、`/hcs/sync/invoice-receipt` | +| HCS 单条重推（付款） | `POST /hcs/sync/payment/{付款申请ID}` | + +> 注意：开票/收票的手动批量与定时任务走同一组合方法（C111/C109 + 履约记录一起推）；单条重推仅覆盖 C111/C109 主单据，发票/分摊行粒度的履约重推走批量扫描（fdId 为空的行自动补偿）。 + +### 8.3 分场景验证步骤 + +**场景 1｜履约收款记录** + +1. 页面对收款流水做认领（分摊到关联合同的正式结算单），推送金蝶认领：`POST /receipt-flow/push-kingdee`。 +2. TMS 日志：`HCS认领记录推送成功` → `HCS履约流水新建成功`（含 perfFdId）。 +3. HCS 侧核对履约记录：标题 `收款履约-{通知单号}`、申请/实际金额=该合同累计认领金额、**fd_plan_date=收款流水交易日期**（改造点，不再是最早/最近认领日期）、fd_plan_id=收款计划行阶段ID。 +4. 边界：交易时间为空的流水 → fd_plan_date 兜底当天；认领作废不触发推送。 + +**场景 2｜履约付款记录（金蝶实际付款了再推）** + +1. 付款申请审批通过并推金蝶（`POST /payment-application/sync-kingdee`）；此时**不应**产生履约付款记录——日志出现 `金蝶未实际付款，待付款后推送履约记录`，HCS 侧无记录。 +2. 在金蝶完成实际付款后，手动回写：`POST /payment-application/sync-kingdee-result`。 +3. 数据库：`SELECT paid_amount, hcs_sync_status FROM blade_payment_application WHERE id=?` → paid_amount>0 且 hcs_sync_status=unsynced。 +4. 手动扫描：`POST /hcs/sync/payment` → 日志 `HCS履约记录新建成功`（C108-1）→ 数据库 `hcs_perf_fd_id` 回填。 +5. 分期付款（金蝶再次付款）→ 再触发回写 → 金额变化置 unsynced → 再扫描 → 日志 `HCS履约记录更新成功`（C108-2）；HCS 侧 fd_fact_amount 与最新 paid_amount 一致。 +6. 反向验证：`paying` 状态下连续两轮回写但金额不变 → 不置 unsynced、不重复推送。 + +**场景 3｜履约开票记录** + +1. 开票申请审批通过 → 推金蝶 → 金蝶完成开票后手动回写：`POST /invoice-application/sync-kingdee-invoice-result` → `blade_invoice_application_invoice` 落库发票。 +2. 手动扫描：`POST /hcs/sync/invoice-application` → 汇总含 `履约开票记录：扫描 X 张，成功 X 张`。 +3. 数据库：`SELECT invoice_no, invoice_date, hcs_perf_fd_id, hcs_perf_sync_msg FROM blade_invoice_application_invoice WHERE invoice_application_id=?` → 每张发票 fdId 回填、msg 清空。 +4. HCS 侧核对：每张发票一条履约记录、标题 `开票履约-{发票号}`、**fd_plan_date=发票完成开票日期**、金额=发票价税合计、fd_plan_id=收款计划行阶段ID。 +5. 失败重试：构造失败（如临时断开 HCS / 删掉合同 hcs_fd_id）→ fdId 保持空、`hcs_perf_retry_count` 每轮 +1、`hcs_perf_sync_msg` 记录原因；恢复后下轮自动补推成功。 + +**场景 4｜履约收票记录** + +1. 收票登记（分摊到结算单）审批通过 → 推金蝶：`POST /invoice-receipt/push-kingdee`。 +2. 手动扫描：`POST /hcs/sync/invoice-receipt` → 先 `C109 收票单推送成功`，再 `履约收票记录：扫描 X 条，成功 X 条`。 +3. 数据库：`SELECT formal_settlement_no, allocated_invoice_amount, hcs_perf_fd_id, hcs_perf_sync_msg FROM blade_invoice_receipt_settlement WHERE invoice_receipt_id=?` → 每条分摊行 fdId 回填。 +4. HCS 侧核对：每条结算信息一条履约记录、申请编号 `-{发票号}-{结算单号}`、**fd_plan_date=收票单发票日期**、金额=分摊收票金额、fd_plan_id=付款计划行阶段ID、履约类型 payment。 +5. 依赖顺序验证：C109 未推送成功时先扫描 → 分摊行 `hcs_perf_sync_msg` 记"收票单尚未推送合规"；C109 成功后下轮自动补推，无需人工干预。 + +### 8.4 通用检查点 + +| 检查项 | 方法 | 预期 | +|--------|------|------| +| 幂等 | 同条件连续触发两轮 `/hcs/sync/{bizType}` | 第二轮履约记录扫描 0 条（fdId 非空跳过），HCS 无重复记录 | +| 失败重试上限 | 持续失败场景观察 | `hcs_perf_retry_count` 达 `thirdParty.hcs.push.max-retry`（默认 5）后不再扫描，人工处理后重置计数 | +| 履约日期口径 | HCS 侧逐条核对 fd_plan_date | 收款=交易日期 / 开票=发票开票日期 / 收票=发票日期 / 付款=申请日期 | +| 溯源字段 fd_business_id | HCS 侧核对 | 付款=付款申请ID、收款=流水ID、开票=发票记录ID、收票=分摊行ID | +| 开关关闭回归 | `perf-record.sync-enabled=false` 后触发各链路 | 金蝶/合规主流程（A301-3、C111、C109）不受影响，仅履约记录跳过 | +| 日志 | 检索 `HCS履约` | 推送开始/成功/失败成对出现，失败带响应 msg 与重试计数 | + +> 服务端核对路径：HCS 管理端按 `fd_doc_subject`（收款履约-/付款履约-/开票履约-/收票履约-前缀）检索履约记录列表。 + +--- + +## 9. 联调注意事项与风险 + +1. **fd_paln_type / 款项性质口径**：开票=collection+收款进度款计划行、收票=payment+付款进度款计划行，为按履约计划行方向推定的口径，需与合规侧确认。 +2. **C108-1 无服务端判重键**：新三场景极端情况下「推送超时但远端已成功」的重试可能在合同系统产生重复记录（与既有 C107-1 同风险）；开票/收票有本地 fdId 幂等只能防"确认成功后"的重复，不能防"未知结果"的重试。 +3. **收票履约依赖 C109 先推**：收票单未推送合规（或推送失败）时分摊行记失败原因等待，C109 成功后下轮自动补偿。 +4. **存量数据**：改造前已按「审批通过即新建」推送过履约付款记录的单据（已有 `hcs_perf_fd_id`），后续金额推进仍走 C108-2，行为兼容；开票/收票新场景上线后只会处理新落库数据（`hcs_perf_fd_id` 为空的历史发票会被补推，如需排除请手工回填标记）。 +5. 测试由业务侧执行；开关 `thirdParty.hcs.perf-record.sync-enabled` 默认关闭，灰度打开后观察 HcsPushTask 日志（前缀 `HCS履约`）。