docs: 新增HCS合同管理操作手册及纯操作版（含操作截图与定时任务说明）

doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册.md

@@ -0,0 +1,714 @@
+# HCS 合同管理操作手册
+
+> **文档日期**：2026-10-23
+> **适用系统**：运输板块数字化管理平台（TMS）
+> **适用对象**：合同经办人、合同负责人、合同审批人、合规管理员
+> **文档目的**：介绍合同新增、审批、变更、附件归档及 HCS 合规同步的完整操作方法
+> **截图说明**：本文截图取自测试环境，合同编号、客商名称、金额等均为测试数据；不同环境因角色权限、功能开关不同，页面按钮和状态可能略有差异，以实际页面为准。
+
+---
+
+## 1. 先了解合同管理与 HCS
+
+### 1.1 合同管理负责什么
+
+合同管理模块用于管理运输业务合同的完整生命周期：
+
+1. **起草合同**：录入合同基本信息、计费方案、结算规则、付款比例及附件。
+2. **合同审批**：支持临时合同审批和正式合同审批。
+3. **合规同步**：合同审批通过后，将合同推送至 HCS 合同合规系统；正式合同及合同变更是合规同步的主要场景。
+4. **合同变更**：正式合同信息发生变化时，通过变更流程修改并重新审批。
+5. **附件归档**：上传用印材料、双章归档文件、特批附件等材料。
+
+### 1.2 关键名词
+
+| 名词 | 说明 |
+| --- | --- |
+| HCS | 桂物合同合规系统，负责合同合规校验、客商风险校验、合同特批及金蝶同步 |
+| 合规状态 | 合同推送 HCS 的结果，分为“待推送”“已推送”“推送失败” |
+| 合规合同ID | 合同成功推送 HCS 后，由 HCS 返回的合同唯一标识 |
+| 金蝶合同ID | 合同在 HCS 完成合规及金蝶同步后，回写到 TMS 的金蝶合同编号 |
+| 特批 | 高风险或黑名单客商合同，需经集团特批后才能完成合规流程 |
+| 临时合同 | 用于提前生效的合同，审批通过后有 **30 天** 临时效力 |
+| 正式合同 | 完成正式审批、可长期履约的合同，是 HCS 合规同步与归档的主要对象 |
+| 合同变更 | 正式合同内容发生变化时发起的变更审批流程 |
+
+### 1.3 使用前必须知道的规则
+
+- 页面中带 `*` 的字段为必填项；保存草稿时可先填写部分信息，提交临时合同或正式合同前需补全。
+- 合同编号可不填写，系统会按合同负责部门配置的规则自动生成；如业务要求手工编号，可直接填写。
+- 临时合同审批通过后有效期为 **30 天**（自提交临时合同审批之日起算），到期前应及时转为正式合同。
+- 高风险、黑名单客商合同，**提交审批前必须上传“特批附件”**，否则系统会阻止提交。
+- 合同审批通过后，系统会将合同推送 HCS；正式合同与合同变更是合规同步、归档的主要场景。是否自动推送由环境开关决定，也可在页面手动推送。
+- 合同已推送 HCS 后，如需修改合同信息，必须走“变更”流程，**不要重复新增合同**，否则会在合规系统产生重复合同。
+- 合同列表默认按创建时间倒序排列。
+
+---
+
+## 2. 业务流程总览
+
+### 2.1 合同全生命周期
+
+```mermaid
+flowchart TD
+    A["新增合同"] --> B["保存草稿"]
+    B --> C["提交临时合同"]
+    C --> D["临时合同审批"]
+    D -->|驳回| B
+    D -->|通过| E["临时合同生效<br/>30 天临时效力"]
+    B --> F["提交正式合同"]
+    E -->|转正式合同| F
+    F --> G["正式合同审批"]
+    G -->|驳回| E
+    G -->|通过| H["推送 HCS 合规系统"]
+    H --> I{"客商风险校验"}
+    I -->|正常| J["合规状态：已推送<br/>回填合规合同ID"]
+    I -->|高风险/黑名单| K["特批中<br/>等待合规特批结果"]
+    K -->|通过| J
+    K -->|驳回| L["合同审批驳回<br/>修改后重新提交"]
+    J --> M["签订 / 用印 / 双章归档"]
+    M --> N["发起变更 → 变更审批 → HCS 更新"]
+```
+
+### 2.2 一句话理解流程
+
+1. **先起草**：新增合同，填写基本信息、计费结算、附件。
+2. **再审批**：可先提交临时合同快速生效，也可以直接提交正式合同。
+3. **后合规**：合同审批通过后，系统自动/手动推送 HCS，高风险客商进入特批。
+4. **有变化走变更**：正式合同内容变化时发起变更，变更审批通过后更新 HCS。
+
+> 上图和流程以正式合同办理为主线。临时合同审批通过后，系统同样会置为待推送并尝试推送 HCS；正式合同与合同变更审批通过是合规同步、归档和金蝶回写的关键节点。
+
+---
+
+## 3. 进入合同管理
+
+登录系统后，在左侧菜单依次点击：
+
+**合同管理 → 合同管理**
+
+![合同列表](images/01-合同列表.png)
+
+> 合同管理列表页
+
+列表页由上到下分为四部分：
+
+1. **搜索区**：按合同编号、名称、项目、状态等条件查询。
+2. **到期标签**：全部、30天内到期、90天内到期、90天以上到期、已到期。
+3. **工具栏**：新增、批量导出、批量推送合规。
+4. **合同列表**：展示合同及操作入口。
+
+---
+
+## 4. 查询合同
+
+### 4.1 搜索条件
+
+在搜索区填写条件后点击“查询”；点击“重置”清空条件。搜索条件超过一行时，可点击“展开/收起”查看全部条件。
+
+![合同列表筛选](images/03-合同列表筛选.png)
+
+> 合同搜索区
+
+| 搜索项 | 说明 |
+| --- | --- |
+| 签约类型 | 新签、续签、补充协议 |
+| 合同类别 | 客户合同、承运商合同、补充协议（对应新增页面的“合同类型”） |
+| 所属项目 | 选择合同关联的项目 |
+| 是否同步合规 | 是 / 否 |
+| 合同名称 | 支持模糊查询 |
+| 是否同步金蝶 | 是 / 否 |
+| 合同编号 | 支持模糊查询 |
+| 合规状态 | 待推送 / 已推送 / 推送失败 |
+| 生效类型 | 未生效 / 临时生效 / 正式生效 / 已过期 |
+| 归档状态 | 未归档 / 已归档 |
+| 审核状态 | 草稿 / 审批中 / 审批通过 / 已驳回 / 已撤回 / 变更审批中 / 变更审批通过 / 变更驳回 |
+| 合同负责部门 | 选择部门 |
+| 合同阶段 | 草稿 / 临时合同 / 正式合同 / 已终止 |
+
+### 4.2 到期标签
+
+列表上方提供 5 个到期标签，标签后的数字为对应合同数量：
+
+- **全部**：全部合同。
+- **30天内到期**：合同结束日期在未来 30 天内。
+- **90天内到期**：合同结束日期在未来 31～90 天内。
+- **90天以上到期**：合同结束日期在 90 天以后。
+- **已到期**：合同结束日期已过。
+
+点击标签即可筛选对应合同。
+
+### 4.3 列表字段
+
+| 字段 | 说明 |
+| --- | --- |
+| 合同编号 / 合同名称 | 合同唯一编号和名称，点击名称可打开详情 |
+| 所属项目 / 合同负责部门 | 合同归属项目及负责部门 |
+| 合同类别 / 签约类型 | 合同业务分类及签约方式 |
+| 甲方 / 乙方 | 合同双方 |
+| 合同金额 | 合同含税金额 |
+| 合同阶段 | 草稿 / 临时合同 / 正式合同 / 已终止 |
+| 审核状态 | 当前审批状态 |
+| 归档状态 | 未归档 / 已归档 |
+| 合规状态 | 待推送 / 已推送 / 推送失败；鼠标悬停可查看失败原因 |
+| 金蝶合同ID | 合规同步完成后回写的金蝶合同编号 |
+| 当前节点 / 当前处理人 | 当前审批节点及处理人 |
+| 创建人 / 创建时间 | 合同创建信息 |
+| 操作 | 查看、编辑、复制、变更、附件上传、推送合规等 |
+
+### 4.4 操作列说明
+
+![合同列表状态与操作列](images/02-合同列表状态与操作列.png)
+
+> 合同列表中的状态与操作列（示例）
+
+操作列会根据合同状态、当前登录人权限动态显示：
+
+| 合同状态 | 常见操作 |
+| --- | --- |
+| 草稿 | 查看、编辑、复制、删除 |
+| 临时合同 - 审批中 | 查看、撤回、通过/驳回（审批人）、流程 |
+| 临时合同 - 审批通过 | 查看、复制、转正式合同、流程 |
+| 临时合同 - 已驳回 | 查看、编辑、复制、重新提交转正 |
+| 正式合同 - 审批中 | 查看、撤回、通过/驳回（审批人）、流程 |
+| 正式合同 - 审批通过 / 变更审批通过 | 查看、复制、变更、附件上传、流程、推送合规（未同步时） |
+| 正式合同 - 变更审批中 | 查看、通过/驳回（审批人）、撤回变更、流程 |
+| 正式合同 - 变更驳回 | 查看、编辑变更内容、重新提交变更 |
+
+> 说明：
+> - “复制”会以当前合同为模板打开新增页面，便于快速新建相似合同。
+> - 只有草稿状态的合同可以删除。
+> - 只有审批通过且未同步合规的合同显示“推送合规”。
+
+---
+
+## 5. 新增合同
+
+### 5.1 新增入口
+
+在合同列表页点击左上角 **新增** 按钮，进入“新增合同管理”页面。
+
+![新增合同-基本信息](images/04-新增合同-基本信息.png)
+
+> 新增合同页面
+
+### 5.2 填写基本信息
+
+按照页面从上到下依次填写：
+
+| 字段 | 填写说明 |
+| --- | --- |
+| 签约类型 `*` | 选择新签、续签或补充协议 |
+| 合同编号 | 不填写时按部门规则自动生成；也可手工录入 |
+| 合同名称 `*` | 最多 100 个字符 |
+| 合同类型 `*` | 选择客户合同、承运商合同或补充协议 |
+| 项目 `*` | 选择合同关联的项目 |
+| 合同负责部门 `*` | 选择负责该合同的部门 |
+| 甲方 `*` | 选择甲方客商 |
+| 乙方 `*` | 选择乙方客商 |
+| 签订日期 `*` | 选择合同签订日期 |
+| 申请日期 | 提交正式合同时系统自动填充为当天，无需手工填写 |
+| 合同期限 `*` | 填写合同开始日期和结束日期 |
+| 回款账期 | 填写回款账期天数 |
+| 合同金额 `*` | 填写合同金额，不能小于 0 |
+| 是否范本 | 选择“是/否” |
+| 原件合同编号 | 如有原件合同，填写原件编号 |
+| 是否电子章 | 选择“是/否” |
+| 开票周期 | 填写开票周期天数 |
+| 结算币种 `*` | 选择人民币等结算币种 |
+| 合同格式 `*` | 选择合同格式 |
+| 一式 | 填写合同份数 |
+| 是否需要加盖法人章 `*` | 选择“是/否” |
+| 结算方式 `*` | 选择先票后款、先款后票、月结等 |
+| 经办人 | 自动带出当前登录人，不可修改 |
+| 合同主要内容 | 填写合同主要条款，最多 1000 字 |
+| 其他事项说明 | 填写补充说明，长度以页面提示为准 |
+
+> 提示：保存草稿时系统仅校验合同名称、合同类型、结算币种等基础信息；提交临时合同或正式合同时会校验更多必填项，请以页面提示为准。
+
+### 5.3 上传用印材料
+
+在“用印材料”区域：
+
+1. 点击表格下方的 **上传附件**。
+2. 选择附件类型：用印材料、双章归档文件、其他文件。
+3. 上传文件，支持 pdf、bmp、jpeg、png、jpg、doc、docx、ppt、pptx、xlsx、xls、eml、msg、zip，单个文件不超过 50MB。
+4. 上传完成后可在表格中查看文件名、大小、上传人、上传时间。
+5. 需要下载时，勾选附件后点击 **批量下载**。
+
+> 说明：附件类型选择“双章归档文件”并上传后，合同审批通过时归档状态会自动变为“已归档”。
+
+### 5.4 填写计费与结算
+
+继续向下填写以下区域：
+
+![新增合同-计费结算与附件](images/05-新增合同-计费结算与附件.png)
+
+> 计费、结算、付款比例与附件区域
+
+**计费信息**
+
+- 费用生成模式：系统生成 / 账单导入生成。
+- 点击 **添加** 新增计费方案，填写方案名称、运输方式。
+
+**结算单规则**
+
+- 分为“预结算配置”和“正式结算配置”两个页签。
+- 每个页签可设置是否自动生成结算单（开启 / 关闭）。
+
+**付款比例设置**
+
+- 点击 **添加**，填写付款笔数、付款比例上限（%）、备注。
+
+**附件（佐证材料等）**
+
+- 用于上传佐证材料、特批附件等。
+- 附件类型：特批附件、其他文件。
+- 高风险/黑名单客商合同必须在此处上传类型为 **特批附件** 的文件。
+
+### 5.5 选择提交方式
+
+页面底部提供 4 个按钮：
+
+| 按钮 | 适用场景 | 提交后状态 |
+| --- | --- | --- |
+| 关闭 | 放弃本次填写 | 不保存 |
+| 保存 | 信息尚未填全，先暂存 | 合同阶段为“草稿”，审核状态为“草稿” |
+| 提交临时合同 | 需要合同尽快生效 | 合同阶段为“临时合同”，进入临时合同审批 |
+| 提交正式合同 | 合同信息完整，直接走正式审批 | 直接进入正式合同审批 |
+
+> 说明：
+> - 提交临时合同前，至少需填写签约类型、合同名称、合同类型、所属项目、合同负责部门、甲方、乙方、合同金额。
+> - 提交正式合同前，需完整填写合同期限、签订日期、结算方式、合同格式、合同金额等字段，并完成计费方案、结算规则、付款比例校验。
+> - 无论选择哪种提交方式，高风险/黑名单客商合同都必须先上传“特批附件”。
+
+---
+
+## 6. 合同审批与状态
+
+### 6.1 审批人操作
+
+审批人在合同列表操作列进行审批：
+
+| 操作 | 说明 |
+| --- | --- |
+| 通过 | 审批通过；系统会尝试推送合规（是否即时推送由环境配置决定），请稍候 |
+| 驳回 | 审批驳回，合同退回经办人修改 |
+| 撤回 | 提交人可在审批中撤回；普通审批撤回后为“已撤回”，可修改后重新提交 |
+| 流程 | 查看审批流程；如提示“流程实例为空”，说明该合同未生成外部流程实例，以审核状态为准 |
+
+> 重要：点击“通过”后，系统会尝试推送 HCS（是否即时推送由环境配置决定），页面会显示“正在推送合规，请稍候…”。如果提示 **“审批通过，但合规推送失败：原因”**，表示合同审批已通过，但合规推送失败，请按第 11 章处理，不要重复审批；如未开启即时推送，可在合同列表手动点击“推送合规”。
+
+### 6.2 合同阶段说明
+
+| 合同阶段 | 含义 |
+| --- | --- |
+| 草稿 | 已保存但未提交审批 |
+| 临时合同 | 正在走临时合同审批，或临时合同已审批通过（30 天临时效力） |
+| 正式合同 | 正在走正式合同审批，或正式合同已审批通过 |
+| 已终止 | 合同已终止（当前版本前端暂未开放终止入口） |
+
+### 6.3 审核状态说明
+
+| 审核状态 | 含义 |
+| --- | --- |
+| 草稿 | 尚未提交审批 |
+| 审批中 | 临时合同或正式合同审批中 |
+| 审批通过 | 审批完成 |
+| 已驳回 | 审批被驳回，需修改后重新提交 |
+| 已撤回 | 提交人主动撤回，可修改后重新提交 |
+| 变更审批中 | 合同变更审批中 |
+| 变更审批通过 | 合同变更审批完成 |
+| 变更驳回 | 合同变更被驳回，可修改后重新提交变更 |
+
+### 6.4 其他状态说明
+
+| 状态 | 说明 |
+| --- | --- |
+| 归档状态：未归档 | 尚未上传双章归档文件 |
+| 归档状态：已归档 | 已上传双章归档文件，合同审批通过后自动置为已归档 |
+| 合规状态：待推送 | 合同已审批通过，等待推送 HCS |
+| 合规状态：已推送 | 合同已成功提交至 HCS，已回填合规合同ID |
+| 合规状态：推送失败 | 推送 HCS 失败，鼠标悬停合规状态可查看失败原因 |
+| 当前节点：特批审核 | 高风险/黑名单合同正在等待合规特批结果 |
+
+---
+
+## 7. 临时合同转正式合同
+
+### 7.1 适用条件
+
+- 合同阶段为“临时合同”，审核状态为“审批通过”。
+- 临时合同被驳回时，可先编辑修改，再点击“重新提交转正”。
+
+### 7.2 操作步骤
+
+1. 在合同列表找到临时合同。
+2. 点击操作列的 **转正式合同**。
+3. 在确认弹窗中点击“确定”。
+4. 系统提示“已提交正式合同审批”。
+
+### 7.3 提交后的变化
+
+- 合同阶段变为“正式合同”。
+- 审核状态变为“审批中”。
+- 当前节点为“正式合同审批”。
+- 申请日期自动更新为当天。
+- 正式审批通过后，系统推送 HCS 合规系统。
+
+> 临时合同有效期为 30 天，请及时转正式合同，避免临时效力到期影响业务。
+
+---
+
+## 8. 查看合同详情
+
+在合同列表点击 **合同名称** 或操作列的 **查看**，进入合同详情页。
+
+![合同详情-基本信息与合规信息](images/06-合同详情-基本信息与合规信息.png)
+
+> 合同详情：基本信息与合规信息
+
+详情页包含以下区域：
+
+### 8.1 基本信息
+
+展示签约类型、合同编号、合同名称、合同类型、项目、甲方、乙方、合同期限、合同负责部门、经办人、归档状态、签订日期、申请日期、合同格式、结算币种、结算方式、开票周期、回款账期、合同金额、是否范本、原件合同编号、是否电子章、合同主要内容、其他事项说明等。
+
+**风险客商提示**：如果甲方或乙方属于高风险/黑名单客商，基本信息下方会显示红色提示，列明风险原因，并提示“提交前须上传特批附件”。
+
+### 8.2 合规信息
+
+合规信息区域展示：
+
+| 字段 | 说明 |
+| --- | --- |
+| 合规同步状态 | 待推送 / 已推送 / 推送失败 |
+| 合规合同ID | HCS 返回的合同唯一标识 |
+| 客商风险 | 是否黑名单、风险等级 |
+| 特批状态 | 待特批 / 特批中 / 特批通过 / 特批驳回 |
+| 特批说明 | 特批原因或处理说明 |
+
+### 8.3 用印材料与附件
+
+向下滚动可查看用印材料、计费信息、结算单规则、付款比例设置、附件（佐证材料等）。
+
+![合同详情-附件佐证材料](images/07-合同详情-附件佐证材料.png)
+
+> 合同详情：计费、结算、付款比例与佐证材料
+
+### 8.4 变更记录
+
+详情页底部展示合同的变更记录，包括变更日期、经办人、变更类型、变更内容、变更原因、状态。
+
+![合同详情-变更记录](images/08-合同详情-变更记录.png)
+
+> 合同详情：附件与变更记录
+
+---
+
+## 9. 附件上传与归档
+
+### 9.1 适用条件
+
+只有**正式合同**且审核状态为“审批通过”或“变更审批通过”时，才显示“附件上传”操作。
+
+### 9.2 操作步骤
+
+1. 在合同列表找到正式合同。
+2. 点击操作列 **附件上传**。
+
+![附件上传弹窗](images/11-附件上传弹窗.png)
+
+> 附件上传弹窗
+
+3. 选择 **附件位置**：
+   - **用印材料**：可上传用印材料、双章归档文件、其他文件。
+   - **附件（佐证材料等）**：可上传特批附件、其他文件。
+4. 选择 **附件类型**。
+5. 将文件拖入上传区域，或点击上传区域选择文件。
+6. 点击 **确定** 保存。
+
+### 9.3 上传限制
+
+- 支持 pdf、bmp、jpeg、png、jpg、doc、docx、ppt、pptx、xlsx、xls、eml、msg、zip 格式。
+- 单个文件不超过 50MB。
+- 上传人、上传时间由系统自动记录。
+
+### 9.4 归档规则
+
+- 上传附件类型为 **双章归档文件** 后，合同归档状态会在审批通过或附件保存后变为“已归档”。
+- 双章归档文件属于用印材料，请在“附件位置”中选择“用印材料”。
+
+---
+
+## 10. 合同变更
+
+### 10.1 适用条件
+
+只有**正式合同**，且审核状态为“审批通过”“变更审批通过”或“变更驳回”时，才允许发起变更。
+
+### 10.2 发起变更
+
+1. 在合同列表找到正式合同。
+2. 点击操作列 **变更**（变更驳回后可点击“重新提交变更”）。
+3. 进入“合同变更”页面。
+
+![合同变更-基本信息](images/09-合同变更-基本信息.png)
+
+> 合同变更页面
+
+4. 修改需要变更的内容：基本信息、用印材料、计费信息、结算单规则、付款比例、附件等。
+5. 页面会展示风险客商提示；如存在高风险/黑名单客商，变更提交前同样必须上传“特批附件”。
+
+### 10.3 填写变更原因与材料
+
+![合同变更-原因与材料](images/10-合同变更-原因与材料.png)
+
+> 合同变更：变更原因与变更材料
+
+1. 在“变更原因”中填写本次变更的原因，最多 500 字。
+2. 在“变更材料”区域上传相关附件。
+3. 点击页面底部 **提交**。
+4. 在确认弹窗中点击“确定”。
+
+### 10.4 变更审批
+
+- 提交后审核状态变为“变更审批中”。
+- 审批人可执行“通过”“驳回”“撤回变更”。
+- 审批通过后，审核状态变为“变更审批通过”，系统按合规合同ID更新 HCS；如该合同尚未推送过，则按首次推送处理。
+- 审批驳回后，审核状态变为“变更驳回”，可点击“重新提交变更”重新填写变更原因后再次提交。
+
+> 说明：
+> - 变更审批通过后，变更附件会合并到合同附件中，变更原因、变更内容会被清空，变更记录保留。
+> - 页面中的“终止合同”选项当前版本暂未开放，请选择“合同信息变更”。
+
+---
+
+## 11. HCS 合规推送
+
+### 11.1 什么时候推送
+
+合同满足以下条件后进入合规推送流程：
+
+- 审核状态为“审批通过”或“变更审批通过”；
+- 合规状态为“待推送”或“推送失败”。
+
+> 说明：临时合同审批通过后系统同样会置为待推送并尝试推送；正式合同与合同变更审批通过是合规同步的主要场景，也是归档、金蝶回写的关键节点。
+
+系统支持两种触发方式：
+
+1. **自动推送**：审批通过后系统会尝试即时推送；同时后台定时任务每 5 分钟扫描待推送/推送失败的合同进行补偿。即时推送和定时任务是否启用均由环境配置决定。
+2. **手动推送**：在合同列表点击“推送合规”或“批量推送合规”。
+
+### 11.2 系统会推送什么
+
+![待推送与推送失败列表](images/14-待推送与推送失败列表.png)
+
+> 列表中的待推送、推送失败状态
+
+推送 HCS 时，系统会依次完成：
+
+| 步骤 | 内容 |
+| --- | --- |
+| ① 客商风险校验 | 校验甲乙双方是否高风险/黑名单（C101-1） |
+| ② 附件转传 | 将合同附件转传到合规系统（C103-2） |
+| ③ 合同判重 | 按合同编号等信息判断合规系统是否已存在（C103-3） |
+| ④ 起草 / 更新 | 首次推送起草合同（C103-1）；已有合规合同ID时更新合同（C103-11） |
+| ⑤ 履约计划同步 | 同步合同履约计划/履约规则（C103-9），系统自动创建默认履约计划，无需人工维护 |
+| ⑥ 特批 | 高风险/黑名单客商合同自动进入特批流程 |
+
+### 11.3 手动推送单条合同
+
+1. 在合同列表找到“待推送”或“推送失败”的合同。
+2. 点击操作列 **推送合规**。
+
+![手动推送合规确认](images/15-手动推送合规确认.png)
+
+> 手动推送合规确认
+
+3. 在确认弹窗中点击“确定”。
+4. 页面显示“正在推送合规，请稍候…”，请勿重复点击。
+5. 推送完成后列表自动刷新，合规状态变为“已推送”或“推送失败”。
+
+### 11.4 批量推送合规
+
+1. 在合同列表勾选需要推送的合同。
+2. 点击工具栏 **批量推送合规**。
+3. 在确认弹窗中点击“确定”。
+
+> 批量推送要求选中的合同全部满足：审核状态为“审批通过”或“变更审批通过”，且合规状态不是“已推送”。如存在不符合条件的合同，系统会提示“选中数据中有 N 条不符合推送条件”，请重新选择。
+>
+> 特批中的合同请勿勾选，需等待特批结果后再处理，系统会拒绝重推。
+
+### 11.5 推送成功后的结果
+
+推送成功后：
+
+- 合规状态变为“已推送”。
+- 详情页“合规信息”中回填“合规合同ID”。
+- 金蝶合同ID由合规系统/金蝶同步完成后回写，可在合同列表查看；如暂时为空，可稍后刷新。
+
+> 注意：“已推送”表示合同已成功提交至合规系统；如客商为高风险/黑名单，特批状态可能仍为“特批中”，需等待特批结果。
+
+### 11.6 推送失败的处理
+
+1. 鼠标悬停在列表的合规状态“推送失败”上，查看失败原因。
+2. 也可进入合同详情，在“合规信息”中查看失败说明。
+3. 根据原因修正数据（如合同类别未配置合规模板、附件异常、客商信息异常等）。
+4. 重新点击“推送合规”。
+
+系统默认会对推送失败的合同自动重试，最多重试 5 次；超过重试次数后，需要人工排查并手动重推（手动重推会将重试次数清零）。
+
+> 特批中的合同不允许重复推送，请等待特批结果后再操作。
+
+---
+
+## 12. 合同特批（高风险/黑名单客商）
+
+### 12.1 什么情况需要特批
+
+当合同甲方或乙方为外部客商，且命中以下任一情况时，需要走特批流程：
+
+- 客商为黑名单；
+- 客商风险等级为高风险。
+
+### 12.2 提交前：上传特批附件
+
+1. 在新增/编辑合同页面，滚动到“附件（佐证材料等）”区域。
+2. 点击上传，附件类型选择 **特批附件**。
+3. 上传特批申请材料及内部审批流程附件。
+
+> 未上传特批附件时提交，系统会提示：**“合同相对方存在高风险/黑名单客商，必须上传「特批附件」类型附件后再提交审批”**。
+
+### 12.3 查看特批状态
+
+高风险/黑名单合同详情页会显示：
+
+- 红色“风险客商提示”，列明风险原因；
+- 合规信息中的“客商风险”“特批状态”“特批说明”。
+
+![特批待发起](images/12-特批待发起.png)
+
+> 高风险客商合同详情（测试环境截图，图中“特批说明”的 C103-8 接口报错为测试环境历史数据）
+
+特批状态说明：
+
+| 特批状态 | 含义 |
+| --- | --- |
+| 待特批 | 历史数据停留在待发起状态，正常新流程不会长期停留在此状态 |
+| 特批中 | 合规系统正在审批特批，当前节点显示“特批审核” |
+| 特批通过 | 特批完成，可继续后续流程 |
+| 特批驳回 | 特批未通过，合同审批会被联动驳回 |
+
+### 12.4 特批的正常流程
+
+1. 合同上传特批附件后提交审批。
+2. 合同审批通过并推送 HCS。
+3. 风险校验命中高风险/黑名单，合同自动进入“特批中”，当前节点为“特批审核”。
+4. 合规系统完成特批后，将结果推送回 TMS；系统定时查询也会补偿获取结果。
+5. 特批通过：合同恢复为“审批通过”；如合规侧已完成金蝶同步，金蝶合同ID会同时回填。
+6. 特批驳回：合同审批状态联动变为“已驳回”，需修改合同后重新提交审批、重新推送。
+
+### 12.5 人工确认特批结果
+
+特批结果通常由合规系统自动回写。如结果未自动回传，合规管理员可在合同详情页人工确认：
+
+1. 打开合同详情，确认特批状态为“特批中”。
+2. 点击“合规信息”右上角的 **确认特批结果**。
+
+![确认特批结果](images/13-确认特批结果.png)
+
+> 确认特批结果
+
+3. 在输入框中输入 `approved`（通过）或 `rejected`（驳回）。
+4. 点击“确定”。
+
+> 人工确认仅允许在“特批中”状态操作，结果只支持 `approved` 和 `rejected`。确认后合同状态会按结果联动变化，请确认结果无误后再提交。
+
+### 12.6 关于“发起特批”按钮
+
+合同详情页右上角的 **发起特批** 是旧版独立发起入口。当前合规接口已改为随合同推送自动发起特批，正常流程**无需点击该按钮**；点击后如提示接口不存在，不影响合同数据。如特批状态长时间停留在“待特批”，请联系系统管理员重新推送合同。
+
+---
+
+## 13. 常见问题
+
+**Q1：审批通过后，合规状态一直显示“待推送”怎么办？**
+
+A：可能当前环境未开启自动推送，或后台扫描任务尚未执行。可先点击操作列“推送合规”手动推送；仍无法推送时联系系统管理员检查推送开关和任务状态。
+
+**Q2：推送失败了怎么办？**
+
+A：将鼠标悬停在“推送失败”上查看原因，或在合同详情“合规信息”中查看。修正数据后点击“推送合规”重推。系统默认自动重试 5 次，超限后必须人工重推。
+
+**Q3：提交时提示必须上传“特批附件”怎么办？**
+
+A：说明合同甲方或乙方命中高风险/黑名单。请在“附件（佐证材料等）”区域上传附件，并将附件类型选择为“特批附件”，然后重新提交。
+
+**Q4：临时合同和正式合同有什么区别？**
+
+A：临时合同用于提前生效，审批通过后有 30 天临时效力；正式合同用于长期履约，是 HCS 合规同步和归档的主要对象。临时合同审批通过后应及时点击“转正式合同”。
+
+**Q5：为什么列表里没有“转正式合同”？**
+
+A：只有合同阶段为“临时合同”，且审核状态为“审批通过”时才显示；临时合同被驳回时显示“重新提交转正”。
+
+**Q6：为什么没有“附件上传”按钮？**
+
+A：只有正式合同，且审核状态为“审批通过”或“变更审批通过”时才允许上传附件。
+
+**Q7：金蝶合同ID为什么为空？**
+
+A：金蝶合同ID由合规系统完成金蝶同步后回写，可能存在延迟。推送成功后可稍后刷新查看；长时间为空请联系系统管理员。
+
+**Q8：合同推送 HCS 后还能修改吗？**
+
+A：不能直接编辑。请通过“变更”流程修改，变更审批通过后系统会更新 HCS，避免产生重复合同或数据不一致。
+
+**Q9：变更页面里的“终止合同”为什么不能提交？**
+
+A：当前版本“终止合同”选项暂未开放，请选择“合同信息变更”完成信息调整；如确需终止合同，请联系系统管理员。
+
+**Q10：上传“双章归档文件”后，归档状态为什么没有变化？**
+
+A：请确认附件位置选择的是“用印材料”，附件类型为“双章归档文件”，并确认合同已审批通过。保存后刷新列表查看；如仍未变化，请联系系统管理员。
+
+**Q11：点击“流程”提示“流程实例为空，无法查看流程”怎么办？**
+
+A：说明该合同没有关联外部审批流程实例。请以列表/详情中的审核状态和当前节点为准；如需查看审批流转，请联系系统管理员。
+
+**Q12：批量推送合规提示“选中数据中有 N 条不符合推送条件”怎么办？**
+
+A：批量推送只允许“审批通过/变更审批通过”且未同步的合同。请取消勾选不符合条件的合同，或单独对符合条件的合同发起推送。
+
+---
+
+## 14. 操作权限速查
+
+| 操作 | 所需条件 |
+| --- | --- |
+| 新增合同 | 具有合同管理新增权限 |
+| 编辑合同 | 草稿、已撤回、已驳回、变更驳回状态 |
+| 删除合同 | 草稿状态 |
+| 复制合同 | 具有合同管理复制权限，复制后为新增草稿 |
+| 转正式合同 | 临时合同 + 审批通过 |
+| 变更 | 正式合同 + 审批通过 / 变更审批通过 |
+| 重新提交变更 | 正式合同 + 变更驳回 |
+| 附件上传 | 正式合同 + 审批通过 / 变更审批通过 |
+| 推送合规 | 审批通过 / 变更审批通过 + 未同步 |
+| 通过 / 驳回 | 审批中 / 变更审批中 + 审批权限 |
+| 撤回 | 审批中（撤回变更仅限变更审批中） |
+
+---
+
+## 15. 注意事项
+
+1. 合同编号不填写时按部门规则自动生成；手工编号请确保唯一。
+2. 合同金额不能小于 0，金额类字段请按实际合同金额填写。
+3. 高风险/黑名单客商合同必须上传“特批附件”，新增、变更、重新提交时均需保留。
+4. 临时合同有效期为 30 天，请及时转正式合同。
+5. 合同审批通过后会自动进入合规推送，请耐心等待，不要重复点击审批或推送。
+6. 已推送 HCS 的合同需要修改时，必须走“变更”流程，禁止重复新建合同。
+7. 推送失败时先查看失败原因，修正后再重推；特批中的合同不要重推。
+8. 合同列表默认按创建时间倒序，审批、归档、合规状态请以页面实时显示为准。
+9. 本文截图取自测试环境，正式环境的数据和按钮以实际权限配置为准。

doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.md

@@ -0,0 +1,647 @@
+# HCS 合同管理操作手册（纯操作版）
+
+> 整理日期：2026-10-23
+> 适用对象：合同经办人、合同负责人、合同审批人、合规管理员、实施运维。
+> 本文只讲**怎么操作**：在哪个页面、点什么按钮、前提是什么、成功的标志是什么、失败了怎么处理。
+> 第 1–3 节为业务操作；第 4 节为实施运维使用的五类 HCS 定时任务逻辑、接口与配置。
+> 完整字段说明、状态字典与流程背景见同目录《2026-10-23-HCS合同管理操作手册》；接口与代码细节见同目录 HCS 相关梳理文档。
+
+---
+
+## 1. 全局须知
+
+TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）。HCS 完成客商风险校验、合同合规校验、特批和金蝶同步，并把合规合同ID、金蝶合同ID、特批结果回写到 TMS。
+
+### 1.1 列表里的三个合规状态
+
+| 状态值 | 页面显示 | 含义 | 还会变吗 |
+|---|---|---|---|
+| unsynced | 待推送 | 审批已通过，尚未成功推送 HCS | 会（推送成功变“已推送”） |
+| synced | 已推送 | HCS 已受理，已回填合规合同ID | 会（特批状态、金蝶合同ID可能继续变化） |
+| failed | 推送失败 | 推送失败，鼠标悬停合规状态可查看原因 | 会（自动重试或手动重推成功后变“已推送”） |
+
+### 1.2 特批状态
+
+| 状态值 | 页面显示 | 含义 | 后续 |
+|---|---|---|---|
+| need | 待特批 | 尚未进入特批流程，多见于存量数据或推送未完成 | 重新推送成功后转“特批中” |
+| processing | 特批中 | HCS 正在审批特批，当前节点显示“特批审核” | 等待 HCS 回传、定时查询或人工确认 |
+| approved | 特批通过 | 特批完成 | 合同恢复“审批通过”，继续后续流程 |
+| rejected | 特批驳回 | 特批未通过 | 合同审批联动“已驳回”，修改后重新提交、重新推送 |
+
+### 1.3 三条推送路径
+
+| 路径 | 触发时机 | 前提 | 说明 |
+|---|---|---|---|
+| 自动即时推送 | 审批人点“通过”后 | `thirdParty.hcs.push.immediate-enabled=true` | 审批响应会等待推送结果；失败提示“审批通过，但合规推送失败：xxx” |
+| 定时扫描推送 | 每 5 分钟 | `thirdParty.hcs.push.contract.sync-enabled=true` | 扫“待推送/推送失败未超限”的合同；同时兜底查询特批结果 |
+| 手动推送 | 随时 | 合同已审批通过且未同步 | 列表“推送合规”或工具栏“批量推送合规” |
+
+三条路径共用同一套推送逻辑；HCS 侧有判重，重复触发不会重复生成合同。即时推送目前只覆盖合同和项目立项，付款链、开票登记、收票单没有即时推送，只能靠定时扫描或手动接口。
+
+### 1.4 硬规则
+
+- 只有审核状态为“审批通过”或“变更审批通过”的合同可以推送；其他状态请先完成审批。
+- 高风险/黑名单客商合同，**提交审批前必须上传“特批附件”**，否则提交会被拦截。
+- 特批中（processing）的合同**不允许重推**，请等待特批结果。
+- 合同推送 HCS 后不能直接编辑；需要修改时必须走“变更”，变更审批通过后更新 HCS。
+- 合同类别必须在 Nacos 配置 HCS 模板映射，否则每次推送都会失败。
+- 推送失败默认自动重试，最多 5 次；超过后只能人工重推。人工重推会把失败次数清零。
+- 当前版本临时合同审批通过后也会进入推送范围（合规状态会变为待推送/已推送），不要因为合同是临时合同就忽略合规状态。
+
+### 1.5 推送与环境前提
+
+**推送成功必需：**
+
+1. 合同已审批通过或变更审批通过。
+2. 合同类别已配置 HCS 模板ID（`thirdParty.hcs.contract.template-mapping`）。
+3. HCS 连接配置可用（`baseUrl`、`authorization`、`key-auth`）。
+4. 合同如有附件，TMS 文件服务可被 HCS 侧下载（`attachment.file-download-base` 已配置）。
+5. 合同不处于“特批中”状态。
+
+**风险校验需要：**
+
+- 甲乙双方名称应能在客商档案中匹配到（全称或简称）。匹配不到不会阻断推送，但会**跳过该方风险校验**，可能导致高风险/黑名单客商未被识别、未触发特批。
+
+---
+
+## 2. 一次性准备（实施/管理员操作）
+
+| # | 事项 | 操作人 | 操作内容 | 不做的后果 |
+|---|---|---|---|---|
+| 1 | HCS 连接配置 | 运维 | Nacos `thirdParty.hcs.baseUrl`、`authorization`、`key-auth` | 所有推送失败或认证被拒 |
+| 2 | 来源与操作人 | 运维 | `thirdParty.hcs.src-system`（约定 WLTMS）、`operator-login-name` | 合规侧来源/操作人不符合约定 |
+| 3 | 合同类别模板映射 | 运维 | `thirdParty.hcs.contract.template-mapping`，为**每个合同类别**配置 HCS 模板ID | 未映射的类别推送必失败，提示“合同类别未配置合规模板ID” |
+| 4 | 附件下载基址 | 运维 | `thirdParty.hcs.attachment.file-download-base`；保持 `transfer-enabled=true` | 合同有附件时转传失败 |
+| 5 | 币种映射 | 运维 | `thirdParty.hcs.contract.currency-name-mapping`（如 RMB→人民币） | 币种传错或为空 |
+| 6 | 风险校验开关 | 运维 | `thirdParty.hcs.contract.require-risk-check` 保持 `true` | 关闭后高风险合同不会触发特批 |
+| 7 | 履约计划同步 | 运维 | `thirdParty.hcs.exe-stage.sync-enabled`，一期默认 `false` | 不推送 C103-9 履约计划，不影响合同主流程 |
+| 8 | 推送开关 | 运维 | 按需开启 `push.immediate-enabled`、`push.contract.sync-enabled` | 只能靠手动按钮推送 |
+| 9 | 客商档案 | 业务 | 确保合同甲乙方名称与客商档案全称或简称一致 | 风险校验取不到客商，无法判定高风险/黑名单 |
+| 10 | 菜单与按钮权限 | 管理员 | 为经办人、审批人、合规管理员配置对应角色权限 | 页面看不到新增、审批或推送合规入口 |
+
+> 模板映射的中文键在 Nacos YAML 中必须使用括号写法，例如 `"[承运商合同]": "模板ID"`，否则配置无法正确绑定。
+>
+> 当前 Nacos 样例只映射了“承运商合同”。客户合同、补充协议如果也要推送，必须在上线前逐类确认并补齐映射。
+
+---
+
+## 3. 日常操作流程
+
+### 3.1 查找与筛选合同
+
+**页面：合同管理 → 合同管理**
+
+![合同管理列表：顶部为到期标签与工具栏，列表含合同阶段、审核状态、合规状态、金蝶合同ID、当前节点/处理人](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/01-合同列表.png)
+
+![合同搜索区：可按合同编号、合同名称、项目、负责部门、审核状态、合规状态等条件筛选](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/03-合同列表筛选.png)
+
+1. 找“待推送”合同：审核状态选 **审批通过** 或 **变更审批通过**，合规状态选 **待推送**。
+2. 找“推送失败”合同：合规状态选 **推送失败**，鼠标悬停合规状态查看失败原因。
+3. 支持按合同编号、合同名称、项目、合同负责部门、签约类型、合同类别、生效类型、归档状态、是否同步合规/金蝶筛选。
+4. 列表上方的到期标签（全部、30天内到期、90天内到期、90天以上到期、已到期）可直接筛选。
+5. 点击合同名称进入详情；操作列按合同状态显示可用操作。
+
+> 说明：
+> - 列表默认按创建时间倒序排列。
+> - 特批中的合同合规状态仍是“已推送”，要通过“特批状态”或当前节点“特批审核”识别，不能只看合规状态。
+
+### 3.2 新增合同并提交审批
+
+**页面：合同管理 → 合同管理 → 新增**
+
+![新增合同：填写签约类型、合同名称、合同类型、项目、甲乙方、合同期限、金额、结算方式等基本信息](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/04-新增合同-基本信息.png)
+
+![新增合同下部：计费信息、结算单规则、付款比例设置和佐证材料附件](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/05-新增合同-计费结算与附件.png)
+
+1. 点左上角 **新增**。
+2. 填写基本信息。合同编号可不填，系统按合同负责部门规则自动生成。
+3. 填写计费信息、结算单规则、付款比例设置。
+   - 提交**正式合同**前，这三块必须完整并通过校验。
+   - 提交**临时合同**只校验基础必填项。
+4. 上传附件：
+   - 用印材料区域可上传“用印材料 / 双章归档文件 / 其他文件”。
+   - 佐证材料区域可上传“特批附件 / 其他文件”。
+   - 高风险/黑名单客商合同必须上传类型为 **特批附件** 的文件。
+5. 选择提交方式：
+
+| 按钮 | 适用场景 | 提交后状态 |
+|---|---|---|
+| 保存 | 信息未填全，先暂存 | 合同阶段“草稿”、审核状态“草稿”，不推送 HCS |
+| 提交临时合同 | 需要合同尽快生效 | 合同阶段“临时合同”、审核状态“审批中” |
+| 提交正式合同 | 信息完整，直接走正式审批 | 合同阶段“正式合同”、审核状态“审批中” |
+
+**成功标志**：列表出现该合同，状态与上表一致。
+
+**常见拦截**：
+
+- 提示必填项缺失 → 补齐后重新提交。
+- 提示付款比例/结算规则校验不通过 → 按页面提示调整计费、结算或付款比例。
+- 提示必须上传“特批附件” → 在“附件（佐证材料等）”区域上传，附件类型选“特批附件”。
+
+### 3.3 临时合同转正式合同
+
+**页面：合同管理 → 合同管理**
+
+前提：合同阶段为“临时合同”，审核状态为“审批通过”。
+
+1. 在列表找到该临时合同。
+2. 点操作列 **转正式合同**。
+3. 在确认弹窗点“确定”。
+4. 提示“已提交正式合同审批”。
+
+**提交后的变化**：
+
+- 合同阶段变为“正式合同”，审核状态变为“审批中”，当前节点“正式合同审批”。
+- 申请日期自动更新为当天。
+- 正式审批通过后进入 HCS 推送。
+
+> 临时合同审批被驳回时，操作列显示“重新提交转正”；编辑修改后再提交即可。临时合同有效期为 30 天，请及时转正式合同。
+
+### 3.4 审批通过与推送 HCS
+
+**页面：合同管理 → 合同管理（审批人操作）**
+
+![合同列表状态与操作列：审批中显示通过/驳回/撤回，审批通过且未同步的合同显示“推送合规”](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/02-合同列表状态与操作列.png)
+
+**审批人操作：**
+
+1. 在操作列点 **通过**。
+2. 如当前环境开启即时推送，页面显示“正在推送合规，请稍候…”遮罩，请等待完成，不要重复点击。
+3. 根据提示判断结果：
+
+| 提示 | 含义 | 处理 |
+|---|---|---|
+| 审批通过 | 审批完成；即时推送成功，或当前未开启即时推送 | 查看合规状态确认；未推送则手动推或等待扫描 |
+| 审批通过，但合规推送失败：xxx | 审批已生效，但 HCS 推送失败 | 按失败原因修复后点“推送合规”重推，**不要重复审批** |
+
+**手动推送单条：**
+
+![手动推送合规确认：列表行内“推送合规”，确认后显示“正在推送合规，请稍候…”](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/15-手动推送合规确认.png)
+
+1. 在列表找到“待推送”或“推送失败”的合同。
+2. 点操作列 **推送合规**。
+3. 在确认弹窗点“确定”。
+4. 等待“正在推送合规，请稍候…”结束，列表自动刷新。
+
+**批量推送：**
+
+1. 勾选需要推送的合同。
+2. 点工具栏 **批量推送合规**。
+3. 在确认弹窗点“确定”。
+4. 系统逐条推送，单条失败不影响其他合同。
+
+> 批量推送要求选中合同全部满足：审核状态为“审批通过/变更审批通过”，且合规状态不是“已推送”。否则提示“选中数据中有 N 条不符合推送条件”，请重新勾选。
+
+**成功标志**：合规状态变为 **已推送**，详情页回填 **合规合同ID**。
+
+> 高风险/黑名单合同推送成功后，合规状态同样是“已推送”，但特批状态会进入“特批中”，这是正常流程，不是推送失败。
+
+### 3.5 查看推送结果
+
+**页面：合同管理 → 合同详情**
+
+![合同详情：基本信息下方显示合规信息，包括合规同步状态、合规合同ID、客商风险、特批状态、特批说明](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/06-合同详情-基本信息与合规信息.png)
+
+在详情页“合规信息”区域查看：
+
+| 字段 | 说明 |
+|---|---|
+| 合规同步状态 | 待推送 / 已推送 / 推送失败；失败时可悬停查看原因 |
+| 合规合同ID | HCS 返回的合同唯一标识，推送成功后回填 |
+| 客商风险 | 是否黑名单、风险等级 |
+| 特批状态 | 待特批 / 特批中 / 特批通过 / 特批驳回 |
+| 特批说明 | 特批原因或处理说明 |
+
+**推送成功的判断标准**：合规状态为“已推送”，且“合规合同ID”不为空。
+
+> 金蝶合同ID由 HCS 完成金蝶同步后回写，可能存在延迟；暂时为空可稍后刷新列表查看。“已推送”只代表 HCS 已受理，不代表特批和金蝶同步已经完成。
+
+### 3.6 推送失败的处理与重推
+
+**页面：合同管理 → 合同管理 / 合同详情**
+
+![待推送与推送失败列表：合规状态列显示“待推送/推送失败”，失败原因可悬停查看](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/14-待推送与推送失败列表.png)
+
+1. 鼠标悬停列表中的“推送失败”，或进入详情查看失败说明。
+2. 按下表排查并修正数据/配置。
+3. 修正后点操作列 **推送合规**，确认后等待结果。
+4. 手动重推会把失败次数清零；如仍失败，按新的失败原因继续处理。
+
+**自动重试规则**：
+
+- 合同扫描任务开启时，每 5 分钟自动重试“推送失败且未超过 5 次”的合同。
+- 超过 5 次后不再自动重试，必须人工重推。
+- 手动重推没有次数限制，但根因不修复会反复失败。
+
+**常见失败原因**：
+
+| 失败提示/现象 | 原因 | 处理 |
+|---|---|---|
+| 合同类别 [xxx] 未配置合规模板ID | Nacos 模板映射缺该类合同 | 运维在 `contract.template-mapping` 补齐后重推 |
+| 附件转传失败 | 下载基址为空、附件文件不存在、文件超限或 HCS 附件接口异常 | 检查 `attachment.file-download-base`、附件是否可下载，修正后重推 |
+| C101-1 客商风险查询失败 | HCS 风险接口异常/无响应 | 联系 HCS 侧确认接口，恢复后重推；客商档案匹配不到不会报此错，而是跳过风险校验 |
+| C103-3 合同判重查询失败 | HCS 查重接口异常/网络超时 | 稍后重推；持续失败联系 HCS 侧 |
+| C103-1 合同发起失败 | HCS 返回业务校验错误（模板、必填字段、主数据等） | 按返回的 msg 修正数据；必要时联系合规方核对模板 |
+| C103-11 合同更新失败 | 变更合同更新 HCS 失败 | 按返回 msg 处理，修正后重推 |
+| 合同特批审核中，禁止重推 | 合同处于“特批中” | 等待特批结果，不要重推 |
+| 网络超时/连接失败 | HCS 服务不可用或网络抖动 | 恢复后重推；扫描开关开启时系统也会自动重试 |
+
+> 如果怀疑 HCS 侧其实已经生成合同，仍可直接重推：本地没有合规合同ID时会先走判重（C103-3），命中后回填已有ID；已有合规合同ID时走更新（C103-11）。两种路径都不会重复生成合同。
+
+### 3.7 高风险/黑名单合同特批
+
+**页面：合同详情 → 合规信息**
+
+![高风险客商合同详情：红色风险客商提示，合规信息显示客商风险、特批状态、特批说明](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/12-特批待发起.png)
+
+**触发条件**：合同甲方或乙方为外部客商，且客商为黑名单或风险等级为高风险。
+
+**提交前：**
+
+1. 在新增/编辑合同的“附件（佐证材料等）”区域上传特批申请材料。
+2. 附件类型必须选择 **特批附件**。
+3. 未上传时提交，系统提示“合同相对方存在高风险/黑名单客商，必须上传「特批附件」类型附件后再提交审批”。
+
+**正常流程：**
+
+1. 合同审批通过并推送 HCS。
+2. 风险校验（C101-1）命中高风险/黑名单，合同自动进入特批流程。
+3. TMS 特批状态变为 **特批中**，当前节点显示 **特批审核**。
+4. HCS 完成特批后，通过结果推送或 TMS 定时查询回传结果。
+5. 特批通过：合同恢复“审批通过”；如 HCS 已完成金蝶同步，金蝶合同ID会同时回填。
+6. 特批驳回：合同审批状态联动变为“已驳回”，修改合同后重新提交审批、重新推送。
+
+**人工确认特批结果（结果未自动回传时）：**
+
+![确认特批结果：在合规信息右上角点击“确认特批结果”，输入 approved 或 rejected](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/13-确认特批结果.png)
+
+1. 打开合同详情，确认特批状态为 **特批中**。
+2. 点“合规信息”右上角 **确认特批结果**。
+3. 输入 `approved`（通过）或 `rejected`（驳回）。
+4. 点“确定”。
+
+> 人工确认仅允许在“特批中”状态操作，结果只支持 `approved` 和 `rejected`。确认后合同状态会按结果联动变化，请核对无误后再提交。
+
+**关于“发起特批”按钮：**
+
+- 详情页右上角的 **发起特批** 是旧版独立入口，当前合规接口已改为随合同推送自动发起特批，正常流程**无需点击**。
+- 点击后如提示接口不存在，不影响合同数据，请忽略。
+- 如特批状态长时间停留在“待特批”，请联系系统管理员重新推送合同。
+
+> 特批中的合同不允许重推，请等待特批结果。特批驳回后的合同必须修改并重新提交审批，不能直接重推。
+
+### 3.8 合同变更并更新 HCS
+
+**页面：合同管理 → 合同管理 → 变更**
+
+![合同变更页面：在正式合同基础上修改基本信息、附件、计费、结算和付款比例](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/09-合同变更-基本信息.png)
+
+![合同变更下部：填写变更原因（最多 500 字）并上传变更材料](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/10-合同变更-原因与材料.png)
+
+前提：合同阶段为“正式合同”，审核状态为“审批通过”“变更审批通过”或“变更驳回”。
+
+1. 在列表点操作列 **变更**（变更驳回后点“重新提交变更”）。
+2. 修改需要变更的内容：基本信息、用印材料、计费信息、结算单规则、付款比例、附件等。
+3. 填写 **变更原因**，最多 500 字。
+4. 在“变更材料”区域上传相关附件。
+5. 点页面底部 **提交**，在确认弹窗点“确定”。
+6. 审核状态变为 **变更审批中**。
+
+**审批人操作：**
+
+- 通过：审核状态变为 **变更审批通过**，系统按合规合同ID更新 HCS（C103-11）；如该合同从未推送过，则按首次推送处理。
+- 驳回：审核状态变为 **变更驳回**，可点“重新提交变更”重新填写并提交。
+- 撤回变更：仅变更审批中可撤回，撤回后恢复为“审批通过”。
+
+**变更结果：**
+
+- 变更附件合并到合同附件，变更原因、变更内容被清空。
+- 变更记录保留，可在详情页底部查看。
+
+![合同详情变更记录：展示变更日期、经办人、变更类型、变更内容、变更原因和状态](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/08-合同详情-变更记录.png)
+
+> 页面中的“终止合同”选项当前版本暂未开放，请选择“合同信息变更”。已推送 HCS 的合同禁止直接编辑，必须走变更流程，否则会产生重复合同。
+
+### 3.9 附件上传与归档
+
+**页面：合同管理 → 合同管理 → 附件上传**
+
+前提：合同阶段为“正式合同”，审核状态为“审批通过”或“变更审批通过”。
+
+![附件上传弹窗：先选择附件位置（用印材料/佐证材料），再选择附件类型并上传](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/11-附件上传弹窗.png)
+
+1. 在列表点操作列 **附件上传**。
+2. 选择 **附件位置**：
+   - **用印材料**：可上传用印材料、双章归档文件、其他文件。
+   - **附件（佐证材料等）**：可上传特批附件、其他文件。
+3. 选择 **附件类型**。
+4. 将文件拖入上传区域，或点击选择文件。
+5. 点 **确定** 保存。
+
+**上传限制**：
+
+- 支持 pdf、bmp、jpeg、png、jpg、doc、docx、ppt、pptx、xlsx、xls、eml、msg、zip。
+- 单个文件不超过 50MB。
+- 上传人、上传时间由系统自动记录。
+
+**归档规则**：
+
+- 上传附件类型为 **双章归档文件**，且附件位置选择“用印材料”时，合同审批通过或附件保存后归档状态变为 **已归档**。
+- 其他附件类型不会改变归档状态。
+
+![合同详情附件区：可查看、下载用印材料和佐证材料](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/07-合同详情-附件佐证材料.png)
+
+---
+
+## 4. 定时任务与接口（运维视角）
+
+HCS 推送由五个独立定时任务和一组手动接口组成。五个任务各有自己的开关与 cron，互不影响；定时任务、手动接口和审批即时推送共用同一套推送逻辑。
+
+### 4.1 五类定时任务总览
+
+| 任务 | bizType | 扫描对象 | 推送链路（HCS 接口） | 独立开关 | 默认 cron | 手动触发 |
+|---|---|---|---|---|---|---|
+| 项目立项 C102 | `project` | 项目立项：审批通过/变更审批通过，待推送/失败未超限 | C102-3 判重 → C102-1 新建 / C102-2 更新 | `push.project.sync-enabled`（默认 `false`） | `0 */5 * * * ?` | `POST /hcs/sync/project/{id}`、`/hcs/sync/project`、`/hcs/sync/project/batch` |
+| 合同 C103 | `contract` | 合同：审批通过/变更审批通过，待推送/失败未超限；同轮补查特批结果 | C101-1 风险 → C103-2 附件 → C103-3 判重 → C103-1 起草 / C103-11 更新 → C103-9 履约规则（开关）→ 高风险挂特批 | `push.contract.sync-enabled`（默认 `false`） | `0 1/5 * * * ?` | `POST /hcs/sync/contract/{id}`、`/hcs/sync/contract`、`/hcs/sync/contract/batch` |
+| 付款链 C106/C108 | `payment` | 付款申请：审批通过，待推送/失败未超限 | C106-3/C106-4 特批（`hcs_spec_status=need` 时）→ C103-9 履约规则重推 → C108-1/C108-2 履约记录（开关） | `push.payment.sync-enabled`（默认 `false`） | `0 2/5 * * * ?` | `POST /hcs/sync/payment/{id}`、`/hcs/sync/payment` |
+| 开票登记 C111 | `invoice-application` | 开票申请：审批通过，待推送/失败未超限 | C111-1 判重 → C111-2 新增 → C111-3 更新（金蝶已开票/已有ID） | `push.invoice-application.sync-enabled`（默认 `false`） | `0 3/5 * * * ?` | `POST /hcs/sync/invoice-application/{id}`、`/hcs/sync/invoice-application` |
+| 收票单 C109 | `invoice-receipt` | 收票单：审批通过，待推送/失败未超限 | C109-1 新建 / C109-2 更新 | `push.invoice-receipt.sync-enabled`（默认 `false`） | `0 4/5 * * * ?` | `POST /hcs/sync/invoice-receipt/{id}`、`/hcs/sync/invoice-receipt` |
+
+> - **即时推送只有项目立项和合同**：审批通过后立即推送（受 `push.immediate-enabled` 控制）。付款链、开票登记、收票单没有即时推送，只能靠定时扫描或手动接口。
+> - 五个扫描开关默认全部 `false`，按业务灰度打开；手动接口不受开关限制。
+> - 只有合同扫描任务额外承担“特批结果兜底查询”，其他任务没有这个动作。
+
+### 4.2 公共执行框架
+
+五个任务都按同一套模板执行：
+
+1. **开关校验**：`push.{bizType}.sync-enabled=false` 时直接跳过本轮，属正常灰度状态。
+2. **抢任务锁**：按 bizType 抢 Redis 锁 `blade:third:hcs:push:task:lock:{bizType}`，TTL 240 秒；抢不到说明其他实例正在执行，本轮跳过。
+3. **扫描单据**：
+   - 项目立项/合同：审核状态为 `approved` / `change_approved`；
+   - 付款申请/开票申请/收票单：审核状态仅 `approved`；
+   - 合规状态为 `unsynced` / `failed`；
+   - 失败次数为空或小于 `push.max-retry`（默认 5）；
+   - 单轮最多 `push.batch-size`（默认 50）条。
+4. **逐条推送**：单条失败只把该条置 `failed`、失败次数 +1、记录原因，不影响同批其他单据；下一轮自动重试未超限单据。
+5. **结果回写**：成功置 `synced`、失败次数清零、记录同步时间和结果说明；项目立项、合同、开票申请、收票单同时回填合规ID。
+6. **任务日志**：每轮输出“扫描 X 条，成功 Y 条，失败 Z 条（重试上限 5）”；抢锁失败输出“其他实例执行中，本轮跳过”。
+
+> 手动接口和定时任务的区别：手动单条/批量/扫一轮接口**不检查开关，也不抢任务锁**，适合开关关闭时临时补推；不要和定时任务同一时刻执行，避免并发重复调用（HCS 侧有判重/更新幂等，但会增加无效请求）。
+
+### 4.3 项目立项任务（C102）
+
+**扫描条件**：审核状态为 `approved` / `change_approved`，合规状态为 `unsynced` / `failed`，失败次数为空或小于 `push.max-retry`；单轮最多 `push.batch-size` 条。
+
+**推送逻辑**：
+
+1. 项目没有合规项目ID（`hcs_fd_id` 为空）：先调 C102-3 判重，查询条件 `fd_num=项目编号`。命中则回填已有合规ID并置 `synced`，不再新建；未命中调 C102-1 新建，成功后回填合规项目ID。
+2. 项目已有合规项目ID（通常是变更审批通过）：调 C102-2 更新。
+3. C102-1 依赖 `project.template-code`；未配置时整条推送失败，提示“立项表单模板编码未配置”。
+4. C102-1 以 `drafter_submit` 方式直接提交（不存草稿）；付款额度、开票额度由万元乘 10000 转为元，计划保证金仍按万元直传。
+
+**金蝶结果回调**：HCS 完成金蝶同步后调 `projectLegal/result`，按 `projectCode`（TMS 项目编号）定位；`success=true` 回填金蝶项目ID/编号，`success=false` 记录失败原因。该回调**不改** HCS 同步状态和重试次数，也不触发 TMS 重推。
+
+**接口**：
+
+| 接口 | 作用 | 关键行为 |
+|---|---|---|
+| `POST /hcs/sync/project/{id}` | 单条重推 | 仅 `approved` / `change_approved` 可推；先重置 `unsynced`、失败次数清零，再立即推送 |
+| `POST /hcs/sync/project` | 按扫描逻辑推一轮 | 最多 `batch-size` 条；**不检查开关、不抢任务锁** |
+| `POST /hcs/sync/project/batch` | 按勾选ID批量重推 | 请求体为ID数组；逐条重置并推送，单条失败不影响其他，返回成功数与失败明细 |
+| `POST /hcs/projectLegal/result` | HCS 回调金蝶同步结果 | 报文含 `projectCode`、`success`、`kingdeeId`、`projectNumber`、`reason`、`sourceSystem`；只回填金蝶ID/编号或失败原因 |
+
+### 4.4 合同任务（C103）
+
+**扫描条件**：审核状态为 `approved` / `change_approved`，合规状态为 `unsynced` / `failed`，失败次数未超限；单轮最多 `batch-size` 条。除推送外，任务每轮还会补查特批结果。
+
+**推送逻辑**：
+
+1. **特批挂起门禁**：`hcs_spec_status=processing` 的合同跳过推送，等待特批结果；手动重推直接报“合同特批审核中，禁止重推”。
+2. **客商风险 C101-1**（`contract.require-risk-check=true`）：甲乙双方分别查询；客商档案匹配不到或为内部组织时跳过该方，不阻断；任一方高风险或黑名单只做标记，**不阻断推送**，推送成功后自动转特批。
+3. **附件转传 C103-2**（`attachment.transfer-enabled=true`）：附件转传失败会导致整次推送失败。
+4. **首次推送**：无合规合同ID时先调 C103-3 判重（`fdNumber=合同编号`）；命中直接回填已有ID并置已推送，未命中调 C103-1 起草；起草成功后立即回填合规合同ID，再继续后续步骤。
+5. **变更推送**：已有合规合同ID时调 C103-11 更新。
+6. **履约规则 C103-9**（`exe-stage.sync-enabled=true`）：按履约计划行级新增/更新/删除；无可同步行时返回“履约规则无待同步行”；同步失败会把整条合同置 `failed`。由于第 4 步已先回填合规ID，下一轮重推会走 C103-11 更新，不会重复起草。
+7. **高风险挂起特批**：风险命中时置 `hcs_spec_status=processing`、当前节点“特批审核”，等待 HCS 特批结果。
+
+**特批结果兜底（随合同任务执行）**：
+
+- 每轮推送完待同步合同后，另查 `hcs_spec_status=processing` 且已有合规合同ID的合同，固定最多 50 条。
+- 逐条调 C103-4 查询合同详情：`fdApprovalStatus=approved` → 特批通过，当前节点恢复“审批通过”；`approvalinvalid` → 特批驳回，合同审批状态联动 `rejected`、当前节点“已驳回”；其他状态继续等待。
+- 单条查询失败只记日志，下一轮继续；HCS 主动回调 `contractLegal/result` 是并行的另一条结果通道。
+- 该兜底只随合同定时任务执行，受 `push.contract.sync-enabled` 控制；手动 `POST /hcs/sync/contract` **不补查**特批结果，需用“确认特批结果”接口人工兜底。
+
+合同链路涉及的 HCS 接口：C101-1 风险查询、C103-2 附件上传、C103-3 判重、C103-1 起草、C103-11 更新、C103-9 履约规则、C103-4 特批结果查询。
+
+**接口**：
+
+| 接口 | 作用 | 关键行为 |
+|---|---|---|
+| `POST /hcs/sync/contract/{id}` | 单条重推 | 仅 `approved` / `change_approved`；`processing` 拒绝；先重置 `unsynced`、失败次数清零 |
+| `POST /hcs/sync/contract` | 按扫描逻辑推一轮 | **不检查开关、不抢任务锁、不补查特批结果** |
+| `POST /hcs/sync/contract/batch` | 按勾选ID批量重推 | 请求体为ID数组；逐条重置并推送，返回成功数与失败明细 |
+| `POST /hcs/contract/spec/confirm` | 人工确认合同特批结果 | 参数 `id`、`result`（`approved`/`rejected`）；仅 `processing` 可确认 |
+| `POST /hcs/contractLegal/result` | HCS 回调特批+金蝶同步结果 | 报文含 `contractType`、`contractCode`、`requestId`、`success`、`reason`、`kingdeeId`、`sourceSystem`；`sourceSystem` 必须匹配；按 `contractCode` 定位；`success=true` → 特批通过并回填 `kingdeeId`；`false` → 特批驳回并联动合同审批驳回 |
+| `POST /hcs/contractKingdee/result` | HCS 回调金蝶最终同步结果 | 报文同上；只回填 `kingdeeId` 或失败原因，**不改**审批状态和特批状态 |
+
+### 4.5 付款链任务（C106/C108）
+
+**扫描条件**：付款申请审核状态仅 `approved`（不含变更状态），合规状态为 `unsynced` / `failed`，失败次数未超限；单轮最多 `batch-size` 条。
+
+**特批从哪来**：付款提交时，收款方为高风险/黑名单（`risk.check-on-payment=true`，须先上传特批附件）或额度超额（`credit.check-enabled=true`）会置 `hcs_spec_status=need`。扫描任务负责把 `need` 的付款发起特批。
+
+**推送逻辑**：
+
+1. `hcs_spec_status=need`：无特批流程ID（`hcs_spec_fd_id`）时调 C106-3 发起特批，已有特批流程ID时调 C106-4 更新。C106-3 依赖 `spec-pay.template-id` 与关联合同的合规合同ID；成功后回填特批流程ID、置 `processing`、当前节点“特批审核”。
+2. 关联合同已推送合规（合同 `hcs_fd_id` 非空）时，调 C103-9 重推履约规则；无待同步行自动跳过。该动作**不受** `exe-stage.sync-enabled` 控制，与合同任务不同。
+3. `perf-record.sync-enabled=false`：直接置整体 `synced` 结束；`true`：无履约记录ID调 C108-1 新建，已有调 C108-2 更新。
+4. 整体合规状态 `synced` 只代表本轮推送完成，**不代表特批已通过**；特批中（`processing`）的付款也可能显示已推送。
+
+**特批结果**：HCS 通过 `paymentLegal/result` 回调，或用 `/hcs/spec-pay/confirm` 人工确认。通过后恢复“审批通过”并重新触发金蝶自动同步；驳回后付款审批状态置 `returned`（已驳回），需修改后重新提交审批、重新发起特批。
+
+付款链路涉及的 HCS 接口：C106-3 特批发起、C106-4 特批更新、C103-9 履约规则、C108-1/C108-2 履约记录。
+
+**接口**：
+
+| 接口 | 作用 | 关键行为 |
+|---|---|---|
+| `POST /hcs/sync/payment/{id}` | 单条重推 | 仅 `approved` 可推；先重置 `unsynced`、失败次数清零 |
+| `POST /hcs/sync/payment` | 按扫描逻辑推一轮 | 不检查开关、不抢任务锁；**无批量 ID 接口** |
+| `POST /hcs/spec-pay/confirm` | 人工确认付款特批结果 | 参数 `id`、`result`（`approved`/`rejected`）；仅 `processing` 可确认 |
+| `POST /hcs/paymentLegal/result` | HCS 回调付款特批结果 | 报文含 `sourceSystem`、`requestId`、`status`、`reason`；`requestId` 为 TMS 付款申请ID；`status=APPROVED/REJECTED`；通过恢复审批并触发金蝶同步，驳回置 `returned` |
+
+### 4.6 开票登记任务（C111）
+
+**扫描条件**：开票申请审核状态仅 `approved`，合规状态为 `unsynced` / `failed`，失败次数未超限；单轮最多 `batch-size` 条。
+
+**推送逻辑**：
+
+1. 没有合规开票登记ID时，先调 C111-1 判重（`fdNumber=开票申请编号`）；命中直接回填已有ID并置已推送，未命中调 C111-2 新增。
+2. C111-2 必须能通过应收结算链路回溯到合同编号，回溯不到整条推送失败；币种映射 `invoice.currency-id-mapping.RMB` 必须非空，否则整条推送失败；发票类型映射缺失只记警告并留空字段，是否被拒取决于 HCS 必填校验。
+3. 新增成功后，若金蝶状态为已开票（`kingdeeStatus=invoiced`），立即调 C111-3 更新票据日期/状态；已有合规ID时同样走 C111-3。
+4. 金蝶开票完成的结果回写会把 `hcs_sync_status` 重置为 `unsynced`，下一轮扫描自动执行 C111-3，不需要人工重推。
+5. 附件在推送时经 C103-2 转传（受 `attachment.transfer-enabled` 控制）。
+
+开票登记没有 HCS 结果回调接口，TMS 不接收 C111 的结果推送；以整体同步状态和 `hcs_sync_msg` 为准。
+
+**接口**：
+
+| 接口 | 作用 | 关键行为 |
+|---|---|---|
+| `POST /hcs/sync/invoice-application/{id}` | 单条重推 | 仅 `approved` 可推；先重置 `unsynced`、失败次数清零 |
+| `POST /hcs/sync/invoice-application` | 按扫描逻辑推一轮 | 不检查开关、不抢任务锁；**无批量 ID 接口** |
+
+### 4.7 收票单任务（C109）
+
+**扫描条件**：收票单审核状态仅 `approved`，合规状态为 `unsynced` / `failed`，失败次数未超限；单轮最多 `batch-size` 条。
+
+**推送逻辑**：
+
+1. 没有合规收票单ID时调 C109-1 新建，成功后回填 `hcs_fd_id`；已有合规ID时调 C109-2 更新。
+2. 合同关联按“收票单 → 结算关系 → 正式结算 → 合同”回溯；回溯不到时取页面人工补录的 `hcs_contract_id` / `hcs_contract_no`；两者都没有时只记警告、合同字段传空，**不阻断推送**。
+3. 附件挂载键为 `fd_attach`，新建时携带 `fdBindType=ADD`，更新时不带。
+4. 税率按 HCS 口径除以 100 转换；发票类型映射来自 `receipt-bill.invoice-type-mapping`，未映射时该字段为空。
+
+收票单没有 HCS 结果回调接口，TMS 不接收 C109 的结果推送。
+
+**接口**：
+
+| 接口 | 作用 | 关键行为 |
+|---|---|---|
+| `POST /hcs/sync/invoice-receipt/{id}` | 单条重推 | 仅 `approved` 可推；先重置 `unsynced`、失败次数清零 |
+| `POST /hcs/sync/invoice-receipt` | 按扫描逻辑推一轮 | 不检查开关、不抢任务锁；**无批量 ID 接口** |
+
+### 4.8 配置项
+
+> 下表键名省略公共前缀 `thirdParty.hcs.`。例如 `push.immediate-enabled` 的完整键为 `thirdParty.hcs.push.immediate-enabled`。
+
+**公共连接与推送配置**
+
+| 配置键 | 默认/样例 | 作用 | 配错的后果 |
+|---|---|---|---|
+| `baseUrl` | 测试网关地址 | HCS 接口基础地址 | 所有推送失败 |
+| `authorization` | 环境值 | HCS Authorization 请求头 | 认证被拒 |
+| `key-auth` | 环境值 | HCS Key-Auth 请求头 | 认证被拒 |
+| `src-system` | `WLTMS` | 来源系统标识 | 合规侧来源不符；回调 `sourceSystem` 校验失败 |
+| `operator-login-name` | `srvadmin`（环境可改） | 操作人登录名 | 合规侧操作人异常 |
+| `creator-unit-id/name` | 环境固定值 | 创建单位 | 合同创建单位错误 |
+| `mock-enabled` | `false`（开发样例 `true`） | Mock 模式开关 | 生产误开会导致推送走本地桩，不真正调用 HCS |
+| `push.immediate-enabled` | `false`（开发样例 `true`） | 审批通过即时推送 | 只影响项目立项和合同；关闭后等扫描或手动 |
+| `push.batch-size` | `50` | 单轮扫描条数上限 | 积压数据需多轮处理 |
+| `push.max-retry` | `5` | 失败自动重试上限 | 超限后仅能人工重推 |
+| `attachment.transfer-enabled` | `true` | 附件转传总开关 | 关闭后合同/开票附件不转传 |
+| `attachment.file-download-base` | 空 | TMS 文件下载基址 | 有附件时转传失败 |
+| `master-data.ttl-minutes` | `120` | 模板/分类/币种缓存时长 | 主数据变更最长延迟 120 分钟生效 |
+
+**五个任务开关与 cron**
+
+| 任务 | 开关（默认） | cron 键 | 默认 cron |
+|---|---|---|---|
+| 项目立项 | `push.project.sync-enabled`（`false`） | `push.project.cron` | `0 */5 * * * ?` |
+| 合同 | `push.contract.sync-enabled`（`false`） | `push.contract.cron` | `0 1/5 * * * ?` |
+| 付款链 | `push.payment.sync-enabled`（`false`） | `push.payment.cron` | `0 2/5 * * * ?` |
+| 开票登记 | `push.invoice-application.sync-enabled`（`false`） | `push.invoice-application.cron` | `0 3/5 * * * ?` |
+| 收票单 | `push.invoice-receipt.sync-enabled`（`false`） | `push.invoice-receipt.cron` | `0 4/5 * * * ?` |
+
+> 五个开关默认全关，按业务灰度打开；cron 不配置时使用代码默认值（每 5 分钟，分钟位 0–4 错峰）。
+
+**各任务业务配置**
+
+| 配置键 | 默认/样例 | 影响任务 | 说明 |
+|---|---|---|---|
+| `project.template-code` | `template_15x0og` | 项目立项 C102-1 | 未配置时推送失败 |
+| `contract.template-mapping` | 样例仅 `[承运商合同]` | 合同 C103-1 | 合同类别未映射必失败；中文键必须写成 `"[承运商合同]"` |
+| `contract.currency-name-mapping` | `RMB→人民币`（另一环境样例 `CNY`） | 合同 C103-1 | 币种传错或为空；上线前与合规方确认取值 |
+| `contract.require-risk-check` | `true` | 合同 C101-1 | 关闭后不做风险校验，高风险合同不会触发特批 |
+| `exe-stage.sync-enabled` | `false` | 合同 C103-9 | 关闭时合同任务不推履约规则 |
+| `exe-stage.fund-type` | `byAmount` | 合同 C103-9 | 金额类型传错会被合规校验拒绝 |
+| `spec-pay.template-id` | 环境值 | 付款 C106-3 | 未配置时付款特批发起失败 |
+| `spec-pay.doc-status` | `10` | 付款 C106-3 | 单据状态不符合合规要求 |
+| `spec-pay.payment-purpose` / `payment-nature` / `payment-type` | 开发样例 `2001` / `1` / `1`，生产样例为空 | 付款 C106-3 | 字典值缺失或错误会导致特批发起失败 |
+| `perf-record.sync-enabled` | `false` | 付款 C108 | 关闭时付款只更新整体状态，不推履约记录 |
+| `perf-record.xform-id` | 空 | 付款 C108 | 开启履约记录但未配置模板ID时字段为空，HCS 必填校验会失败 |
+| `invoice.invoice-type-mapping` | 空映射 | 开票 C111-2 | 未映射时只告警、字段不传，可能被 HCS 必填校验拒绝 |
+| `invoice.currency-id-mapping` | 样例 `RMB` 为空 | 开票 C111-2 | `RMB` 映射为空时所有开票登记推送失败 |
+| `invoice.fund-nature-default` | `progress` | 开票 C111-2 | 款项性质传错会被合规校验拒绝 |
+| `receipt-bill.invoice-type-mapping` | 空映射 | 收票 C109 | 未映射时发票类型字段为空，可能被 HCS 必填校验拒绝 |
+| `risk.check-on-payment` | `true` | 付款提交 | 关闭后高风险/黑名单收款方不会被标记特批 |
+| `credit.check-enabled` | `false` | 付款提交 | 关闭后不调 C106-1，额度超额不会自动转特批 |
+| `credit.require-contract-synced` | `true` | 付款提交 | 额度校验开启时，关联合同未推送合规会直接拦截提交 |
+
+> 不同环境样例中的币种名称映射可能不同（`CNY` 与 `人民币`），上线前必须与合规方确认 HCS 主数据实际取值。
+
+### 4.9 运维注意
+
+- **开关灰度**：五个扫描开关默认全关且互相独立；即时推送只有项目立项和合同，受 `push.immediate-enabled` 控制；手动接口始终可用，不受开关限制。
+- **先看存量再开扫描**：扫描不区分“从未推送”和“推送失败”，开关一开，所有审批通过且未同步的历史单据都会进入扫描范围（每轮最多 50 条）。上线前先确认待推送数据量。
+- **修复根因优先**：失败单据每 5 分钟自动重试，达到 `push.max-retry`（默认 5）后停止；人工重推会清零次数，但不修复配置/数据会反复失败。
+- **付款依赖合同**：C106-3 要求关联合同已有合规合同ID，C103-9 也以合同 `hcs_fd_id` 为前提；合同未推送合规时付款特批/履约规则相关步骤会失败或跳过。
+- **开票必配币种映射**：`invoice.currency-id-mapping` 的 `RMB` 必须配置为 HCS 币种 fdId，否则开票登记每轮都会失败。
+- **收票合同关联**：回溯不到合同且未人工补录 `hcs_contract_id` / `hcs_contract_no` 时不会失败，但合同字段为空；需要完整合同信息时先补录再重推。
+- **模板映射逐个类别确认**：样例只配了承运商合同；客户合同、补充协议未配置时推送必失败。Nacos YAML 中文键必须写成 `"[承运商合同]"`。
+- **附件下载基址必配**：合同有附件时，`attachment.file-download-base` 为空会导致附件转传失败。
+- **生产禁用 Mock**：`thirdParty.hcs.mock-enabled` 生产环境必须为 `false`。
+- **主数据刷新**：模板映射调整后，可调用 `POST /hcs/master-data/refresh` 刷新模板/分类/币种缓存并校验映射。
+- **多实例与手动接口**：定时任务按 bizType 抢 Redis 锁（TTL 240 秒），抢不到本轮跳过；手动接口不抢锁，避免与定时任务同一时刻执行。
+- **日志排查**：服务日志按单据编号、合规ID、`hcs` 关键字检索；本地日志目录为 `F:\home\tms\blade-transport`。
+
+---
+
+## 5. 常见问题与异常处理（FAQ）
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 审批通过后合规状态一直“待推送” | 未开启即时推送，合同扫描也未开启或未到执行时间 | 手动点“推送合规”；或让运维开启对应开关 |
+| 审批通过时提示“审批通过，但合规推送失败：xxx” | 审批已生效，HCS 推送失败 | 按失败原因修复后手动重推，不要重复审批 |
+| 列表没有“推送合规”按钮 | 合同不是审批通过/变更审批通过，或合规状态已是“已推送” | 先完成审批；已推送合同如需修改走“变更” |
+| 批量推送提示“选中数据中有 N 条不符合推送条件” | 勾选了未审批通过或已同步的合同 | 取消勾选不符合条件的合同，或单独推送 |
+| 推送失败原因在哪里看 | 列表悬停合规状态，或详情“合规信息” | 看 `hcs_sync_msg`/失败说明，按原因处理 |
+| 失败超过 5 次后不再自动重试 | 达到 `push.max-retry` 上限 | 修复根因后手动“推送合规”，会清零重试次数 |
+| 提示“合同类别 [xxx] 未配置合规模板ID” | Nacos 模板映射缺该类合同 | 运维补齐 `contract.template-mapping` 后重推 |
+| 提示附件转传失败 | 下载基址为空、附件不可下载、文件超限或 HCS 附件接口异常 | 检查 `attachment.file-download-base` 和附件，修正后重推 |
+| 提示 C101-1 客商风险查询失败 | HCS 风险接口异常/无响应 | 联系 HCS 侧确认接口，恢复后重推 |
+| 高风险客商没有触发特批 | 客商名称与档案不匹配导致风险校验被跳过，或 HCS 返回的风险等级不是高风险/黑名单 | 核对甲乙方名称与客商档案；在 HCS 侧确认客商风险等级和黑名单状态 |
+| 提示 C103-1/C103-11 合同发起/更新失败 | HCS 业务校验不通过 | 按返回 msg 修正模板、字段或主数据后重推 |
+| 特批状态一直是“待特批” | 存量数据或推送未成功，未进入特批流程 | 联系管理员重新推送；推送成功后会自动转“特批中” |
+| 特批中想重推 | 特批流程未结束 | 不允许重推，等待 HCS 回传或人工确认结果 |
+| 如何人工确认特批结果 | HCS 结果未自动回传 | 详情 → 合规信息 → 确认特批结果，输入 `approved`/`rejected`；仅“特批中”可用 |
+| 特批驳回后合同变成“已驳回” | 特批结果联动合同审批 | 修改合同、重新提交审批、重新推送 |
+| 点击“发起特批”提示接口不存在 | 旧版独立入口，后端接口已取消，特批随推送自动发起 | 忽略即可；正常流程不需要点击 |
+| 已推送合同不能编辑 | 防止 HCS 产生重复合同 | 走“变更”流程，变更审批通过后更新 HCS |
+| 金蝶合同ID为空 | HCS/金蝶同步有延迟 | 稍后刷新；长时间为空联系管理员 |
+| 上传双章归档文件后归档状态没变 | 附件位置或类型不对，或合同未审批通过 | 附件位置选用印材料、类型选双章归档文件，审批通过后刷新 |
+| “流程”提示流程实例为空 | 合同未关联外部审批流程实例 | 以列表/详情的审核状态和当前节点为准；需要流转记录联系管理员 |
+| 变更页面“终止合同”不能提交 | 当前版本未开放终止入口 | 选择“合同信息变更”；确需终止联系管理员 |
+| 临时合同审批通过后也变成待推送/已推送 | 当前实现按审批状态扫描，未按合同阶段过滤 | 属当前版本行为，按合规状态正常处理即可 |
+
+---
+
+## 6. 附：操作入口速查表
+
+| 页面 | 按钮/操作 | 作用 |
+|---|---|---|
+| 合同管理列表 | 工具栏“新增” | 新增合同 |
+| 合同管理列表 | 行内“编辑” | 编辑草稿/已撤回/已驳回/变更驳回合同 |
+| 合同管理列表 | 行内“复制” | 以当前合同为模板新建草稿 |
+| 合同管理列表 | 行内“删除” | 删除草稿合同 |
+| 合同管理列表 | 行内“转正式合同” | 临时合同审批通过后转正式 |
+| 合同管理列表 | 行内“重新提交转正” | 临时合同被驳回后重新提交 |
+| 合同管理列表 | 行内“变更”/“重新提交变更” | 正式合同发起变更/变更驳回后重提 |
+| 合同管理列表 | 行内“附件上传” | 正式合同审批通过后补传附件 |
+| 合同管理列表 | 行内“推送合规” | 单条推送/重推 HCS |
+| 合同管理列表 | 工具栏“批量推送合规” | 勾选多条合同批量推送 |
+| 合同管理列表 | 审批中行内“通过/驳回/撤回” | 审批合同；通过时尝试推送 HCS |
+| 合同详情 | 合规信息“确认特批结果” | 特批中人工确认 `approved`/`rejected` |
+| 运维专用 | `POST /hcs/sync/contract/{id}` | 单条重推合同 |
+| 运维专用 | `POST /hcs/sync/contract` | 按扫描逻辑推送一轮待同步/失败合同 |
+| 运维专用 | `POST /hcs/sync/contract/batch` | 按勾选ID批量重推（请求体为ID数组） |
+| 运维专用 | `POST /hcs/contract/spec/confirm` | 人工确认合同特批结果（参数 `id`、`result`） |
+| 运维专用 | `POST /hcs/master-data/refresh` | 刷新 HCS 模板/分类/币种缓存并校验模板映射 |
+
+> 五类单据通用手动入口：`POST /hcs/sync/{bizType}/{id}`（单条重推）、`POST /hcs/sync/{bizType}`（扫一轮）；`bizType` 取 `project`、`contract`、`payment`、`invoice-application`、`invoice-receipt`，批量 `/batch` 仅支持 `project`、`contract`。各任务链路与接口详见 4.3–4.7。
+
+---
+
+> 本文基于 2026-10-23 代码与页面现状整理；按钮、提示和环境开关以实际页面为准。临时合同推送、旧版“发起特批”入口、变更页“终止合同”未开放属于当前版本现状，后续版本调整时请同步核对。