diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md index 462c0452..63ff19da 100644 --- a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md +++ b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md @@ -1,9 +1,10 @@ -# 金蝶（星瀚）BFI 对接操作手册（纯操作版） +# 金蝶（星瀚）BFI 与合同合规系统（HCS）对接操作手册（纯操作版） -> 整理日期：2026-10-14（2026-11-03 汇总修订） -> 适用对象：TMS 业务操作人员（财务/业务）、系统管理员、实施运维。 +> 整理日期：2026-10-14（2026-11-04 金蝶+合同系统合并修订） +> 适用对象：TMS 业务操作人员（财务/业务/合同经办）、系统管理员、实施运维。 > 本文只讲**怎么操作**：在哪个页面、点什么按钮、前提是什么、成功的标志是什么、失败了怎么处理。 -> 接口与代码细节见同目录《2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）》； +> 覆盖两个外部系统的全部日常操作：**金蝶（星瀚）BFI**（客商、结算、付款、开票、收票、收款、结算调整）与**合同合规系统（HCS）**（项目立项、合同、特批、客商风险、履约计划/记录，见 4.2–4.18）。 +> 接口与代码细节见同目录《2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）》与 hcs合同 目录各梳理文档； > 预付与结算调整的深度说明见《2026-10-18-预付转正式结算单与项目预付操作手册（纯操作·带状态）》《2026-10-17-结算调整单操作流程说明（分场景）》（本文已汇总其操作要点）。 ## 修改记录 @@ -11,9 +12,10 @@ | 日期 | 修订内容 | |---|---| | 2026-10-14 | 初版 | -| 2026-10-19 | 核对并补充 4.2 定时任务运转逻辑（cron 默认值、错峰、终态不轮询、防呆与自愈行为） | +| 2026-10-19 | 核对并补充 5.2 定时任务运转逻辑（cron 默认值、错峰、终态不轮询、防呆与自愈行为） | | 2026-10-31 | ① 收票登记改「先票后款」：收票登记只选票推金蝶收票单（不再关联结算单，新增手选结算组织/发票明细），「认领收票单+指定应付」移到付款结算单；② 收款流水与认领改口径：数据源改金蝶收款单（A301-1）、「推送金蝶」「查询金蝶认领结果」按钮下线、认领只登记本地、作废同步合同合规；③ 客商建档新增供应商编码自动获取与收款信息开户行带出联行号操作；④ 准备事项、定时任务清单、FAQ、速查表同步更新 | -| 2026-11-03 | **四文档汇总修订（合并《2026-10-17 结算调整单》《2026-10-18 预付与项目预付》两本手册 + 按 11-01/11-02 代码与界面更新）**：① 全篇菜单更名对齐系统实际（预付结算单/付款结算单/收款结算单，新增 1.4 页面名称对照）；② 1.1 状态表补页面显示别名与「已指定应付」列；③ 新增 3.3 进度预付、3.4 项目预付（含客商风险与付款特批）、3.5 项目预付核销、3.6 尾款结算、3.10 结算调整单、3.14 作废与撤销；④ 开票申请按「剩余可开票金额」累计控制（放开必须未开票限制）、分摊发票金额系统自动分摊；⑤ **收票后款认领按 11-02 改造更新**：发票登记移到付款结算单工具栏、弹窗回显已认领收票单、「匹配结算单金额」支持手动修改、查看页新增「是否已指定应付」列与「重新推送」入口、列表指定失败悬浮展示原因；⑥ **A302-6 指定应付定时自动补偿改开关控制（默认关闭）改人工兜底**；⑦ 4/5/6 节同步更新，截图全面更新（付款结算单列表与发票登记弹窗、选择收票单、查看页发票信息、指定失败悬浮、付款管理已指定应付列、收票登记表单去税率） | +| 2026-11-03 | **四文档汇总修订（合并《2026-10-17 结算调整单》《2026-10-18 预付与项目预付》两本手册 + 按 11-01/11-02 代码与界面更新）**：① 全篇菜单更名对齐系统实际（预付结算单/付款结算单/收款结算单，新增 1.4 页面名称对照）；② 1.1 状态表补页面显示别名与「已指定应付」列；③ 新增 4.5 进度预付、4.6 项目预付（含客商风险与付款特批）、4.7 项目预付核销、4.8 尾款结算、4.12 结算调整单、4.16 作废与撤销；④ 开票申请按「剩余可开票金额」累计控制（放开必须未开票限制）、分摊发票金额系统自动分摊；⑤ **收票后款认领按 11-02 改造更新**：发票登记移到付款结算单工具栏、弹窗回显已认领收票单、「匹配结算单金额」支持手动修改、查看页新增「是否已指定应付」列与「重新推送」入口、列表指定失败悬浮展示原因；⑥ **A302-6 指定应付定时自动补偿改开关控制（默认关闭）改人工兜底**；⑦ 4/5/6 节同步更新，截图全面更新（付款结算单列表与发票登记弹窗、选择收票单、查看页发票信息、指定失败悬浮、付款管理已指定应付列、收票登记表单去税率） | +| 2026-11-04 | **合并合同系统（HCS）操作内容，形成金蝶+合同系统组合手册（并入《HCS合同管理操作手册（纯操作版）》《履约计划与履约记录四场景业务说明》《客商黑名单与风险等级业务说明》）**：① **新增第 2 节「全链路总览」**（**12 条环节流程链**【系统】→步骤→▼ 格式逐环节梳理、两条通用规则与三条先后依赖；场景分流/拦截提示原文/成功提示在 4.x 对应小节体现），原第 2–6 节顺延为第 3–7 节，日常操作小节相应重排为 4.1–4.18；② 新增 1.5–1.8（HCS 是什么与合规状态、特批状态、三条推送路径、客商风险与黑名单口径），1.4 页面对照补客商/项目/合同顺序；③ 第 3 节新增合同系统准备清单；④ **项目立项推合规、合同管理与推送合规（含合同特批/变更/归档）置于 4.2/4.3（客商章节后）**；付款特批操作细节不单独成节（`spec-pay.enabled` 开关口径保留在 4.6）；⑤ 新增 4.17 客商风险查看与筛选、4.18 履约计划与履约记录四场景；⑥ 4.6/4.10/4.14 补合同系统联动与金蝶实付门禁口径；⑦ 第 5 节新增 5.5 HCS 定时任务与开关及**六任务逐项运转逻辑**（判重/更新分流、特批兜底查询、金蝶实付门禁、开票自愈、收票合同回溯、风险分批刷新）；⑧ 第 6/7 节补 HCS 常见问题与操作入口；⑨ 合同支持甲乙丙多方客商（2026-11-02）已写入 4.3；⑩ 新增截图 41/42/43（付款结果回写列表效果，FKD2026110300003↔FKSQ-000000282 对照），引用 HCS 手册现有截图 | --- @@ -26,6 +28,8 @@ ​ 13737128880 websoft5386339 +合同合规系统（HCS）测试环境地址：https://contract-sit.gxwuzi.com/ 账号：13737128880 密码：Mk13737128880@ + ### 1.1 金蝶单据状态含义（列表里看到的字段） 各列表的「金蝶单据状态」列是同一个字段，但不同页面的**显示文案**不同（下表「页面显示」列），看到哪个词都对得上： @@ -53,21 +57,27 @@ | 金蝶锁定中（红标） | 金蝶已锁单 | 不可编辑、不可作废 | | 锁定失败·补偿中 | 加锁没成功 | 系统每 5 分钟自动补偿重锁（≤5 次） | | 锁定失败·已达上限 | 自动补偿 5 次都没成功 | 不再自动重试；重新点一次「同步金蝶」即可重置计数补锁，必要时联系管理员 | -| 金蝶删单 / 金蝶解锁（留痕） | 金蝶侧把单删了或解锁过 | 付款申请→金蝶状态变"生成失败"待重推；结算单/开票申请→系统自动作废（见 3.14） | +| 金蝶删单 / 金蝶解锁（留痕） | 金蝶侧把单删了或解锁过 | 付款申请→金蝶状态变"生成失败"待重推；结算单/开票申请→系统自动作废（见 4.16） | ### 1.3 两条推送路径 -- **自动**：审批「通过」时系统自动推送金蝶（需管理员开启对应开关，见第 4 节）；开启后审批接口会直接返回推送结果，失败时页面提示「审批通过，但自动同步金蝶失败：xxx」。 -- **手动**：列表勾选单据点工具栏「同步金蝶 / 批量同步」按钮。开关没开时用这条路径。（收款流水认领没有推送动作——认领只登记本地并自动推合同合规，见 3.12。） +- **自动**：审批「通过」时系统自动推送金蝶（需管理员开启对应开关，见第 5 节）；开启后审批接口会直接返回推送结果，失败时页面提示「审批通过，但自动同步金蝶失败：xxx」。 +- **手动**：列表勾选单据点工具栏「同步金蝶 / 批量同步」按钮。开关没开时用这条路径。（收款流水认领没有推送动作——认领只登记本地并自动推合同合规，见 4.14。） 两条路径效果完全一样，重复点不会重复推送（系统自动查重）。 +合同系统（HCS）另有自己的三条推送路径（即时/定时/手动），见 1.7；两条系统各自独立推送、互不替代。 + ### 1.4 页面名称对照（先看这个） 系统菜单已按"应付 / 应收"拆分，本文全部使用系统里的实际名称（旧的「正式结算单/预结算单」叫法已不再使用）： | 本文场景 | 系统菜单位置 | 页面名称 | |---|---|---| +| 客商档案 | 客商管理 | 客商档案 | +| 项目立项 | 项目管理 | **项目管理** | +| 合同新增/审批/推送合规 | 合同管理 | **合同管理** | +| 合同变更单 | 合同管理 | **合同变更** | | 预付结算单（原预结算单） | 结算管理 | **预付结算单** | | 应付正式结算单 | 结算管理 | **付款结算单** | | 应收正式结算单 | 结算管理 | **收款结算单** | @@ -76,7 +86,6 @@ | 开票申请列表 | 收付款管理 | **开票管理** | | 收票登记 | 收付款管理 | 收票管理 | | 收款流水/认领记录 | 收付款管理 | 收款流水、认领记录 | -| 客商档案 | 客商管理 | 客商档案 | 付款申请的**付款类型**有三种，列表和表单里都按这个名称显示： @@ -86,9 +95,271 @@ | 项目预付 | 项目预付 | 不挂结算单，按项目+承运商合同预付 | | 尾款付款 | 尾款付款 | 挂付款结算单付尾款 | +### 1.5 合同系统（HCS）与「合规状态」 + +TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）。HCS 完成客商风险校验、合同合规校验、特批和金蝶同步，并把合规合同ID、金蝶合同ID、特批结果回写到 TMS。项目立项、开票登记、收票单、付款履约数据按同一套框架推送（见 4.2–4.18）。 + +各单据列表的「**合规状态**」列是同一个字段，不同页面显示文案一致： + +| 状态值 | 页面显示 | 含义 | 还会变吗 | +|---|---|---|---| +| unsynced | 待推送 | 审批已通过，尚未成功推送 HCS | 会（推送成功变已推送） | +| synced | 已推送 | HCS 已受理，已回填合规ID | 会（特批状态、金蝶ID可能继续变化） | +| failed | 推送失败 | 推送失败，鼠标悬停合规状态可查看原因 | 会（自动重试或手动重推成功后变已推送） | + +> 「已推送」只代表 HCS 已受理，不代表特批和金蝶同步已完成；金蝶合同ID/金蝶项目ID由 HCS 完成金蝶同步后回写，可能延迟。 + +### 1.6 特批状态（合同与付款共用） + +| 状态值 | 页面显示 | 含义 | 后续 | +|---|---|---|---| +| need | 待特批 | 尚未进入特批流程，多见于存量数据或推送未完成 | 重新推送成功后转特批中 | +| processing | 特批中 | HCS 正在审批特批；合同列表当前节点显示「特批审核」 | 等待 HCS 回传、定时查询或人工确认 | +| approved | 特批通过 | 特批完成 | 合同恢复「审批通过」，继续后续流程 | +| rejected | 特批驳回 | 特批未通过 | 合同/付款审批联动「已驳回」，修改后重新提交 | + +合同特批看合同详情「合规信息」区的特批状态；**付款申请页面没有独立特批状态列**，看列表「当前节点」：显示「特批审核」即为特批中，通过后恢复「审批通过」，驳回则审核状态变「已驳回」。 + +![付款管理列表「当前节点」列：特批中的付款申请当前节点显示「特批审核」（审核状态仍为审批通过，不能只看审核状态判断流程是否结束；特批通过恢复「审批通过」后金蝶单据才会生成）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/42-付款管理-特批审核当前节点.png) + +### 1.7 合同系统三条推送路径 + +| 路径 | 触发时机 | 开关 | 说明 | +|---|---|---|---| +| 自动即时推送 | 审批人点「通过」后 | `thirdParty.hcs.push.immediate-enabled` | 项目立项、合同受此开关控制；审批响应等待推送结果，失败提示「审批通过，但合规推送失败：xxx」 | +| 定时扫描推送 | 每 5 分钟（五个业务错峰） | `thirdParty.hcs.push.{bizType}.sync-enabled` | 扫「待推送/推送失败未超限」的单据；只有合同任务额外兜底查询特批结果 | +| 手动推送 | 随时 | 无 | 列表行内「推送合规」或工具栏「批量推送合规」（开票登记、收票单页面无推送按钮，靠定时或运维接口） | + +- **付款申请**：审批通过后即时发起付款特批/推送合规的动作受 `thirdParty.hcs.spec-pay.enabled` 控制（★2026-11-03 起默认关闭，见 4.6）；定时扫描只做失败补偿。 +- 三条路径共用同一套推送逻辑；HCS 侧有判重，重复触发不会重复生成。 +- 推送失败默认自动重试 **5 次**，超过后只能人工重推（人工重推会把失败次数清零）。 + +### 1.8 客商风险与黑名单口径 + +客商风险数据来自两个外部系统，每日 02:30 自动刷新到客商档案（范围：合同期限内生效合同的甲乙方客商）： + +| 数据 | 来源 | 说明 | +|---|---|---| +| 风险等级 | 合同合规系统（C101-1） | 低风险 / 中风险 / 高风险 | +| 金蝶黑名单 | 金蝶（星瀚）· 国资委黑名单（A801-5） | 命中记录失信类别（**A 类禁止交易类** / B 类风险警示类）与列入事由 | + +- **黑名单仅指金蝶黑名单命中**；合同合规系统返回的黑名单状态字段只用于付款提交强制校验，不在列表展示。 +- 客商档案、合同列表的「客商风险」列为等级+黑名单组合展示（等级在前，如「高风险、黑名单」），红色标签悬浮查看明细（失信类别、列入事由、风险等级）；查看与筛选操作见 4.17。 +- 内部组织客商不查询风险，默认「无风险」；数据每天 02:30 刷新，当天新增客商以客商表单实时提示为准，列表次日生效。 +- 风险管控作用点：①客商准入提审黑名单硬校验（4.1 第 3 步）；②合同推送自动特批（4.3 第四步）；③付款提交特批附件必传（4.6）。 + --- -## 2. 一次性准备（实施/管理员操作） +## 2. 全链路总览（各环节流程） + +> 本章讲清各环节的先后顺序、每一步推给哪个系统、成功标志是什么；逐环节的操作细节见「日常操作流程」章节对应小节（节号在各链标题中）。 + +### 2.1 各环节流程链（【系统】→ 步骤 → ▼，按业务顺序编号） + +**① 客商建档与同步（4.1）** +```text +【TMS】客商档案新增（blade_customer_archive） + │ ① 录统一社会信用代码满 18 位 → 实时查金蝶（A901-1）回填工商信息 + │ ② 收款信息「开户行」失焦 → 按行名从金蝶带出联行号；保存前按行号反查校验 + │ ③ 提交审批 → 按纳税人识别号查金蝶黑名单（A801-5）：A 类禁止提交 + ▼ +审批通过 → 自动推金蝶（A902） + │ ④ 成功 kingdee_status=synced；失败 failed（行内「同步金蝶」重推） + │ ⑤ 定时任务（每天 02:00）复查金蝶审核状态：通过 → exist（终态） + ▼ +金蝶已审核客商（exist） +``` + + +**② 项目立项推合规（4.2）** +```text +【TMS】项目立项（blade_project_apply） + │ ① 审批通过 / 变更审批通过 → 待推送 + ▼ +推送合规（审批即时开关 / 定时扫描 / 行内「推送合规」） + │ ② C102-3 按项目编号判重：命中 → 回填已有合规ID（不重复建） + │ ③ 未命中 → C102-1 新建（付款/开票额度万元×10000 转元） + │ ④ 已有合规ID（变更）→ C102-2 更新 + ▼ +【TMS】合规状态=已推送 + 合规项目ID 落库（hcs_fd_id） + │ ⑤ 合规完成金蝶同步后回调 projectLegal/result → 回填金蝶项目ID/编号（不改合规状态） + ▼ +列表「金蝶项目ID / 金蝶项目编号」回显（推送成功≠金蝶项目已建） +``` + + +**③ 合同推合规与合同特批（4.3）** +```text +【TMS】合同（blade_contract_manage） + │ ① 审批通过 / 变更审批通过 → 推合规（即时开关 / 定时扫描 / 行内「推送合规」） + ▼ +推送链（单条依次执行） + │ ② 附件转传 C103-2（失败整条推送失败） + │ ③ 客商风险 C101-1 + 金蝶黑名单 A801-5（甲乙逐个查，命中只标记不阻断） + │ ④ C103-3 按合同编号判重 → C103-1 起草 / C103-11 更新（高风险随报文发起特批） + │ ⑤ 履约规则 C103-9 行级同步（开关开启时；失败整条 failed，下轮凭合规ID走更新补偿） + ▼ +【TMS】合规状态=已推送 + 合规合同ID 落库 + │ ⑥ 风险命中 → 特批状态=特批中、当前节点「特批审核」（特批中禁止重推） + ▼ +特批结果：contractLegal/result 回调 或 定时 C103-4 查询兜底 + │ ⑦ 通过 → 恢复「审批通过」（金蝶合同ID可能同时回填） + │ ⑧ 驳回 → 合同联动「已驳回」，修改后重新提交审批、重新推送 +``` + + +**④ 预付结算单 → 进度预付（4.4/4.5）** +```text +【TMS】预付结算单（blade_pre_settlement，本身不推金蝶） + │ ① 制单/审批通过（外币在此选汇率日期带出结算汇率） + ▼ +三个出口：预付申请（进度预付） / 项目预付核销 / 尾款结算 + │ ② 工具栏「预付申请」（限应付+审批通过+未转结算+同一合同，可多选） + ▼ +【TMS】付款申请新增页（blade_payment_application，类型锁定「进度预付」） + │ ③ 结算金额/可付款金额自动带出 → 填申请付款金额/付款方式/收款方 → 保存 + │ ④ 提交 → 审批通过 → 推金蝶（见⑧） + ▼ +金蝶付讫（已付款）→ 自动回写预付结算单垫资记录与「已付款金额」 +``` + + +**⑤ 项目预付与核销（4.6/4.7）** +```text +【TMS】付款申请新增，付款类型=项目预付（不挂结算单） + │ ① 先选项目再选承运商合同 → 提交校验项目额度/客户额度 → 审批通过 + ▼ +推金蝶（预付款通道，金蝶生成「其他付款申请」） + │ ② 金蝶付款完成 → 金蝶状态「已付款」（未付款不能核销） + ▼ +【TMS】结算单编辑页「项目预付核销」分区（blade_settlement_project_advance_write_off） + │ ③ 「选择」弹窗只列：同合同 + 审批通过 + 金蝶已付款 + 有剩余可核销额 + │ ④ 核销金额计入「已付金额（含预付、核销）」，可核销额度即时占用 +``` + + +**⑥ 尾款结算（4.8）** +```text +【TMS】预付结算单列表勾选（同项目、应付、审批通过、无在途预付申请） + │ ① 工具栏「尾款结算」→ 跳新增付款结算单，明细/费用项合并带入 + │ ② 结算合计三口径：结算合计（全额）/ 已付金额（含预付、核销）/ 剩余未付 + │ ③ 来源预付结算单被锁定（不能再发起预付、不能作废） + ▼ +保存草稿 → 提交 → 审批通过 → 推金蝶（见⑦） +``` + + +**⑦ 结算单推送金蝶（4.9）** +```text +【TMS】付款结算单 / 收款结算单（blade_formal_settlement） + │ ① 审批通过；外币先重选汇率日期带出结算汇率（预付结算单汇率不自动继承） + ▼ +推送（审批自动开关 / 工具栏「同步金蝶」） + │ ② 应付 A102-2 / 应收 A302-2 按结算类型自动分流 + │ ③ 成功：金蝶单据号回填 + 状态已同步 + 金蝶锁定（不可改/不可作废） + │ ④ 应付单生成后，系统自动对本单认领的收票单执行「指定应付」（见⑩） + ▼ +失败：悬浮状态标签看原因；failed 重推任务每 10 分钟自动续推 +``` + + +**⑧ 付款申请推送与实付回写（4.10）** +```text +【TMS】付款申请（blade_payment_application，审批通过） + │ ① 门禁：付款特批审核中拦截推送金蝶（仅特批走合规开关开启时） + │ ② 推金蝶 A103（预付走预付款通道）：已生成 + 金蝶单号 + 落锁 + │ ③ 履约计划金额本地累加（blade_contract_exe_stage，按款项性质精确匹配） + ▼ +金蝶付款结果回写（定时 10 分钟 / 工具栏「同步付款结果」） + │ ④ 已生成 → 付款中 → 已付款（回写付款记录/凭证）/ 已关闭 + ▼ +实付回写（paidAmount>0）→ 自动重新置待同步 + │ ⑤ C103-9 重推履约计划 → C108-1 新建 / C108-2 更新付款履约记录（一张申请一条） + │ 未实付时整体照常已推送，结果说明「金蝶未实际付款…」（正常等待，非失败） +``` + + +**⑨ 开票申请（4.11）** +```text +【TMS】开票申请（blade_invoice_application） + │ ① 选应收结算单（审批通过+剩余可开票金额>0）→ 分摊发票金额系统自动分摊 → 审批通过 + ▼ +推金蝶（按发票张次逐张） + │ ② A303-1：一张申请 N 张发票 → N 张金蝶开票申请单，逐张锁定 + ▼ +开票结果回写（定时 10 分钟） + │ ③ 发票逐张落库 → 状态「开票完成」（终态） + │ ④ 合规 C111 开票登记（金蝶已开票自动重置待同步 → C111-3 更新票据日期/状态） + │ ⑤ 每张发票一条开票履约记录（C108-1，合规检索「开票履约-发票号」） +``` + + +**⑩ 收票登记 → 认领 → 指定应付（4.12，先票后款两段式）** +```text +【TMS】收票登记（blade_invoice_receipt） + │ ① 票池选票（带出发票明细）+ 手选结算组织 → 保存前重查金蝶票池可用性 + │ ② 审批通过 → 推金蝶收票单 A303-2（按登记ID幂等防重）→ 终态 pushed + │ ③ 合规 C109 推收票单 → 成功后按认领分摊行推履约收票记录（C108-1） + ▼ +【TMS】付款结算单认领收票单（blade_invoice_receipt_settlement） + │ ④ 三入口等效：编辑页「选择收票单」/ 工具栏「发票登记」/ 查看页「重新推送」 + │ ⑤ 一张收票单只能被一张付款结算单认领；匹配金额默认=发票金额可改小 + ▼ +应付单推送金蝶后 → 系统自动指定应付（A302-6） + │ ⑥ 收票状态 pushed → assigned（终态）；指定失败不影响结算单，人工入口重推兜底 +``` + + +**⑪ 收款流水与认领（4.14）** +```text +【金蝶】A301-1 收款单 + │ ① 手动同步（可按窗口重复执行，幂等） + ▼ +【TMS】收款流水列表（blade_kingdee_receipt_flow） + │ ② 勾选/单条 → 选择应收正式结算单 → 填分摊金额 + ▼ +【TMS】认领（blade_receipt_claim + blade_receipt_claim_settlement） + │ ③ 更新流水累计认领金额/状态、刷新结算单收款汇总 + │ ④ 事务提交后推合规：C103-9 → C107-1 → C108-1（失败只落标记，不自动重试） + ▼ +合规侧认领记录（C107-1 返回 fdId 落库 blade_receipt_claim_hcs_record） + │ ⑤ 需要撤销时在「认领记录」页作废 + ▼ +本地回退金额 + 推 C107-3（fdStatus=1 已作废；计划金额与履约流水不回冲） +``` + + +**⑫ 结算调整单（4.13）** +```text +【TMS】结算调整单（blade_settlement_adjustment，只能手工新增，无作废） + │ ① 选可调整结算单（审批通过+未完成收付款+无在途付款申请）→ 带出费用明细 + │ ② 录调整金额（可为负/新增手工费用）→ 选单时做金蝶冲销预检（软提示不拦截） + ▼ +审批「通过」（确认后按原单是否推过金蝶自动分流） + │ ③ 场景A 原单未推金蝶：调整直接回写原单 → 自动推送金蝶（应付/应收+落锁+附件） + │ ④ 场景B 原单已推金蝶：原单零改动只追加变更记录 → 提示财务先在金蝶手工冲销旧单 + ▼ +场景B 续：金蝶侧冲销完成后 → 业务点「重新推送（高危）」 + │ ⑤ 硬闸门查金蝶旧单必须已冲销 → 克隆新结算单（直接审批通过态）→ 推金蝶 + │ ⑥ 项目预付核销行随迁新单；原单标记「已调整」仅存档；失败复用新单续推（幂等） +``` + + +### 2.2 两条通用规则与三条先后依赖（先记这些，大部分问题都是顺序或状态没走到） + +**通用规则**： +- 同一套推送逻辑两条触发路径：审批通过自动推（开关开启时）与页面手动按钮效果完全一致，重复触发自动查重，不会重复生成金蝶/合规单据。 +- 推送成功即落锁：结算单/付款/开票推送成功后自动锁金蝶侧单据——不可编辑、不可作废（见 1.2）。 + +**三条先后依赖**： + +1. **结算单必须先推金蝶**，付款申请、开票申请才能推——付款从金蝶应付单下推、开票前系统检查金蝶应收单。 +2. **合同必须先推合规**，付款特批与履约数据才有前提（C106-3 要求关联合同有合规ID；履约计划/记录以合同为根）。 +3. **履约记录晚于业务发生**：付款=金蝶实付后、收款=认领提交后、开票=金蝶开票完成后、收票=收票单推合规后——审批通过就去合规找记录是找不到的（付款场景连计划金额都还没同步），口径对照见 4.18。 + +--- + +## 3. 一次性准备（实施/管理员操作） | # | 事项 | 操作人 | 操作内容 | 不做的后果 | |---|---|---|---|---| @@ -98,14 +369,30 @@ | 4 | 平台公司金蝶组织编码 | 管理员 | 组织管理维护「是否平台公司=是」并填**金蝶编码** | 收款流水同步直接报错拦截；收票按手选部门上溯平台公司取组织编码失败也会推送拦截 | | 5 | 票池票种白名单 | 运维 | Nacos 配 `thirdParty.bfi.invoiceReceipt.invoiceTypes`（要同步的发票种类编码，逗号分隔） | 票池同步不到对应票种 | | 6 | 物料映射 | 运维 | Nacos 配 `thirdparty.bfi.material.*`（有默认值，建议显式确认） | 推送报「运输方式未配置」类拦截 | -| 7 | 定时任务开关 | 运维 | 按第 4 节清单逐项开启 | 只能全靠手动按钮 | -| 8 | 审批自动同步开关 | 运维 | 按第 4 节 `autoSync.*` 按域开启 | 审批通过后不自动推送，走手动 | +| 7 | 定时任务开关 | 运维 | 按第 5 节清单逐项开启 | 只能全靠手动按钮 | +| 8 | 审批自动同步开关 | 运维 | 按第 5 节 `autoSync.*` 按域开启 | 审批通过后不自动推送，走手动 | + +**合同系统（HCS）准备**（Nacos 前缀 `thirdParty.hcs.*`，与上表金蝶准备相互独立）： + +| # | 事项 | 操作人 | 操作内容 | 不做的后果 | +|---|---|---|---|---| +| 1 | HCS 连接配置 | 运维 | `baseUrl`、`authorization`、`key-auth` | 所有推送失败或认证被拒 | +| 2 | 合同类别模板映射 | 运维 | `contract.template-mapping` 为**每个合同类别**配置 HCS 模板ID（YAML 中文键必须写 `"[承运商合同]"` 括号写法） | 未映射的类别推送必失败 | +| 3 | 项目立项模板编码 | 运维 | `project.template-code` | 项目立项推送必失败 | +| 4 | 付款特批模板与开关 | 运维 | `spec-pay.template-id`、`payment-purpose/nature/type` 字典；★`spec-pay.enabled` 特批走合规开关，**默认 false**（见 4.6） | 开启但未配模板时特批发起失败；默认关闭时付款不走合规特批 | +| 5 | 履约计划/记录开关 | 运维 | `exe-stage.sync-enabled`（履约计划）、`perf-record.sync-enabled`（履约记录，默认 false，开启需配 `perf-record.xform-id`） | 不推送履约数据（不影响合同主流程） | +| 6 | 附件下载基址 | 运维 | `attachment.file-download-base`；`transfer-enabled=true` | 合同有附件时转传失败 | +| 7 | 币种映射 | 运维 | 合同 `contract.currency-name-mapping`；开票 `invoice.currency-id-mapping`（**RMB 必配**） | 币种传错或为空；RMB 未配时开票登记每轮失败 | +| 8 | 风险/额度校验开关 | 运维 | `contract.require-risk-check=true`、`risk.check-on-payment=true`、`credit.check-enabled`（超额自动转特批） | 关闭后高风险合同/付款不触发特批 | +| 9 | 推送开关 | 运维 | `push.immediate-enabled`（项目/合同即时）、`push.{project|contract|payment|invoice-application|invoice-receipt}.sync-enabled`（定时扫描，默认全关，见 5.5） | 只能靠手动按钮推送 | +| 10 | 客商风险每日刷新 | 运维 | `risk.refresh-enabled` 上线置 `true`（默认 false，每天 02:30） | 客商档案/合同列表「客商风险」列无数据 | +| 11 | 客商名称一致性 | 业务 | 合同甲乙方名称与客商档案全称或简称一致 | 风险校验取不到客商被跳过，可能漏特批 | --- -## 3. 日常操作流程 +## 4. 日常操作流程 -### 3.1 客商建档与同步 +### 4.1 客商建档与同步 **页面：客商管理 → 客商档案** @@ -117,9 +404,10 @@ 2. 维护**收款账户**和发票信息（纳税人识别号用于黑名单校验）。 - 收款信息「开户行」输入后失焦，系统自动按行名从金蝶**带出联行号**；带不出时可手动填写，保存时系统会按联行号反查金蝶校验，查不到会拦截保存。 3. 提交审批：系统自动做**黑名单校验**。 - - 提交被拦「命中黑名单」→ 该客商为国资委黑名单 A 类，**不能提交**，走线下处置。 + - 提交被拦「命中黑名单」→ 该客商为国资委黑名单 A 类（禁止交易类），**不能提交**，走线下处置；B 类（风险警示类）仅告警默认放行并记录；黑名单查询异常时暂缓提交（防漏拦），稍后重试。 4. 审批「通过」→ 系统自动推送金蝶 → 列表 `kingdee_status` 变 **synced**。 - 变 **failed** → 看失败原因（悬停/详情），修复后点行内「同步金蝶」重推。 + - failed 原因是金蝶侧该客商「审核中」→ 等金蝶审核完由定时任务自动升级（**无需反复重推**）。 5. synced 是「金蝶已受理」；金蝶审核通过后由定时任务升级为 **exist**（终态，无需操作）。 推送成功后金蝶侧效果（供确认推送结果时对照）： @@ -132,7 +420,7 @@ ![客商档案表单：基础信息含「供应商编码」（金蝶供应商编码，系统自动获取）；收款信息 tab 维护开户行/联行号（开户行失焦按行名从金蝶带出联行号，保存前按行号校验）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/15-客商档案-供应商编码.png) -![image-20261030195438695](F:\workspace\work\xdwl\tms-api\doc\docs\业务流程\2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets\image-20261030195438695.png) +![新增客商表单风险实时提示：客商名称下方显示「被列入外部黑名单（失信类别：风险警示类）…」红色提示，悬浮见明细；提交审批时按纳税人识别号做金蝶黑名单硬校验（A 类禁止提交）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/image-20261030195438695.png) @@ -140,7 +428,88 @@ > ·注意：审批通过后的**档案变更不会重新推送金蝶**。改了信用代码等关键信息需人工确认金蝶侧一致性。 -### 3.2 预付结算单（进度预付与尾款结算的前置） +### 4.2 项目立项推送合同合规 + +**页面：项目管理 → 项目管理** + +项目立项审批通过后，TMS 把项目信息推送到合同合规系统（C102）：首次推送先按**项目编号**判重，命中直接回填已有合规项目ID（不重复建）；变更审批通过后按已有合规项目ID更新。项目没有客商风险特批环节。 + +![项目管理列表：审批通过且未推送的项目行内显示「推送合规」；合规状态/金蝶项目ID列在表格右侧横向滚动区](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/41-项目管理列表-推送合规.png) + +**前提**：项目审核状态为「审批通过」或「变更审批通过」、项目编号不为空；运维已配置 `thirdParty.hcs.project.template-code`（第 3 节 HCS 准备 #3）。 + +1. **自动路径**：审批「通过」时即时推送（开关 `push.immediate-enabled` 开启时页面显示「正在推送合规，请稍候…」遮罩，等待结束勿重复点击）；未开启时等定时扫描（`push.project.sync-enabled`，每 5 分钟）。 +2. **手动路径**：行内「**推送合规**」→ 确认弹窗「确定」→ 等遮罩结束列表自动刷新；勾选多条可点工具栏「**批量推送合规**」（选中项必须全部满足推送条件，否则整批提示「选中数据中有 N 条不符合推送条件」）。 +3. **成功标志**：合规状态变**已推送**；提示可能为「项目立项新建成功：项目编号」（新建）、「项目立项更新成功：项目编号」（变更更新）、「判重命中，回填已有合规项目ID」。 +4. **结果查看**：列表「金蝶项目ID」「金蝶项目编号」由 HCS 完成金蝶同步后回调回填，可能延迟——**推送成功 ≠ 金蝶项目已建**，稍后刷新查看。 +5. **失败处理**：悬停合规状态看原因（常见：「立项表单模板编码未配置」→运维补配置；C102 接口异常/超时→稍后重推）。失败每 5 分钟自动重试，超 5 次停止，人工重推清零。 +6. **项目变更**：审批通过/变更审批通过的项目行内「变更」→ 修改提交审批 → 通过后按合规项目ID更新 HCS；从未推送过的按首推处理（先判重再新建）。 + +### 4.3 合同管理：新增、审批与推送合规 + +**页面：合同管理 → 合同管理 / 合同变更** + +合同是付款特批与履约数据的前提：付款申请的特批、履约计划/记录都挂在**已推送合规的合同**下。合同列表的「合规状态」「金蝶合同ID」「当前节点」「归档状态」列是本节的主看板。 + +![合同列表状态与操作列：合同阶段/审核状态/归档状态/合规状态/金蝶合同ID/当前节点（特批审核=特批中）/操作列（查看/复制/变更/附件上传/推送合规），工具栏含「批量推送合规」](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/02-合同列表状态与操作列.png) + +**第一步：新增与提交审批** + +![新增合同：签约类型、合同名称、合同类型、项目、甲乙方、合同期限、金额、结算方式等基本信息（甲乙方可选多个客商，支持甲乙丙多方；推送合规按多方展开签署方）](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/04-新增合同-基本信息.png) + +1. 「新增」填写基本信息（合同编号可不填，按合同负责部门规则自动生成）、计费信息、结算单规则、付款比例设置——**正式合同**这三块必须完整并通过校验，**临时合同**只校验基础必填项。 +2. 上传附件：用印材料区（用印材料/双章归档文件/其他文件）、佐证材料区（**特批附件**/其他文件）。**高风险/黑名单客商合同必须上传「特批附件」**，否则提交被拦截（提示见 4.6 同款）。 +3. 三种提交：「保存」（草稿，不推送）/「提交临时合同」（有效期 30 天，及时「转正式合同」）/「提交正式合同」。提交后审核状态「审批中」。 + +**第二步：审批与推送合规** + +![手动推送合规确认：列表行内「推送合规」，确认后显示「正在推送合规，请稍候…」](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/15-手动推送合规确认.png) + +1. 审批人点「通过」→ 即时推送（开关开启时）或等定时扫描；也可对「待推送/推送失败」的合同行内「推送合规」/勾选后工具栏「批量推送合规」手工推。 +2. **成功标志**：合规状态**已推送** + 详情回填**合规合同ID**。 +3. **推送时系统自动做的事**（供理解，无需操作）：附件转传合规（C103-2）→ 客商风险校验（C101-1 + 金蝶黑名单 A801-5，甲乙双方逐个查，**命中只标记不阻断推送**）→ 判重/起草（C103-3/C103-1，报文含业务合同号与归档状态）→ 履约规则同步（C103-9，开关开启时同步合同表单「履约规则」页签的付款/收款计划行）→ 高风险/黑名单命中则挂起「特批审核」（第四步）。 +4. **失败处理**：悬停合规状态看原因。常见：「合同类别 [xxx] 未配置合规模板ID」→运维补映射；附件转传失败→查下载基址与附件；C103-1/C103-11 业务校验错误→按返回 msg 修数据。超 5 次停止自动重试，人工重推清零。 + - 怀疑合规侧其实已生成：**直接重推即可**——本地无合规ID先走判重回填，已有合规ID走更新，两种路径都不会重复生成合同。 + +![待推送与推送失败列表：合规状态列「待推送/推送失败」，行内「推送合规」按钮，失败原因可悬停查看](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/14-待推送与推送失败列表.png) + +**第三步：查看推送结果（合同详情「合规信息」区）** + +![合同详情合规信息：合规同步状态、合规合同ID、客商风险、特批状态、特批说明](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/06-合同详情-基本信息与合规信息.png) + +- 合规状态=已推送且合规合同ID不为空即推送成功；**金蝶合同ID**由 HCS 金蝶同步后回写，可能延迟，空着先刷新。 +- **已推送的合同不能直接编辑**——要改内容必须走「变更」（第五步），否则会在合规侧产生重复合同。 + +**第四步：高风险/黑名单合同特批** + +![高风险客商合同：合规信息显示客商风险红色标签与特批状态](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/12-特批待发起.png) + +1. 触发条件：甲方或乙方为外部客商，且客商为高风险或金蝶黑名单命中（口径见 1.8）。 +2. 流程：推送成功后合同自动进入特批 → 特批状态「特批中」、当前节点「**特批审核**」→ HCS 完成后经回调或定时查询（随合同扫描任务，每 5 分钟兜底）回传 → **特批通过**：恢复「审批通过」（金蝶合同ID可能同时回填）；**特批驳回**：合同审批联动「已驳回」，修改后重新提交审批、重新推送。 +3. **人工确认特批结果**（结果长时间未回传时）：详情「合规信息」右上角「**确认特批结果**」→ 输入 `approved`（通过）或 `rejected`（驳回）→ 确定。仅「特批中」可操作，确认前务必与合规侧核对。 + +![确认特批结果：输入 approved 或 rejected](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/13-确认特批结果.png) + +4. 特批中的合同**不允许重推**（提示「合同特批审核中，禁止重推」）。详情页右上角「发起特批」是旧版独立入口，点击提示接口不存在可忽略——特批随推送自动发起。 + +**第五步：合同变更（已推送合同改内容）** + +![合同变更页面：在正式合同基础上修改基本信息、附件、计费、结算和付款比例](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/09-合同变更-基本信息.png) + +1. 合同管理列表行内「**变更**」（变更驳回后点「重新提交变更」）→ 系统创建变更单草稿并跳转「**合同变更**」页面；同一合同已有审批中的变更单时拦截，有草稿/已撤回/变更驳回的变更单时打开继续编辑。 +2. 选**变更类型**（合同信息变更/结算规则变更/终止合同——「终止合同」当前版本未开放）→ 修改内容 → 填**变更原因**（最多 500 字）→ 上传变更材料 → 「提交」。 +3. 审批人在「合同变更」列表审批：**通过** → 回写原合同（状态变「变更审批通过」）并按合规合同ID更新 HCS（C103-11），履约计划行随变更重推，变更记录保留在合同详情底部；**驳回** → 变更单「变更驳回」可改后重提；审批中可**撤回**（不影响原合同状态）。 + +![合同变更下部：填写变更原因（最多 500 字）并上传变更材料](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/10-合同变更-原因与材料.png) + +**第六步：附件上传与归档** + +![附件上传弹窗：先选附件位置（用印材料/佐证材料），再选附件类型并上传](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/11-附件上传弹窗.png) + +1. 列表行内「**附件上传**」（正式合同审批通过后）：选附件位置与类型上传（支持 pdf/图片/office/zip 等，单个 ≤50MB）。 +2. **归档**：附件类型选「**双章归档文件**」（位置=用印材料）→ 合同归档状态变「已归档」，且已推送合规的合同**即时**更新合规侧归档状态为「待归档」并挂载归档附件；未推送的合同在首次推送报文中自带归档状态。合规侧后续归档流转由合规系统维护。 + +### 4.4 预付结算单（进度预付与尾款结算的前置） **页面：结算管理 → 预付结算单**（原「预结算单」，本身不推送金蝶） @@ -152,19 +521,19 @@ ![预付结算单编辑页：汇率日期/结算汇率字段（人民币时禁用为 1.00，外币选择日期后自动带出）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/12-预结算单-汇率字段.png) 2. 提交审批 → 审批「通过」（或驳回后修改重新提交）。 3. 审批通过后的三个出口： - - **发起进度预付**：工具栏「预付申请」（限应付且已审批、未转付款结算、同一合同可多选）→ 跳转付款申请新增页，见 3.3； - - **项目预付核销**：付款结算单/预付结算单编辑页「项目预付核销」分区，见 3.5； - - **尾款结算（转付款结算单）**：工具栏「尾款结算」→ 见 3.6；转后本单被锁定（不能再发起预付、不能作废）。 -4. 注意：**付款结算单的汇率不自动继承预付结算单**，转正式后需在编辑时重新选汇率日期带出（见 3.13），否则推送金蝶不带汇率。 + - **发起进度预付**：工具栏「预付申请」（限应付且已审批、未转付款结算、同一合同可多选）→ 跳转付款申请新增页，见 4.5； + - **项目预付核销**：付款结算单/预付结算单编辑页「项目预付核销」分区，见 4.7； + - **尾款结算（转付款结算单）**：工具栏「尾款结算」→ 见 4.8；转后本单被锁定（不能再发起预付、不能作废）。 +4. 注意：**付款结算单的汇率不自动继承预付结算单**，转正式后需在编辑时重新选汇率日期带出（见 4.15），否则推送金蝶不带汇率。 5. 金蝶付款回写联动：进度预付在金蝶付讫（已付款）后，系统自动在本单垫资记录回写付款金额与金蝶付款单号，并刷新「申请预付金额 / 已付款金额」两列——无需手工登记（异常时管理员可用回写接口手工补）。 -### 3.3 进度预付（预付结算单 → 付款申请） +### 4.5 进度预付（预付结算单 → 付款申请） **页面：结算管理 → 预付结算单 →（预付申请）→ 收付款管理 → 付款管理** **前提**：预付结算单是**应付**、状态**审批通过**、还没转付款结算。 -1. 进「预付结算单」列表，勾选单据（**同一合同**可多选；不满足"应付+审批通过+未转付款结算+同合同"会按钮拦截提示）。 +1. 进「预付结算单」列表，勾选单据（**同一合同**可多选；不满足"应付+审批通过+未转付款结算+同合同"会按钮拦截提示 → 逐项核对：类型改应付/先完成审批/已转单的换其他预付结算单/不同合同的分开勾选）。 2. 点工具栏「**预付申请**」→ 自动跳到「付款申请新增页」：**付款类型固定为"进度预付"不可改**，所选预付结算单已带入、结算单号只读，"结算金额 / 可付款金额"自动带出。 ![付款申请表单（进度预付）：付款类型=进度预付且锁定，结算单号只读带出，结算金额/可付款金额自动显示，需填申请付款金额、付款方式、收款方](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/32-付款申请表单-进度预付.png) @@ -176,12 +545,12 @@ 4. 填「申请付款金额」（不超过可付款金额）、「付款方式」（选承兑汇票时要再选汇票台账）、「收款方」→「**保存**」。 5. 回到「付款管理」列表 → 找到该单 →「提交」→ 审批人「通过」。 -**状态变化**：付款申请 `草稿 → 审批中 → 审批通过`；随后系统自动推金蝶，金蝶状态 `未生成 → 已生成 → 付款中 → 已付款`（推送与回写见 3.8）。 +**状态变化**：付款申请 `草稿 → 审批中 → 审批通过`；随后系统自动推金蝶，金蝶状态 `未生成 → 已生成 → 付款中 → 已付款`（推送与回写见 4.10）。 **同时发生**：预付结算单列表出现「申请预付金额 / 已付款金额」两列并随付款进度更新；预付结算单仍可继续「尾款结算」。 > 若提交/通过后看到黄色警告写着金蝶推送失败：审批结果**不受影响**，稍后自动重推，或到付款管理列表勾选后点「批量同步」。 -### 3.4 项目预付（不挂结算单） +### 4.6 项目预付（不挂结算单） **页面：收付款管理 → 付款管理 →（新增付款申请，付款类型=项目预付）** @@ -195,23 +564,25 @@ 1. 填写：**所属项目**（必选）→ **合同名称**（必选，**选了项目后才能选**，只能选承运商合同）→ 申请付款金额、付款方式、付款方/收款方等。本类型不挂结算单，不显示结算信息与发票相关内容。 2. 「保存」→「付款管理」列表「提交」→ 审批人「通过」。 -**会被拦截的情况（提示原文）**： -- "申请付款金额不能超过项目额度"（项目额度 = 项目资金需求额度 + **审批通过且在有效期内**的临时额度；按单笔申请金额比较） -- "申请付款金额不能超过客户额度"（按收款方匹配客商档案的信用额度） -- "项目预付必须选择有效合同"、"付款申请只能选择承运商合同" -- "申请付款金额不能超过可付款金额"（项目预付的可付款金额=项目资金需求×10000） +**会被拦截的情况（提示原文 → 解决）**： +- "申请付款金额不能超过项目额度"（项目额度 = 项目资金需求额度 + **审批通过且在有效期内**的临时额度；按单笔申请金额比较）→ 调小申请金额，或让管理员先审批通过临时额度管理里的临时额度。 +- "申请付款金额不能超过客户额度"（按收款方匹配客商档案的信用额度）→ 调小申请金额，或联系管理员上调该客商档案的信用额度。 +- "项目预付必须选择有效合同"、"付款申请只能选择承运商合同" → 先选所属项目再选合同；只选承运商合同，选了其他类别合同换掉。 +- "申请付款金额不能超过可付款金额"（项目预付的可付款金额=项目资金需求×10000）→ 调小申请金额；确需更大额度先在项目立项/变更里调增资金需求额度。 -**状态变化**：同 3.3。**务必等到金蝶状态「已付款」**，否则下一步核销（3.5）做不了。 +**状态变化**：同 4.5。**务必等到金蝶状态「已付款」**，否则下一步核销（4.7）做不了。 **客商风险与付款特批（所有付款申请提交时通用）**： - 提交时如果**收款方是高风险/黑名单客商**：会被拦截——"收款方[x]为高风险/黑名单客商，必须上传「特批附件」类型附件后再提交审批"。先在附件区上传类型为「特批附件」的文件再提交。 -- 如果触发**合规额度超额**（HCS 口径）：**不会拦截提交**，单据转入「付款特批」流程，特批完成后才会推金蝶。 -- 审批人点「通过」后，弹窗提示可能带一句话，常见三种： - - "审批通过，已发起付款特批，特批通过后将自动推送履约数据并同步金蝶" → 等特批完成，系统自动推； - - "审批通过，已同步金蝶：XXX" → 已经推成功； +- **付款特批是否走合同合规系统由开关 `thirdParty.hcs.spec-pay.enabled` 控制（2026-11-03 起默认关闭）**： + - **关闭（当前默认）**：审批通过后**不发起**合规特批、不挂起「特批审核」，直接同步金蝶；触发合规额度超额也不转特批，照常走金蝶。特批附件必传校验保留（高风险/黑名单收款方仍必须上传）。 + - **开启**：触发合规额度超额（或高风险/黑名单）时**不拦截提交**，审批通过后自动发起付款特批，特批完成后才推金蝶（特批流程由实施/管理员配合处理，本文不展开）。 +- 审批人点「通过」后，弹窗提示可能带一句话： + - "审批通过，已同步金蝶：XXX" → 已经推成功（开关关闭时的常见提示）； + - "审批通过，已发起付款特批，特批通过后将自动推送履约数据并同步金蝶" → 开关开启且走了特批，等特批完成； - "审批通过，但自动同步金蝶失败：…" → 审批不受影响，稍后自动重推或手动「批量同步」。 -### 3.5 项目预付核销（在结算单上抵扣） +### 4.7 项目预付核销（在结算单上抵扣） **页面：结算管理 → 预付结算单 / 付款结算单（编辑页「项目预付核销」分区）** @@ -228,18 +599,18 @@ 4. 在「**本次核销金额**」列：默认已按"可核销金额"填满，可以改小。 5. 「保存」。 -**会被拦截的情况（提示原文）**： -- "预付单 XXX 本次核销金额必须大于 0" -- "预付单 XXX 本次核销金额不能超过可核销金额" -- "项目预付核销合计不能超过结算单金额" -- "仅可选择审核通过的项目预付单" -- "预付单 XXX 尚未付款，项目预付须金蝶付款完成后方可核销" -- "同一项目预付单不可重复核销" -- "项目预付单与结算单合同不一致" +**会被拦截的情况（提示原文 → 解决）**： +- "预付单 XXX 本次核销金额必须大于 0" → 核销行本次核销金额填大于 0 的数（不需要核销就删掉该行）。 +- "预付单 XXX 本次核销金额不能超过可核销金额" → 把本次核销金额改小到不超过该行「可核销金额」。 +- "项目预付核销合计不能超过结算单金额" → 减小各行核销金额，使合计不超过结算单金额。 +- "仅可选择审核通过的项目预付单" → 只能从弹窗候选里选（弹窗已过滤），手工改动数据导致的不合法行删掉重选。 +- "预付单 XXX 尚未付款，项目预付须金蝶付款完成后方可核销" → 等该预付单金蝶状态变「已付款」（4.10 回写）后再核销。 +- "同一项目预付单不可重复核销" → 该预付单已在本单或其他结算单核销过，弹窗里已灰掉的行不能重复选。 +- "项目预付单与结算单合同不一致" → 只核销与结算单同一合同的项目预付单。 **状态变化**：结算单「**已付金额（含预付、核销）**」立刻增大、「剩余未付金额」减小；核销金额会同时计入"已申请付款金额"和"已付金额"两个口径；列表上"申请付款金额（含预付）/已收已付合计（含预付）/剩余可付/收付款状态"同步变化。 -### 3.6 尾款结算（预付结算单转付款结算单，容纳预付） +### 4.8 尾款结算（预付结算单转付款结算单，容纳预付） **页面：结算管理 → 预付结算单 →（尾款结算）→ 新增付款结算单** @@ -254,17 +625,17 @@ ![编辑付款结算单：结算合计区底部一行显示 结算合计（原金额）/已付金额（含预付、核销）/剩余未付金额，下方依次为 结算明细/附件/项目预付核销/发票信息 分区](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/37-付款结算单编辑页-结算合计三口径.png) -4. 「项目预付核销」区会**自动带出来源预付结算上已核销的行**，可增/删/改金额（口径见 3.5）。 +4. 「项目预付核销」区会**自动带出来源预付结算上已核销的行**，可增/删/改金额（口径见 4.7）。 5. 「保存」（草稿）→「提交」→ 审批人「通过」。 -**会被拦截的情况**： -- "仅审核通过的预付结算单可转付款结算" -- "尾款结算只能选择同一项目下的预付结算单" -- "该预结算单存在在途预付申请，无法尾款结算"（**审批中或已审批但还没付完款的预付申请都算在途**，先把预付处理完/付完再来转） +**会被拦截的情况（提示原文 → 解决）**： +- "仅审核通过的预付结算单可转付款结算" → 先把预付结算单审批通过再勾选。 +- "尾款结算只能选择同一项目下的预付结算单" → 取消勾选不同项目的单据，只留同一项目。 +- "该预结算单存在在途预付申请，无法尾款结算"（**审批中或已审批但还没付完款的预付申请都算在途**）→ 先把在途预付申请处理完/付完款再来转。 -**状态变化**：付款结算单 `草稿 → 审批中 → 审批通过`；预付结算单被标记为已转付款结算（来源被锁定：不能再发起预付、不能作废）。随后走 3.7 推送金蝶。 +**状态变化**：付款结算单 `草稿 → 审批中 → 审批通过`；预付结算单被标记为已转付款结算（来源被锁定：不能再发起预付、不能作废）。随后走 4.9 推送金蝶。 -### 3.7 结算单推送（付款结算单 / 收款结算单） +### 4.9 结算单推送（付款结算单 / 收款结算单） **页面：结算管理 → 付款结算单（应付）/ 收款结算单（应收）** @@ -272,15 +643,15 @@ ![收款结算单列表（应收）：与付款结算单同构，工具栏含 同步金蝶；金蝶单据状态需为「已同步」才能开票](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/40-收款结算单列表-应收.png) -前提：结算单已审批通过；非人民币结算单已维护汇率（见 3.13）；客商已 synced/exist。 +前提：结算单已审批通过；非人民币结算单已维护汇率（见 4.15）；客商已 synced/exist。 1. **自动路径**：审批「通过」时自动推送（开关开启时）。 2. **手动路径**：勾选一条或多条单据 → 工具栏「同步金蝶」。 - 应付单（A102-2）/ 应收单（A302-2）按结算类型自动分流，无需选择。 3. 成功标志：列表出现**金蝶单据号**，状态变 **已同步**，并出现「金蝶锁定中」标签。 4. 失败处理：状态变 **同步失败** → 鼠标悬浮状态标签看失败原因 → 常见原因： - - 「请先同步金蝶应付单」类 → 关联结算单还没推（付款/开票依赖结算单先推，见 3.8/3.9）； - - 客商编码取不到 → 先完成 3.1； + - 「请先同步金蝶应付单」类 → 关联结算单还没推（付款/开票依赖结算单先推，见 4.10/4.11）； + - 客商编码取不到 → 先完成 4.1； - 部门金蝶组织编码缺失 → 找管理员维护。 5. 纠偏：如果怀疑推送实际成功但本地状态没更新，等定时勾稽（或联系运维手动触发），系统会自动核对金蝶侧并纠正状态/补单号。 @@ -290,7 +661,7 @@ ![金蝶财务应收单与 TMS 结算单对照：应收金额、费用合计对应，明细行物料/车号/运输货物逐行对应](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a302-应收单对照.png) -### 3.8 付款申请推送与结果回写 +### 4.10 付款申请推送与结果回写 **页面：收付款管理 → 付款管理** @@ -311,28 +682,28 @@ - **生成失败** → 鼠标悬浮状态标签看失败原因，修复后重推（批量同步按钮即可，系统会自动跳过金蝶已有的）；系统每 10 分钟也会自动重推。 - 单据在金蝶被删：回调后自动置生成失败并清单号，直接重推； - 金蝶删了但回调丢了：约 20 分钟后系统自动检测到「查不到」并解锁置生成失败，再重推。 + - 推送被拦"收款方客商为高风险/黑名单，付款特批审核中（特批审核），特批完成后方可推送金蝶" → 仅付款特批走合规开关（`spec-pay.enabled`，默认关闭）开启时出现：特批通过（当前节点恢复「审批通过」）后自动续推，无需人工操作（特批流程由实施配合处理，口径见 4.6）。 +6. **合同系统联动（履约数据自动推送）**：付款申请审批通过只做**本地履约计划金额累加**（不推合规）；**金蝶实际付款（状态「已付款」）回写后**，系统才自动推送履约计划（C103-9）与履约记录（C108）到合同合规系统——受 `exe-stage.sync-enabled`/`perf-record.sync-enabled` 开关控制，效果与核对方法见 4.18。 -推送成功后金蝶侧效果（供确认推送结果时对照）： +推送成功后的效果对照（TMS 回填与金蝶侧，供确认推送结果时对照）： ![TMS 付款申请与金蝶付款申请单对照：申请付款金额、收款账号、结算方式逐项对应；金蝶单号 FKSQ-… 与 TMS 列表回写的金蝶单号一致](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a103-付款申请对照.png) ![预付款推送效果：TMS 进度预付在金蝶生成「其他付款申请」，预付款金额、收款账户对应，附件随单上传](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a103-3-预付款对照.png) +![付款结果回写后付款管理列表效果：金蝶单据状态变「已付款」（FKSQ-000000282），已付款金额 66364.33 自动回填；右侧「已指定应付」列同步展示（指定失败红色可悬浮看原因）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/43-付款管理列表-已付款回写.png) - -![image-20261030203349665](F:\workspace\work\xdwl\tms-api\doc\docs\业务流程\2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets\image-20261030203349665.png) - - +![付款结果回写效果：TMS 付款申请（FKD2026110300003）查看页「付款记录」回写实付金额 66364.33/付款单号/付款凭证（出纳付款-桂糖物流-202611-0007），与金蝶付款处理单（上游单据编码 FKSQ-000000282、付款金额 ¥66,364.33、票据状态已付款）逐项对应](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/image-20261103185134875.png) > 注意：推送后单据被金蝶锁定，**不能改金额、不能作废**。发现金额错误必须先金蝶侧处理。 -### 3.9 开票申请推送与开票结果 +### 4.11 开票申请推送与开票结果 **页面：收付款管理 → 开票管理** ![开票管理：工具栏「批量同步」逐张推送（按发票张次拆单）；搜索区可按「金蝶单据状态」筛选](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/05-开票管理-批量同步.png) -前提：有一张**收款结算单**（应收），**审批通过**、未作废、**剩余可开票金额 > 0**，且已完成 3.7 应收推送（开票前系统会先检查金蝶里有没有这张单的应收单）。 +前提：有一张**收款结算单**（应收），**审批通过**、未作废、**剩余可开票金额 > 0**，且已完成 4.9 应收推送（开票前系统会先检查金蝶里有没有这张单的应收单）。 > 已放开"必须未开票"的限制：**部分开票过的结算单只要还有剩余可开票金额，可以再次选择继续开**，累计额度自动控制（可开票金额=结算金额 − 已被其他未作废开票申请占用的金额）。 1. 新增：进「开票管理」列表 → 点「新增」→ 「结算单」右侧「**选择**」→ 弹窗「**选择应收正式结算单**」→ 按结算单号/项目/合同搜索并勾选 →「确定」（**合并开票必须同一合同**）。 @@ -352,13 +723,13 @@ 7. 查开票结果：等定时回写（默认每 10 分钟），状态变 **开票完成**（终态，全部发票张次都有回写结果才到这一步）。 8. 查看发票文件：正式结算单详情 →「开票发票」区 → 查看/下载（PDF 优先）。 -**会被拦截的情况（提示原文）**： -- "只能选择审批通过、未作废的应收正式结算单" -- "合并开票的结算单必须属于同一合同" -- "本次开票金额不能超过可开票金额" / "本次开票金额必须大于 0" -- "电子专票的纳税人识别号/开户行/开户账号/注册地址…"（必填校验） -- "运费不能与其他费用合并开在同一张发票中" -- 推金蝶时提示"正式结算单[x]财务应收单未在金蝶生成，请先在正式付款单页面同步金蝶"（先做 3.7 应收推送） +**会被拦截的情况（提示原文 → 解决）**： +- "只能选择审批通过、未作废的应收正式结算单" → 先把收款结算单审批通过/不作废，再重新选单。 +- "合并开票的结算单必须属于同一合同" → 取消不同合同的结算单，分两张开票申请（每张限同一合同）。 +- "本次开票金额不能超过可开票金额" / "本次开票金额必须大于 0" → 调小开票内容金额到剩余可开票金额以内；负数/0 修正为有效金额。 +- "电子专票的纳税人识别号/开户行/开户账号/注册地址…"（必填校验）→ 到客商档案补全发票信息（受票方开票信息），或改选其他发票类型。 +- "运费不能与其他费用合并开在同一张发票中" → 运费单独放一张发票（增加发票张次分开放）。 +- 推金蝶时提示"正式结算单[x]财务应收单未在金蝶生成，请先在正式付款单页面同步金蝶" → 先做 4.9 应收推送，成功后再推开票。 **限制**：开票申请一旦推到金蝶（已同步/开票完成）就**锁定不能改**；数电票已经开出来的只能走红冲，不能在本系统作废。**预付和核销不影响开票金额**，开票始终按结算单的**全额**来匹配。 @@ -366,7 +737,7 @@ ![开票申请按发票张次拆分：TMS 开票内容第1张/第2张分别生成金蝶开票申请单，购销方、不含税金额逐项对应](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a303-1-开票张次对照.png) -### 3.10 收票登记（进项发票·先票后款） +### 4.12 收票登记（进项发票·先票后款） **页面：收付款管理 → 收票管理（先票）+ 结算管理 → 付款结算单（后款）** @@ -386,14 +757,15 @@ ![金蝶侧收票管理·全票池查询：TMS 票池选票的数据源头](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/img.png) - 票池数据来自定时同步（默认每 30 分钟）；票号精确搜索时若本地没有会**自动去金蝶现查**。 - - 查不到票 → 等同步或让运维检查票种白名单配置/手动触发同步（见 4.2）。 + - 查不到票 → 等同步或让运维检查票种白名单配置/手动触发同步（见 5.2）。 2. 选**结算组织**（合同承办部门）——推送金蝶时按它确定结算组织编码，必填。 3. 保存：系统自动**重查金蝶票池校验可用性**——票已被别人登记/认领/红冲/作废会保存失败并提示原因。 4. 提交审批 → 审批「通过」自动推送，或勾选 → 工具栏「批量同步」。 5. 成功标志：状态 **已推送（pushed）**（金蝶收票单已生成）。**到这里收票就完成了**——指定应付由付款结算单负责（见第二步）。 - failed 且提示发票状态异常（红冲/作废）→ 该票在金蝶已不可用，需人工处理，不要重推。 - - failed 且提示「供应商代码/往来户」→ 发票销方未建档或未同步金蝶，先完成 3.1 客商建档再重推。 + - failed 且提示「供应商代码/往来户」→ 发票销方未建档或未同步金蝶，先完成 4.1 客商建档再重推。 - failed 且提示免税/零税率行 → 该票存在系统无法映射的税率行，人工核实后联系金蝶方约定编码。 + - failed 且提示结算组织/平台公司类 → 手选结算组织部门上溯不到带金蝶编码的平台公司，管理员补维护组织档案后重推。 6. 附件：表单附件区可查看/下载发票原件（系统自动从金蝶取，PDF 优先）。 ![收票登记表单（先票后款改造后）：发票号码选金蝶票据池发票带出票面与「发票明细」；「结算组织（合同承办部门）」必选；「结算信息」区只读——认领关系由付款结算单侧维护](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/13-收票登记-先票后款表单.png) @@ -425,7 +797,7 @@ ![付款结算单查看页「发票信息」区：列为 发票号/开票日期/发票类型/发票金额/可匹配发票金额/匹配结算单金额（指定失败行可编辑）/「是否已指定应付」（未指定·指定失败·已指定应付）＋操作列 查看/下载/重新推送；下方付款信息区回显付款申请金蝶单号](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/19-查看页发票信息-指定应付状态与重新推送.png) -**系统自动指定应付**：付款结算单推送金蝶（应付单生成，见 3.7）后，系统对**本单认领且已推送**的收票单逐张执行「指定应付」，收票状态推进为 **assigned**（已指定应付，终态）。指定失败不影响结算单推送——失败票用入口 B/C 人工重推兜底。 +**系统自动指定应付**：付款结算单推送金蝶（应付单生成，见 4.9）后，系统对**本单认领且已推送**的收票单逐张执行「指定应付」，收票状态推进为 **assigned**（已指定应付，终态）。指定失败不影响结算单推送——失败票用入口 B/C 人工重推兜底。 ![付款结算单列表「指定失败」悬浮：聚合展示本单各票的失败原因（如"发票xxx：推送金蝶收票单失败：…"），无需翻日志](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/16b-付款结算单列表-指定失败原因悬浮.png) @@ -434,7 +806,7 @@ **口径与注意**： - 一张收票单只能被一张付款结算单认领；匹配金额合计可超结算金额（覆盖即完成收票）。 - 收票单一直卡在 pushed：说明还没被任何付款结算单认领（或认领它的结算单应付单还没推送成功），认领并推送后自动接上；已认领但指定失败的，用入口 B/C 重推。 -- ⚠️ **定时自动补发指定默认关闭**（2026-11-02 起）：收票结果回写任务不再自动对「pushed+已认领」的票补发指定应付（开关 `thirdParty.bfi.receivedInvoiceResult.assignCompensationEnabled`，默认 false），**由人工入口兜底**（发票登记推送 / 查看页重新推送）；需要恢复自动补发时由运维开启该开关（见 4.1）。 +- ⚠️ **定时自动补发指定默认关闭**（2026-11-02 起）：收票结果回写任务不再自动对「pushed+已认领」的票补发指定应付（开关 `thirdParty.bfi.receivedInvoiceResult.assignCompensationEnabled`，默认 false），**由人工入口兜底**（发票登记推送 / 查看页重新推送）；需要恢复自动补发时由运维开启该开关（见 5.1）。 - 结算单作废/移除认领**不会**自动通知金蝶解除指定，需金蝶侧人工处理后重推。 推送成功后金蝶侧状态与效果（供确认推送结果时对照）： @@ -445,7 +817,7 @@ ![结算单详情「发票信息」区：认领的发票可 查看/下载（系统从金蝶取原件，PDF 优先）；付款信息区回显付款申请金蝶单号](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a801-2-发票查看下载.png) -### 3.11 结算调整单（结算单金额调整） +### 4.13 结算调整单（结算单金额调整） **页面：结算管理 → 结算调整单** @@ -514,7 +886,7 @@ - 原单的下游关联（开票申请、收款认领、对账）**不迁移**，留在原单；新单发票状态、收付款状态从零开始（应收新单显示"未开票/未收款"属正常）。 - 已审批通过的调整单**无法驳回、无法作废、无法撤回**；金额再错就新建调整单二次调整。 -### 3.12 收款流水与认领 +### 4.14 收款流水与认领 **页面：收付款管理 → 收款流水、认领记录** @@ -522,17 +894,17 @@ 1. **同步流水**：收款流水页 → 工具栏「**手动同步流水**」→ 拉取金蝶收款单（按业务日期窗口，默认今天倒推 60 天，全公司口径）。 ![收款流水：工具栏「手动同步流水」拉取金蝶收款单、「批量认领」进入认领；列表展示收款单号（即金蝶收款单号）/收款金额（认领上限）/未匹配金额（仅参考）等，无推送相关列](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-手动同步流水.png) - - 报错「组织管理中未维护平台公司金蝶编码」→ 找管理员维护组织档案（第 2 节 #4）。 + - 报错「组织管理中未维护平台公司金蝶编码」→ 找管理员维护组织档案（第 3 节 #4）。 - 需要更早的历史流水 → 让运维调大同步窗口天数配置后重新同步。 2. **认领**：点流水「认领」进入详情（或勾选多条「批量认领」，要求同付款人+对方账号）→ 选择**审批通过的应收结算单**、填分摊金额 → 确认。 - - 认领只落本地，不推金蝶；认领后系统自动把本次认领推送到**合同合规系统**（失败只记标记，不影响认领）。 - - 分摊总额不能超过「剩余可认领金额」（=收款金额−已认领金额）；「未匹配金额」是金蝶参考值，**为 0 不影响认领**。 + - 认领只落本地，不推金蝶；认领提交后系统自动把本次认领推送到**合同合规系统**（履约计划金额累加 + 认领记录 C107-1 + 履约流水 C108-1，效果见 4.18；推送失败只记标记**不自动重试**，不影响认领本身）。 + - 分摊总额不能超过「剩余可认领金额」（=收款金额−已认领金额），超出会拦截 → 调小本次分摊金额，或先作废之前的认领腾出额度；「未匹配金额」是金蝶参考值，**为 0 不影响认领**。 3. **查看进度**：金蝶收款单状态（已推送/审核通过/已收款）随每次「手动同步流水」自动刷新，无需回写操作。 -4. **作废**：认领记录页 → 本人记录行内「作废」→ 确认（提示含"同步作废合同合规系统认领记录"）→ 本地回退金额 + 自动同步合规作废。 +4. **作废**：认领记录页 → 本人记录行内「作废」→ 确认（提示含"同步作废合同合规系统认领记录"）→ 本地回退金额 + 自动同步合规作废（合规侧认领记录置为作废 C107-3；**履约计划金额与履约流水不回冲**，见 4.18）。 ![认领记录：仅显示本人认领记录；行内「作废」回退金额并同步作废合同合规系统认领记录；原「查询金蝶认领结果」按钮已删除](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-列表.png) - 作废不会影响金蝶收款单本身（金蝶侧红冲由财务人工处置）。 -### 3.13 汇率维护（非人民币结算） +### 4.15 汇率维护（非人民币结算） 结算单（预付结算单/付款结算单/收款结算单）编辑时：选择非 RMB 币种 → 选择**汇率日期** → 系统自动从金蝶带出汇率并重算本位币金额。带不出（金蝶该日无汇率）→ 换日期或联系金蝶侧确认。**预付结算单的汇率不自动继承到付款结算单**，转正式后需重新维护。 @@ -542,7 +914,7 @@ ![金蝶侧效果：汇率 6.7367、金额(本位币)自动换算，与 TMS 结算单的本位币合计一致](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a801-4-外币汇率推送.png) -### 3.14 作废与撤销：能做什么、状态怎么变 +### 4.16 作废与撤销：能做什么、状态怎么变 | 我想…… | 前提 | 操作位置 | 状态变化 | |---|---|---|---| @@ -554,16 +926,81 @@ | 金蝶侧删付款申请 | — | 金蝶操作后系统自动处理 | 付款申请金蝶状态→生成失败，金蝶单号被清空；**未付的预付记录联动作废**；人工核实后重推，重推成功会重新建档；**已核销的行不会自动删**，需要人工作废该预付款才回落 | | 金蝶侧删结算单 | — | 金蝶操作后系统自动处理 | 结算单被**系统自动作废**，同步状态还原，核销行删除 | | 金蝶侧删开票申请 | — | 金蝶操作后系统自动处理 | 开票申请被**系统自动作废**，来源结算单开票状态回落 | -| 结算调整 | 结算单已审批通过（含已同步金蝶） | 结算调整单（3.11） | 金额调整走调整单：原单标记"已调整"并禁止再付款，调整后的新单自动迁移核销行与金蝶推送 | -| 作废收票认领 | — | 结算单移除认领后金蝶侧人工解除 | 移除认领/结算单作废**不会**自动通知金蝶解除指定，需金蝶侧人工处理（3.10） | +| 结算调整 | 结算单已审批通过（含已同步金蝶） | 结算调整单（4.13） | 金额调整走调整单：原单标记"已调整"并禁止再付款，调整后的新单自动迁移核销行与金蝶推送 | +| 作废收票认领 | — | 结算单移除认领后金蝶侧人工解除 | 移除认领/结算单作废**不会**自动通知金蝶解除指定，需金蝶侧人工处理（4.12） | > 一句话记住：**预付一旦真付出去（已付款），作废不会把钱退回**，只会把台账和核销额度清掉。 +### 4.17 客商风险与黑名单（查看与筛选） + +**页面：客商管理 → 客商档案（列表/表单）、合同管理列表/详情** + +数据每日 02:30 自动刷新（合同期限内生效合同的甲乙方客商），口径见 1.8。 + +![客商档案列表：展开搜索后可见「客商风险」下拉筛选，列表客商风险列为等级+黑名单组合标签](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/16-客商档案列表-客商风险.png) + +1. **筛选**：搜索栏「展开」→「客商风险」下拉选 黑名单/高风险/中风险/低风险 → 查询。 +2. **看明细**：红色标签**鼠标悬浮**，展示失信类别、列入事由、风险等级。 + +![客商风险悬浮明细：被列入外部黑名单（失信类别、列入事由）与风险等级](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/17-客商风险悬浮明细.png) + +3. **当天新增客商**：客商表单填客商名称失焦即实时查询，名称下方显示红色风险提示（悬浮见明细）；列表落库数据次日刷新后生效。 +4. **显示规则**：组合展示等级在前（如「高风险、黑名单」红）；仅黑名单/仅高风险红；中风险黄；低风险/无风险绿；内部组织默认「无风险」；未查询到显示「-」。 +5. **合同列表/详情同口径**：实时关联客商档案组装甲乙双方风险，红色标签悬浮看双方明细。 + +![合同列表客商风险列：红色标签悬浮展示甲乙双方风险明细](../hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/18-合同列表-客商风险悬浮.png) + +> 「客商风险」显示「-」：客商不在合同期限内生效合同的关联范围，或刚创建未被刷新过——等次日 02:30 或联系运维补刷。黑名单命中但标签没显示「黑名单」字样：金蝶黑名单类别/事由数据缺失时只显示等级段，同样等刷新。 + +### 4.18 履约计划与履约记录（付款/收款/开票/收票四场景） + +**页面：无 TMS 页面**——履约数据由系统在各业务节点**自动**推送合同合规系统，业务侧只在**合规系统履约记录列表**核对（按标题前缀检索最快：付款履约- / 收款履约- / 开票履约- / 收票履约-；核对四项：合同、金额、日期口径、条数）。 + +**先看懂两个概念**： +- **履约计划**＝合同收付款的**计划台账**（打算收/付多少）：来源为合同表单「履约规则」页签；合同没维护时审批通过自动补默认行（承运商合同=付款计划，客户合同=收款计划）。 +- **履约记录**＝计划行的**实际发生流水**（真正付/收/开/收了多少）。**先有计划（拿到合规阶段ID）才有记录**；记录必须挂某条计划下——合同没推合规或计划没推成功时记录暂时生成不了，条件满足后自动补上。 + +**计划金额什么时候变**（系统自动，无需操作）： + +| 业务动作 | 变化 | 同步合规时点 | +|---|---|---| +| 付款申请审批通过 | 对应付款计划金额 += 申请金额（按款项性质精确匹配，预付款不加进度款） | **金蝶实际付款后**随履约记录一起推 | +| 收款流水认领完成 | 收款计划金额 += 本次分摊金额 | 认领提交后立即推 | +| 合同「履约规则」增删改 | 行级新增/更新/删除标记 | 随合同链/付款链/收款链下一次推送 | + +计划金额是「已批准/已认领」口径，实际发生额看履约记录——两者对不上属正常口径差异。 + +**四场景履约记录对照**（全部自动生成）： + +| 场景 | 什么时候生成 | 生成条数 | 金额 | 日期 | 合规检索标题 | +|---|---|---|---|---|---| +| 付款 | **金蝶实际付款回写后**（4.10「已付款」状态就是触发点） | 一张付款申请一条，分次付款更新同一条的实际金额 | 申请金额/实付金额 | 申请日期 | 付款履约- | +| 收款 | **认领提交后**（4.14，事件驱动，失败不自动重试） | 每次认领 × 涉及合同各一条 | 本次分摊金额 | 认领日期 | 收款履约- | +| 开票 | **金蝶开票完成、发票回写后**（4.11 开票完成状态之后） | 每张发票一条 | 发票价税合计 | 发票开票日期 | 开票履约- | +| 收票 | **收票单推合规成功后**（4.12 推送成功后） | 每条结算分摊行（认领关系行）一条 | 分摊收票金额 | 发票日期 | 收票履约- | + +**与本文操作的对应关系与常见误区**： +- 付款：审批通过后去合规找付款履约记录——**还没有**，属正常；金蝶付款（4.10 第 4 步）后才会出现，计划金额累加也同步此时才推（提示「金蝶未实际付款，待付款后推送履约计划与履约记录」是正常结果说明，不是失败）。特批中的付款不推履约，特批通过同样要等实付。 +- 收款：认领提交后自动推（认领记录 C107-1 + 履约流水）；**作废认领**只在合规侧把认领记录置作废（C107-3），计划金额与履约流水**不回冲**。 +- 开票：4.11 推送金蝶→开票完成回写→下一轮开票任务自动推；金蝶开票结果回写会自动把开票登记重置为待同步，无需人工重推。 +- 收票：收票登记推送金蝶后收票单推合规（C109）→ 成功后按**已认领的分摊行**自动推；未认领结算单的收票单没有分摊行，不生成履约记录（属正常）。 + +**异常与重试**： + +| 场景 | 失败自动重试 | 业务要做什么 | +|---|---|---| +| 付款/开票/收票 | 是（对应扫描任务每 5 分钟） | 一般无需处理；长期失败联系管理员 | +| 收款 | **否**（事件驱动） | 合规侧没数据时联系管理员排查 | + +暂时生成不了的常见原因（按顺序自查，条件满足后自动补推）：合同未推合规 → 履约计划未推成功 → 单据未审批通过 →（开票）金蝶未开票完成 →（收票）收票单未推合规 →（付款）金蝶未实际付款。 + +> 作废/驳回的影响：付款审批驳回不产生记录；付款申请作废、认领作废**不回冲**计划金额与履约记录（认领仅合规侧认领记录作废）；需要金额回退在合规侧人工处理或单独提需求。 + --- -## 4. 定时任务与开关（运维视角） +## 5. 定时任务与开关（运维视角） -### 4.1 任务清单（Nacos `thirdparty.bfi.*` 配置） +### 5.1 任务清单（Nacos `thirdparty.bfi.*` 配置） | 任务 | 干什么 | 开关键 | cron 键（默认值） | 手动替代按钮 | |---|---|---|---|---| @@ -577,7 +1014,7 @@ > 收款认领推送定时任务（原 `receiptClaimPush`）已于 2026-10-29 随 A301-3 链路下线删除；相关 Nacos 配置 `claimAnnounce.*`、`receiptClaimPush.*` 可清理。 -### 4.2 各任务的运转逻辑 +### 5.2 各任务的运转逻辑 **共性规则（先读这个）** @@ -587,53 +1024,122 @@ - **默认执行时间错峰**（付款 ：01、failed 重推 ：05、收票 ：08、锁补偿每 5 分钟的 ：02、票池每 30 分钟的 ：16），互不挤占；自行改 cron 时建议保留错峰。 **① 付款结果回写（10 分钟）** -扫「审批通过且已推送 / 付款中 / 推送失败」的付款申请 → 到金蝶查付款申请单和付款处理单 → 推进 已生成 → 付款中 → **已付款 / 已关闭**，已付款时回写付款记录/凭证，并联动刷新预付结算垫资、结算付款记录（3.8 第 3 步的「正常等定时回写」就是它）。 +扫「审批通过且已推送 / 付款中 / 推送失败」的付款申请 → 到金蝶查付款申请单和付款处理单 → 推进 已生成 → 付款中 → **已付款 / 已关闭**，已付款时回写付款记录/凭证，并联动刷新预付结算垫资、结算付款记录（4.10 第 3 步的「正常等定时回写」就是它）。 - 自愈一（应收勾稽）：已推送但失败、或缺金蝶单号的**应收结算单**，查金蝶有则自动补单号、纠回已同步——「实际推成功但本地显示失败」的场景自动痊愈； -- 自愈二（开票结果）：已受理的开票申请自动落发票信息并推进 **开票完成（终态）**（3.9 第 7 步的定时回写就是它）； +- 自愈二（开票结果）：已受理的开票申请自动落发票信息并推进 **开票完成（终态）**（4.11 第 7 步的定时回写就是它）； - 防呆（金蝶删单）：已生成/付款中的单据**连续 2 轮（约 20 分钟）在金蝶查不到** → 判定金蝶侧已删，自动解锁置生成失败并清空金蝶单号，等人工核实后重推；重推带幂等预检，金蝶单据其实还在时会自动回填，不会重复生成。 **② 收票结果回写（10 分钟）** 扫 已推送（pushed）/ 已指定应付（assigned）的收票登记，按近 **30 天**回看窗口查金蝶收票单，一轮处理三种情况： -- 票在金蝶被作废/红冲 → 置 failed（推送失败）并提示人工处理（**不要重推**，见 3.10）； -- pushed 且**已被付款结算单认领** → 自动补发「指定应付」推进 已指定应付（终态）——**受开关 `…receivedInvoiceResult.assignCompensationEnabled` 控制，默认关闭**：关闭时跳过补发并记日志，由人工入口（发票登记推送/查看页重新推送）指定；pushed 且未被认领 → 跳过不动（认领后由结算单侧接上，见 3.10）； +- 票在金蝶被作废/红冲 → 置 failed（推送失败）并提示人工处理（**不要重推**，见 4.12）； +- pushed 且**已被付款结算单认领** → 自动补发「指定应付」推进 已指定应付（终态）——**受开关 `…receivedInvoiceResult.assignCompensationEnabled` 控制，默认关闭**：关闭时跳过补发并记日志，由人工入口（发票登记推送/查看页重新推送）指定；pushed 且未被认领 → 跳过不动（认领后由结算单侧接上，见 4.12）； - assigned 但缺金蝶收票单号 → 自动补登单号。 窗口内查不到的保持现状不动（不判删除），由人工重推兜底。 **③ 客商同步（每天 02:00）** 一次扫全部审批通过客商，干三件事： - **未推送/推送失败** → 先复查金蝶：已有且已审核的直接置 **exist（终态）**（不重复建档）；金蝶侧审核中则置 failed 提示稍后；确实没有才推送； -- **已推送（synced）** → 金蝶审核通过自动升级 **exist（终态）**（3.1 第 5 步的定时升级就是它）； +- **已推送（synced）** → 金蝶审核通过自动升级 **exist（终态）**（4.1 第 5 步的定时升级就是它）； - **金蝶侧停用（enable=0）** → TMS 档案联动停用；金蝶恢复可用**不会**自动启用（单向联动，需人工启用）。 **④ 全票池同步（30 分钟）** -按近 **30 天**增量窗口分页拉取金蝶全票池发票到本地镜像表（含发票明细行），收票选票、发票明细带出、票池查询全部走本地镜像——所以**刚在金蝶开的票要等同步后才能选到**；急用可让运维手动触发同步端点，或用票号精确搜索（会自动去金蝶现查，见 3.10）。 +按近 **30 天**增量窗口分页拉取金蝶全票池发票到本地镜像表（含发票明细行），收票选票、发票明细带出、票池查询全部走本地镜像——所以**刚在金蝶开的票要等同步后才能选到**；急用可让运维手动触发同步端点，或用票号精确搜索（会自动去金蝶现查，见 4.12）。 **⑤ failed 重推（10 分钟）** 只重推 **failed（推送失败）** 单据（结算 → 付款 → 开票 → 收票四个域依次处理）；**unsynced（审批通过但从未推送）不会自动推**——历史存量单不会被上线后批量补推，仍走手动按钮。前置没就绪（如销方供应商代码缺失、镜像明细缺失）会再次 failed、下轮继续；前置就绪后自动续推成功。 -⚠️ 重推**没有次数上限**：根因不修（联行号缺失、组织编码缺失等）会每 10 分钟失败一次刷日志，修复根因是唯一正解（呼应 4.4）。 +⚠️ 重推**没有次数上限**：根因不修（联行号缺失、组织编码缺失等）会每 10 分钟失败一次刷日志，修复根因是唯一正解（呼应 5.4）。 **⑥ 锁单补偿（5 分钟）** 扫「推送成功但金蝶锁定失败」的锁记录，重试加锁，**最多 5 次**；超过 5 次放弃，需运维调手动补偿端点 `POST /formal-settlement/retry-kingdee-bill-lock`（对应 1.2 的「锁定失败·已达上限」标签）。 -### 4.3 审批自动同步开关（按业务域独立） +### 5.3 审批自动同步开关（按业务域独立） `thirdParty.bfi.autoSync.settlement`（结算单）/ `…payment`（付款）/ `…invoiceApply`（开票）/ `…receipt`（收票），默认全关。**代码默认全部关闭，必须在 Nacos 显式开启**；客商档案审批推送不受此开关控制（始终自动）。 -### 4.4 运维注意 +### 5.4 运维注意 - 所有定时任务带**分布式锁**：多实例部署只跑一份；手动按钮和定时共用锁，定时运行中手动触发会直接跳过（属正常）。 - 开了「failed 重推」后，持续失败的单据每 10 分钟会重试一次，**修复根因**（配置/数据）比反复观察更重要。 - 手动触发全票池同步与定时是同一逻辑，数据量大时耐心等待，不要反复点。 - **A302-6 指定应付补偿开关**默认关闭（安全兜底）：pushed+已认领的收票单不会自动变"已指定应付"，业务用「发票登记」/查看页「重新推送」人工指定；确需自动补偿时在 Nacos 开 `thirdParty.bfi.receivedInvoiceResult.assignCompensationEnabled=true`。 +### 5.5 合同系统（HCS）定时任务与开关（Nacos `thirdParty.hcs.*` 配置） + +HCS 推送由**五个推送定时任务**（各 5 分钟、分钟位 0–4 错峰）、**一个客商风险每日刷新任务**和一组手动接口组成；定时任务、手动接口与审批即时推送共用同一套推送逻辑。 + +| 任务 | 扫描对象 | 推送链路（HCS 接口） | 独立开关（默认 false） | 默认 cron | 手动触发 | +|---|---|---|---|---|---| +| 项目立项 C102 | 审批通过/变更审批通过，待推送/失败未超限 | C102-3 判重 → C102-1 新建 / C102-2 更新 | `push.project.sync-enabled` | `0 */5 * * * ?` | `POST /hcs/sync/project/{id}`、`/hcs/sync/project`、`/batch` | +| 合同 C103 | 同上；**同轮补查特批结果**（仅此任务有） | C101-1 风险 → C103-2 附件 → C103-3 判重 → C103-1 起草 / C103-11 更新 → C103-9 履约规则（开关）→ 高风险挂特批 | `push.contract.sync-enabled` | `0 1/5 * * * ?` | `POST /hcs/sync/contract/{id}`、`/hcs/sync/contract`、`/batch` | +| 付款链 C106/C108 | 审批通过付款申请 | `hcs_spec_status=need` 时 C106-3/4 特批（受 `spec-pay.enabled` 门禁，默认关）→ **金蝶实付门禁** → C103-9 计划重推 → C108 履约记录（开关） | `push.payment.sync-enabled` | `0 2/5 * * * ?` | `POST /hcs/sync/payment/{id}`、`/hcs/sync/payment` | +| 开票登记 C111 | 审批通过开票申请 | C111-1 判重 → C111-2 新增 → C111-3 更新（金蝶开票结果回写后自动重置待同步触发） | `push.invoice-application.sync-enabled` | `0 3/5 * * * ?` | `POST /hcs/sync/invoice-application/{id}`、`/hcs/sync/invoice-application` | +| 收票单 C109 | 审批通过收票单 | C109-1 新建 / C109-2 更新 → 成功后按认领分摊行推履约收票记录 | `push.invoice-receipt.sync-enabled` | `0 4/5 * * * ?` | `POST /hcs/sync/invoice-receipt/{id}`、`/hcs/sync/invoice-receipt` | +| 客商风险刷新 | 期限内生效合同甲乙方客商 | 逐个 C101-1 风险等级 + 批量 A801-5 金蝶黑名单，落库客商档案 | `risk.refresh-enabled`（上线置 true） | `0 30 2 * * ?` | 无手动接口（可临时改 cron 补刷） | + +**公共规则**：扫描条件=审批通过 + 待推送/失败未超限（`push.max-retry` 默认 5，单轮 `push.batch-size` 默认 50 条）；按业务域抢 Redis 锁（TTL 240 秒），多实例只跑一份；单条失败只记该条不拖批次；**手动接口不检查开关、不抢锁**（开关关闭时可临时补推，避免与定时同一时刻执行）。 + +**各任务运转逻辑** + +**① 项目立项任务（C102，每 5 分钟）** +扫「审批通过/变更审批通过 + 待推送/推送失败」的项目立项： +- **无合规项目ID（首推）**：先调 C102-3 按项目编号判重——命中直接回填已有合规ID置已推送（不重复建）；未命中调 C102-1 新建（依赖 `project.template-code`，未配置整条失败），成功后回填合规项目ID。 +- **已有合规项目ID（变更）**：调 C102-2 更新。 +- **金蝶结果回调**（`projectLegal/result`）：HCS 完成金蝶同步后按项目编号定位，成功回填「金蝶项目ID/编号」、失败记原因——**不改合规状态、不触发重推**，所以「已推送但金蝶项目ID空」只代表金蝶同步未完成。 +- 付款额度/开票额度按万元×10000 转元推送，计划保证金仍按万元直传。 + +**② 合同任务（C103，每 5 分钟）** +扫「审批通过/变更审批通过 + 待推送/推送失败」的合同，单条推送依次： +- **特批挂起门禁**：特批中（processing）的合同跳过推送；手动重推报「合同特批审核中，禁止重推」。 +- **客商风险 C101-1 + 金蝶黑名单 A801-5**：甲乙双方逐个查（客商档案匹配不到或内部组织则跳过该方不阻断）；命中只做标记，**不阻断推送**。 +- **附件转传 C103-2**：失败会导致整条推送失败（查下载基址与附件）。 +- **判重/起草/更新**：无合规合同ID先 C103-3 按合同编号判重（命中回填置已推送），未命中 C103-1 起草（报文含业务合同号、归档状态；高风险/黑名单时随报文 `fdSepcailContract=true` 在合规侧发起特批）；已有合规ID走 C103-11 更新（变更、归档即时同步同走此接口）。 +- **履约规则 C103-9**（`exe-stage.sync-enabled`）：按合同「履约规则」页签的行级新增/更新/删除同步；无可同步行自动跳过。失败整条置 failed——因合规ID已先回填，下轮重推走 C103-11 更新补偿，**不会重复起草**。 +- **高风险挂起特批**：风险命中时置特批中、当前节点「特批审核」；合规回调（秒批/秒驳）先到时不覆盖已落地结果。 +- **★特批结果兜底查询（仅本任务有）**：每轮推完待同步合同后，另查「特批中且有合规ID」的合同（最多 50 条），逐条调 C103-4 查详情：合规侧已通过 → 恢复「审批通过」；已驳回 → 合同审批联动「已驳回」；其他状态继续等。手动接口不补查特批结果，需用「确认特批结果」人工兜底。 + +**③ 付款链任务（C106/C108，每 5 分钟）** +扫「审批通过 + 待推送/推送失败」的付款申请： +- **特批发起**（`spec-pay.enabled=true` 时）：待特批（need）且无特批流程ID调 C106-3 发起（依赖 `spec-pay.template-id` 与关联合同的合规ID），已有流程ID调 C106-4 更新；发起成功回填流程ID、置特批中。**开关关闭（当前默认）时整步跳过**。 +- **★金蝶实际付款门禁**：付款审批通过只做**本地履约计划金额累加**；金蝶实付金额为空或 ≤0 时，履约计划与履约记录**都不推送**，整体照常置已推送，结果说明「金蝶未实际付款，待付款后推送履约计划与履约记录」（**正常状态不是失败**）；金蝶付款回写（4.10「已付款」）后自动重新置待同步，下一轮扫描自动续推。 +- **实付后推送**：先 C103-9 重推累加后的付款计划行（按款项性质精确匹配），再推履约记录——无履约记录ID调 C108-1 新建（返回ID立即落库），已有则 C108-2 更新（分期付款推进实际金额，一张申请永远一条记录）。 +- **特批结果**：HCS 回调 `paymentLegal/result` 或人工 `POST /hcs/spec-pay/confirm`——通过恢复「审批通过」并触发金蝶自动同步；驳回置「已驳回」，重新提交后重新发起特批。 + +**④ 开票登记任务（C111，每 5 分钟）** +扫「审批通过 + 待推送/推送失败」的开票申请： +- 无合规ID先 C111-1 按申请编号判重，未命中 C111-2 新增——**必须能经应收结算链路回溯到合同编号**，回溯不到整条失败；币种映射 `invoice.currency-id-mapping` 的 RMB 必配，否则整条失败。 +- 新增成功后若金蝶状态已是开票完成，立即调 C111-3 更新票据日期/状态；已有合规ID同样走 C111-3。 +- **自愈**：金蝶开票结果回写（4.11「开票完成」）会把合规状态自动重置为待推送，下一轮扫描自动执行 C111-3 更新——无需人工重推。 +- 本任务**没有结果回调**，以列表合规状态与失败说明为准。 + +**⑤ 收票单任务（C109，每 5 分钟）** +扫「审批通过 + 待推送/推送失败」的收票登记： +- 无合规ID调 C109-1 新建，成功回填合规ID；已有合规ID调 C109-2 更新。 +- **合同关联回溯**：收票单 → 结算关系（付款结算单认领）→ 正式结算单 → 合同；先票后款下**未认领结算单的收票单回溯不到合同**，取人工补录字段（运维），都没有时合同字段传空只记警告、**不阻断推送**。 +- 推送成功后按**认领分摊行**逐条推履约收票记录（C108-1，每条分摊行一条）；未认领的没有分摊行，不生成履约记录（属正常，见 4.18）。 + +**⑥ 客商风险每日刷新任务（C101-1 + A801-5，每天 02:30）** +- 刷新范围：**合同期限内**（起止或临时期限覆盖当天）且审核通过、未终止合同的甲乙方关联客商；内部组织客商跳过（默认无风险）。 +- 外部客商按 **200/批**：每批调一次 A801-5 金蝶黑名单批量查询 + 逐个调 C101-1 风险等级（该接口仅支持单编号）；结果立即落库客商档案（风险等级、金蝶黑名单类别/事由、查询时间）并留痕校验日志；**批间互不影响，单批失败不中断其余批次**。 +- 该任务**不走推送框架**：不抢推送锁、不改单据合规状态、无手动触发接口；临时补刷可把 `risk.refresh-cron` 改为近时刻执行后改回。 +- 日志按「定时刷新客商风险」检索。 + +**关键业务开关**：`push.immediate-enabled`（项目/合同审批即时推送）；`spec-pay.enabled`（★付款特批走合规，默认 false，见 4.6）；`exe-stage.sync-enabled`（履约计划 C103-9，合同/付款/收款三条链共用）；`perf-record.sync-enabled`（履约记录 C108，默认 false）；`contract.require-risk-check`、`risk.check-on-payment`、`credit.check-enabled`（风险与额度校验）；`attachment.transfer-enabled` + `attachment.file-download-base`（附件转传）；`mock-enabled` 生产必须 false。 + +**运维注意**： +- 开关默认全关、按域灰度打开；**开启扫描前先看存量**——扫描不区分"从未推送/推送失败"，一开所有审批通过且未同步的单据都入队（每轮 50 条）。 +- 失败每 5 分钟自动重试、超 5 次停止；人工重推清零计数，但**修复根因**（模板映射/币种映射/附件基址）才是正解。 +- **付款依赖合同**：付款特批与履约规则都以合同合规ID为前提；履约数据以**金蝶实际付款**为门禁——结果说明「金蝶未实际付款，待付款后推送履约计划与履约记录」是正常状态，不要当失败处理。 +- 开票登记必须配 `invoice.currency-id-mapping` 的 `RMB`，否则每轮失败。 +- 模板映射调整后可调 `POST /hcs/master-data/refresh` 刷新模板/分类/币种缓存并校验映射；日志按单据编号/`hcs` 关键字检索（本地目录 `F:\home\tms\blade-transport`），客商风险刷新按「定时刷新客商风险」检索。 + --- -## 5. 常见问题与异常处理（FAQ） +## 6. 常见问题与异常处理（FAQ） | 现象 | 原因 | 处理 | |---|---|---| | 推送结算单不带汇率 | 结算单没维护汇率（预付结算单的汇率**不自动继承**到付款结算单） | 在结算单编辑页重选汇率日期自动带出后再推 | -| 推送报「客商编码」类错误 | 客商未推送金蝶或档案缺数据 | 先完成客商同步（3.1），再推单据 | +| 推送报「客商编码」类错误 | 客商未推送金蝶或档案缺数据 | 先完成客商同步（4.1），再推单据 | | 推送报「请先同步金蝶应付单/应收单」 | 前置单据未推送 | 顺序：结算单(应付/应收) → 付款/开票（收票登记已不依赖结算单，仅付款结算单指定应付需要应付单先推送） | | 推送报组织/部门编码类错误 | 部门没维护金蝶组织编码 | 管理员补维护后重推 | | 推送报联行号类错误 | 客商收款账户联行号缺失 | 财务补维护收款账户后重推 | @@ -642,36 +1148,49 @@ | 列表「锁定失败」标签 | 推送成功但金蝶锁单接口失败 | 系统自动补偿（≤5 次）；急用让运维调手动补偿端点 | | 单据要改但显示「金蝶锁定中」 | 已推送并被金蝶锁定 | 到金蝶侧解锁/删单 → TMS 自动还原后即可编辑；不可强行作废 | | 付款状态长时间不更新 | 回写定时未开启或金蝶侧未处理 | 点「同步付款结果」；仍无 → 金蝶侧查付款处理单 | -| 付款申请审批通过了，但金蝶那边没有单 | 推送失败（生成失败）或走了付款特批 | 看「金蝶单据状态」：生成失败勾选后点「批量同步」或等 10 分钟自动重推；提示"已发起付款特批"要等特批完成 | +| 付款申请审批通过了，但金蝶那边没有单 | 推送失败（生成失败）或走了付款特批 | 看「金蝶单据状态」：生成失败勾选后点「批量同步」或等 10 分钟自动重推；提示"已发起付款特批"（特批走合规开关开启时）要等特批完成 | | 开票申请已同步但没发票信息 | 开票结果未回写 | 等定时/联系运维手动触发；确认金蝶票易通已开票 | | 票池选票查不到 | 镜像未同步到该票种 | 检查票种白名单配置；运维手动触发全票池同步；票号精确搜索可触发自动现查 | | 保存收票登记被拦「可用金额为0」 | 票已被占用/认领/红冲 | 换票或在金蝶确认票据状态 | -| 收票推送报「供应商代码/往来户」类错误 | 发票销方未建档或未同步金蝶（取不到金蝶供应商代码） | 先完成客商建档与同步（3.1），再重推 | +| 收票推送报「供应商代码/往来户」类错误 | 发票销方未建档或未同步金蝶（取不到金蝶供应商代码） | 先完成客商建档与同步（4.1），再重推 | | 收票推送报免税/零税率行 | 系统无法映射该税率行编码 | 人工核实票面，联系金蝶方约定编码后放开 | | 收票推送报结算组织/平台公司类错误 | 手选部门上溯不到带金蝶编码的平台公司 | 找管理员维护组织金蝶编码后重推 | -| 收票卡在已推送（pushed）不动 | 未被付款结算单认领，或认领它的结算单应付单未推送成功；或已认领但指定失败且自动补偿开关关闭 | 在付款结算单「发票登记」/查看页「重新推送」处理；未认领的先认领；已认领失败的用人工入口重推（3.10） | +| 收票卡在已推送（pushed）不动 | 未被付款结算单认领，或认领它的结算单应付单未推送成功；或已认领但指定失败且自动补偿开关关闭 | 在付款结算单「发票登记」/查看页「重新推送」处理；未认领的先认领；已认领失败的用人工入口重推（4.12） | | 结算单/付款管理「已指定应付」列显示指定失败 | 认领的收票单 A302-6 指定失败 | **悬浮状态标签看聚合失败原因** → 付款结算单查看页对该票「重新推送」（可先改匹配金额），或工具栏「发票登记」重推 | | 认领收票单被拦「一张收票单只能被一张付款结算单认领」 | 已被其他有效付款结算单认领 | 先在原结算单移除认领（金蝶侧人工解除指定）再认领 | -| 为什么选不到某张预付结算单发起预付 | 需要**应付**、**审批通过**、**未转付款结算**、且所选单据**同一合同** | 按 3.3 前提检查 | -| 付款管理工具栏的「预付申请」发起的是哪种预付 | 固定是**进度预付**（配合预付结算单） | **项目预付**要点「新增付款申请」后手动把付款类型选成"项目预付"（3.4） | -| 为什么核销弹窗里找不到那笔项目预付 | 必须与结算单**同一合同**、**审批通过**、**金蝶已付款**、还有**剩余可核销额** | 按 3.5 前提检查 | +| 为什么选不到某张预付结算单发起预付 | 需要**应付**、**审批通过**、**未转付款结算**、且所选单据**同一合同** | 按 4.5 前提检查 | +| 付款管理工具栏的「预付申请」发起的是哪种预付 | 固定是**进度预付**（配合预付结算单） | **项目预付**要点「新增付款申请」后手动把付款类型选成"项目预付"（4.6） | +| 为什么核销弹窗里找不到那笔项目预付 | 必须与结算单**同一合同**、**审批通过**、**金蝶已付款**、还有**剩余可核销额** | 按 4.7 前提检查 | | 为什么新增开票申请时选不到某张收款结算单 | 需要**审批通过、未作废、剩余可开票金额>0**；跨合同不能合并开票 | 已申请开票金额（未作废的占用）会扣减可开票额；部分开票过的单只要还有余额可以再选 | -| 开票提示要先去同步金蝶 | 开票前系统检查金蝶应收单 | 先在「收款结算单」列表点「同步金蝶」（3.7） | +| 开票提示要先去同步金蝶 | 开票前系统检查金蝶应收单 | 先在「收款结算单」列表点「同步金蝶」（4.9） | | 结算单已付金额比我算的多/少 | 已付金额**含**进度预付、项目预付核销；核销金额同时计入"已申请付款金额"和"已付金额" | 属正常口径 | -| 结算单金额写错了怎么改 | 审批通过后不能直接改 | 走「结算调整单」（3.11） | -| 结算调整单选不到某张结算单 | 已完成收付款 / 已发起尾款 / 有关联付款申请在途 / 未审批通过 | 按 3.11 前提检查 | +| 结算单金额写错了怎么改 | 审批通过后不能直接改 | 走「结算调整单」（4.13） | +| 结算调整单选不到某张结算单 | 已完成收付款 / 已发起尾款 / 有关联付款申请在途 / 未审批通过 | 按 4.13 前提检查 | | 结算调整单重推被拦「旧单未冲销」 | 原单已推送金蝶且财务还没在金蝶冲销 | 财务在金蝶手工冲销旧单后再点「重新推送（高危）」（部分冲销视同已冲销） | | 结算调整单重推失败，新单显示同步失败 | 克隆新单已生成但推送金蝶失败 | 再点「重新推送」复用新单续推，不会重复建单；失败原因悬浮看新单 | | 对「已调整」原单发起付款被拦 | 原单已作废（被调整单重推替代） | 使用调整后的新单发起付款 | -| 单据上的「作废」是灰的/没有 | 状态不是审批通过；结算单已同步金蝶；已被金蝶锁定 | 见 3.14 作废前提 | +| 单据上的「作废」是灰的/没有 | 状态不是审批通过；结算单已同步金蝶；已被金蝶锁定 | 见 4.16 作废前提 | | 收款流水同步为空/报组织编码错误 | 组织管理未维护「平台公司」金蝶编码，或窗口内无数据 | 找管理员维护组织金蝶编码；需要更早流水时调大同步窗口天数配置 | | 认领/作废后合规侧没有记录 | 合同合规推送失败（只落标记不重试） | 让运维查合规推送记录失败原因，人工在合规侧补录；认领/作废本身不受影响 | | 想作废认领 | — | 认领记录页本人记录直接「作废」：本地回退金额并自动同步合规作废；金蝶收款单本身不受影响（红冲由金蝶财务人工处置） | | 断网/金蝶宕机期间推了一半 | 部分单据 failed | 恢复后 failed 重推任务（或手动）自动续推，系统查重不会重复生成金蝶单据 | +| 合同审批通过后合规状态一直「待推送」 | 未开即时推送，合同扫描也未开启或未到执行时间 | 手动点「推送合规」；或让运维开启 `push.contract.sync-enabled`（5.5） | +| 合同推送失败提示「合同类别 [xxx] 未配置合规模板ID」 | Nacos 模板映射缺该类别 | 运维补 `contract.template-mapping` 后重推（注意中文键括号写法） | +| 合同「特批审核」节点长时间不动 | HCS 特批结果未回传 | 详情「合规信息」→「确认特批结果」人工确认 approved/rejected（4.3 第四步） | +| 特批中的合同想重推/想改内容 | 特批未结束；已推送合同不能直接编辑 | 不允许重推，等结果；改动走「变更」流程（4.3 第五步） | +| 合同已推送但金蝶合同ID为空 | HCS 金蝶同步有延迟 | 稍后刷新；长期为空联系管理员 | +| 高风险收款方提交付款被拦截 | 未上传「特批附件」 | 附件区新增一行类型选「特批附件」重新提交（**特批开关关闭也拦截**，属客商准入风控） | +| 付款/合同没触发特批但客商明明是高风险 | 客商名称与客商档案不匹配导致风险校验被跳过；或非高风险且未命中金蝶黑名单 | 核对甲乙方/收款方名称与客商档案全称或简称一致（1.8） | +| 客商档案/合同「客商风险」列显示「-」 | 客商不在合同期限内生效合同关联范围，或刚创建未被刷新过 | 等次日 02:30 刷新；当天可在客商表单实时查询（4.17） | +| 金蝶黑名单命中但列表没显示「黑名单」 | 金蝶黑名单类别/事由数据缺失，只显示等级段 | 等次日刷新或联系运维补刷；确认 `risk.refresh-enabled` 已开启 | +| 合规里没有付款履约计划/记录 | 履约数据以**金蝶实际付款**为门禁，未实付不推 | 正常等待金蝶付款回写后自动推（4.18） | +| 合规里没有收款履约记录 | 认领推送失败**不自动重试** | 联系运维查合规推送记录，人工在合规侧补录；认领本身不受影响 | +| 项目审批通过后合规状态「待推送」 | 未开即时推送或项目扫描未开启 | 行内「推送合规」；或运维开 `push.project.sync-enabled`（4.2） | +| 项目推送成功但金蝶项目ID为空 | HCS 金蝶同步结果未回传 | 稍后刷新；长期为空联系管理员 | --- -## 6. 附：操作入口速查表 +## 7. 附：操作入口速查表 | 页面 | 按钮/操作 | 作用 | |---|---|---| @@ -705,7 +1224,16 @@ | 运维专用 | `POST /formal-settlement/sync-kingdee-ar-result` | 手动应收勾稽纠偏 | | 运维专用 | `POST /invoice-application/sync-kingdee-invoice-result` | 手动开票结果回写 | | 运维专用 | `POST /formal-settlement/invoice-assign-kingdee` | 手动触发结算单认领收票单的指定应付 | +| 项目管理 | 行内「推送合规」/工具栏「批量推送合规」 | 推送/重推项目立项到合同合规（C102，4.2） | +| 合同管理 | 行内「推送合规」/工具栏「批量推送合规」 | 推送/重推合同到合同合规（C103，4.3） | +| 合同详情 | 合规信息「确认特批结果」 | 特批中人工确认 approved/rejected（4.3） | +| 合同管理 | 行内「变更」/「附件上传」 | 合同变更更新 HCS（C103-11）；补传附件与归档即时同步（4.3） | +| 客商档案 | 搜索「客商风险」筛选 / 红色标签悬浮 | 按风险筛选客商；看失信类别/列入事由/等级明细（4.17） | +| 运维专用 | `POST /hcs/sync/{bizType}/{id}` | 单条重推（bizType=project/contract/payment/invoice-application/invoice-receipt，不受开关限制） | +| 运维专用 | `POST /hcs/sync/{bizType}`（`/batch` 仅 project、contract） | 按扫描逻辑推一轮 / 按勾选ID批量重推 | +| 运维专用 | `POST /hcs/spec-pay/confirm`、`POST /hcs/contract/spec/confirm` | 人工确认付款/合同特批结果（参数 id、result） | +| 运维专用 | `POST /hcs/master-data/refresh` | 刷新 HCS 模板/分类/币种缓存并校验映射 | --- -> 本文基于 2026-10-14 代码整理；2026-10-19 核对补充定时任务运转逻辑；2026-10-31 按先票后款改造与收款流水 A301-1 改造修订；**2026-11-03 汇总《2026-10-17 结算调整单》《2026-10-18 预付与项目预付》两本操作手册，并按 2026-11-01/11-02 代码修订收票指定应付链路（发票登记工具栏入口、匹配金额可改、查看页重新推送、已指定应付列、A302-6 自动补偿开关默认关闭）**。系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档的更新说明。 +> 本文基于 2026-10-14 代码整理；2026-10-19 核对补充定时任务运转逻辑；2026-10-31 按先票后款改造与收款流水 A301-1 改造修订；2026-11-03 汇总《2026-10-17 结算调整单》《2026-10-18 预付与项目预付》两本操作手册，并按 2026-11-01/11-02 代码修订收票指定应付链路（发票登记工具栏入口、匹配金额可改、查看页重新推送、已指定应付列、A302-6 自动补偿开关默认关闭）；**2026-11-04 合并合同合规系统（HCS）操作内容（项目立项、合同、特批、客商风险、履约计划/记录），并纳入付款特批走合规开关（`thirdParty.hcs.spec-pay.enabled` 默认关闭，2026-11-03）**。系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档与 HCS 手册的更新说明。