docs: HCS技术设计文档入库并同步v4认证口径（静态双头）

- 技术设计文档（2026-09-27）首次入库：D2/§3.2/§7 更新为固定双请求头方案 - 实施状态清单：认证组件条目改写，待确认项改为附件接口头生效性 - nacos样例配置：base-url指向网关前缀，authorization/key-auth走环境变量注入
2026-10-01 02:06:57 +08:00
parent 6255d65e21
commit c6a817fb3a
3 changed files with 432 additions and 15 deletions
@@ -0,0 +1,423 @@
+# 桂物合同合规系统（HCS）接入技术设计
+
+> **日期**：2026-09-27
+> **依据**：《桂物合同集成相关接口说明-v4.docx》及其整理稿 [桂物合同集成接口逻辑梳理.md](../桂物合同集成接口逻辑梳理.md)、接口调试文件 [桂物合同集成接口-apifox导入.json](../桂物合同集成接口-apifox导入.json)
+> **说明**：设计过程已明确排除《TMS业财融合-集成流程图文字版与业务流程梳理.md》，本文所有场景与规则仅以上述 v4 接口文档与 TMS 代码现状为依据
+> **关联决策**：[ADR-0001 定时扫描推送模式](../../adr/0001-hcs推送采用定时扫描模式.md)、[ADR-0002 履约规则独立数据表](../../adr/0002-履约规则独立数据表.md)、[ADR-0003 收款流水与认领记录不由TMS推送](../../adr/0003-收款流水与认领记录不由TMS推送.md)
+
+---
+
+## 1. 决策记录（共识摘要）
+
+以下决策已经在设计评审中逐项确认：
+
+| # | 决策点 | 结论 |
+|---|---|---|
+| 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、废弃旧履约接口 |
+| D5 | TMS 角色 | TMS 是业务发起方：立项/合同/履约规则/特批/开票/收票/履约记录由 TMS 推送 |
+| D6 | 落库模式 | 业务表加 `hcs_*` 集成字段；新建履约规则表 `blade_contract_exe_stage`；不建合规镜像库 |
+| D7 | 可靠性 | 同步状态机 + `@Scheduled` 扫描首推/补偿 + 页面手动重推；Feign 无自动 Retryer；写前判重查询 |
+| D8 | 交付物 | 本设计文档 + CONTEXT.md + ADR，落 `doc/docs/hcs合同/`（ADR 落 `doc/adr/`） |
+| D9 | 触发模式 | 审批代码零埋点：approve/MK 回调只落 `approved + hcs_sync_status=unsynced`，扫描任务准实时首推（R3-Q1→(c)）。付款申请/开票/收票的 MK 处理器由其他团队补齐，不在本设计范围 |
+| D10 | 履约规则源头 | 新建 `blade_contract_exe_stage`，合同维度维护，C103-9 行级同步，合规 fdId 回填 |
+| D11 | 履约记录来源 | 付款申请为主线：审批通过→C108-1 新增；实际付款推进→C108-2 更新 |
+| D12 | 开票登记时机 | 审批通过即推 C111-2（票据日期空）；金蝶开票完成后 C111-3 回填 |
+| D13 | 收票合同关联 | 应付结算链路自动回溯；回溯不到收票表单加合同字段人工补录 |
+| D14 | 来源标识 | `fd_sources="TMS"`（Nacos `src-system` 可配）；`fd_kingdee_id`=TMS 业务单据主键 |
+| D15 | 特批载体 | 付款申请表加 `hcs_credit_*`/`hcs_spec_*` 字段组；C106-1 提交时同步；超额转 C106-3；**特批结果回传方式未决**（过渡：页面人工确认）；合同 `fdSepcailContract` 一期固定 false |
+
+---
+
+## 2. 范围
+
+### 2.1 接口范围（24 个）
+
+| 场景组 | 接口 | TMS 触发业务 |
+|---|---|---|
+| 项目立项 | C102-1 新建 / C102-2 更新 / C102-3 查询 | ProjectApply 审批通过 / 变更审批通过 / 判重与回查 |
+| 合同 | 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 审批通过 / 实际付款推进 |
+| 开票登记 | C111-1 查询 / C111-2 新增 / C111-3 更新 | InvoiceApplication 审批通过 / 金蝶开票完成 |
+| 收票单 | C109-1 新建 / C109-2 更新 | InvoiceReceipt 审批通过 / 票据变更 |
+
+### 2.2 明确排除（No-s）
+
+- **C104 收款流水（C104-1/2/3）、C107 认领记录（C107-1/2/3）**：不由 TMS 推送，推送方与链路待定（见 ADR-0003）。
+- **C103-9旧 / C103-10旧**：合规方已废弃，不接。
+- 附件下载 C103-5：仅在对账/排查需要时备用接入。
+
+---
+
+## 3. 总体架构
+
+### 3.1 模块与包结构
+
+```
+blade-third-party-api/blade-hcs-api/            （新建，照 blade-bfi-api 模式）
+org.springblade.hcs
+├── constant/HcsConstant.java                  # URI 常量（可被配置覆盖）、认证头名称
+├── config/HcsProperties.java                  # @ConfigurationProperties("thirdParty.hcs")
+├── config/HcsFeignClientConfig.java           # 覆盖全局拦截器、超时（connect 10s / read 60s）
+├── interceptor/HcsAuthInterceptor.java        # 所有请求注入 Authorization + Key-Auth 两个静态认证头（v4）
+├── feign/IHcsClient.java                      # @FeignClient(name="HCS", url="${thirdParty.hcs.base-url}")
+├── dto/                                       # 各接口请求/响应 DTO（HcsResult<T>、HcsPageVO<T>）
+└── util/HcsPageUtil.java                      # queryAllPages 翻页工具（照 BfiUtil，默认上限 50 页）
+
+blade-service/blade-transport/                  （业务侧扩展）
+org.springblade.transport
+├── support/hcs/
+│   ├── HcsProjectSyncSupport.java             # 立项 C102
+│   ├── HcsContractSyncSupport.java            # 合同 C103-1/11 + 前置：风险校验、附件转传、履约规则
+│   ├── HcsExeStageSyncSupport.java            # 履约规则 C103-9
+│   ├── HcsCreditCheckSupport.java             # C106-1 + C101-1（付款提交时同步校验）
+│   ├── HcsSpecPaySyncSupport.java             # 特批 C106-3/4
+│   ├── HcsInvoiceRegSyncSupport.java          # 开票登记 C111
+│   ├── HcsReceiptBillSyncSupport.java         # 收票单 C109
+│   └── HcsAttachmentSupport.java              # 附件转传 + TMS→HCS 附件ID映射缓存
+├── task/HcsPushTask.java                      # @Scheduled 扫描首推/补偿（照 PaymentKingdeeResultTask 模式）
+├── controller/HcsSyncController.java          # 手动推送/重推、校验重放、对账查询端点
+└── entity/HcsContractExeStage.java            # 履约规则实体（blade-transport-api）
+```
+
+依赖方向：`blade-transport` → `blade-hcs-api`（同 blade-transport → blade-bfi-api）。`blade-hcs-api` 不依赖业务模块。
+
+### 3.2 认证设计（D2，v4 接口说明已变更）
+
+- **静态双请求头**：所有接口统一携带 `Authorization` 与 `Key-Auth` 两个请求头，由 `HcsAuthInterceptor` 注入，不再调用 getToken、不做令牌缓存。
+- 两个头的值均为整值可配（Nacos + 环境变量注入）：`third-party.hcs.authorization`（含 `Basic ` 前缀，如 `Basic d2Njazp...`）、`third-party.hcs.key-auth`。前缀/密钥轮换只改配置，不改代码。
+- 未配置时拦截器告警并放行，由对端 401 暴露问题（便于环境配置缺失排查）。
+
+### 3.3 超时与重试（D7）
+
+- Feign：connect 10s / read 60s（照 BfiFeignClientConfig），**不配 Retryer**——写接口重试会造成 HCS 重复建单。
+- 重试职责归扫描任务：失败落 `failed` 状态，下轮扫描按 `hcs_retry_count < max-retry` 自动重试，超限仅人工重推。
+- 幂等：写前判重（见 §5.1/§5.2），并依赖 `fd_kingdee_id`=TMS 主键作为对账/幂等候选键（HCS 侧是否按其幂等，联调确认，见 §9）。
+
+### 3.4 字段标注规范（DTO 组装，照 `pushArBill` 惯例）
+
+所有 Support 组装 HCS 请求 DTO 时，**每个字段赋值的上一行必须以注释标注外部接口字段**，格式照 `KingdeeArBillSyncSupport#pushArBill` 的既有惯例：
+
+- 必填字段：`// 【必填】外部字段中文名`（层级用"主.子"表示，如"往来户.编码"）
+- 非必传字段：`// 外部字段中文名（非必传）：TMS 取值来源说明`
+- 取值来源统一跟在冒号后说明；字段中文名以《桂物合同集成接口逻辑梳理.md》各接口入参表的中文说明为准
+- 待联调确认的字段：`// TODO 待确认：...`，并标注对应设计文档 §9 未决事项编号
+
+示例（C111-2 开票登记 DTO 组装）：
+
+```java
+HcsInvoiceRegAddDTO param = new HcsInvoiceRegAddDTO();
+// 【必填】合同编号：经应收结算链路回溯的合同编号
+param.setFdContractNumber(contractNo);
+// 单据编号：开票申请单号（同租户唯一，判重候选键）
+param.setFdNumber(application.getApplicationNo());
+// 【必填】结算币种：TMS 币种码映射 HCS 币种ID（currency-id-mapping，§9-U3）
+param.setFdCurrencyId(currencyFdId);
+// 开票金额（含税）：本次开票金额 invoiceAmount
+param.setFdInvoiceAmount(application.getInvoiceAmount());
+// TODO 待确认：款项性质，默认 progress，字典值联调后配置（§9-U3）
+param.setFdFundNature(hcsProperties.getInvoice().getFundNatureDefault());
+```
+
+§5 各场景的"字段映射"表即本规范的标注依据：表中"HCS 字段 / TMS 来源 / 备注"三列直接翻译成上述逐字段注释，一一对应，不得遗漏或凭空造字段。
+
+---
+
+## 4. 数据模型变更
+
+SQL 脚本落 `tms-api/doc/sql/transport/`，命名照既有惯例 `blade_xxx_hcs_yyyymmdd.sql`。所有业务表统一追加的集成字段组：
+
+```sql
+hcs_fd_id        varchar(64)   COMMENT '合规系统单据ID（fdId/fdContractId）',
+hcs_sync_status  varchar(16)   DEFAULT 'unsynced' COMMENT '同步状态 unsynced/synced/failed',
+hcs_retry_count  int           DEFAULT 0 COMMENT '推送失败重试次数',
+hcs_sync_time    datetime      COMMENT '最近同步时间',
+hcs_sync_msg     varchar(512)  COMMENT '最近同步结果信息/失败原因'
+```
+
+| 表 | 变更 | 用途 |
+|---|---|---|
+| `blade_project_apply` | +统一字段组 | C102 回填 fdId、状态 |
+| `blade_contract_manage` | +统一字段组、`hcs_exeplan_id varchar(64)`、`hcs_risk_level varchar(8)`、`hcs_black_status varchar(8)`、`hcs_risk_time datetime` | C103 回填、履约计划ID、风险留痕 |
+| `blade_payment_application` | +统一字段组、特批字段组：`hcs_credit_status varchar(16)`（pass/over）、`hcs_credit_msg varchar(512)`、`hcs_credit_time datetime`、`hcs_spec_fd_id varchar(64)`、`hcs_spec_status varchar(16)`（none/need/pushing/processing/approved/rejected） | C106-1 结果、C106-3 流程ID 与状态 |
+| `blade_payment_application` | +履约记录字段：`hcs_perf_fd_id varchar(64)` | C108-1 返回 fdId |
+| `blade_invoice_application` | +统一字段组 | C111 回填 |
+| `blade_invoice_receipt` | +统一字段组、`hcs_contract_id bigint`、`hcs_contract_no varchar(64)`（人工补录兜底） | C109 回填、合同补录 |
+| **`blade_contract_exe_stage`（新建）** | 见 §4.1 | 履约规则 |
+| **`blade_hcs_check_log`（新建）** | id、biz_type、biz_id、check_type（risk/credit）、result、msg、trace_id、create_time | 风险/额度校验留痕（照 ops 日志惯例） |
+
+### 4.1 履约规则表 `blade_contract_exe_stage`（D10）
+
+```sql
+CREATE TABLE blade_contract_exe_stage (
+  id                bigint       PRIMARY KEY,
+  contract_id       bigint       NOT NULL COMMENT '合同ID（blade_contract_manage.id）',
+  perform_type      varchar(16)  NOT NULL COMMENT '履约类型 payment=付款/collection=收款',
+  fund_nature       varchar(16)  COMMENT '款项性质 prepayment/progress/acceptance/retention',
+  fund_amount       decimal(18,2) COMMENT '计划金额（元）',
+  fund_date         datetime     COMMENT '计划资金日期',
+  invoice_rule      varchar(16)  COMMENT '开票规则（如 payFirst）',
+  invoice_cycle     int          COMMENT '账期',
+  fund_type         varchar(16)  DEFAULT 'byAmount' COMMENT '金额类型',
+  is_finish         tinyint      DEFAULT 0 COMMENT '是否完成',
+  row_op            varchar(8)   DEFAULT 'none' COMMENT '行级同步操作 none/add/update/delete',
+  hcs_stage_fd_id   varchar(64)  COMMENT '合规阶段ID（C103-9 返回，update/delete 必用）',
+  hcs_sync_status   varchar(16)  DEFAULT 'unsynced',
+  hcs_sync_msg      varchar(512),
+  tenant_id         varchar(12), create_user bigint, create_time datetime,
+  update_user bigint, update_time datetime, is_deleted tinyint DEFAULT 0
+);
+```
+
+维护入口：合同新建/变更表单的"履约规则"页签。合同审批通过置 `row_op=add`；后续编辑按行差异置 add/update/delete，由扫描任务随合同链路调 C103-9。
+
+---
+
+## 5. 场景设计
+
+> 本节各"字段映射"表是 §3.4 标注规范的依据：Support 组装 DTO 时逐字段照表标注，字段中文名取自《桂物合同集成接口逻辑梳理.md》。
+
+### 5.0 推送引擎（全部场景共用，D9）
+
+```mermaid
+flowchart LR
+    A[业务操作\n提交/审批/变更/付款推进] -->|事务内| B[置 hcs_sync_status=unsynced\n（+特批/履约等业务标记）]
+    B --> C{HcsPushTask\n@Scheduled cron 可配}
+    C -->|扫 unsynced & failed(retry&lt;max)| D[Support 判重查询]
+    D -->|已存在| E[回填 hcs_fd_id → synced]
+    D -->|不存在| F[调 HCS 写接口]
+    F -->|success| E
+    F -->|失败| G[failed + retry_count+1 + msg]
+    H[页面 手动推送/重推] --> F
+```
+
+- **审批零埋点**：`approve()` 与 `MkProcessBizHandlers.approveFromProcess` 只置状态；两审批入口（/approve 与 MK 回调）与未来新入口天然全覆盖。付款申请/开票/收票目前未注册 MK 处理器，**由其他团队补齐，不在本设计范围**——新处理器只要遵循既有约定置 `approvalStatus=approved`，HCS 扫描即自动覆盖，本设计无需任何配套改造。
+- **任务顺序**：项目 → 合同（内含：风险校验→附件转传→C103-1→履约规则 C103-9）→ 付款特批/履约记录 → 开票登记 → 收票单。每类批量 `push.batch-size`（默认 50）。
+- **多实例部署**：任务体加 Redis 分布式锁（照既有 BladeRedis 用法）；若维持单实例部署则与既有金蝶任务一致。
+- **手动入口**：`HcsSyncController` 提供 `POST /hcs/sync/{bizType}/{id}`（单条重推，重置 unsynced）与批量端点，前端列表页加"推送合规/重推"按钮（照"同步金蝶"按钮模式）。
+
+### 5.1 项目立项（C102-1/2/3 ← ProjectApply）
+
+**触发与链路**：审批通过（approve / MK 回调 `project-apply` 处理器）→ `unsynced`；变更审批通过（change_approved）→ 走 C102-2 更新。推送前判重：C102-3 `conditions={"fd_num": projectCode}`，命中则直接回填 `fdId` 置 synced（跳过新建）。
+
+**字段映射**（dynamicProps）：
+
+| HCS 字段 | TMS 来源（ProjectApply） | 备注 |
+|---|---|---|
+| fd_pro_name | projectName | |
+| fd_pro_simple_name | projectShortName | |
+| fd_num | projectCode | |
+| fd_creator_unit | businessDeptName → `{fdName}` | ⚠️ HCS 组织 fdId 无法映射，先传名称（见 §9-U2） |
+| fd_head | principalUserId → 用户登录名 `{fdLoginName}` | |
+| fd_taker_dept | undertakeDeptName → `{fdName}` | 同上 |
+| fd_taker | handlerUserName 对应用户 `{fdLoginName}` | |
+| fd_pay_limit | fundLimit × 10000 | TMS 万元 → HCS 元 |
+| fd_out_invoice_limit | receivableLimit × 10000 | 同上 |
+| fd_pro_content | situationRemark | |
+| fd_is_available | true | 固定 |
+| fd_avail_units | [{fdName: businessDeptName}] | 同 fd_creator_unit |
+| fd_settlement_type | settlementMode | ⚠️ 字典映射待联调（§9-U3） |
+| fd_pro_plan_deposit | fundDemand × 10000 | ⚠️ 变更映射曾名"履约保证金"，语义联调确认 |
+| fd_is_self_pro / fd_pro_income_goal | 无直接对应 | 一期默认 "1" / 不传，联调确认 |
+| fd_kingdee_sync_status | "1" | |
+| fd_sources / fd_kingdee_id | "TMS" / ProjectApply.id | D14 |
+| fd_creator | 当前操作人 `{fdLoginName}` | |
+
+顶层：`bpmOperation.templateCode` ← 配置 `thirdParty.hcs.project.template-code`（环境相关值，§9-U9）；`saveOption.saveDraft=false`。**出参**：`data.fdId` → `hcs_fd_id`。
+
+### 5.2 合同发起/更新（C103-1/11 ← ContractManage）+ 附件 + 履约规则
+
+**触发与链路**：合同审批通过（含变更单 change_approved）→ `unsynced`。扫描任务按序执行：
+1. **风险校验**（可配开关）：C101-1 查甲方/乙方客商风险，结果写 `blade_hcs_check_log` + 合同 `hcs_risk_level/hcs_black_status`；黑名单且 `risk.block-blacklist=true` 时该单置 failed、msg 提示"客商黑名单，禁止推送"。
+2. **判重**：C103-3 `conditions={"fdNumber": contractNo}`（HCS 条件能力联调确认，§9-U4），命中回填跳过。
+3. **C103-1 起草**：成功回填 `data.fdContractId → hcs_fd_id`。
+4. **履约规则 C103-9**（§5.3）。
+5. 变更单（change_approved）→ C103-11 `updateDraft`，入参同发起；⚠️ HCS 侧如何定位已有合同 v4 未说明（§9-U5）。
+
+**xformFields 字段映射**：
+
+| name | TMS 来源（ContractManage） | 备注 |
+|---|---|---|
+| fdNumber / CONTRACT_NO | contractNo | |
+| fdSubject / CONTRACT_NAME | contractName | |
+| fdAmount / AMOUNT | contractAmount | 字符串传值 |
+| fdCurrencyId / CURRENCY | settlementCurrency → "人民币" | 配置 `currency-name-mapping: {"RMB":"人民币"}`（照金蝶 RMB→CNY 惯例） |
+| fdSettlementType | settlementMode | ⚠️ 映射到"付款/收款"待联调（§9-U3） |
+| fdSepcailContract | "false" | D15，配置项预留 |
+| CONTRACT_TYPE | contractCategory | |
+| PARTY_A / PARTY_B | partyA / partyB | TMS 存名称字符串 |
+| SIGN_DATE | signDate | fdType=timestamp |
+| fdEstimateStartTime / fdEstimateEndTime | startDate / endDate | fdType=timestamp |
+| CREATE_TIME / fdCreateTime | createTime | fdType=timestamp |
+| fd_syn_time | 推送时刻 | fdType=timestamp |
+| CREATE_USER_NAME | handlerUserName（承办人） | |
+| CONTRACT_STATUS | — | ⚠️ 无对应，联调确认是否必传（§9-U3） |
+
+**signer[]（相对方）**：`{fdStanding:"甲", fdName:partyA, fdNumber:←按名称反查 CustomerArchive 编码}`、乙方同理。⚠️ TMS 合同只存甲乙方名称，编号反查不到时留空；`fdType`（inner/外部）判定规则联调确认（§9-U6）。
+
+**顶层**：`fdTemplateId` ← `template-mapping[contractCategory]`（Nacos，需合规方提供模板ID清单，§9-U7）；`fdOuterSystem` ← src-system；`fdLoginName` ← handlerUser 登录名；`saveType=submit`。
+
+**合同附件**：⚠️ v4 的 C103-1 入参未定义附件字段——合同附件向 HCS 的传递方式**待合规方确认**（§9-U8）；本设计先按 `HcsAttachmentSupport` 通用转传能力建设（合同主文件 `contractFileJson` 中 approved=true 的文件 + `attachmentsJson`），确认后按其要求挂载。
+
+### 5.3 履约规则同步（C103-9新 ← blade_contract_exe_stage）
+
+- 数据源与表结构见 §4.1（ADR-0002）。
+- **行级同步算法**：扫描任务对 `hcs_sync_status=unsynced` 的合同聚合其规则行：`row_op=add` 的行入 fdStages（不带 fdId）；`update/delete` 行必须带 `hcs_stage_fd_id`。整体 `fdEopExeplanOperateType=add`（或 update，随场景）。顶层 `fdContractId` 传 **HCS 合同ID（hcs_fd_id）**。
+- **回填**：`data.fdExeplanId` → `blade_contract_manage.hcs_exeplan_id`；`data.fdChangeStages[].fdId` 按行回填 `hcs_stage_fd_id`。**合规返回的 fdId 必须持久化**——后续行更新/删除全靠它。
+- fdStages 行字段：fdPerformType、fdFundNature、fdFundAmount（元）、fdFundDate（毫秒）、fdInvoiceRule、fdInvoiceCycle、fdFundType（默认 byAmount）、fdIsFinish、fdExtendContent="{}"。
+
+### 5.4 客商风险 + 额度校验（C101-1 / C106-1 ← PaymentApplication 提交时）
+
+付款申请**提交（submit）事务内同步调用**（查询类同步，D15/R2-Q3）：
+1. **C101-1**：`fdNumber` ← 收款方客商编号（按 payeeName 反查 CustomerArchive；编号体系联调确认 §9-U6）。结果写 `blade_hcs_check_log`；黑名单且 `risk.block-blacklist=true` → 阻断提交。
+2. **C106-1**：`{fdContractId: 合同.hcs_fd_id, fdApplyAmount: appliedAmount}`。`fdIsCredit=true` → `hcs_credit_status=pass` 正常提交；`false` → `hcs_credit_status=over` + `hcs_credit_msg=fdMessage`，**不拦截提交**，标记 `hcs_spec_status=need`（走特批链路，D15/R2-Q2）。
+
+> 校验依赖合同已推送（hcs_fd_id 存在）；合同未推送时按 `credit.require-contract-synced` 配置决定阻断或跳过校验。
+
+### 5.5 结算付款特批（C106-3/4 ← PaymentApplication）
+
+**触发**：审批通过且 `hcs_spec_status=need` → 扫描任务发起 C106-3；返回 `data.data.fdId`（双层嵌套）→ `hcs_spec_fd_id`，状态置 `processing`（特批中）。
+
+**dynamicProps 映射**：
+
+| HCS 字段 | TMS 来源 | 备注 |
+|---|---|---|
+| fd_contract_name | ContractManage.hcs_fd_id | ⚠️ 传**合规合同ID**，非名称 |
+| fd_contract_no | contractNo | |
+| fd_doc_subject | "结算付款特批-" + paymentNo | |
+| fd_doc_no / fd_id | paymentNo | 来源付款单标识 |
+| fd_pay_amount | appliedAmount | |
+| fd_total_amount | settlementAmount | |
+| fd_payer / fd_payee | payerName / payeeName | |
+| fd_receive_account_name / fd_receive_account / fd_bank_name | receiptAccountName / bankAccount / bankName | |
+| fd_settle_currency | "人民币"（映射） | |
+| fd_payment_purpose / fd_payment_nature / fd_payment_type | 配置映射（示例 2001 / 1 / 1） | 字典值联调确认（§9-U3） |
+| fd_reason / fd_supplement_note | remark | |
+| fd_doc_subject / fd_doc_status | 表单层主题 / 配置 "10" | |
+| fd_spc_approval_attach | 固定 "fd_spc_approval_attach" | 特批附件标识 |
+
+`mechanisms.attachment`：`attachmentsJson` 经 C103-2 转传，特批附件 `fdEntityKey=fd_spc_approval_attach` 且带 `fdBindType=ADD`。更新（C106-4）：单据变更且特批流程存在时调用，顶层 `fdId=hcs_spec_fd_id`，附件不带 fdBindType。
+
+**特批结果**：v4 无结果查询/回调接口 → `approved/rejected` 一期由页面人工确认（未决 §9-U1）。
+
+### 5.6 履约记录（C108-1/2 ← PaymentApplication，D11）
+
+- **新增**：付款申请审批通过 → 随推送链路调 C108-1：`fd_apply_amount`=appliedAmount、`fd_plan_date`=applyDate（毫秒）、`fd_paln_type`=paymentType、`fd_property`=款项性质（取关联履约规则行/结算性质）、`fd_id`=关联履约阶段 `hcs_stage_fd_id`（无关联则不传）、`fd_contract_id`=合同ID、`fd_xform_id` ← 配置（环境值）。附件经转传 `fdEntityKey=fd_plan_att`。返回 `data.fdId → hcs_perf_fd_id`。
+- **更新**：`paidAmount` 变化/付清 → C108-2：`formData.fdId=hcs_perf_fd_id` 必填，传 `fd_fact_amount`（实际金额）、`fd_contract_id` 等；响应无 data，success 即成功。
+
+### 5.7 开票登记（C111-1/2/3 ← InvoiceApplication，D12）
+
+- **新增**：审批通过 → 扫描推 C111-2；**更新**：金蝶开票完成（`kingdeeStatus=invoiced`，由既有 PaymentKingdeeResultTask 开票回写时置"待更新"）→ 扫描推 C111-3 回填 `fdBillDate`/`fdStatus`。
+- **映射**：fdNumber←applicationNo；fdRegisterDate←applicationDate（毫秒）；fdInvoiceAmount←invoiceAmount（含税）；fdInvoiceParty←issuerName（销方）；fdInvoiceType←invoiceType 字典映射（electronic_normal/electronic_special，§9-U3）；fdCurrencyId←RMB→币种fdId（启动时经 C103-12 缓存币种表，配置 `currency-id-mapping`）；fdRemark←remark；fdThirdCreatorCode/DeptCode←申请人工号/部门编码；fdStatus=0；fdAttIds←附件转传。
+- ⚠️ **fdContractNumber 缺口**：InvoiceApplication 无合同字段，需经应收结算链路回溯（具体关联字段开发时确认，§9-U10）。
+- 判重：C111-1 `conditions={"fdNumber": applicationNo}`（联调确认）。
+
+### 5.8 收票单（C109-1/2 ← InvoiceReceipt，D13）
+
+- **触发**：审批通过 → C109-1；票据变更/作废 → C109-2（顶层 `fdId=hcs_fd_id` 必填，只传变更字段，不带文档状态）。
+- **映射**：fd_invoice_code←invoiceNo；fd_bill_date←invoiceDate（`YYYY-MM-DD`）；fd_invoicer←issuerName（销方）；fd_buyer←receiverName（购方）；fd_invoice_amt_tax_incl←invoiceAmount；fd_tax_rate←taxRate÷100（13→0.13）；fd_invoice_type←字典映射（§9-U3）；fd_remark←remark；fd_contract_subject/fd_contract_no←**应付结算链路回溯**（收票→应付结算 FormalSettlement.contractId/No），回溯不到→页面补录 `hcs_contract_id/hcs_contract_no`；fd_ap_bill_src_subject←收票认领应付单号（键联调确认 §9-U11）；附件转传 `fdEntityKey=fd_attach`、`fdBindType=ADD`。
+- 返回 `data.data.fdId → hcs_fd_id`（双层嵌套）。
+
+### 5.9 主数据接口（C103-6/7/12）与查询（C103-3/4）
+
+- **启动/首次使用时拉取并缓存**（Redis，照 BFI token 缓存惯例，TTL 可配）：模板列表（供 template-mapping 校验）、合同分类树、币种表（fdId 映射）。提供管理端"刷新缓存"端点。
+- **C103-3/C103-4**：判重与对账回查（按 fdNumber/fdId）；C103-4 的 data 结构 v4 未定义，对账功能联调后补充。
+
+---
+
+## 6. 附件转传设计（HcsAttachmentSupport，D 补充 R2-Q5）
+
+1. 输入：单据 `attachmentsJson`/`contractFileJson`（JSON 元素含 url/fileType/approved 等，去重键照 `attachmentKey` 惯例 url|link|fileUrl|downloadUrl|uid|originalName）。
+2. 下载：按元数据 URL 从文件服务拉取流（文件服务基址可配 `attachment.file-download-base`）。
+3. 上传：C103-2 multipart（fdFile、fdAnonymous=false、fdLoginName=操作人）→ 附件 `fdId`。
+4. 映射缓存：Redis `hcs:att:{attachmentKey}` → 合规 fdId（TTL 7d），未命中重传（重复上传仅浪费存储，无业务风险，故不做持久化映射表）。
+5. 任一附件转传失败 → 整单推送失败进补偿重试。
+
+---
+
+## 7. 配置项清单（Nacos `third-party-api.yaml` → `thirdParty.hcs.*`）
+
+```yaml
+thirdParty:
+  hcs:
+    base-url: http://172.16.203.134:8000/gwzh/HTHG   # 网关前缀，直连/iPaaS 部署时改此处
+    authorization: ${HCS_AUTHORIZATION:}      # Authorization 头整值（含 Basic 前缀）
+    key-auth: ${HCS_KEY_AUTH:}                # Key-Auth 头整值
+    src-system: TMS                           # fd_sources
+    push:
+      sync-enabled: false                     # 总开关（默认关，灰度打开）
+      cron: "0 */5 * * * ?"
+      batch-size: 50
+      max-retry: 5
+    project:
+      template-code: ""                       # bpmOperation.templateCode（环境值）
+    contract:
+      template-mapping: {}                    # {TMS合同类别: HCS模板ID}
+      settlement-type-mapping: {}             # {TMS结算方式: 付款|收款}
+      currency-name-mapping: {"RMB": "人民币"}
+      special-contract-enabled: false
+      require-risk-check: true
+    exe-stage:
+      fund-type: byAmount
+    risk:
+      check-on-contract: true
+      check-on-payment: true
+      block-blacklist: true
+    credit:
+      require-contract-synced: true
+    spec-pay:
+      doc-status: "10"
+      payment-purpose: ""                     # 字典值联调后配置
+      payment-nature: ""
+      payment-type: ""
+    invoice:
+      invoice-type-mapping: {"electronic_normal": "", "electronic_special": ""}
+      currency-id-mapping: {"RMB": ""}        # {TMS币种码: HCS币种fdId}
+      fund-nature-default: progress
+    receipt-bill:
+      invoice-type-mapping: {}
+    attachment:
+      transfer-enabled: true
+      file-download-base: ""
+```
+
+---
+
+## 8. 实施拆分（建议排期）
+
+| 阶段 | 内容 | 依赖 |
+|---|---|---|
+| P0 基础 | blade-hcs-api 骨架：Feign/拦截器/认证头/DTO（24 接口全量 DTO）/分页工具；Nacos 配置段；统一字段组 SQL | 合规方提供测试环境地址与凭据 |
+| P1 立项与合同 | ProjectApply/ContractManage 字段+Support+扫描任务+手动端点；C102-3/C103-3 判重；C103-6/7/12 缓存 | P0；模板ID清单（§9-U7） |
+| P2 履约规则 | blade_contract_exe_stage 表+表单维护+C103-9 行级同步 | P1（合同先推送） |
+| P3 付款链 | C106-1/C101-1 提交校验+check_log；特批字段组+C106-3/4；C108-1/2 | P1（合同 fdId） |
+| P4 开票与收票 | C111-1/2/3（含金蝶回写联动）；C109-1/2（含合同回溯/补录） | P0；开票/收票关联字段确认 |
+| P5 运维收尾 | 对账查询页、失败重推批量、监控埋点（traceId 落日志）、多实例锁 | 全部 |
+
+**全部阶段通用**：Support 组装 HCS 请求 DTO 时按 §3.4 规范逐字段标注外部字段中文名与 TMS 取值来源（照 `pushArBill` 惯例），代码评审以此为一票否决项。
+
+---
+
+## 9. 未决事项（需合规方/联调确认）
+
+| # | 事项 | 影响 |
+|---|---|---|
+| U1 | **特批流程结果回传方式**：v4 无查询/回调接口 | 特批 approved/rejected 一期人工确认 |
+| U2 | 组织/人员引用体系：HCS `{fdId,fdName}` 的 fdId 与 TMS 部门ID 不同源；登录名是否同源（见原文登录名截图） | 立项/合同操作人字段解析方式 |
+| U3 | 字典值映射：fd_settlement_type、fd_invoice_type、付款用途/性质/类型、CONTRACT_STATUS 是否必传 | 各映射配置 |
+| U4 | C103-3/C102-3/C111-1 conditions 是否支持 fdNumber/fd_num/fdKingdeeId 精确查询；HCS 是否按 fd_kingdee_id 幂等 | 判重与防重方案 |
+| U5 | C103-11 updateDraft 如何定位已有合同 | 合同更新链路 |
+| U6 | signer 相对方编号体系与 fdType（inner/外部）判定；C101-1 的 fdNumber 用客商哪个编码 | 合同签署方、风险校验 |
+| U7 | 合规模板ID清单（template-mapping 数据源） | 合同推送 |
+| U8 | **合同附件向 HCS 的传递方式**（C103-1 未定义附件字段） | 附件转传挂载点 |
+| U9 | 立项 bpmOperation.templateCode 环境值；C108 fd_xform_id 环境值 | 立项/履约记录推送 |
+| U10 | 开票申请→合同/应收结算的关联字段确认 | C111 fdContractNumber |
+| U11 | 收票 fd_ap_bill_src_subject 关联键（应付单号体系） | C109 |
+| U12 | C104/C107 收款流水与认领的推送方及链路 | 范围外备忘（ADR-0003） |
@@ -15,9 +15,8 @@

 | 组件 | 内容 | 状态 |
 |---|---|---|
-| `feign/IHcsClient` | `@FeignClient(name="HCS", url="${thirdParty.hcs.baseUrl}")`，**24 个业务接口端点全部建成**（C101-1、C102-1/2/3、C103-1/2/3/4/5/6/7/9/11/12、C106-1/3/4、C108-1/2、C109-1/2、C111-1/2/3）+ OAuth2 getToken；URI 均可被 `thirdParty.hcs.*Url` 覆盖 | ✅ |
-| `interceptor/HcsAuthInterceptor` | oauth2（URL 追加 access_token）/ basic（Authorization 头）双模式并存，切换只改配置；取令牌请求有路径+空令牌双重守卫 | ✅ |
-| `token/HcsTokenService` | getToken → Redis（`blade:third:hcs:token`，120s 过期缓冲），`refreshAccessToken()` 供 401 强刷重放 | ✅ |
+| `feign/IHcsClient` | `@FeignClient(name="HCS", url="${thirdParty.hcs.baseUrl}")`，**24 个业务接口端点全部建成**（C101-1、C102-1/2/3、C103-1/2/3/4/5/6/7/9/11/12、C106-1/3/4、C108-1/2、C109-1/2、C111-1/2/3）；URI 均可被 `thirdParty.hcs.*Url` 覆盖 | ✅ |
+| `interceptor/HcsAuthInterceptor` | 所有请求注入 `Authorization`（整值可配）+ `Key-Auth` 两个静态认证头（v4 接口说明，2026-10-01 变更；原 oauth2/getToken 与 basic 双模式已删除） | ✅ |
 | `config/HcsProperties` | `third-party.hcs.*` 全量配置（§7 清单 + master-data.ttl-minutes + perf-record.xform-id 两个落实性补充），含默认值 | ✅ |
 | `config/HcsFeignClientConfig` | connect 10s / read 60s，空拦截器覆盖全局，**无 Retryer**（D7） | ✅ |
 | `dto/`（49 个文件） | 24 接口全量请求/响应 DTO + `HcsResult`/`HcsPageVO`/引用对象等公共结构；字段按《桂物合同集成接口逻辑梳理》核对，双层嵌套（C106-3/4、C109-1/2）以 `HcsResult<HcsResult<T>>` 承接 | ✅ |
@@ -188,5 +187,5 @@
 | `HcsInvoiceRegSyncSupport#requireContractNumber` | 应收结算回溯口径（§9-U10） |
 | `HcsInvoiceRegSyncSupport#latestInvoiceDate` | 票据日期取值口径（发票日期 vs 回写时间） |
 | `HcsReceiptBillSyncSupport#buildSaveParam` | fd_ap_bill_src_subject（§9-U11）；作废推送缺接口依据 |
-| `HcsTokenVO` / `HcsTokenService#cacheToken` | getToken 响应字段与 expires_in 单位（v4 未给出示例） |
+| `HcsAuthInterceptor` | Authorization/Key-Auth 头对全部接口（含 C103-2 附件上传/下载）是否同样生效；网关密钥轮换时仅改 Nacos 配置 |
 | `HcsReconSupport#reconContractDetail` | C103-4 出参结构 |
@@ -65,17 +65,12 @@ thirdParty:
      # 调度 cron，默认每10分钟
      cron: ${BFI_PAY_RESULT_CRON:0 */10 * * * ?}
  hcs:
-    # 合同合规系统（HCS）开放接口地址，直连可配（网关/iPaaS 部署时改此处，代码不感知）
-    base-url: ${HCS_BASE_URL:http://127.0.0.1:8050}
-    # 认证方式：oauth2（默认，URL 追加 access_token）| basic（Authorization 请求头），切换不改代码
-    auth-type: ${HCS_AUTH_TYPE:oauth2}
-    # OAuth2 应用 appKey
-    app-key: ${HCS_APP_KEY:}
-    # OAuth2 应用 appSecret，敏感值通过环境变量注入
-    app-secret: ${HCS_APP_SECRET:}
-    # Basic 认证用户名/密码（auth-type=basic 时生效）
-    basic-username: ${HCS_BASIC_USER:}
-    basic-password: ${HCS_BASIC_PASSWORD:}
+    # 合同合规系统（HCS）开放接口地址（v4 接口说明：带网关前缀，直连可配，代码不感知）
+    base-url: ${HCS_BASE_URL:http://172.16.203.134:8000/gwzh/HTHG}
+    # Authorization 请求头整值（含 Basic 前缀，敏感值通过环境变量注入）
+    authorization: ${HCS_AUTHORIZATION:}
+    # Key-Auth 请求头值（v4 接口说明：所有接口固定携带 Authorization + Key-Auth 两个头）
+    key-auth: ${HCS_KEY_AUTH:}
    # 来源系统标识（fd_sources，约定值 TMS）
    src-system: ${HCS_SRC_SYSTEM:TMS}
    # 推送任务（扫描首推/补偿，P1 接线）