From 4cd7fb24df92091f782004773ff12acff1fd4b97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com> Date: Fri, 9 Oct 2026 12:00:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20HCS=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=B8=8E=E5=AE=9E=E6=96=BD=E6=B8=85=E5=8D=95=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E4=B8=80=E6=9C=9F=E8=8C=83=E5=9B=B4=E8=B0=83=E6=95=B4=EF=BC=88?= =?UTF-8?q?20=E6=8E=A5=E5=8F=A3=E5=8F=A3=E5=BE=84=EF=BC=8CC103-9/C106-1/C1?= =?UTF-8?q?08=E8=AE=B0=E5=BD=95=E6=9A=82=E4=B8=8D=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E5=8F=8A=E7=89=B9=E6=89=B9=E8=A7=A6=E5=8F=91=E5=BD=B1=E5=93=8D?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...2026-09-27-桂物合同合规系统HCS接入技术设计.md | 18 ++++++++++++------ .../2026-09-28-HCS接入实施状态与确认清单.md | 11 +++++++---- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/doc/docs/hcs合同/2026-09-27-桂物合同合规系统HCS接入技术设计.md b/doc/docs/hcs合同/2026-09-27-桂物合同合规系统HCS接入技术设计.md index 64822019..a5d16f3a 100644 --- a/doc/docs/hcs合同/2026-09-27-桂物合同合规系统HCS接入技术设计.md +++ b/doc/docs/hcs合同/2026-09-27-桂物合同合规系统HCS接入技术设计.md @@ -16,7 +16,7 @@ | D1 | 客户端模块 | 新建 `blade-third-party-api/blade-hcs-api`，客户端 `IHcsClient`，配置前缀 `thirdParty.hcs.*`（照 blade-bfi-api 模式） | | D2 | 认证 | v4 接口说明：所有接口固定携带 `Authorization`（整值可配）+ `Key-Auth` 两个静态请求头，由拦截器统一注入，不再调用 getToken 取令牌 | | D3 | 网络 | 直连 `base-url` 可配置（Nacos），预留 iPaaS 前缀能力，代码不感知 | -| D4 | 范围 | 一期 24 个接口：C101-1、C102-1/2/3、C103-1/2/3/4/6/7/9(新)/11/12、C106-1/3/4、C108-1/2、C109-1/2、C111-1/2/3；排除 C104、C107、废弃旧履约接口 | +| D4 | 范围 | 一期 20 个接口：C101-1、C102-1/2/3、C103-1/2/3/4/5/6/7/11/12、C106-3/4、C109-1/2、C111-1/2/3；排除 C104、C107、C103-9(新)/C103-10旧、C106-1、C108-1/2（范围调整见 §2.2） | | D5 | TMS 角色 | TMS 是业务发起方：立项/合同/履约规则/特批/开票/收票/履约记录由 TMS 推送 | | D6 | 落库模式 | 业务表加 `hcs_*` 集成字段；新建履约规则表 `blade_contract_exe_stage`；不建合规镜像库 | | D7 | 可靠性 | 同步状态机 + `@Scheduled` 扫描首推/补偿 + 页面手动重推；Feign 无自动 Retryer；写前判重查询 | @@ -33,7 +33,7 @@ ## 2. 范围 -### 2.1 接口范围（24 个） +### 2.1 接口范围（20 个，2026-10-09 调整：C103-9/C106-1/C108-1/2 暂不对接） | 场景组 | 接口 | TMS 触发业务 | |---|---|---| @@ -41,17 +41,18 @@ | 合同 | C103-1 发起 / C103-11 更新 / C103-3 列表 / C103-4 详情 | ContractManage 审批通过 / 变更审批通过 / 判重与回查 | | 附件 | C103-2 上传（下载 C103-5 备用） | 各单据推送前附件转传 | | 主数据 | C103-6 模板 / C103-7 分类 / C103-12 币种 | 下拉/映射（模板ID、币种ID 缓存） | -| 履约规则 | C103-9(新) 行级同步 | blade_contract_exe_stage（合同维度） | | 客商风险 | C101-1 | 合同推送前 + 付款提交前校验 | -| 额度与特批 | C106-1 校验 / C106-3 特批发起 / C106-4 特批更新 | PaymentApplication 提交时 / 审批通过后 | -| 履约记录 | C108-1 新增 / C108-2 更新 | PaymentApplication 审批通过 / 实际付款推进 | +| 额度与特批 | C106-3 特批发起 / C106-4 特批更新 | ~~额度超额自动转特批~~ 暂无自动触发（依赖 C106-1，见 §2.2） | | 开票登记 | C111-1 查询 / C111-2 新增 / C111-3 更新 | InvoiceApplication 审批通过 / 金蝶开票完成 | | 收票单 | C109-1 新建 / C109-2 更新 | InvoiceReceipt 审批通过 / 票据变更 | ### 2.2 明确排除（No-s） +- **2026-10-09 范围调整（暂不对接，代码开关默认关闭，接入时打开配置即可）**： + - **C103-9（新）履约计划保存 / C103-10旧 履约计划更新**：合同链路第⑤步履约规则同步跳过（`exe-stage.sync-enabled=false`），`blade_contract_exe_stage` 表与维护端点保留，仅不再上报 HCS。 + - **C106-1 额度校验**：付款提交校验只保留 C101-1 客商风险（`credit.check-enabled=false`）；特批 C106-3 失去自动触发源（原依赖 fdIsCredit=false 置 need），暂无自动触发。 + - **C108-1/C108-2 履约记录**：付款链路跳过履约记录推送（`perf-record.sync-enabled=false`），付款单直接置 synced。 - **C104 收款流水（C104-1/2/3）、C107 认领记录（C107-1/2/3）**：不由 TMS 推送，推送方与链路待定（见 ADR-0003）。 -- **C103-9旧 / C103-10旧**：合规方已废弃，不接。 - 附件下载 C103-5：仅在对账/排查需要时备用接入。 --- @@ -365,18 +366,23 @@ thirdParty: special-contract-enabled: false require-risk-check: true exe-stage: + sync-enabled: false # C103-9 履约规则同步开关（一期暂不对接，默认关） fund-type: byAmount risk: check-on-contract: true check-on-payment: true block-blacklist: true credit: + check-enabled: false # C106-1 额度校验开关（一期暂不对接，默认关；关闭后特批无自动触发） require-contract-synced: true spec-pay: doc-status: "10" payment-purpose: "" # 字典值联调后配置 payment-nature: "" payment-type: "" + perf-record: + sync-enabled: false # C108-1/2 履约记录同步开关（一期暂不对接，默认关） + xform-id: "" invoice: invoice-type-mapping: {"electronic_normal": "", "electronic_special": ""} currency-id-mapping: {"RMB": ""} # {TMS币种码: HCS币种fdId} diff --git a/doc/docs/hcs合同/2026-09-28-HCS接入实施状态与确认清单.md b/doc/docs/hcs合同/2026-09-28-HCS接入实施状态与确认清单.md index 131f400d..ed57b841 100644 --- a/doc/docs/hcs合同/2026-09-28-HCS接入实施状态与确认清单.md +++ b/doc/docs/hcs合同/2026-09-28-HCS接入实施状态与确认清单.md @@ -32,10 +32,10 @@ |---|---|---| | `HcsProjectSyncSupport` | C102-3 判重（命中回填跳过）→ C102-1 新建 / C102-2 更新；万元×10000 换算；合规 fdId 回填；手动重推 | ✅ | | `HcsContractSyncSupport` | 链路编排：①C101-1 甲乙双方风险校验（留痕 check_log + `hcs_risk_*`，黑名单且 block-blacklist 阻断）→ ②附件转传 → ③C103-3 判重 → ④C103-1 起草/C103-11 更新（先持久化 fdId 再走后续）→ ⑤履约规则同步 | ✅ | -| `HcsExeStageSyncSupport` | C103-9 行级同步：聚合 row_op 非 none 行（add 不带 fdId、update/delete 必带），整体操作首推 add/后续 update；fdExeplanId 与阶段 fdId 按行回填持久化；软删行经原生 SQL 照常上报 delete | ✅ | -| `HcsCreditCheckSupport` | 付款提交事务内同步校验：C101-1 黑名单阻断提交；C106-1 超额不拦截、置 over + spec=need 转特批（超额时 success 仍 true，以 fdIsCredit 为准） | ✅ | -| `HcsSpecPaySyncSupport` | C106-3 发起（双层嵌套 fdId → hcs_spec_fd_id，状态 processing）/ C106-4 更新；特批附件 fdEntityKey=fd_spc_approval_attach、发起带 fdBindType=ADD | ✅ | -| `HcsPerfRecordSyncSupport` | C108-1 新建（fdId 回填 hcs_perf_fd_id）/ C108-2 更新（实际金额）；关联履约阶段 fd_id；附件 fd_plan_att | ✅ | +| `HcsExeStageSyncSupport` | C103-9 行级同步：聚合 row_op 非 none 行（add 不带 fdId、update/delete 必带），整体操作首推 add/后续 update；fdExeplanId 与阶段 fdId 按行回填持久化；软删行经原生 SQL 照常上报 delete。**2026-10-09 调整：一期暂不对接，`exe-stage.sync-enabled` 默认关，合同链路跳过本步骤** | ✅（开关默认关） | +| `HcsCreditCheckSupport` | 付款提交事务内同步校验：C101-1 黑名单阻断提交；C106-1 超额不拦截、置 over + spec=need 转特批（超额时 success 仍 true，以 fdIsCredit 为准）。**2026-10-09 调整：C106-1 一期暂不对接，`credit.check-enabled` 默认关，仅保留 C101-1；关闭后特批无自动触发** | ✅（C106-1 开关默认关） | +| `HcsSpecPaySyncSupport` | C106-3 发起（双层嵌套 fdId → hcs_spec_fd_id，状态 processing）/ C106-4 更新；特批附件 fdEntityKey=fd_spc_approval_attach、发起带 fdBindType=ADD。**C106-1 暂不对接后无自动置 need，仅历史数据/人工场景可达** | ✅ | +| `HcsPerfRecordSyncSupport` | C108-1 新建（fdId 回填 hcs_perf_fd_id）/ C108-2 更新（实际金额）；关联履约阶段 fd_id；附件 fd_plan_att。**2026-10-09 调整：一期暂不对接，`perf-record.sync-enabled` 默认关，付款链路跳过履约记录直接置 synced** | ✅（开关默认关） | | `HcsPaymentSyncSupport` | 付款链编排（特批→履约记录）+ 整体状态回写 + 特批结果人工确认（§9-U1 过渡） | ✅ | | `HcsInvoiceRegSyncSupport` | C111-1 判重 / C111-2 新增 / C111-3 票据日期回填（金蝶回写发票最新 invoiceDate）；合同编号经应收结算链路回溯 | ✅ | | `HcsReceiptBillSyncSupport` | C109-1 新建（双层嵌套 fdId）/ C109-2 更新；合同回溯 + 人工补录兜底；税率 ÷100；fd_bill_date 为 YYYY-MM-DD 字符串 | ✅ | @@ -91,6 +91,9 @@ | 项 | 说明 | |---|---| +| **C103-9 履约计划保存 / C103-10 履约计划更新（2026-10-09 范围调整）** | 一期暂不对接：合同链路第⑤步跳过（`exe-stage.sync-enabled=false`）；`blade_contract_exe_stage` 表与维护端点保留，仅不上报 HCS；C103-10旧 合规方本已废弃 | +| **C106-1 额度校验（2026-10-09 范围调整）** | 一期暂不对接：付款提交校验只保留 C101-1（`credit.check-enabled=false`）；特批 C106-3 失去自动触发源，暂无自动触发（历史 need 数据/人工场景仍可推） | +| **C108-1/C108-2 履约记录（2026-10-09 范围调整）** | 一期暂不对接：付款链路跳过履约记录推送（`perf-record.sync-enabled=false`），付款单直接置 synced | | C104 收款流水（C104-1/2/3）、C107 认领记录（C107-1/2/3） | ADR-0003 边界排除：推送方与链路待定，TMS 不承担；Feign 端点也未建 | | 付款申请/开票/收票的 MK 处理器**补齐** | 约束"他人负责"。注：现状 PaymentHandler 实际已由他人注册（探索发现），本次仅按零埋点约定补了 1 行状态置位，未动处理器归属；开票/收票仍无 MK 处理器，直批入口已接线，未来新处理器只要置 approved 即被扫描自动覆盖 | | 前端页面改动 | 列表页"推送合规/重推"按钮、履约规则页签、特批结果确认入口、对账查询页——本次只交付后端端点，前端（tms-erp-web）未动 |