feat: 立项与合同HCS前端接入配套端点——C103-8合同特批发起/B103结果回传、C103-2/5附件代理、C101-1风险与C103-6/12主数据查询，合同推送高风险客商挂起待特批

2026-10-09 19:45:40 +08:00
parent e41863d7f7
commit 7855254a4f
12 changed files with 1018 additions and 9 deletions
@@ -0,0 +1,254 @@
+# 项目立项与合同 HCS 前端接入设计（tms-erp-web）
+
+> **日期**：2026-10-09
+> **依据**：《桂物合同集成相关接口说明-v4.docx》、[TMS业财融合方案.docx](../TMS业财融合方案.docx)、[2026-09-27-桂物合同合规系统HCS接入技术设计.md](./2026-09-27-桂物合同合规系统HCS接入技术设计.md)、[2026-09-28-HCS接入实施状态与确认清单.md](./2026-09-28-HCS接入实施状态与确认清单.md)
+> **涉及工程**：`tms-api`（后端补前端代理端点）、`tms-erp-web`（前端页面与 API 模块）
+
+---
+
+## 1. 总体原则
+
+| # | 原则 |
+|---|---|
+| P1 | **前端不直连 HCS**。所有 C 系列接口由 tms-api 代理：`Authorization`/`Key-Auth` 静态双头只存在于服务端，浏览器不可见，也无跨域问题 |
+| P2 | **自动推送不动**。C102-1/2、C103-1/11 仍走"审批通过 → 置 unsynced → 扫描任务推送"链路（零埋点，ADR-0001），前端只补**状态展示 + 手动重推 + 对账回查** |
+| P3 | **附件主存储仍在 TMS OSS**。表单上传逻辑不改；HCS 转传由后端推送链路自动完成（HcsAttachmentSupport 已实现）。前端新增的是**手动转传**（特批材料、确定性上传）与**HCS 附件回下载** |
+| P4 | **前端结算币种/合同分类不改**。两个下拉继续用本地字典（`currency_type`/`contractCategory`），存量值与交互零变化；C103-12 币种、C103-7 分类只在后端推送侧映射（`currency-name-mapping`/`template-mapping`，已实现），前端无触点 |
+| P5 | UI 照**"同步金蝶"按钮模式**（参考 `customer-archive.vue`、`formal-settlement-table-panel.vue` 的 kingdeeSyncStatus 列 + 推送按钮），HCS 用 `hcsSyncStatus` 等同构字段 |
+
+---
+
+## 2. 接口 → 前端触点映射总表
+
+| HCS 接口 | 后端现状 | 面向前端端点 | 前端触点 |
+|---|---|---|---|
+| C101-1 客商风险等级 | Feign 已有，合同推送/付款提交时服务端调用 | **`GET /hcs/risk`（新增）** | 合同表单选甲乙方后展示风险标签；高风险+黑名单给"发起特批"入口 |
+| C102-1 项目立项新增 | 扫描任务自动推送 | — | 无直接触点（列表展示同步结果） |
+| C102-2 项目立项更新 | 变更审批通过自动推送 | — | 同上 |
+| C102-3 项目立项查询 | `GET /hcs/recon/project` 已有 | 已有 | 立项列表"合规对账"弹窗 |
+| C103-12 币种列表 | Feign + Redis 缓存已有（推送侧映射用） | **移出前端范围**（2026-10-09 确认：前端结算币种沿用本地字典，无触点） | — |
+| C103-6 模板列表 | Feign + Redis 缓存已有 | **`GET /hcs/master-data/template`（新增）** | 管理端"合规主数据/映射"查看页（表单不选模板，template-mapping 在 Nacos） |
+| ~~C103-7 分类列表~~ | Feign + 缓存已有 | **移出前端范围**（2026-10-09 确认：分类为推送侧 Nacos 映射的前置，前端无界面触点） | — |
+| C103-1 合同同步 | 审批通过自动推送 | `POST /hcs/sync/contract/{id}` 已有 | 合同列表"推送合规"按钮 |
+| C103-11 合同信息更新 | 变更审批通过自动推送 | 同上（重推入口） | 同上 |
+| C103-2 附件上传 | Feign 已有，推送链路自动转传 | **`POST /hcs/attachment/upload`（新增）** | 合同/特批材料"上传到合同系统"手动操作，返回 fdId 落库 |
+| C103-3 合同列表查询 | `GET /hcs/recon/contract` 已有 | 已有 | 合同列表"合规对账"弹窗 |
+| C103-4 合同详情查询 | `GET /hcs/recon/contract/detail` 已有 | 已有 | 对账弹窗"查看合规详情" |
+| C103-5 合同附件下载 | 仅 Feign 端点 | **`GET /hcs/attachment/download`（新增）** | 对账弹窗/合同详情中下载 HCS 侧附件 |
+| C103-8 合同发起特批 | **本期正式接入**（业务闭环见集成流程梳理：高风险客商签约必走；B103 结果回传） | **`POST /hcs/contract/spec-apply`（新增）+ `POST /hcs/callback/spec-result`（B103 接收，新增）** | 合同详情"发起特批"、特批状态展示、回传后自动恢复推送 |
+
+---
+
+## 3. 后端补充端点设计（tms-api）
+
+全部挂在 `HcsSyncController`（`/hcs` 前缀，与既有端点同文件），复用 `HcsMasterDataSupport`、`HcsAttachmentSupport`、`IHcsClient`，不新建 Support。
+
+### 3.1 主数据查询（走 Redis 缓存，未命中自动拉取）
+
+```
+GET /hcs/master-data/template
+返回 R<List<HcsTemplateVO>>：直接序列化
+```
+
+仅模板一个端点；币种/分类已在 `HcsMasterDataSupport` 内部缓存供推送映射，不暴露前端。
+
+### 3.2 附件代理
+
+```
+POST /hcs/attachment/upload        （multipart：fdFile + bizType 可选）
+  → 服务端包装 fdLoginName=当前登录名、fdAnonymous=false，调 C103-2
+  → 返回 R<{ fdId }>；同时写 HcsAttachmentSupport 的 Redis 映射缓存（attachmentKey → fdId），
+    使后续 C103-1 推送链路命中缓存不再重传
+  → 文件限制与 TMS OSS 现行一致：pdf/bmp/jpeg/png/jpg/doc/docx/ppt/pptx/xlsx/xls/eml/msg/zip，≤50M
+
+GET /hcs/attachment/download?fdId=...
+  → 调 C103-5，文件流透传（Content-Disposition attachment，文件名从附件元数据或 fdId 兜底）
+  → axios 需 responseType: 'blob'
+```
+
+### 3.3 客商风险查询（C101-1）
+
+```
+GET /hcs/risk?customerCode=...
+  → 调 IHcsClient.relativeRisk（C101-1）
+  → 返回 R<HcsRiskVO>：{ fdId, fdNumber, fdBlackStatus, fdRiskLevel }
+  → 结果写 blade_hcs_check_log（biz_type=risk，留痕与合同推送链路同表）
+```
+
+> 前端仅用于**展示与提示**，不作为安全边界：强制校验仍在合同推送链路（`risk.block-blacklist`）与付款提交事务内。
+
+### 3.4 合同发起特批（C103-8）+ 结果回传（B103）——本期正式接入
+
+**业务闭环**（依据《TMS业财融合-集成流程图文字版与业务流程梳理.md》§3.3/§8）：
+
+```
+合同审批通过 → C101-1 查甲乙方风险
+  ├─ 非高风险 → 常规链路：C103-2 附件转传 → C103-1 推送（现状不变）
+  └─ 高风险 → 合同链路挂起（hcs_spec_status=need）
+       → TMS 内部特批审批（按原审批流）
+       → 前端补特批申请材料 + 内部审批流程附件 → C103-8 发起特批（hcs_spec_status=processing）
+       → 合同系统集团审批（流程在合同系统预配置）
+       → B103 特批结果回传 TMS（hcs_spec_status=approved/rejected）
+       → approved → 自动恢复 C103-1 推送 → 完成签订；rejected → 前端提示，重新发起
+```
+
+**数据模型**：`blade_contract_manage` 追加特批字段组（照付款申请 `hcs_spec_*` 惯例），SQL 落 `doc/sql/transport/`：
+
+```sql
+hcs_spec_fd_id     varchar(64)  COMMENT '合规特批流程ID（C103-8 返回）',
+hcs_spec_status    varchar(16)  DEFAULT 'none' COMMENT '特批状态 none/need/processing/approved/rejected',
+hcs_spec_time      datetime     COMMENT '最近特批动作时间',
+hcs_spec_msg       varchar(512) COMMENT '特批结果/失败原因',
+hcs_spec_files_json text        COMMENT '特批申请材料+内部审批附件（含C103-2 fdId）'
+```
+
+**端点设计**：
+
+```
+POST /hcs/contract/spec-apply      （body：{ contractId, attachments: [{fdId, name}] }）
+  校验：合同审批通过 && hcs_spec_status ∈ {need, rejected} && 特批材料非空
+  组装报文调 C103-8（报文模式预估照 C106-3：fd_contract_id=hcs_fd_id、fd_contract_no、
+  fd_doc_subject="合同特批-"+contractNo、特批附件 mechanisms.attachment 带 fdBindType=ADD）
+  → 返回 data.fdId → hcs_spec_fd_id，状态置 processing；失败置 need 并记 hcs_spec_msg
+  → C103-8 v4 未含报文，联调前按上述预估实现并加 TODO 标注（§6-U1）
+
+POST /hcs/callback/spec-result     （B103 合规→TMS 回调接收端点）
+  公开端点（@PreAuth(AuthConstant.PERMIT_ALL) + 报文验签字段待合规方口径，先记录原文留痕）
+  body：{ 合同标识/特批流程fdId, 审批结果, 审批意见 }   ← 字段名待 B103 报文（§6-U1）
+  处理：定位合同 → 回写 hcs_spec_status=approved/rejected + hcs_spec_msg
+  → approved 时把合同 hcs_sync_status 重置 unsynced，由既有扫描任务自动走 C103-1（零新增链路）
+  → B103 报文未到位前端点先落库留痕不置状态，联调时接线
+```
+
+**状态展示与操作权限**：
+
+| hcs_spec_status | 前端表现 |
+|---|---|
+| none | 无特批相关 UI |
+| need（高风险待特批） | 合同详情警告条 +【发起特批】按钮可用；推送合规按钮禁用并提示"高风险客商，需先完成特批" |
+| processing | "特批中"标签（橙）；发起按钮禁用 |
+| approved | "特批通过"标签（绿）；推送恢复 |
+| rejected | "特批驳回"标签（红）+ 驳回原因；可重新发起 |
+
+### 3.5 权限
+
+`/hcs/**` 补 `@PreAuth`（菜单权限码，随菜单 SQL 一起落 `doc/sql/transport/`）：
+
+| 权限码 | 控制点 |
+|---|---|
+| `hcs_sync_push` | 推送合规/重推按钮 |
+| `hcs_sync_status` | 合规状态列/筛选（登录可见即可时不建） |
+| `hcs_recon` | 合规对账弹窗 |
+| `hcs_attachment` | 上传到合同系统 / 合规附件下载 |
+| `hcs_master_data` | 主数据/映射查看页 |
+| `hcs_spec_apply` | 发起特批按钮 |
+
+---
+
+## 4. 前端设计（tms-erp-web）
+
+### 4.1 新增 API 模块 `src/api/business/hcs.js`
+
+集中一个文件，不拆散到各业务 api（对齐 `api/payment/paymentApplication.js` 的超时覆盖惯例）：
+
+```js
+import request from '@/axios';
+
+const baseUrl = '/blade-transport/hcs';
+
+// 合规推送涉及 HCS 远程多次调用（风险校验+附件转传+起草），可达 20s+，覆盖全局 10s 超时
+export const repush = (bizType, id) =>
+  request({ url: `${baseUrl}/sync/${bizType}/${id}`, method: 'post', timeout: 60000 });
+
+export const getTemplates = () =>
+  request({ url: `${baseUrl}/master-data/template`, method: 'get' });
+
+export const getRisk = customerCode =>
+  request({ url: `${baseUrl}/risk`, method: 'get', params: { customerCode } });
+
+export const uploadAttachment = formData =>
+  request({ url: `${baseUrl}/attachment/upload`, method: 'post', data: formData, timeout: 60000 });
+
+export const downloadAttachment = fdId =>
+  request({ url: `${baseUrl}/attachment/download`, method: 'get', params: { fdId }, responseType: 'blob' });
+
+export const reconProject = projectCode =>
+  request({ url: `${baseUrl}/recon/project`, method: 'get', params: { projectCode } });
+export const reconContract = contractNo =>
+  request({ url: `${baseUrl}/recon/contract`, method: 'get', params: { contractNo } });
+export const reconContractDetail = params =>
+  request({ url: `${baseUrl}/recon/contract/detail`, method: 'get', params });
+
+export const applyContractSpec = data =>
+  request({ url: `${baseUrl}/contract/spec-apply`, method: 'post', data });
+```
+
+### 4.2 结算币种（C103-12）——前端不改
+
+前端"结算币种"下拉继续用本地字典 `currency_type`（`loadSettlementDictionaries()` 现状不动），存储值、编辑回显、下游运单/结算取值全部维持现状。C103-12 币种列表仅在后端推送 C103-1 时经 `currency-name-mapping`（`RMB→人民币`）映射，已实现，无前端工作。
+
+### 4.3 合同模板（C103-6）
+
+- **表单"合同类别"保留本地字典 `contractCategory`**：它是 TMS 业务主数据，推送侧靠 Nacos `template-mapping` 转模板ID。C103-7 已移出前端范围（2026-10-09 确认）。
+- 新增**管理端"合规主数据"查看页**（`views/business/hcs-master-data.vue`，模板列表 + "刷新缓存"按钮，`POST /hcs/master-data/refresh` 已有）。菜单挂系统管理或合规管理目录下。
+
+### 4.4 客商风险等级（C101-1）
+
+合同表单（新增/变更）选择甲方/乙方后：
+
+- 调 `getRisk(customerCode)`，在甲乙方字段旁展示风险标签：无风险/低/中/高 + 黑名单红标（`fdBlackStatus === 'yes'`）。
+- 高风险或黑名单时，表单顶部警告条："该客商为高风险/黑名单客商，按集团规定不可签约，如需签约请发起特批"，并提供【发起特批】按钮（走 §4.7）。
+- 项目立项表单不做强制校验（业务流程：风险校验在合同签订与付款环节），立项页不加。
+- 失败静默（HCS 不可达不阻塞填写，强校验在后端推送/付款链路）。
+
+### 4.5 附件上传到合同系统（C103-2）
+
+- **表单附件流程不变**：仍传 TMS OSS，推送时后端自动转传（已实现，含 7 天 fdId 映射缓存）。
+- 新增**手动转传入口**：合同详情页附件区（`contract-attachment-section.vue`）加"上传到合同系统"操作（仅已审批通过的合同显示）：
+  1. 选中附件行 → `uploadAttachment(formData)`（前端从 OSS url 拉文件或直接复用原始 File）；
+  2. 返回 `fdId` 写入附件行 `hcsFdId` 字段（后端 `update-attachments` 已有，行结构加一字段即可）；
+  3. 已转传的行显示"已上传合规"标记。
+- 特批材料（C103-8 占位）也走此端点先取得 fdId。
+
+### 4.6 合同附件下载（C103-5）
+
+- 对账弹窗（§4.7）中展示 HCS 侧附件列表（来自 C103-4 详情），点击下载调 `downloadAttachment(fdId)`，blob 落地文件。
+- `contract-attachment-section.vue` 的行内"下载"仍走 TMS OSS url，不改。
+
+### 4.7 列表页合规状态 + 推送/对账（照"同步金蝶"模式）
+
+`project-apply.vue` 与 `contract-manage.vue` 各加：
+
+1. **状态列**：`合规状态`（prop `hcsSyncStatus`）——`unsynced 待推送`（灰）/`synced 已推送`（绿）/`failed 推送失败`（红）；失败时 tooltip 显示 `hcsSyncMsg`；已推送的可附 `hcsFdId`。
+   - 列配置加在 `src/option/business/project-apply.js`、`contract-manage.js`（或页面内 column 定义，与两页现状一致）。
+   - 筛选区加"合规状态"下拉（unsynced/synced/failed，复用 settlement 模块 kingdeeSyncStatusOptions 的写法）。
+2. **操作按钮**：行操作"推送合规"（`repush(bizType, id)`，成功后刷新行；按钮文案照 customer-archive 的"推送中…"防重态）；权限码 `hcs_sync_push`。
+3. **对账弹窗**：行操作/工具栏"合规对账"——立项按 `projectCode` 调 `reconProject`，合同按 `contractNo` 调 `reconContract`；弹窗内 JSON 树/描述列表展示 HCS 返回，附"查看合规详情"（C103-4，合同页专属）与 HCS 附件下载（§4.6）。权限码 `hcs_recon`。
+
+### 4.8 合同发起特批（C103-8，本期接入）
+
+- **入口**：合同详情页【发起特批】按钮，仅 `hcsSpecStatus ∈ {need, rejected}` 时可用；权限码 `hcs_spec_apply`。
+- **交互**：弹窗选择/确认特批申请材料（先经 §4.5 `uploadAttachment` 取 fdId，弹窗内表格展示已传材料，含内部审批流程附件）→ 确认调 `applyContractSpec({ contractId, attachments })` → 成功后详情刷新为"特批中"。
+- **状态展示**：合同列表与详情按 §3.4 状态表展示特批标签（need/processing/approved/rejected）；`need` 时列表"推送合规"按钮禁用并 tooltip 提示。
+- **结果回传**：B103 回调由后端接收并自动恢复推送，前端无需轮询；详情页打开时实时拉取最新状态即可，`rejected` 时展示 `hcsSpecMsg` 驳回原因。
+
+---
+
+## 5. 实施拆分
+
+| 阶段 | tms-api | tms-erp-web | 依赖 |
+|---|---|---|---|
+| F1 基础 | `GET /hcs/master-data/template` + `@PreAuth`/菜单 SQL | `api/business/hcs.js`；管理端主数据页 | 无 |
+| F2 状态与推送 | 无（端点已有） | 两列表页：状态列/筛选 + 推送合规按钮 | F1（hcs.js） |
+| F3 对账与附件 | `/hcs/risk`、`/hcs/attachment/upload`、`/hcs/attachment/download` | 对账弹窗 + 合规附件下载 + 手动转传 + 附件行 `hcsFdId` | F2 |
+| F4 特批 | 合同特批字段组 SQL；`POST /hcs/contract/spec-apply` + `POST /hcs/callback/spec-result`（B103）；合同推送链路加 need 挂起判断 | 发起特批弹窗 + 特批状态标签 + 按钮联动 | C103-8/B103 报文（§6-U1，可先按预估模式实现联调替换） |
+
+---
+
+## 6. 未决事项
+
+| # | 事项 | 影响 | 当前处理 |
+|---|---|---|---|
+| U1 | **C103-8 / B103 报文 v4 未提供**（业务闭环已在集成流程梳理中明确） | 特批发起与结果回传的报文字段 | 按 C106-3 模式预估实现 + 回调端点先落库留痕；联调拿到报文后替换（代码已留 TODO） |
+| U2 | **C103-5 返回流是否带文件名**（v4 仅写"文件流"） | 下载文件命名 | 后端以附件元数据/`fdId` 兜底命名，联调校准 |
+| U3 | 合规状态列/菜单权限是否需要按租户差异化 | 菜单 SQL | 先按统一菜单落地 |