docs: HCS设计文档与实施清单同步一期范围调整（20接口口径，C103-9/C106-1/C108记录暂不对接及特批触发影响）
This commit is contained in:
刘泉佳
@@ -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}
|
||||
|
||||
@@ -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）未动 |
|
||||
|
||||
Reference in New Issue
Block a user