feat: 新增桂物合同合规系统（HCS）接入P0骨架（blade-hcs-api模块：Feign/认证拦截器/令牌服务/24接口DTO/分页工具，附Nacos配置段与业务表统一字段组SQL）

2026-09-27 22:22:36 +08:00
parent 50573e7263
commit a739211d6f
62 changed files with 4928 additions and 0 deletions
@@ -64,3 +64,83 @@ thirdParty:
      syncEnabled: ${BFI_PAY_RESULT_SYNC_ENABLED:false}
      # 调度 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:}
+    # 来源系统标识（fd_sources，约定值 TMS）
+    src-system: ${HCS_SRC_SYSTEM:TMS}
+    # 推送任务（扫描首推/补偿，P1 接线）
+    push:
+      # 总开关（默认关，灰度打开）
+      sync-enabled: ${HCS_PUSH_SYNC_ENABLED:false}
+      # 扫描调度 cron，默认每5分钟
+      cron: ${HCS_PUSH_CRON:0 */5 * * * ?}
+      # 每类单据单轮扫描批量
+      batch-size: ${HCS_PUSH_BATCH_SIZE:50}
+      # 推送失败自动重试上限，超限仅人工重推
+      max-retry: ${HCS_PUSH_MAX_RETRY:5}
+    # 项目立项（C102）
+    project:
+      # 立项 bpmOperation.templateCode（环境相关值，§9-U9 待合规方提供）
+      template-code: ${HCS_PROJECT_TEMPLATE_CODE:}
+    # 合同（C103-1/11）
+    contract:
+      # TMS 合同类别 -> HCS 模板ID（§9-U7 待合规方提供模板清单）
+      template-mapping: {}
+      # TMS 结算方式 -> 付款|收款（§9-U3 字典映射待联调）
+      settlement-type-mapping: {}
+      # TMS 币种码 -> HCS 币种名称（照金蝶 RMB->CNY 映射惯例）
+      currency-name-mapping: {"RMB": "人民币"}
+      # 合同 fdSepcailContract 固定 false（D15，配置项预留）
+      special-contract-enabled: ${HCS_CONTRACT_SPECIAL_ENABLED:false}
+      # 合同推送前是否强制客商风险校验
+      require-risk-check: ${HCS_CONTRACT_REQUIRE_RISK_CHECK:true}
+    # 履约规则（C103-9）
+    exe-stage:
+      # 金额类型默认值（fdFundType）
+      fund-type: ${HCS_EXE_STAGE_FUND_TYPE:byAmount}
+    # 客商风险校验（C101-1）
+    risk:
+      check-on-contract: ${HCS_RISK_CHECK_ON_CONTRACT:true}
+      check-on-payment: ${HCS_RISK_CHECK_ON_PAYMENT:true}
+      # 黑名单是否阻断（合同置 failed / 付款提交拦截）
+      block-blacklist: ${HCS_RISK_BLOCK_BLACKLIST:true}
+    # 额度校验（C106-1）
+    credit:
+      # 付款提交校验是否要求合同已推送合规
+      require-contract-synced: ${HCS_CREDIT_REQUIRE_CONTRACT_SYNCED:true}
+    # 结算付款特批（C106-3/4）
+    spec-pay:
+      # 单据状态（示例 10）
+      doc-status: ${HCS_SPEC_PAY_DOC_STATUS:10}
+      # 付款用途/性质/类型字典值（§9-U3 待联调后配置）
+      payment-purpose: ${HCS_SPEC_PAY_PAYMENT_PURPOSE:}
+      payment-nature: ${HCS_SPEC_PAY_PAYMENT_NATURE:}
+      payment-type: ${HCS_SPEC_PAY_PAYMENT_TYPE:}
+    # 开票登记（C111）
+    invoice:
+      # TMS 发票类型 -> HCS 发票类型字典值（§9-U3 待联调后配置）
+      invoice-type-mapping: {"electronic_normal": "", "electronic_special": ""}
+      # TMS 币种码 -> HCS 币种 fdId（经 C103-12 币种表缓存取值，§9-U3 待联调后配置）
+      currency-id-mapping: {"RMB": ""}
+      # 款项性质默认值（fdFundNature）
+      fund-nature-default: ${HCS_INVOICE_FUND_NATURE_DEFAULT:progress}
+    # 收票单（C109）
+    receipt-bill:
+      # TMS 发票类型 -> HCS 收票发票类型字典值（§9-U3 待联调后配置）
+      invoice-type-mapping: {}
+    # 附件转传（C103-2）
+    attachment:
+      # 附件转传总开关
+      transfer-enabled: ${HCS_ATTACHMENT_TRANSFER_ENABLED:true}
+      # TMS 文件服务下载基址（拉取附件流用）
+      file-download-base: ${HCS_ATTACHMENT_FILE_DOWNLOAD_BASE:}
@@ -0,0 +1,191 @@
+-- 桂物合同合规系统（HCS）接入：业务表统一集成字段组（设计文档 §4，P0）。
+-- blade_project_apply / blade_contract_manage / blade_payment_application /
+-- blade_invoice_application / blade_invoice_receipt 统一追加 hcs_* 五列；
+-- 后续阶段按 §8 排期再追加各场景扩展字段（履约计划ID、风险留痕、特批字段组等）。
+-- 通过 information_schema 判断字段是否存在，可重复执行。
+SET @db_name = DATABASE();
+
+-- ==================== blade_project_apply（C102 立项回填） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_project_apply' AND column_name = 'hcs_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_project_apply ADD COLUMN hcs_fd_id varchar(64) DEFAULT NULL COMMENT ''合规系统单据ID（fdId/fdContractId）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_project_apply' AND column_name = 'hcs_sync_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_project_apply ADD COLUMN hcs_sync_status varchar(16) DEFAULT ''unsynced'' COMMENT ''同步状态 unsynced/synced/failed'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_project_apply' AND column_name = 'hcs_retry_count'),
+  'SELECT 1',
+  'ALTER TABLE blade_project_apply ADD COLUMN hcs_retry_count int DEFAULT 0 COMMENT ''推送失败重试次数'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_project_apply' AND column_name = 'hcs_sync_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_project_apply ADD COLUMN hcs_sync_time datetime DEFAULT NULL COMMENT ''最近同步时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_project_apply' AND column_name = 'hcs_sync_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_project_apply ADD COLUMN hcs_sync_msg varchar(512) DEFAULT NULL COMMENT ''最近同步结果信息/失败原因'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+-- ==================== blade_contract_manage（C103 合同回填） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_contract_manage' AND column_name = 'hcs_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_contract_manage ADD COLUMN hcs_fd_id varchar(64) DEFAULT NULL COMMENT ''合规系统单据ID（fdId/fdContractId）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_contract_manage' AND column_name = 'hcs_sync_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_contract_manage ADD COLUMN hcs_sync_status varchar(16) DEFAULT ''unsynced'' COMMENT ''同步状态 unsynced/synced/failed'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_contract_manage' AND column_name = 'hcs_retry_count'),
+  'SELECT 1',
+  'ALTER TABLE blade_contract_manage ADD COLUMN hcs_retry_count int DEFAULT 0 COMMENT ''推送失败重试次数'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_contract_manage' AND column_name = 'hcs_sync_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_contract_manage ADD COLUMN hcs_sync_time datetime DEFAULT NULL COMMENT ''最近同步时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_contract_manage' AND column_name = 'hcs_sync_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_contract_manage ADD COLUMN hcs_sync_msg varchar(512) DEFAULT NULL COMMENT ''最近同步结果信息/失败原因'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+-- ==================== blade_payment_application（C106 额度/特批、C108 履约记录） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_fd_id varchar(64) DEFAULT NULL COMMENT ''合规系统单据ID（fdId/fdContractId）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_sync_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_sync_status varchar(16) DEFAULT ''unsynced'' COMMENT ''同步状态 unsynced/synced/failed'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_retry_count'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_retry_count int DEFAULT 0 COMMENT ''推送失败重试次数'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_sync_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_sync_time datetime DEFAULT NULL COMMENT ''最近同步时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_payment_application' AND column_name = 'hcs_sync_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_payment_application ADD COLUMN hcs_sync_msg varchar(512) DEFAULT NULL COMMENT ''最近同步结果信息/失败原因'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+-- ==================== blade_invoice_application（C111 开票登记回填） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_application' AND column_name = 'hcs_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_application ADD COLUMN hcs_fd_id varchar(64) DEFAULT NULL COMMENT ''合规系统单据ID（fdId/fdContractId）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_application' AND column_name = 'hcs_sync_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_application ADD COLUMN hcs_sync_status varchar(16) DEFAULT ''unsynced'' COMMENT ''同步状态 unsynced/synced/failed'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_application' AND column_name = 'hcs_retry_count'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_application ADD COLUMN hcs_retry_count int DEFAULT 0 COMMENT ''推送失败重试次数'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_application' AND column_name = 'hcs_sync_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_application ADD COLUMN hcs_sync_time datetime DEFAULT NULL COMMENT ''最近同步时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_application' AND column_name = 'hcs_sync_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_application ADD COLUMN hcs_sync_msg varchar(512) DEFAULT NULL COMMENT ''最近同步结果信息/失败原因'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+-- ==================== blade_invoice_receipt（C109 收票单回填） ====================
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_receipt' AND column_name = 'hcs_fd_id'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_receipt ADD COLUMN hcs_fd_id varchar(64) DEFAULT NULL COMMENT ''合规系统单据ID（fdId/fdContractId）'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_receipt' AND column_name = 'hcs_sync_status'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_receipt ADD COLUMN hcs_sync_status varchar(16) DEFAULT ''unsynced'' COMMENT ''同步状态 unsynced/synced/failed'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_receipt' AND column_name = 'hcs_retry_count'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_receipt ADD COLUMN hcs_retry_count int DEFAULT 0 COMMENT ''推送失败重试次数'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_receipt' AND column_name = 'hcs_sync_time'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_receipt ADD COLUMN hcs_sync_time datetime DEFAULT NULL COMMENT ''最近同步时间'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
+SET @sql = IF(
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = @db_name AND table_name = 'blade_invoice_receipt' AND column_name = 'hcs_sync_msg'),
+  'SELECT 1',
+  'ALTER TABLE blade_invoice_receipt ADD COLUMN hcs_sync_msg varchar(512) DEFAULT NULL COMMENT ''最近同步结果信息/失败原因'''
+);
+PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;