diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册.md b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册.md index 808af093..3a4c191b 100644 --- a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册.md +++ b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册.md @@ -1,11 +1,18 @@ # HCS 合同管理操作手册 -> **文档日期**：2026-10-23 +> **文档日期**：2026-10-23（最近更新：2026-11-01） > **适用系统**：运输板块数字化管理平台（TMS） > **适用对象**：合同经办人、合同负责人、合同审批人、合规管理员 > **文档目的**：介绍合同新增、审批、变更、附件归档及 HCS 合规同步的完整操作方法 > **截图说明**：本文截图取自测试环境，合同编号、客商名称、金额等均为测试数据；不同环境因角色权限、功能开关不同，页面按钮和状态可能略有差异，以实际页面为准。 +## 修改记录 + +| 日期 | 修改内容 | +| --- | --- | +| 2026-11-01 | ① 客商黑名单口径调整：黑名单以金蝶黑名单查询（A801-5）命中为准（含失信类别、列入事由），合同合规系统 C101-1 的黑名单状态不再用于展示与筛选；合同列表/详情"客商风险"改为实时关联客商档案组装，红色标签悬浮可查看甲乙双方风险明细（新增 16、17、18 截图）。② 新增客商风险每日定时刷新任务（每天 02:30，`risk.refresh-enabled` / `risk.refresh-cron`），刷新合同期限内生效合同关联客商并落库客商档案（新增 12.7 节）。③ 归档状态即时同步合规：上传"双章归档文件"后即时调 C103-11 更新合规归档状态（fdArchiveStatus=toarchive）并挂载归档附件；未推送合同首次推送报文自带归档状态（更新 9.4 节）。④ 付款链履约数据推送时点调整：金蝶实际付款门禁——未实付时履约计划（C103-9）与履约记录（C108）均不推送，金蝶付款回写后自动推送（同步更新纯操作版 3.11/4.5）。⑤ 合同推送报文新增业务合同号（fdBusContractNumber，=合同编号）与归档状态（fdArchiveStatus）字段；币种映射样例更新为 RMB/CNY→人民币、USD→美元。⑥ 新增 19 项目立项列表、20 付款申请列表截图；常见问题补充 3 条。 | +| 2026-10-23 | 首次整理。 | + --- ## 1. 先了解合同管理与 HCS @@ -29,6 +36,8 @@ | 合规合同ID | 合同成功推送 HCS 后，由 HCS 返回的合同唯一标识 | | 金蝶合同ID | 合同在 HCS 完成合规及金蝶同步后，回写到 TMS 的金蝶合同编号 | | 特批 | 高风险或黑名单客商合同，需经集团特批后才能完成合规流程 | +| 黑名单 | 客商被列入外部（国资委）黑名单，**以金蝶黑名单查询（A801-5）命中为准**，命中记录含失信类别与列入事由；金蝶分 A 类（禁止交易类）和 B 类（风险警示类） | +| 风险等级 | 合同合规系统（HCS）对客商的风险评级：0=低风险、1=中风险、2=高风险 | | 临时合同 | 用于提前生效的合同，审批通过后有 **30 天** 临时效力 | | 正式合同 | 完成正式审批、可长期履约的合同，是 HCS 合规同步与归档的主要对象 | | 合同变更 | 正式合同内容发生变化时发起的变更审批流程 | @@ -38,7 +47,7 @@ - 页面中带 `*` 的字段为必填项；保存草稿时可先填写部分信息，提交临时合同或正式合同前需补全。 - 合同编号可不填写，系统会按合同负责部门配置的规则自动生成；如业务要求手工编号，可直接填写。 - 临时合同审批通过后有效期为 **30 天**（自提交临时合同审批之日起算），到期前应及时转为正式合同。 -- 高风险、黑名单客商合同，**提交审批前必须上传“特批附件”**，否则系统会阻止提交。 +- 高风险、黑名单客商合同，**提交审批前必须上传“特批附件”**，否则系统会阻止提交。黑名单口径见 12.7 节。 - 合同审批通过后，系统会将合同推送 HCS；正式合同与合同变更是合规同步、归档的主要场景。是否自动推送由环境开关决定，也可在页面手动推送。 - 合同已推送 HCS 后，如需修改合同信息，必须走“变更”流程，**不要重复新增合同**，否则会在合规系统产生重复合同。 - 合同列表默认按创建时间倒序排列。 @@ -150,6 +159,7 @@ flowchart TD | 合同阶段 | 草稿 / 临时合同 / 正式合同 / 已终止 | | 审核状态 | 当前审批状态 | | 归档状态 | 未归档 / 已归档 | +| 客商风险 | 甲方/乙方客商的风险等级与黑名单组合展示（如“低风险、黑名单”）；红色标签鼠标悬浮可查看风险明细；数据实时关联客商档案组装 | | 合规状态 | 待推送 / 已推送 / 推送失败；鼠标悬停可查看失败原因 | | 金蝶合同ID | 合规同步完成后回写的金蝶合同编号 | | 当前节点 / 当前处理人 | 当前审批节点及处理人 | @@ -384,10 +394,14 @@ flowchart TD | --- | --- | | 合规同步状态 | 待推送 / 已推送 / 推送失败 | | 合规合同ID | HCS 返回的合同唯一标识 | -| 客商风险 | 是否黑名单、风险等级 | +| 客商风险 | 甲方/乙方客商风险等级与黑名单组合展示（如“高风险、黑名单”）；黑色标签为命中风险，鼠标悬浮可查看明细（失信类别、列入事由、风险等级） | | 特批状态 | 待特批 / 特批中 / 特批通过 / 特批驳回 | | 特批说明 | 特批原因或处理说明 | +![合同列表客商风险悬浮明细](images/18-合同列表-客商风险悬浮.png) + +> 合同列表“客商风险”列：红色标签为高风险/黑名单客商，鼠标悬浮展示甲乙双方风险明细（失信类别、列入事由、风险等级）。 + ### 8.3 用印材料与附件 向下滚动可查看用印材料、计费信息、结算单规则、付款比例设置、附件（佐证材料等）。 @@ -438,6 +452,7 @@ flowchart TD - 上传附件类型为 **双章归档文件** 后，合同归档状态会在审批通过或附件保存后变为“已归档”。 - 双章归档文件属于用印材料，请在“附件位置”中选择“用印材料”。 +- **归档状态即时同步合规**：上传双章归档文件保存后，若合同已推送合规（已有合规合同ID），系统会立即调 C103-11 更新合规侧归档状态为“待归档”（fdArchiveStatus=toarchive），并将归档附件挂载到合规合同的其他附件面板；若合同尚未推送合规，首次推送报文会自带归档状态。合规侧后续的归档流转（归档中/已归档/归档异常）由合规系统自行维护。 --- @@ -513,7 +528,7 @@ flowchart TD | ① 客商风险校验 | 校验甲乙双方是否高风险/黑名单（C101-1） | | ② 附件转传 | 将合同附件转传到合规系统（C103-2） | | ③ 合同判重 | 按合同编号等信息判断合规系统是否已存在（C103-3） | -| ④ 起草 / 更新 | 首次推送起草合同（C103-1）；已有合规合同ID时更新合同（C103-11） | +| ④ 起草 / 更新 | 首次推送起草合同（C103-1）；已有合规合同ID时更新合同（C103-11）。报文含业务合同号（fdBusContractNumber，取值同合同编号）与归档状态（fdArchiveStatus，已上传双章归档文件时传“待归档”） | | ⑤ 履约计划同步 | 同步合同履约计划/履约规则（C103-9），系统自动创建默认履约计划，无需人工维护 | | ⑥ 特批 | 高风险/黑名单客商合同自动进入特批流程 | @@ -569,8 +584,8 @@ flowchart TD 当合同甲方或乙方为外部客商，且命中以下任一情况时，需要走特批流程： -- 客商为黑名单； -- 客商风险等级为高风险。 +- 客商为黑名单（以金蝶黑名单查询 A801-5 命中为准，见 12.7 节）； +- 客商风险等级为高风险（合同合规系统 C101-1 评级）。 ### 12.2 提交前：上传特批附件 @@ -629,6 +644,27 @@ flowchart TD 合同详情页右上角的 **发起特批** 是旧版独立发起入口。当前合规接口已改为随合同推送自动发起特批，正常流程**无需点击该按钮**；点击后如提示接口不存在，不影响合同数据。如特批状态长时间停留在“待特批”，请联系系统管理员重新推送合同。 +### 12.7 客商风险数据与每日刷新 + +合同列表、详情和客商档案展示的“客商风险”来自两个外部系统，每日自动更新到客商档案： + +| 数据 | 来源 | 说明 | +| --- | --- | --- | +| 风险等级 | 合同合规系统（C101-1） | 低风险 / 中风险 / 高风险 | +| 金蝶黑名单 | 金蝶（星瀚）· 国资委黑名单（A801-5） | 命中记录失信类别（A 类禁止交易类 / B 类风险警示类）与列入事由 | + +- **刷新时机**：系统每天凌晨 02:30 自动刷新（合同期限内生效合同的甲乙方关联客商）；当天新增的客商在客商档案表单里有实时风险提示，列表数据次日刷新后生效。 +- **展示口径**：黑名单仅指金蝶黑名单命中；风险等级与黑名单组合展示（等级在前，如“高风险、黑名单”）；内部组织客商不查询风险，默认“无风险”。 +- **悬浮明细**：红色标签（黑名单/高风险）鼠标悬浮可查看明细，格式：`【客商名称】：被列入外部黑名单（失信类别：xx）；列入事由 xx；风险等级：xx`。 + +![客商档案列表客商风险列](images/16-客商档案列表-客商风险.png) + +> 客商档案列表：搜索栏“客商风险”下拉可筛选黑名单/高风险/中风险/低风险；红色标签为命中风险客商。 + +![客商风险悬浮明细](images/17-客商风险悬浮明细.png) + +> 红色标签悬浮明细：失信类别、列入事由、风险等级。 + --- ## 13. 常见问题 @@ -681,6 +717,18 @@ A：说明该合同没有关联外部审批流程实例。请以列表/详情中 A：批量推送只允许“审批通过/变更审批通过”且未同步的合同。请取消勾选不符合条件的合同，或单独对符合条件的合同发起推送。 +**Q13：客商档案/合同列表的“客商风险”列显示“-”是为什么？** + +A：该客商不在任何合同期限内生效合同的关联范围内，尚未被每日刷新任务（每天 02:30）查询过；或客商档案刚创建、数据次日才落库。当天需要确认时，可在客商档案新增/编辑表单填写客商名称，系统会实时查询并显示风险提示。 + +**Q14：客商明明命中了金蝶黑名单，列表为什么只显示风险等级、没有“黑名单”？** + +A：黑名单标签需要金蝶黑名单记录的失信类别/列入事由数据（每日刷新任务落库）。数据缺失时只显示风险等级；等待次日刷新或联系管理员执行刷新后恢复完整展示。 + +**Q15：付款特批通过后，为什么合规系统里迟迟没有履约计划和履约记录？** + +A：付款链的履约数据以金蝶实际付款为门禁：付款审批通过只做本地计划金额累加，**金蝶完成实际付款并回写实付金额后**，系统才自动推送履约计划（C103-9）与履约记录（C108）。实付前属正常等待，不是推送失败。 + --- ## 14. 操作权限速查 diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/01-合同列表.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/01-合同列表.png index 7553fe86..326c01e0 100644 Binary files a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/01-合同列表.png and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/01-合同列表.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/16-客商档案列表-客商风险.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/16-客商档案列表-客商风险.png new file mode 100644 index 00000000..0ee0f7b8 Binary files /dev/null and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/16-客商档案列表-客商风险.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/17-客商风险悬浮明细.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/17-客商风险悬浮明细.png new file mode 100644 index 00000000..7273b7e3 Binary files /dev/null and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/17-客商风险悬浮明细.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/18-合同列表-客商风险悬浮.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/18-合同列表-客商风险悬浮.png new file mode 100644 index 00000000..9c631e7d Binary files /dev/null and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/18-合同列表-客商风险悬浮.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/19-项目立项列表.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/19-项目立项列表.png new file mode 100644 index 00000000..12ef7911 Binary files /dev/null and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/19-项目立项列表.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/20-付款申请列表.png b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/20-付款申请列表.png new file mode 100644 index 00000000..9cf1a6da Binary files /dev/null and b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.assets/20-付款申请列表.png differ diff --git a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.md b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.md index 2f8efae9..bd2cd93a 100644 --- a/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.md +++ b/doc/docs/hcs合同/2026-10-23-HCS合同管理操作手册（纯操作版）.md @@ -1,11 +1,18 @@ # HCS 合同管理操作手册（纯操作版） -> 整理日期：2026-10-23 +> 整理日期：2026-10-23（最近更新：2026-11-01） > 适用对象：合同经办人、合同负责人、合同审批人、合规管理员、实施运维。 > 本文只讲**怎么操作**：在哪个页面、点什么按钮、前提是什么、成功的标志是什么、失败了怎么处理。 -> 第 1–3 节为业务操作（合同、项目立项、付款特批）；第 4 节为实施运维使用的五类 HCS 定时任务逻辑、接口与配置。 +> 第 1–3 节为业务操作（合同、项目立项、付款特批、客商风险）；第 4 节为实施运维使用的定时任务逻辑、接口与配置。 > 完整字段说明、状态字典与流程背景见同目录《2026-10-23-HCS合同管理操作手册》；接口与代码细节见同目录 HCS 相关梳理文档。 +## 修改记录 + +| 日期 | 修改内容 | +|---|---| +| 2026-11-01 | ① 客商黑名单口径调整：黑名单以金蝶黑名单查询（A801-5）命中为准（含失信类别、列入事由），C101-1 黑名单状态不再用于展示与筛选；合同列表/详情“客商风险”改为实时关联客商档案组装，红色标签悬浮查看甲乙双方明细（新增 1.6、3.12 节与截图 16/17/18）。② 新增客商风险每日定时刷新任务（02:30，`risk.refresh-enabled`/`refresh-cron`），第 4 章任务数 5→6。③ 归档状态即时同步合规：上传双章归档文件后即时调 C103-11 传 fdArchiveStatus=toarchive 并挂归档附件（更新 3.9）。④ 付款链履约数据改金蝶实际付款门禁：未实付不推履约计划 C103-9 与履约记录 C108，实付回写后自动推送（更新 3.11、4.5）；付款链履约计划重推纳入 `exe-stage.sync-enabled` 控制。⑤ 合同推送报文新增业务合同号（=合同编号）与归档状态字段；币种映射样例更新。⑥ 常见问题补 3 条。 | +| 2026-10-23 | 首次整理。 | + --- 合同系统 @@ -64,6 +71,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） - 付款申请收款方为高风险/黑名单客商时，提交前必须上传“特批附件”，否则提交被拦截。 - 付款申请审批通过后系统自动发起付款特批；特批中“当前节点”为“特批审核”，特批未通过前不推送履约数据、不同步金蝶。 - 付款特批驳回后付款申请变“已驳回”，修改后重新提交审批会重新发起特批。 +- 上传“双章归档文件”保存后，已推送合规的合同会即时更新 HCS 归档状态（待归档）并挂载归档附件；未推送合同首次推送自带归档状态。 ### 1.5 推送与环境前提 @@ -92,6 +100,20 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） 2. `thirdParty.hcs.spec-pay.template-id` 已配置，付款用途/性质/类型字典值正确。 3. 收款方为高风险/黑名单时，已上传“特批附件”。 +### 1.6 客商风险与黑名单口径 + +客商风险数据来自两个外部系统，每日自动刷新到客商档案（详见 3.12、4.8 节）： + +| 数据 | 来源 | 说明 | +|---|---|---| +| 风险等级 | 合同合规系统（C101-1） | 低风险 / 中风险 / 高风险 | +| 金蝶黑名单 | 金蝶（星瀚）· 国资委黑名单（A801-5） | 命中记录失信类别（A 类禁止交易类 / B 类风险警示类）与列入事由 | + +- **黑名单仅指金蝶黑名单命中**；合同合规系统返回的黑名单状态字段只用于付款提交强制校验，不在列表展示。 +- 合同列表/详情、客商档案的“客商风险”列为等级+黑名单组合展示（等级在前，如“高风险、黑名单”）；红色标签悬浮可查看明细（失信类别、列入事由、风险等级）。 +- 内部组织客商不查询风险，默认“无风险”。 +- 数据每天 02:30 刷新（合同期限内生效合同关联客商）；当天新增客商以表单实时提示为准，列表次日生效。 + --- ## 2. 一次性准备（实施/管理员操作） @@ -102,7 +124,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） | 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→人民币） | 币种传错或为空 | +| 5 | 币种映射 | 运维 | `thirdParty.hcs.contract.currency-name-mapping`（样例：RMB/CNY→人民币、USD→美元） | 币种传错或为空 | | 6 | 风险校验开关 | 运维 | `thirdParty.hcs.contract.require-risk-check` 保持 `true` | 关闭后高风险合同不会触发特批 | | 7 | 履约计划同步 | 运维 | `thirdParty.hcs.exe-stage.sync-enabled`，一期默认 `false` | 不推送 C103-9 履约计划，不影响合同主流程 | | 8 | 推送开关 | 运维 | 按需开启 `push.immediate-enabled`（项目/合同即时）、`push.project/contract/payment.sync-enabled`（定时扫描） | 只能靠手动按钮推送；付款审批即时特批不受 `push.immediate-enabled` 控制 | @@ -112,10 +134,11 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） | 12 | 付款特批模板与字典 | 运维 | `thirdParty.hcs.spec-pay.template-id`、`payment-purpose`、`payment-nature`、`payment-type` | 付款特批发起失败 | | 13 | 付款履约记录 | 运维 | `thirdParty.hcs.perf-record.sync-enabled`（一期默认 `false`）；开启时同时配置 `perf-record.xform-id` | 开启但未配模板ID时履约记录推送失败 | | 14 | 付款额度校验 | 运维 | 如需“超额自动转特批”，开启 `thirdParty.hcs.credit.check-enabled` | 关闭时超额付款不会自动进入特批 | +| 15 | 客商风险每日刷新 | 运维 | `thirdParty.hcs.risk.refresh-enabled` 上线置 `true`（默认 `false`）、`refresh-cron` 默认每天 02:30 | 客商档案/合同列表“客商风险”列无数据或长期不更新 | > 模板映射的中文键在 Nacos YAML 中必须使用括号写法，例如 `"[承运商合同]": "模板ID"`，否则配置无法正确绑定。 > -> 当前 Nacos 样例只映射了“承运商合同”。客户合同、补充协议如果也要推送，必须在上线前逐类确认并补齐映射。 +> 当前 Nacos 样例已映射“承运商合同”“客户合同”。补充协议等其他类别如果也要推送，必须在上线前逐类确认并补齐映射。 --- @@ -242,10 +265,12 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） |---|---| | 合规同步状态 | 待推送 / 已推送 / 推送失败；失败时可悬停查看原因 | | 合规合同ID | HCS 返回的合同唯一标识，推送成功后回填 | -| 客商风险 | 是否黑名单、风险等级 | +| 客商风险 | 甲方/乙方客商等级+黑名单组合展示；红色标签悬浮查看明细（失信类别、列入事由、风险等级），口径见 1.6 | | 特批状态 | 待特批 / 特批中 / 特批通过 / 特批驳回 | | 特批说明 | 特批原因或处理说明 | +![合同列表客商风险列：红色标签悬浮展示甲乙双方风险明细（失信类别、列入事由、风险等级）](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/18-合同列表-客商风险悬浮.png) + **推送成功的判断标准**：合规状态为“已推送”，且“合规合同ID”不为空。 > 金蝶合同ID由 HCS 完成金蝶同步后回写，可能存在延迟；暂时为空可稍后刷新列表查看。“已推送”只代表 HCS 已受理，不代表特批和金蝶同步已经完成。 @@ -382,6 +407,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） - 上传附件类型为 **双章归档文件**，且附件位置选择“用印材料”时，合同审批通过或附件保存后归档状态变为 **已归档**。 - 其他附件类型不会改变归档状态。 +- **即时同步合规**：双章归档文件保存后，已推送合规的合同会立即调 C103-11 更新合规侧归档状态为“待归档”（fdArchiveStatus=toarchive）并挂载归档附件；尚未推送的合同在首次推送报文中自带归档状态。合规侧后续归档流转由合规系统自行维护。 ![合同详情附件区：可查看、下载用印材料和佐证材料](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/07-合同详情-附件佐证材料.png) @@ -477,7 +503,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） | 提示 | 含义 | 后续 | |---|---|---| -| 审批通过，已发起付款特批，特批通过后将自动推送履约数据并同步金蝶 | 特批已发起 | 列表“当前节点”显示“特批审核”，等待结果 | +| 审批通过，已发起付款特批，特批通过后将自动推送履约数据并同步金蝶 | 特批已发起 | 列表“当前节点”显示“特批审核”，等待结果；履约数据在金蝶实际付款后才推送（见“特批通过后”） | | 审批通过，付款特批待发起，可在详情页重推合规 | 特批尚未发起（并发跳过或前置条件不满足） | 当前页面没有重推按钮；联系实施检查模板、合同合规ID后重推 | | 审批通过，但发起付款特批/推送合规失败：xxx，可稍后重推合规 | 审批已生效，特批发起或推送失败 | 按原因修复后联系实施重推，**不要重复审批** | | 审批通过，已同步金蝶：xxx / 审批通过，但自动同步金蝶失败：xxx | 未走特批，直接同步金蝶的结果 | 金蝶失败按提示原因处理 | @@ -497,8 +523,8 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS） **特批通过后：** -1. 当前节点恢复“审批通过”。 -2. 系统自动补推履约计划（C103-9）和履约记录（C108，若开启），并自动同步金蝶。 +1. 当前节点恢复“审批通过”，系统自动同步金蝶付款申请。 +2. **金蝶实际付款后**，系统才自动推送履约计划（C103-9，受 `exe-stage.sync-enabled` 控制）和履约记录（C108，若开启）：付款审批通过只做本地计划金额累加，未实付时推送结果提示“金蝶未实际付款，待付款后推送履约计划与履约记录”，属正常等待，不是推送失败。 3. 金蝶单据号、金蝶单据状态稍后回填，可刷新列表查看。 **特批驳回后：** @@ -525,25 +551,56 @@ HCS 正常情况下通过 `paymentLegal/result` 回传结果。长时间停留 任一条件不满足时，审批仍会成功，但特批发起失败；按审批提示或日志修复后重推。 +### 3.12 客商档案客商风险（查看与筛选） + +**页面：客商管理 → 客商档案（`/vehicle/customer-archive`）** + +客商风险数据每天 02:30 自动刷新（合同期限内生效合同的甲乙方关联客商），供客商档案展示、筛选，以及合同/付款环节风险管控使用。 + +![客商档案列表：展开搜索后可见“客商风险”下拉筛选，列表客商风险列为等级+黑名单组合标签](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/16-客商档案列表-客商风险.png) + +**查看规则：** + +| 客商情况 | 显示 | 颜色 | +|---|---|---| +| 等级 + 黑名单命中（组合展示，等级在前） | 高风险、黑名单 / 中风险、黑名单 / 低风险、黑名单 | 红 | +| 仅黑名单命中（无等级数据） | 黑名单 | 红 | +| 仅高风险 | 高风险 | 红 | +| 中风险 | 中风险 | 黄 | +| 低风险 | 低风险 | 绿 | +| 内部组织客商 | 无风险（默认，不查询） | 绿 | +| 尚未查询到数据 | - | — | + +**操作：** + +1. 筛选：搜索栏点 **展开**，“客商风险”下拉选黑名单/高风险/中风险/低风险后点 **查询**。 +2. 查明细：红色标签 **鼠标悬浮**，展示失信类别、列入事由、风险等级。 +3. 当天新增客商：在新增/编辑客商表单填写客商名称后失焦，系统实时查询并在名称下方显示红色风险提示（悬浮见明细）；列表落库数据次日刷新后生效。 + +![客商风险悬浮明细：被列入外部黑名单（失信类别、列入事由）与风险等级](./2026-10-23-HCS合同管理操作手册（纯操作版）.assets/17-客商风险悬浮明细.png) + +> 合同列表“客商风险”列与本页同口径，实时关联客商档案组装（见 3.5 节截图）。数据未刷新或金蝶黑名单类别/事由缺失时只显示等级段，等待次日刷新或联系运维执行刷新。 + --- ## 4. 定时任务与接口（运维视角） -HCS 推送由五个独立定时任务和一组手动接口组成。五个任务各有自己的开关与 cron，互不影响；定时任务、手动接口和审批即时推送共用同一套推送逻辑。 +HCS 推送由五个推送定时任务、一个客商风险每日刷新任务和一组手动接口组成。五个推送任务各有自己的开关与 cron，互不影响；定时任务、手动接口和审批即时推送共用同一套推送逻辑。客商风险刷新任务独立于推送框架（不抢推送锁、不走合规状态回写），详见 4.8。 -### 4.1 五类定时任务总览 +### 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` | +| 合同 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` | +| 客商风险刷新（C101-1 + A801-5） | — | 合同期限内生效合同的甲乙方关联客商 | 逐个 C101-1 风险等级 + 批量 A801-5 金蝶黑名单，落库客商档案 | `risk.refresh-enabled`（默认 `false`） | `0 30 2 * * ?` | 无手动接口（可临时改 cron 或调 `refreshCustomerRiskForActiveContracts()`） | -> - **即时推送**：项目立项、合同审批通过后立即推送（受 `push.immediate-enabled` 控制）；付款申请审批通过后立即发起特批/推送履约数据（**不受**该开关控制）；开票登记、收票单没有即时推送，只能靠定时扫描或手动接口。 -> - 五个扫描开关默认全部 `false`，按业务灰度打开；手动接口不受开关限制。 -> - 只有合同扫描任务额外承担“特批结果兜底查询”，其他任务没有这个动作。 +> - **即时推送**：项目立项、合同审批通过后立即推送（受 `push.immediate-enabled` 控制）；付款申请审批通过后立即发起付款特批/推送合规（**不受**该开关控制，但履约计划与履约记录要等金蝶实际付款后才推送）；开票登记、收票单没有即时推送，只能靠定时扫描或手动接口。 +> - 五个推送扫描开关默认全部 `false`，按业务灰度打开；客商风险刷新开关 `risk.refresh-enabled` 同样默认 `false`（上线需置 `true`）；手动接口不受推送开关限制。 +> - 只有合同扫描任务额外承担“特批结果兜底查询”，其他推送任务没有这个动作。 ### 4.2 公共执行框架 @@ -592,10 +649,10 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 **推送逻辑**： 1. **特批挂起门禁**：`hcs_spec_status=processing` 的合同跳过推送，等待特批结果；手动重推直接报“合同特批审核中，禁止重推”。 -2. **客商风险 C101-1**（`contract.require-risk-check=true`）：甲乙双方分别查询；客商档案匹配不到或为内部组织时跳过该方，不阻断；任一方高风险或黑名单只做标记，**不阻断推送**，推送成功后自动转特批。 +2. **客商风险 C101-1**（`contract.require-risk-check=true`）：甲乙双方分别查询；客商档案匹配不到或为内部组织时跳过该方，不阻断；任一方高风险（C101-1 评级）或金蝶黑名单命中（A801-5，`HcsCreditCheckSupport` 公共判定）只做标记，**不阻断推送**，推送成功后自动转特批。 3. **附件转传 C103-2**（`attachment.transfer-enabled=true`）：附件转传失败会导致整次推送失败。 -4. **首次推送**：无合规合同ID时先调 C103-3 判重（`fdNumber=合同编号`）；命中直接回填已有ID并置已推送，未命中调 C103-1 起草；起草成功后立即回填合规合同ID，再继续后续步骤。 -5. **变更推送**：已有合规合同ID时调 C103-11 更新。 +4. **首次推送**：无合规合同ID时先调 C103-3 判重（`fdNumber=合同编号`）；命中直接回填已有ID并置已推送，未命中调 C103-1 起草；起草成功后立即回填合规合同ID，再继续后续步骤。报文含业务合同号（`fdBusContractNumber`，取值同合同编号）与归档状态（`fdArchiveStatus`，已上传双章归档文件时传 `toarchive` 待归档）。 +5. **变更推送**：已有合规合同ID时调 C103-11 更新，报文同样携带业务合同号与归档状态；已推送合同上传双章归档文件后也会即时单独触发一次 C103-11 归档状态更新（见 3.9 节）。 6. **履约规则 C103-9**（`exe-stage.sync-enabled=true`）：按履约计划行级新增/更新/删除；无可同步行时返回“履约规则无待同步行”；同步失败会把整条合同置 `failed`。由于第 4 步已先回填合规ID，下一轮重推会走 C103-11 更新，不会重复起草。 7. **高风险挂起特批**：风险命中时置 `hcs_spec_status=processing`、当前节点“特批审核”，等待 HCS 特批结果。 @@ -628,9 +685,10 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 **推送逻辑**： 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`）的付款也可能显示已推送。 +2. **金蝶实际付款门禁**：付款审批通过只做本地计划金额累加，`paid_amount` 为空或 ≤0 时履约计划与履约记录均不推送，整体照常回写 `synced`，结果说明为“金蝶未实际付款，待付款后推送履约计划与履约记录”；金蝶付款回写推进后会重新置待同步，由扫描任务自动触发再次推送。 +3. 关联合同已推送合规（合同 `hcs_fd_id` 非空）且通过实付门禁时，调 C103-9 重推履约规则；无待同步行自动跳过。该动作受 `exe-stage.sync-enabled` 控制，与合同链、收款链一致。 +4. `perf-record.sync-enabled=false`：直接置整体 `synced` 结束；`true`：无履约记录ID调 C108-1 新建，已有调 C108-2 更新。 +5. 整体合规状态 `synced` 只代表本轮推送完成，**不代表特批已通过、也不代表已实际付款**；特批中（`processing`）或未实付的付款也可能显示已推送。 **特批结果**：HCS 通过 `paymentLegal/result` 回调，或用 `/hcs/spec-pay/confirm` 人工确认。通过后恢复“审批通过”并重新触发金蝶自动同步；驳回后付款审批状态置 `returned`（已驳回），需修改后重新提交审批、重新发起特批。 @@ -686,7 +744,22 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | `POST /hcs/sync/invoice-receipt/{id}` | 单条重推 | 仅 `approved` 可推；先重置 `unsynced`、失败次数清零 | | `POST /hcs/sync/invoice-receipt` | 按扫描逻辑推一轮 | 不检查开关、不抢任务锁；**无批量 ID 接口** | -### 4.8 配置项 +### 4.8 客商风险每日刷新任务（C101-1 + A801-5） + +**任务类**：`CustomerRiskRefreshTask`；**开关**：`risk.refresh-enabled`（默认 `false`，上线需置 `true`）；**调度**：`risk.refresh-cron`（默认 `0 30 2 * * ?`，每天 02:30，错开金蝶客商同步 02:00）。 + +**刷新范围**：合同期限内（起止日期或临时期限覆盖当天）且审核通过、未终止的合同，其甲乙方关联客商；内部组织客商跳过（默认无风险）。 + +**执行逻辑**： + +1. 一次 SQL 取期限内生效合同的甲乙方名称，按名称反查客商档案。 +2. 外部客商按 **200/批**：每批调一次 A801-5 金蝶黑名单批量查询 + 逐个调 C101-1 风险等级查询（该接口仅支持单编号）。 +3. 批内结果立即落库 `blade_customer_archive`（`hcs_risk_level`、`kingdee_black_status`、`hcs_risk_time`、`kingdee_black_category`、`kingdee_black_reason`）并留痕 `blade_hcs_check_log`；**批间互不影响，单批失败不中断其余批次**。 +4. 该任务不走推送框架：不抢推送任务锁、不改单据合规状态、无手动触发接口；临时补刷可把 `refresh-cron` 改为近时刻执行后改回，或调用 `HcsCreditCheckSupport#refreshCustomerRiskForActiveContracts()`。 + +**结果用途**：客商档案/合同列表“客商风险”列展示与筛选、红色标签悬浮明细、合同推送与付款提交的风险判定数据源。查询逐次留痕，日志关键字“定时刷新客商风险”。 + +### 4.9 配置项 > 下表键名省略公共前缀 `thirdParty.hcs.`。例如 `push.immediate-enabled` 的完整键为 `thirdParty.hcs.push.immediate-enabled`。 @@ -708,7 +781,7 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | `attachment.file-download-base` | 空 | TMS 文件下载基址 | 有附件时转传失败 | | `master-data.ttl-minutes` | `120` | 模板/分类/币种缓存时长 | 主数据变更最长延迟 120 分钟生效 | -**五个任务开关与 cron** +**五个推送任务与风险刷新开关、cron** | 任务 | 开关（默认） | cron 键 | 默认 cron | |---|---|---|---| @@ -717,16 +790,17 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | 付款链 | `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 * * * ?` | +| 客商风险刷新 | `risk.refresh-enabled`（`false`，上线置 `true`） | `risk.refresh-cron` | `0 30 2 * * ?` | -> 五个开关默认全关，按业务灰度打开；cron 不配置时使用代码默认值（每 5 分钟，分钟位 0–4 错峰）。 +> 五个推送开关默认全关，按业务灰度打开；客商风险刷新上线需单独开启。推送 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.template-mapping` | 样例含 `[承运商合同]`、`[客户合同]` | 合同 C103-1 | 合同类别未映射必失败；中文键必须写成 `"[承运商合同]"` | +| `contract.currency-name-mapping` | `RMB`/`CNY`→人民币，`USD`→美元 | 合同 C103-1 | 币种传错或为空；上线前与合规方确认取值 | | `contract.require-risk-check` | `true` | 合同 C101-1 | 关闭后不做风险校验，高风险合同不会触发特批 | | `exe-stage.sync-enabled` | `false` | 合同 C103-9 | 关闭时合同任务不推履约规则 | | `exe-stage.fund-type` | `byAmount` | 合同 C103-9 | 金额类型传错会被合规校验拒绝 | @@ -745,20 +819,22 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 > 不同环境样例中的币种名称映射可能不同（`CNY` 与 `人民币`），上线前必须与合规方确认 HCS 主数据实际取值。 -### 4.9 运维注意 +### 4.10 运维注意 -- **开关灰度**：五个扫描开关默认全关且互相独立；项目立项/合同的即时推送受 `push.immediate-enabled` 控制，付款审批即时特批不受该开关控制；手动接口始终可用，不受开关限制。 +- **开关灰度**：五个推送扫描开关默认全关且互相独立；项目立项/合同的即时推送受 `push.immediate-enabled` 控制，付款审批即时特批不受该开关控制；客商风险刷新开关 `risk.refresh-enabled` 上线需单独置 `true`；手动接口始终可用，不受推送开关限制。 - **先看存量再开扫描**：扫描不区分“从未推送”和“推送失败”，开关一开，所有审批通过且未同步的历史单据都会进入扫描范围（每轮最多 50 条）。上线前先确认待推送数据量。 - **修复根因优先**：失败单据每 5 分钟自动重试，达到 `push.max-retry`（默认 5）后停止；人工重推会清零次数，但不修复配置/数据会反复失败。 - **付款依赖合同**：C106-3 要求关联合同已有合规合同ID，C103-9 也以合同 `hcs_fd_id` 为前提；合同未推送合规时付款特批/履约规则相关步骤会失败或跳过。 +- **付款履约数据看实付**：付款链履约计划/履约记录以金蝶实际付款为门禁，未实付时整体状态照常回写 `synced`，不要把“金蝶未实际付款，待付款后推送…”当失败处理。 +- **客商风险刷新依赖合同范围**：刷新范围是合同期限内生效合同的关联客商，期限外客商风险列显示“-”属正常；金蝶黑名单类别/事由来自 A801-5，缺失时列表只显示等级段。客商黑名单与风险等级专项说明见《2026-10-30-客商黑名单与风险等级运维手册（运维侧）》（doc/docs/业务流程/）。 - **开票必配币种映射**：`invoice.currency-id-mapping` 的 `RMB` 必须配置为 HCS 币种 fdId，否则开票登记每轮都会失败。 - **收票合同关联**：回溯不到合同且未人工补录 `hcs_contract_id` / `hcs_contract_no` 时不会失败，但合同字段为空；需要完整合同信息时先补录再重推。 -- **模板映射逐个类别确认**：样例只配了承运商合同；客户合同、补充协议未配置时推送必失败。Nacos YAML 中文键必须写成 `"[承运商合同]"`。 +- **模板映射逐个类别确认**：样例只配了承运商合同、客户合同；补充协议未配置时推送必失败。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`。 +- **日志排查**：服务日志按单据编号、合规ID、`hcs` 关键字检索；客商风险刷新日志按“定时刷新客商风险”检索；本地日志目录为 `F:\home\tms\blade-transport`。 --- @@ -775,7 +851,7 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | 提示“合同类别 [xxx] 未配置合规模板ID” | Nacos 模板映射缺该类合同 | 运维补齐 `contract.template-mapping` 后重推 | | 提示附件转传失败 | 下载基址为空、附件不可下载、文件超限或 HCS 附件接口异常 | 检查 `attachment.file-download-base` 和附件，修正后重推 | | 提示 C101-1 客商风险查询失败 | HCS 风险接口异常/无响应 | 联系 HCS 侧确认接口，恢复后重推 | -| 高风险客商没有触发特批 | 客商名称与档案不匹配导致风险校验被跳过，或 HCS 返回的风险等级不是高风险/黑名单 | 核对甲乙方名称与客商档案；在 HCS 侧确认客商风险等级和黑名单状态 | +| 高风险客商没有触发特批 | 客商名称与档案不匹配导致风险校验被跳过，或风险等级不是高风险且未命中金蝶黑名单 | 核对甲乙方名称与客商档案；黑名单以金蝶黑名单命中（A801-5）为准，核对客商档案金蝶黑名单字段与 HCS 风险等级 | | 提示 C103-1/C103-11 合同发起/更新失败 | HCS 业务校验不通过 | 按返回 msg 修正模板、字段或主数据后重推 | | 特批状态一直是“待特批” | 存量数据或推送未成功，未进入特批流程 | 联系管理员重新推送；推送成功后会自动转“特批中” | | 特批中想重推 | 特批流程未结束 | 不允许重推，等待 HCS 回传或人工确认结果 | @@ -799,6 +875,9 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | 付款审批提示“已发起付款特批”但迟迟没有金蝶单据 | 特批仍在审批，特批通过后才同步金蝶 | 等待特批结果；长时间无结果联系实施人工确认 | | 付款特批发起失败（模板未配/合同未推送） | `spec-pay.template-id` 为空或关联合同无合规ID | 运维修复后重推；不要重复审批 | | 付款特批中能否重复审批 | 特批中审核状态已是“审批通过” | 不需要也不能重复审批；等待 HCS 结果 | +| 客商档案/合同列表“客商风险”列显示“-” | 客商不在合同期限内生效合同关联范围，或档案刚创建未被每日刷新任务查询过 | 等次日 02:30 刷新；当天可在客商表单按名称实时查询风险提示 | +| 客商命中金蝶黑名单但列表没有“黑名单” | 黑名单展示依赖金蝶记录的失信类别/列入事由（每日刷新落库），数据缺失时只显示等级段 | 等待次日刷新或联系运维执行刷新；确认 `risk.refresh-enabled` 已开启 | +| 付款特批通过后合规里没有履约计划/履约记录 | 付款链履约数据以金蝶实际付款为门禁，未实付不推送 | 正常等待金蝶付款回写后自动推送；整体状态显示“金蝶未实际付款，待付款后推送履约计划与履约记录”属正常 | --- @@ -825,6 +904,8 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 | 付款申请表单 | 附件类型“特批附件” | 高风险/黑名单收款方提交前必传 | | 付款申请列表 | 行内“通过” | 审批通过后自动发起付款特批 | | 付款申请列表 | “当前节点”列 | 查看“特批审核/审批通过/已驳回”判断特批进度 | +| 客商档案列表 | 搜索栏“客商风险”筛选 | 按黑名单/高风险/中风险/低风险筛选客商（数据每日 02:30 刷新） | +| 客商档案列表 | 客商风险列红色标签悬浮 | 查看失信类别、列入事由、风险等级明细 | | 运维专用 | `POST /hcs/sync/project/{id}` | 单条重推项目立项 | | 运维专用 | `POST /hcs/sync/project/batch` | 按勾选ID批量重推项目立项 | | 运维专用 | `POST /hcs/spec-pay/confirm` | 人工确认付款特批结果（参数 `id`、`result`；页面无按钮） | @@ -838,4 +919,4 @@ HCS 推送由五个独立定时任务和一组手动接口组成。五个任务 --- -> 本文基于 2026-10-23 代码与页面现状整理；按钮、提示和环境开关以实际页面为准。临时合同推送、旧版“发起特批”入口、变更页“终止合同”未开放属于当前版本现状，后续版本调整时请同步核对。 +> 本文基于 2026-10-23 代码与页面现状整理，2026-11-01 按最新实现更新（客商风险口径、归档即时同步、付款履约实付门禁、客商风险刷新任务）；按钮、提示和环境开关以实际页面为准。临时合同推送、旧版“发起特批”入口、变更页“终止合同”未开放属于当前版本现状，后续版本调整时请同步核对。 diff --git a/doc/docs/hcs合同/images/01-合同列表.png b/doc/docs/hcs合同/images/01-合同列表.png index 7553fe86..326c01e0 100644 Binary files a/doc/docs/hcs合同/images/01-合同列表.png and b/doc/docs/hcs合同/images/01-合同列表.png differ diff --git a/doc/docs/hcs合同/images/16-客商档案列表-客商风险.png b/doc/docs/hcs合同/images/16-客商档案列表-客商风险.png new file mode 100644 index 00000000..0ee0f7b8 Binary files /dev/null and b/doc/docs/hcs合同/images/16-客商档案列表-客商风险.png differ diff --git a/doc/docs/hcs合同/images/17-客商风险悬浮明细.png b/doc/docs/hcs合同/images/17-客商风险悬浮明细.png new file mode 100644 index 00000000..7273b7e3 Binary files /dev/null and b/doc/docs/hcs合同/images/17-客商风险悬浮明细.png differ diff --git a/doc/docs/hcs合同/images/18-合同列表-客商风险悬浮.png b/doc/docs/hcs合同/images/18-合同列表-客商风险悬浮.png new file mode 100644 index 00000000..9c631e7d Binary files /dev/null and b/doc/docs/hcs合同/images/18-合同列表-客商风险悬浮.png differ diff --git a/doc/docs/hcs合同/images/19-项目立项列表.png b/doc/docs/hcs合同/images/19-项目立项列表.png new file mode 100644 index 00000000..12ef7911 Binary files /dev/null and b/doc/docs/hcs合同/images/19-项目立项列表.png differ diff --git a/doc/docs/hcs合同/images/20-付款申请列表.png b/doc/docs/hcs合同/images/20-付款申请列表.png new file mode 100644 index 00000000..9cf1a6da Binary files /dev/null and b/doc/docs/hcs合同/images/20-付款申请列表.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-2-公告同步对照.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-2-公告同步对照.png deleted file mode 100644 index 4b16d08d..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-2-公告同步对照.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-认领推送对照.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-认领推送对照.png deleted file mode 100644 index 2ecd50fa..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-认领推送对照.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-金蝶认领结果.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-金蝶认领结果.png deleted file mode 100644 index 022c9a96..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-金蝶认领结果.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-a301-1-收款流水列表.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-a301-1-收款流水列表.png new file mode 100644 index 00000000..c663dc22 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-a301-1-收款流水列表.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-付款结算单发票登记.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-付款结算单发票登记.png new file mode 100644 index 00000000..b5402258 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-付款结算单发票登记.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记列表.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记列表.png new file mode 100644 index 00000000..740654da Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记列表.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记表单.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记表单.png new file mode 100644 index 00000000..dba51689 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记表单.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-客商供应商编码.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-客商供应商编码.png new file mode 100644 index 00000000..c231ebf1 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-客商供应商编码.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-认领记录页.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-认领记录页.png new file mode 100644 index 00000000..1b51c52e Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-认领记录页.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md index 6eeac324..72a7b3e6 100644 --- a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md +++ b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md @@ -1,23 +1,30 @@ # 金蝶（星瀚）BFI 全链路梳理：前端入口 → 后端链路 → 定时任务（业务域汇总 + 操作手册） -> 整理日期：2026-10-14 -> 代码基线：`tms-api` 当前 master（`805ca9d3`，2026-10-13），全量按当前代码重新核实（上一版总纲基线为 09-24 `50573e7`）。 +> 整理日期：2026-10-14（2026-10-31 修订） +> 代码基线：`tms-api` 分支 feature/20261031-bfi-收票收款改造（`933fb37d`，2026-10-31）。 > 本文替代《2026-09-27-金蝶（星瀚）BFI接口调用全链路梳理（按业务域汇总·更新版）》作为新总纲： > - **组织方式改为三层**：每个业务域按「前端入口（页面/按钮）→ 后端链路（触发/顺序/口径/落库）→ 定时任务」梳理； -> - 新增**操作手册**（第 11 节）：按业务时序给出端到端操作步骤与异常处理操作； -> - 自 09-27 以来代码有 40+ 提交（09-28～10-13），**收票回写缺陷已修、调试残留已清、新增锁单/解锁、审批自动同步、failed 重推、票池镜像读回切、全票池定时同步、A801-5 黑名单、A801-2/A902 附件接线、收款认领重构**等，接口清单、分录口径、状态机均有实质变化，全文按当前代码重写。 +> - 新增**操作手册**（第 11 节）：按业务时序给出端到端操作步骤与异常处理操作。 + +## 修改记录 + +| 日期 | 代码基线 | 修订内容 | +|---|---|---| +| 2026-10-14 | master `805ca9d3`（10-13） | 初版总纲，替代 09-27 版；全量按代码重写 | +| 2026-10-15 | master | 增补（更新要点、入参映射表交叉引用等） | +| 2026-10-31 | feature/20261031-bfi-收票收款改造 `933fb37d`（10-31） | ① **第 5 节收票域整体重写**：收票登记改「先票后款」两段式（收票登记只推 A303-2 终态 pushed、A302-6 指定应付移到付款结算单侧，A303-2 报文按发票明细行组装、往来户=销方供应商代码、结算组织页面手选、币别固定 CNY）；② **第 6 节收款认领整体重写**：数据源 A301-2→A301-1，A301-2/A301-3 推送链路与定时任务整体下线，认领只登记本地并推送合同合规（C103-9/C107-1/C108-1，作废推 C107-3）；③ **2 节客商域**：新增 A901-1 供应商编码查询落库、A905-3 行名行号查询（收款账户联行号带出/保存校验）；④ **3 节付款域**：金蝶实际付款（A103-2 paid 回写）后才推送 HCS 付款履约计划/履约记录；⑤ 1.2 接口清单、1.3 防重键、8 全景、9 状态机、10 定时任务、11 操作手册、12 风险清单同步更新；⑥ 补充 TMS 侧新页面截图（收票登记先票后款表单、付款结算单发票登记、收款流水 A301-1 列表、认领记录、客商供应商编码），下线 A301-2/A301-3 金蝶侧旧效果截图 | --- ## 目录 -- [0. 本次更新要点（09-27 → 10-14）](#0-本次更新要点09-27--10-14) +- [0. 本次更新要点（10-14 → 10-31 与 09-27 → 10-14）](#0-本次更新要点10-14--10-31-与-09-27--10-14) - [1. 集成总览与公共机制](#1-集成总览与公共机制) -- [2. 业务域一：客商档案（A902-1 / A902-2 / A801-5 黑名单）](#2-业务域一客商档案a902-1--a902-2--a801-5-黑名单) +- [2. 业务域一：客商档案（A902-1 / A902-2 / A901-1 供应商 / A905-3 行名行号 / A801-5 黑名单）](#2-业务域一客商档案a902-1--a902-2--a901-1-供应商--a905-3-行名行号--a801-5-黑名单) - [3. 业务域二：财务应付与付款（A102-2 / A102-4 / A103-1 / A103-3 / A103-2 / A103-4）](#3-业务域二财务应付与付款) - [4. 业务域三：财务应收与开票（A302-2 / A302-4 / A303-4 / A303-1 / A303-5）](#4-业务域三财务应收与开票) -- [5. 业务域四：收票与金蝶票池（A801-1 / A303-2 / A302-6 / A801-3 / A801-2 / A902 附件）](#5-业务域四收票与金蝶票池) -- [6. 业务域五：收款认领（A301-2 / A301-3 / A301-1）](#6-业务域五收款认领a301-2--a301-3--a301-1) +- [5. 业务域四：收票与金蝶票池（先票后款两段式）](#5-业务域四收票与金蝶票池先票后款两段式) +- [6. 业务域五：收款流水与认领（A301-1 数据源 + 合同合规推送）](#6-业务域五收款流水与认领a301-1-数据源--合同合规推送) - [7. 业务域六：公共取数（A801-4 汇率）](#7-业务域六公共取数a801-4-汇率) - [8. 全景：接口依赖与先后顺序](#8-全景接口依赖与先后顺序) - [9. 状态机汇总](#9-状态机汇总) @@ -27,7 +34,22 @@ --- -## 0. 本次更新要点（09-27 → 10-14） +## 0. 本次更新要点（10-14 → 10-31 与 09-27 → 10-14） + +### 0.1 本次更新要点（10-14 → 10-31，本次修订） + +| # | 变化 | 说明 | +|---|---|---| +| 1 | **★★收票登记改「先票后款」两段式（禅道 #15850）** | 收票登记不再关联结算单/合同：从票池选票 → 手选结算组织（承办部门）→ 推 A303-2 生成金蝶收票单即**终态 pushed**（删除 A102-4 应付预检与推送时立即 A302-6）；A302-6 指定应付移到**付款结算单侧**——结算单编辑/发票登记认领收票单（候选=审批通过+未认领，全额认领），A102-2 应付单推送成功后逐单指定；A801-3「指定补偿」升级为重试引擎（pushed+已认领→补发 A302-6；未认领→跳过不置 failed）。专项文档：`2026-10-31-先票后款改造方案V2….md` | +| 2 | **★A303-2 报文按先票后款重写** | 主表：往来户=发票销方的金蝶供应商代码（登记时尽力回填、推送前强校验，取自客商档案 `supplier_code`）；结算组织=页面手选部门沿部门树上溯平台公司金蝶组织编码；币别固定 CNY。分录：**逐行取票池镜像发票明细**（商品编码=物料/税收分类编码、"V+整数税率"、单价统一 4 位小数、分录候选键=发票号码_seq） | +| 3 | **★全额认领放开匹配合计上限、收票状态按覆盖判定** | 结算单认领收票单不再校验「发票匹配合计≤结算金额」；结算单收票状态按 `已匹配金额 ≥ 结算金额` 判 completed（覆盖即完成，允许超额） | +| 4 | **★★收款认领链路整体下线 A301-3，数据源 A301-2→A301-1** | 收款流水菜单数据源改为 **A301-1 收款单查询**（手动同步，窗口默认 60 天，全公司口径）；认领只登记本地（额度上限=收款金额 actrecamt），**不再推送金蝶**；认领事务提交后推合同合规 C103-9→C107-1→C108-1，作废推 C107-3；`ReceiptClaimPushTask` 定时、`/push-kingdee`、`/query-kingdee-result` 端点、A301-2 公告同步全部删除。专项文档：`2026-10-29-收款流水菜单改造….md`、`2026-10-29-收款流水认领操作流程….md` | +| 5 | **★A901-1 供应商查询启用** | `bd_supplier/query` 按统一社会信用代码查金蝶供应商编码：客商新增/金蝶同步复查回填 `supplier_code`，手动端点 `GET /customer-archive/query-supplier-code`；先票后款 A303-2 往来户取值的数据前提 | +| 6 | **★A905-3 行名行号查询启用** | `bd_bebank/query`：客商收款信息开户行失焦按行名精确匹配带出联行号（`GET /customer-archive/query-bank`）；保存前按行号反查校验（`GET /customer-archive/query-bank-by-number`，查不到拦截保存） | +| 7 | **★金蝶实际付款后才推 HCS 付款履约计划/记录** | A103-2 回写付款推进（paid 金额变化）时置付款申请 `hcsSyncStatus=unsynced`，由 HCS 推送任务在**金蝶实付门禁**（paidAmount>0）通过后推 C103-9/C108-1（`HcsPaymentSyncSupport`）；合同链首推时点不变 | +| 8 | **收票域辅助端点** | `GET /invoice-receipt/invoice-detail-query?invoiceNo=`（表单带出发票明细，镜像缺明细时按票号回源）；`GET /invoice-receipt/claim-candidates?keyword=`（付款结算单选收票单候选，审批通过+未被认领，limit 200）；`POST /formal-settlement/invoice-assign-kingdee`（发票登记保存后手动触发指定应付） | + +### 0.2 历史更新要点（09-27 → 10-14，初版总纲） | # | 变化 | 说明 | |---|---|---| @@ -66,14 +88,14 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） 金蝶星瀚 /ierp/kapi/... 反向：金蝶删单 ──▶ POST /blade-transport/kingdee-bfi/unLockNotifyBusiData（免登 skip-url） -定时：blade-transport task/ 包 7 个任务（Spring @Scheduled，全库无 PowerJob/XxlJob 接线） +定时：blade-transport task/ 包金蝶相关任务 5 类（Spring @Scheduled，全库无 PowerJob/XxlJob 接线） ``` - 无 Feign 重试（NEVER_RETRY）、无 fallback；失败抛 `BfiException`，批量循环逐条 catch，单条失败不中断整批。 - 令牌：Redis `blade:third:bfi:token`，TTL=expires_in−120s；`setIfAbsent` 写入（已有缓存不覆盖）。 - 配置前缀两套并存（读同一批 Nacos 键）：bfi-api `third-party.bfi.*`（baseUrl/认证/令牌），transport `thirdparty.bfi.*`（业务开关/口径/映射）。样例：`doc/nacos/third-party-api.yaml`。 -### 1.2 接口清单总表（2026-10-14，含在用状态） +### 1.2 接口清单总表（2026-10-31，含在用状态） 来源：`blade-bfi-api/.../feign/IBfiClient.java`（URL 可被 `thirdParty.bfi.*Url` 覆盖）。 @@ -81,35 +103,37 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） |---|---|---|---| | A100-1 | POST /ierp/kapi/oauth2/getToken | 获取令牌 | ✅ 自动（每次调用前） | | A100-2 / A100-3 | verifyToken / withdrawToken | 校验/撤回令牌 | ❌ 已实现无调用 | -| A102-2 | POST …/awrp/ap/ap_finapbill/save | 财务应付单保存 | ✅ 正式结算单（应付）推送 | -| A102-4 | GET …/awrp/ap/ap_finapbill/query | 财务应付单查询 | ✅ 预检 / 硬校验 / 批量预热 | +| A901-1 | POST …/basedata/bd_supplier/query | 供应商查询 | ✅ **10-28 新增启用**：按信用代码查金蝶供应商编码（客商建档/同步复查回填 supplier_code、手动端点 query-supplier-code） | +| A905-3 | POST …/basedata/bd_bebank/query | 行名行号查询 | ✅ **10-31 新增启用**：客商收款信息开户行带出联行号 + 保存前按行号校验 | +| A102-2 | POST …/awrp/ap/ap_finapbill/save | 财务应付单保存 | ✅ 正式结算单（应付=付款结算单）推送；推送成功后触发本单认领收票单的 A302-6 指定 | +| A102-4 | GET …/awrp/ap/ap_finapbill/query | 财务应付单查询 | ✅ 付款申请硬校验 / 预检 / 批量预热；**收票链路已不再依赖**（先票后款删除 A102-4 预检） | | A103-1 | POST …/awrp/ap/ap/ap_finapbill/push | 应付下推生成付款申请 | ✅ 付款申请推送（单分录） | -| A103-2 | GET …/awrp/ap/ap_payapply/query | 付款申请单查询 | ✅ 推送预检 + 状态回写 + 消失解锁计数 | +| A103-2 | GET …/awrp/ap/ap_payapply/query | 付款申请单查询 | ✅ 推送预检 + 状态回写 + 消失解锁计数；paid 回写后触发 HCS 付款履约计划/记录推送（金蝶实付门禁） | | A103-3 | POST …/awrp/ap/ap/ap_payapply/save | 预付款申请保存 | ✅ 预付款直推 | | A103-4 | GET …/awrp/cas/cas_paybill/query | 付款处理查询 | ✅ 付款记录回写（含 voucher_json） | -| A301-1 | GET …/awrp/cas/cas_recbill/queryRecBill | 收款单查询 | ✅ 认领结果回写（手动） | -| A301-2 | GET …/awrp/cas/cas_claimannounce/query | 收款认领公告查询 | ✅ 流水同步（手动 + 定时认领推送前置重查） | -| A301-3 | POST …/awrp/cas/cas/cas_claimbill/claimbillPush | 收款认领结果推送 | ✅ 定时 + 手动双入口，按流水归集 | +| A301-1 | GET …/awrp/cas/cas_recbill/queryRecBill | 收款单查询 | ✅ **角色变更**：收款流水菜单数据源（手动同步，窗口默认 60 天）；原「认领结果回写」用途随 A301-3 下线作废 | +| A301-2 | GET …/awrp/cas/cas_claimannounce/query | 收款认领公告查询 | ❌ **10-29 下线**（数据源改 A301-1；代码与 `claimAnnounce.*` 配置已删除） | +| A301-3 | POST …/awrp/cas/cas/cas_claimbill/claimbillPush | 收款认领结果推送 | ❌ **10-29 下线**（认领只登记本地+推合同合规；`ReceiptClaimPushTask`、`/push-kingdee` 已删除） | | A302-2 | POST …/awrp/ar/ar_finarbill/save | 财务应收单保存 | ✅ 正式结算单（应收）推送 | | A302-4 | GET …/awrp/ar/ar_finarbill/query | 财务应收单查询 | ✅ 预检 / 硬校验 / 定时勾稽纠偏 | -| A302-6 | POST …/awrp/ap/ap/ap_invoice/assign | 收票指定应付 | ✅ 收票推送第二步 | +| A302-6 | POST …/awrp/ap/ap/ap_invoice/assign | 收票指定应付 | ✅ **触发方变更**：由付款结算单侧执行（A102-2 推送成功后逐单指定 / 发票登记推送 / 手动端点 invoice-assign-kingdee / A801-3 指定补偿）；收票登记推送链不再调用 | | A303-1 | POST …/awrp/sim/sim_original_bill/save | 开票申请单新增 | ✅ 按发票张次逐张推送 | -| A303-2 | POST …/awrp/ap/ap_invoice/cusBatchSave | 收票单批量保存 | ✅ 收票登记推送 | +| A303-2 | POST …/awrp/ap/ap_invoice/cusBatchSave | 收票单批量保存 | ✅ 收票登记推送（**先票后款**：报文按发票明细行组装，终态 pushed） | | A303-4 | GET …/awrp/sim/sim_original_bill/query | 开票申请单查询 | ✅ 批量 billno 幂等预检 / 附件补传反查星瀚内码 | | A303-5 | POST /ierp/kapi/app/sim/openApi | 开票发票查询（票易通） | ✅ 定时回写开票结果 | -| A801-1 | POST …/awrp/rim/rim_invoice/query | 全票池发票查询（rim 契约） | ✅ 定时全量同步 + 票号回源 + 保存/认领闸门 + 附件回源 | -| A801-2 | POST …/awrp/bosext/attachment/download | 进项发票文件下载 | ✅ **已接线**：附件查看/下载流式代理 | -| A801-3 | GET …/awrp/ap/ap_invoice/apinvoicequery | 收票单查询 | ✅ 推送预检 + 定时回写（防重键已修复=登记 id） | +| A801-1 | POST …/awrp/rim/rim_invoice/query | 全票池发票查询（rim 契约） | ✅ 定时全量同步 + 票号回源 + 保存/认领闸门 + 附件回源 + **发票明细带出（items_json，先票后款分录取数来源）** | +| A801-2 | POST …/awrp/bosext/attachment/download | 进项发票文件下载 | ✅ 已接线：附件查看/下载流式代理 | +| A801-3 | GET …/awrp/ap/ap_invoice/apinvoicequery | 收票单查询 | ✅ 推送预检 + 定时回写（防重键=登记 id）；「指定补偿」升级为重试引擎（pushed+已认领→补发 A302-6） | | A801-4 | GET …/awrp/base/bd_exrate_tree/Forexquery | 汇率查询 | ✅ 结算页面取汇率 | -| A801-5 | POST …/awrp/bdm/bdm_blacklist_config/blacklistquery | 黑名单查询 | ✅ **新增启用**：客商提审校验 | -| A902 | POST /ierp/kapi/v2/frame/attachment/uploadFile | 附件上传 | ✅ **已接线**：4 条推送链路联带上传 | +| A801-5 | POST …/awrp/bdm/bdm_blacklist_config/blacklistquery | 黑名单查询 | ✅ 客商提审校验 | +| A902 | POST /ierp/kapi/v2/frame/attachment/uploadFile | 附件上传 | ✅ 已接线：4 条推送链路联带上传 | | — | POST /API_lockAction_Router | lockBusiData 单据锁定 | ✅ 推送成功后锁单（{updateCount,updateResultList} 应答） | | — | （回调）POST /kingdee-bfi/unLockNotifyBusiData | 解锁/删单通知（unLockNotifyBusiData） | ✅ 金蝶回调本系统（免登放行） | -> 仍未实现：A901-1 供应商查询、A913 项目、A101-1/2 合同、A102-1/A302-1 暂估单（合同/项目走合同合规系统）。 -> 查询时间窗约束：A103-2/A103-4/A102-4/A302-4/A303-4/A301-1 ≤ 1 个月；A902-1 ≤ 6 个月；A301-2 无时间窗参数（按认领人+分页，时间窗口取 `thirdParty.bfi.claimAnnounce.months` 默认 6）。 +> 仍未实现：A913 项目、A101-1/2 合同、A102-1/A302-1 暂估单（合同/项目走合同合规系统）；A901-1 已实现（查询回填，无推送）。 +> 查询时间窗约束：A103-2/A103-4/A102-4/A302-4/A303-4/A301-1 ≤ 1 个月（A301-1 同步按业务日期窗口切片拉取，窗口总天数取 `thirdParty.bfi.recBillSync.days` 默认 60）；A301-2/A301-3 已下线。 -### 1.3 防重键（候选键）总表（2026-10-14 口径） +### 1.3 防重键（候选键）总表（2026-10-31 口径） 金蝶侧按「来源系统 + 来源单据号」幂等（`awrp_src_sys` + `awrp_src_code`）。组装：`ExternalSrcCodeSupport.buildSrcCode`（下划线拼接、去空白、去重保序）。 @@ -120,11 +144,13 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） | 付款申请 A103-1 | `paymentNo` | 配置 `0KzXs` | 固定 `paymentNo-1`（单分录）；勾稽键 `awrp_finapbill_entryid`=主结算单应付防重键（本地组装） | A103-2 | | 预付款申请 A103-3 | 付款申请号口径 | `0KzXs` | `paymentNo-1` | A103-2 | | 开票申请 A303-1 | billno：单张=`application_no`，多张=`application_no-张次序号`；`awrp_src_con_no`=首张结算单应收防重键 | `0KzXs` | 开票商品行 id | A303-4（批量 billno） | -| 收票单 A303-2 | **收票登记 id** | TMS收票登记 | 与 A102-2 分录同源同口径 | A801-3（预检与回写同键） | -| 收款认领 A301-3 | **分摊结算单号下划线拼接**（重试复用同一编码）★改 | WLTMS | 单条：seq/e_corebillno=第一张结算单**金蝶内码** | A301-1（sourcebillnumber 匹配） | +| 收票单 A303-2 | **收票登记 id** | TMS收票登记 | 先票后款：逐行镜像明细，`awrp_entry_code`=发票号码_seq（重推幂等） | A801-3（预检与回写同键） | +| ~~收款认领 A301-3~~ | ~~分摊结算单号下划线拼接~~ | WLTMS | — | **10-29 下线**：认领只登记本地+推合同合规，不再推送金蝶 | | 客户 A902-2 | `number`=TMS 客商编号（KS+6位）；`societycreditcode` 为金蝶侧候选键 | awrp_datasourcesys=WLTMS | — | A902-1 | -### 1.4 公共档案取数（应付/应收/收票复用 `KingdeeApBillSyncSupport`） +### 1.4 公共档案取数（应付/应收复用 `KingdeeApBillSyncSupport`；收票先票后款另见第 5.3 节） + +> ★收票 A303-2 先票后款改造后不再复用「结算明细拆分」口径：往来户=销方供应商代码（`supplier_code`，A901-1 落库）、结算组织=页面手选部门派生、币别固定 CNY、分录=镜像发票明细行（详见 5.3）。下表为应付/应收（A102-2/A302-2）共用口径。 | 取数项 | 规则（当前代码） | |---|---| @@ -186,22 +212,31 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） --- -## 2. 业务域一：客商档案（A902-1 / A902-2 / A801-5 黑名单） +## 2. 业务域一：客商档案（A902-1 / A902-2 / A901-1 供应商 / A905-3 行名行号 / A801-5 黑名单） -**定位**：全局数据前提。其他链路的往来户编码（`customer_code`）来自 `blade_customer_archive`；金蝶客户编码 = TMS 客商编号。 +**定位**：全局数据前提。其他链路的往来户编码（`customer_code`）与先票后款销方供应商代码（`supplier_code`）均来自 `blade_customer_archive`；金蝶客户编码 = TMS 客商编号。 ### 2.1 前端入口 | 页面 | 操作 | 后端端点 | 触发时机 | |---|---|---|---| -| 客商档案（`/vehicle/customer-archive`） | 新增/编辑表单录统一社会信用代码（满 18 位防抖） | `GET /bfi/customer/query-by-credit-code`（A902-1） | 回填名称/法人/地址/经营范围等并锁定；金蝶状态 A/B 阻断保存 | +| 客商档案（`/vehicle/customer-archive`） | 新增/编辑表单录统一社会信用代码（满 18 位防抖） | `GET /bfi/customer/query-by-credit-code`（A902-1） | 回填名称/法人/地址/经营范围等并锁定；金蝶状态 A/B 阻断保存；**同时按信用代码查金蝶供应商编码回填 `supplier_code`（A901-1）** | +| 同上 | 表单「供应商编码」字段 | `GET /customer-archive/query-supplier-code?creditCode=`（A901-1） | 修改信用代码后即时回显金蝶供应商编码（只读展示，系统自动获取） | +| 同上 | 收款信息「开户行」失焦 | `GET /customer-archive/query-bank?bankName=`（A905-3） | 行名精确匹配金蝶行名行号档案，**带出联行号** | +| 同上 | 收款信息保存前校验 | `GET /customer-archive/query-bank-by-number?cnapsCode=`（A905-3） | 按联行号反查金蝶行名行号档案，查不到拦截保存（接口异常上抛，与「查不到」区分） | | 同上 | 行内「同步金蝶」链接（仅 approved 且 failed 显示） | `POST /customer-archive/sync-kingdee`（A902-2） | 失败人工重推 | | 同上 | 行内「审批通过」 | `POST /customer-archive/approve` → 内部 `syncKingdee(id)` | **提审校验 A801-5 黑名单；通过后自动推送 A902-2** | +![客商档案表单：基础信息含「供应商编码」字段（金蝶供应商编码，系统自动获取，A901-1 按信用代码回填）；收款信息 tab 维护开户行/联行号（A905-3 行名带出、保存前校验）](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-客商供应商编码.png) + ### 2.2 后端链路 **A902-1 客户查询（3 入口）**：前端回填 / 单条推送前复查（`syncKingdee` 先查一次，C→exist 终态、A/B→failed）/ 定时批量复查（50 信用代码/批翻页取全）。 +**A901-1 供应商查询（★10-28 新增）**：`CustomerArchiveServiceImpl.queryKingdeeSupplierNumber` 按「统一社会信用代码 + enable=启用」调 `bd_supplier/query` 取金蝶供应商 `number`。落库三个入口：① 客商新增建档（提交前）；② 金蝶同步复查回填（`fillSupplierCode`，查到才覆盖）；③ 手动端点 `GET /customer-archive/query-supplier-code?creditCode=`（前端修改信用代码后即时回显）。查不到/异常返回 null 不阻断——该字段是**先票后款 A303-2 往来户的数据前提**（收票登记销方供应商代码按销方名称匹配本地客商档案 `supplier_code`）。 + +**A905-3 行名行号查询（★10-31 新增）**：`bd_bebank/query` 查金蝶行名行号档案。两个端点：`GET /customer-archive/query-bank?bankName=`（已审核+启用档案按行名查，pageSize=10，本地全称精确比对取第一条，**失焦带出联行号**，异常返回 null）；`GET /customer-archive/query-bank-by-number?cnapsCode=`（按行号精确比对，**保存前校验**，查不到返回 null 由前端拦截保存、接口异常直接上抛）。后端保存仅校验联行号非空/长度，真实性校验由前端调此接口完成。 + **A801-5 黑名单（★新增，提审拦截）**：`CustomerArchiveServiceImpl.submitApproval` → 取客商各发票 `taxNo` 去重大写 → `queryBlacklist("1", taxNos)`（enable=1，pageSize 上限 2000，循环翻页取全）→ **A 类硬拦截**；B 类默认放行告警（`thirdparty.bfi.blacklist.blockRiskWarning=true` 时拦截）；其他类别放行告警；**查询异常上抛阻断提审**。 **A902-2 客户保存（3 入口收敛 `pushCustomerToKingdee`）**：审批通过自动（失败不影响审批）/ 人工重推（synced/exist 幂等返回）/ 定时重推（pending=approved 且 none/failed）。先 A902-1 复查（金蝶已有 C 直接置 exist 跳过）再保存。只推新增建档（审批后变更不重推）。参数要点：`entry_groupstandard` 按 `customerKind` internal→1101 / 其余→1102；`entry_bank` 取 `blade_customer_receipt_account`（账号/开户行/CNY/默认 + **真实联行号 cnaps_code**，硬编码已删）；`bizfunction` 固定 `1,2,3,4`。 @@ -265,6 +300,7 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） ![预付款对照：TMS 进度预付申请（240.12）下推金蝶生成「其他付款申请」FKSQ-00000219（进项货付款申请），分录预付款金额、往来户、结算方式对应；附件区可见 A902 联带上传的文件](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a103-3-预付款对照.png) - **A103-2 回写状态映射**：`Alreadypay`→paid（终）＞`billstatus=D`→closed（终）＞`Inpayment`→paying＞其余 synced；`entry[].e_paidamt` 汇总→paid_amount（缺失且 paid 兜底=申请金额）；paid 联动履约（预结算垫资/结算付款记录）；**failed 纳入勾稽纠偏**（查到即纠正 synced）；**查不到→消失解锁计数**（仅已生成/付款中参与，连续 2 轮→解锁置 failed）。 +- **★HCS 付款履约计划/记录改金蝶实付后推送（10-31）**：A103-2 回写付款推进（首次付款或 paid 金额变化）时将付款申请 `hcs_sync_status` 置回 unsynced，由 HCS 推送任务重新编排；`HcsPaymentSyncSupport` 内置**金蝶实付门禁**——`paidAmount<=0` 直接跳过标记 synced，`paidAmount>0` 才推 C103-9 付款履约计划与 C108-1/2 履约记录（原「未付款跳过履约记录」分支合并为统一门禁）。合同链履约计划首推时点不变；收款认领链的 C103-9 累加的是收款计划行，与本门禁互不影响。 - **A103-4 付款记录**：按付款组织编码分组查询（`org_number` 优先取 A103-2 返回值），窗口最近 1 个月，`sourcebillid`==kingdee_bill_id 优先、`sourcebillnumber` 兜底；upsert `blade_payment_application_record`（actpayamt/paid_date/整单 JSON→voucher_json）；清理 MOCK-PAY- 模拟记录。 - **A902 附件**：推送成功事务提交后联带上传（`KingdeeAttachmentSyncSupport.syncUserAttachments`），失败不污染主单状态，重推补传。 - **异常落库**：手动/自动同步失败统一独立事务落 `failed` + 原因（截 500 字），由「手动重推/failed 重推任务」续推。 @@ -311,33 +347,47 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） --- -## 5. 业务域四：收票与金蝶票池 +## 5. 业务域四：收票与金蝶票池（先票后款两段式） -### 5.1 架构现状（★10-05 回切后终态） +> ★10-31 先票后款改造（禅道 #15850）：收票登记拆分为纯「收票」动作（不关联结算单/合同，推 A303-2 即终点）；「发票跟结算单的指定」移到**付款结算单**侧完成（认领收票单 → 应付单生成后 A302-6 指定应付）。方案细节见《2026-10-31-先票后款改造方案V2（收票登记A303-2+付款结算单A102-2+A302-6指定应付·实现流程与逻辑）》。 + +### 5.1 架构现状（★10-31 先票后款改造后终态） ``` 【数据面】InvoiceReceiptKingdeeSyncTask 定时（默认关，每30分钟） A801-1 全票池增量同步（incrementDays=30）→ invoiceTypes 白名单下推远端逐票种切片轮询 - → 2.5 万窗口硬上限触顶二分时间片递归 → 镜像 blade_kingdee_invoice_pool 批量 upsert（无变化跳写） + → 2.5 万窗口硬上限触顶二分时间片递归 → 镜像 blade_kingdee_invoice_pool 批量 upsert（含 items_json 明细，无变化跳写） → refreshBoundReceipts：未绑定存量登记补绑（已绑定零写入） 手动端点：POST /invoice-receipt/sync-invoice-pool（同一方法+同一把锁） -【选票面】收票登记表单 / 结算单认领弹窗（KingdeeInvoicePoolDialog） - GET /invoice-receipt/invoice-pool、GET /formal-settlement/invoice-pool - → 本地镜像真分页；仅「票号精确查 + 无认领/登记过滤 + 本地空页」时窄查 A801-1 回源一次再本地重查 +【选票面】 + GET /invoice-receipt/invoice-pool 收票登记选票弹窗：本地镜像真分页；仅「票号精确查+无过滤+本地空页」窄查 A801-1 回源 + GET /invoice-receipt/invoice-detail-query ★新增 选票后带出发票明细行（镜像 items_json 优先，缺则按票号回源，仍无走票池窄查） + GET /invoice-receipt/claim-candidates ★新增 付款结算单「选择收票单」候选：审批通过+未被有效应付结算单认领，keyword 模糊，limit 200 行过滤：票号非空 + amountUseStatus=0 + availableAmount>0 -【闸门】收票登记保存 persistMirrorFromRemote（按票号精确单查+可用性复核+FOR UPDATE upsert） - 结算单认领确认 assertInvoicesClaimable（★10-05 补上：逐票窄查+可用复核，红冲/作废/被占用在此拦截） +【先票——收票登记】（不关联结算单/合同） + 选票 → 表单带出票面+明细 → 手选结算组织（承办部门）→ 保存草稿（销方供应商代码尽力回填 queryCustomerCode） + → 提交审批 → 审批通过（receipt 开关自动 / 工具栏「批量同步」手动） + → 前置校验：审批通过 + assigned 不重推 + 已绑镜像（checkStatus=2）+ 镜像明细齐备（缺则回源）+ 结算组织必选 + （★删除原 A102-4 应付预检与「恰好分摊 1 张应付结算单」要求） + → A303-2 收票单保存 → 终态【pushed】→ A902 附件联带上传；缺票种编码按票号窄查 A801-1 补填 -【推送链】审批通过自动推送（receipt 开关）/ 工具栏「批量同步」 - A102-4 预检（应付已生成）→ A801-3 幂等预检（防重键=收票登记 id） - → A303-2 收票单保存（付款方式固定现购）→ pushed → A302-6 指定应付 → assigned（终态） - → A902 附件联带上传；缺票种编码按票号窄查 A801-1 补填 +【后款——付款结算单（正式结算单应付 Tab）】 + 路径A 编辑器/新增：发票信息「选择收票单」（claim-candidates）→ 全额认领（匹配金额=发票全额， + ★放开「发票匹配合计≤结算金额」上限校验） + 路径B 审批后：列表行内「发票登记」→ 选收票单保存认领 → 弹窗「是否将发票匹配数据推送金蝶?」→ 确认调 A302-6 + 关系同步：rebuildInvoices / claimInvoices → syncSettlementReceiptRelations + （按发票号匹配审批通过收票登记 + 一票一结算单校验 + 重建 InvoiceReceiptSettlement + 刷新结算单收票状态） + 结算单审批通过 → A102-2 应付单推送成功 → assignClaimedReceipts：本单认领且收票单 pushed 的逐单 A302-6 → assigned（终态） + （未推送/已指定跳过；单笔失败仅记日志不阻断结算同步） + 手动端点：POST /formal-settlement/invoice-assign-kingdee（前置 payable+approved+synced） -【回写面】PaymentKingdeeResultTask.syncKingdeeReceivedInvoiceResult（默认关，每10分钟）/ 手动端点 - A801-3 按「收票登记 id」匹配（★缺陷已修）→ 发票状态异常回收置 failed - / pushed 补偿重发 A302-6 / assigned 缺单号补登；窗口内查不到不改状态 +【回写面】PaymentKingdeeResultTask.syncKingdeeReceivedInvoiceResult（独立开关，每10分钟）/ 手动端点 + A801-3 按「收票登记 id」匹配 → 发票状态异常（作废2/红冲3/部分红冲7/全部红冲8）回收置 failed + → pushed+已认领（应付防重键恰好可组装）→ 补发 A302-6 → assigned（★指定补偿升级为重试引擎） + → pushed+未认领 → 跳过不再置 failed（认领后由结算单侧补指定） + → assigned 缺单号补登；窗口内查不到不改状态 【附件面】GET /invoice-receipt/invoice-pool/attachment/download?invoiceNo=（A801-2 流式代理） 镜像优先、实时回源兜底；pdfurl 优先 taxPdfUrl 兜底，都缺退 downloadUrl（fileType=4 判 OFD） @@ -348,78 +398,114 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） | 页面 | 操作 | 后端端点 | 说明 | |---|---|---|---| | 收票登记（`/payment/invoice-receipt`） | 工具栏「批量同步」 | `POST /invoice-receipt/push-kingdee`（ids） | 单笔失败不中断整批，逐单报因 | -| 收票登记表单 | 发票号码放大镜（选票弹窗） | `GET /invoice-receipt/invoice-pool` | 镜像分页 + 回源；确认/保存前防重校验 | -| 收票登记表单 | 附件 查看/下载 | `GET /invoice-receipt/invoice-receipt/invoice-pool/attachment/download`（A801-2 代理） | 120s blob；PDF 优先 | +| 收票登记表单 | 发票号码放大镜（选票弹窗） | `GET /invoice-receipt/invoice-pool` | 镜像分页 + 回源；保存前防重校验 | +| 收票登记表单 | 选票后自动带出「发票明细」区块 | `GET /invoice-receipt/invoice-detail-query?invoiceNo=` | A303-2 分录取数预览（货物名称/数量/单价/金额/税率/商品编码） | +| 收票登记表单 | 手选「结算组织（合同承办部门）」必填 | 部门树选择 | 推送时沿部门树上溯平台公司取金蝶组织编码 | +| 收票登记表单 | 「结算信息」区 | 无调用（只读） | 展示认领关系：「暂无认领数据（认领关系由付款结算单侧维护）」 | | 收票登记 | 行内「审批通过」 | `POST /invoice-receipt/approve` | receipt 开关开启时自动推送 | -| 正式结算单编辑器 | 发票认领区「查询可认领发票」/「确认识领」 | `GET /formal-settlement/invoice-pool`、`POST /formal-settlement/claim-invoices` | 确认时走认领闸门；未保存单仅本地暂存 | -| 共享弹窗 `KingdeeInvoicePoolDialog` | 行附件 查看/下载 | 同 A801-2 代理 | 票池弹窗、结算认领行、付款申请发票附件行、收票附件表 4 处复用 | +| 收票登记 | 附件 查看/下载 | `GET /invoice-receipt/invoice-pool/attachment/download`（A801-2 代理） | 120s blob；PDF 优先 | +| 付款结算单编辑器（应付） | 发票信息「选择收票单」 | `GET /invoice-receipt/claim-candidates` + `POST /formal-settlement/claim-invoices` | 候选=审批通过+未认领收票登记；**全额认领**（匹配金额=发票金额，不校验合计上限）；保存同步收票侧关系 | +| 付款结算单列表 | 行内「发票登记」（审批通过行） | `POST /formal-settlement/claim-invoices` + `POST /formal-settlement/invoice-assign-kingdee` | 认领收票单 → 弹窗确认推送指定应付 | +| 共享弹窗 `KingdeeInvoicePoolDialog` | 行附件 查看/下载 | 同 A801-2 代理 | 票池弹窗、付款申请发票附件行、收票附件表等复用 | -### 5.3 后端要点 +![收票登记表单（先票后款改造后）：发票号码从金蝶票据池选票带出票面；新增「结算组织（合同承办部门）」手选必填；「发票明细」区块按票带出发票明细行（A303-2 分录取数来源）；「结算信息」区只读——认领关系由付款结算单侧维护](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记表单.png) -**金蝶侧效果**： +![付款结算单「发票登记」弹窗（先票后款路径B）：结算基本信息（结算单号/结算总金额/已匹配发票金额/金蝶同步状态）+ 认领收票单（选择收票单 → 发票号/开票单位（销方）/发票金额/匹配结算单金额）→ 保存认领后可推送指定应付](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-付款结算单发票登记.png) + +### 5.3 后端要点（当前口径） + +**A303-2 主表取值（★先票后款重写）**： + +| 字段 | 取值 | +|---|---| +| awrp_src_code | 收票登记 id（重推幂等） | +| receivablessupp_number 往来户 | 登记回填的 `supplier_code`（销方名称→本地客商档案匹配，`customer_code` 兜底）；缺失推送时实时再查一次，仍缺失**报错阻断**。供应商编码由 A901-1 在客商建档/同步复查时落库 | +| org_number 结算组织 | 页面手选部门 `kingdeeOrgNumberByDept`（沿部门树上溯唯一平台公司取金蝶组织编码） | +| currency_number 结算币别 | 固定 **CNY**（不挂合同后的默认，外币票暂无取值来源） | +| asstacttype 往来类型 | 固定 `bd_customer` | +| invoiceno/receivedate/issuedate | 登记发票号 / 推送当日 / 镜像开票日期 | +| biztype | 固定 `PUR`（采购）；销方=镜像开票单位、购方=受票单位；`isincludetax=true`；awrp_src_type=TMS收票登记 | + +**A303-2 分录（逐行取镜像 `items_json`，明细缺失/解析失败拦截）**： + +| 字段 | 取值 | +|---|---| +| e_pricetaxtotal | 明细金额+税额（合计为 0 拦截） | +| quantity / price | 明细数量（≤0 兜底 1）/ 明细单价（**统一 4 位小数 HALF_UP**，空按价税合计÷数量反算） | +| material_number / e_taxclass_number | 行商品编码 goodsCode（数电票行商品编码即税收分类编码；缺失拦截） | +| taxrateid_number | `V`+整数税率（13%/13/0.13→V13；**缺失或 0/免税行拦截**提示人工） | +| e_amount / e_tax | 明细金额 / 税额（空不送） | +| awrp_entry_code | **发票号码_seq**（分录候选键，重推幂等） | + +![收票登记列表：批量同步/新增/导出；付款方（受票单位）/收款方（开票单位）列随新表单口径展示](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-先票后款-收票登记列表.png) + +**状态机与关键规则**： + +- 状态机：`unsynced → pushed`（A303-2 成功，**收票推送终点**）→ `assigned`（仅由付款结算单侧 A302-6 成功后）→ failed（A303-2 失败 / A801-3 发票状态异常回收 / 指定失败回收 / 自动路径前置拦截）。 +- 关系同步 `syncSettlementReceiptRelations`：按行发票号匹配审批通过收票登记 → **一票一结算单校验**（已挂其他有效应付结算单抛「一张收票单只能被一张付款结算单认领」）→ 删旧建新（认领金额=发票全额）→ 刷新结算单收票状态。 +- **收票状态按覆盖判定**：结算单已匹配发票金额 `>=` 结算金额即 completed（允许超额覆盖），否则 partial。 +- **反向操作不同步金蝶**：结算单作废/认领移除不调 A302-6 解除指定，需金蝶侧人工解除后重推（已拍板）。 +- 历史兼容：历史已 assigned 单据不受影响；收票登记编辑未传 settlements 时不动既有分摊关系（关系只由结算单侧维护）。 +- 镜像比对集含 `itemsJson`（先票后款后明细是分录唯一取数来源，明细变化必须跟随票池刷新）；全票池同步细节不变（2.5 万上限、单调二分、轻量比对跳写）。 + +**金蝶侧效果（历史推送数据，供对照）**： ![TMS 收票管理列表「金蝶状态」列：已指定应付（终态）/推送失败（带失败原因）/未推送，金蝶单据号 AVT-202608-000396 悬浮展示](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-收票金蝶状态列表.png) ![A902 附件上传金蝶侧效果：金蝶财务应付单详情「附件」区收到 TMS 推送单据联带上传的文件；付款计划区同时可见下推生成的付款计划（外部系统来源标识=防重键）](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a902-附件上传金蝶侧.png) -![A801-2 发票查看/下载入口：正式结算单详情「发票信息」区认领的发票行提供 查看/下载（走后端 A801-2 流式代理，PDF 版式优先）；付款信息区同时回显付款申请的金蝶单号](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a801-2-发票查看下载.png) - -- 推送计划校验：approved、状态≠assigned、已绑定镜像、`checkStatus=2`、**恰好分摊 1 张审批通过应付结算单（一票一应付）**、有结算明细；不满足写 `blockedReason` 不改状态。 -- A801-3 预检命中且状态正常→跳过 A303-2 直接续推指定（断点恢复）；发票状态异常（作废2/红冲3/部分红冲7/全部红冲8）→failed 报人工。 -- 落库：`kingdee_received_invoice_no`、状态机 `unsynced→pushed→assigned/failed` →`kingdee_push_status`（唯一金蝶状态来源）；终态/失败写 `blade_invoice_receipt_record`；pushed/assigned 禁止本地作废。 -- 全票池同步细节：单查询窗口 MAX_POOL_PAGES×500=2.5 万上限，`updateTime` 单调二分不重不漏；镜像 upsert 轻量比对（流水号/价税合计/税额/可用金额/使用状态）无变化跳写。 +![A801-2 发票查看/下载入口：结算单详情「发票信息」区认领的发票行提供 查看/下载（走后端 A801-2 流式代理，PDF 版式优先）；付款信息区同时回显付款申请的金蝶单号](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a801-2-发票查看下载.png) --- -## 6. 业务域五：收款认领（A301-2 / A301-3 / A301-1） +## 6. 业务域五：收款流水与认领（A301-1 数据源 + 合同合规推送） -**定位**：业务先行认领。金蝶司库第一轮自动认领到客户维度 → TMS 二次认领到结算单维度 → **本地认领完成后**（定时或手动）回推金蝶生成收款单 → 手动查询回写结果。★09-28 重构后：认领与推送解耦，推送按流水归集、定时+手动双入口。 +> ★10-29 改造：数据源 A301-2 → **A301-1 收款单查询**，A301-3 推送金蝶链路整体下线，认领只登记本地并推送**合同合规系统**。金蝶收款单在认领前已存在（A301-1 即金蝶收款处理单），因此**不再向金蝶回写任何数据**。方案与操作细节见《2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）》《2026-10-29-收款流水认领操作流程（收款金额本地额度·单条批量与作废）》。 ### 6.1 链路总览 ``` -阶段一 收款流水页「流水同步」（手动） - POST /receipt-flow/sync ▶ A301-2 认领公告查询（claimusers=Nacos thirdParty.bfi.claimAnnounce.claimusers， - ★不再按登录用户姓名；未配置则以空值调用会查不到数据） - ▶ 全量翻页（窗口 months=6）▶ 按 detail_serial_no 幂等 upsert blade_kingdee_receipt_flow +阶段一 收款流水页「手动同步流水」（手动，无定时任务） + POST /receipt-flow/sync ▶ A301-1 queryRecBill + ▶ 业务日期窗口=当天倒推 thirdParty.bfi.recBillSync.days（默认 60 天，支持热更新） + ▶ 按平台公司金蝶组织编码过滤，全量翻页（pageSize 200，窗口切片规避单查 1 个月上限） + ▶ 一张金蝶收款单=一条流水（幂等键 detail_serial_no=收款单号），金蝶单号/单据状态随同步刷新 + ▶ 前置：组织管理维护「是否平台公司=是」+ 金蝶组织编码，缺失直接报错拦截 -阶段二 流水详情/批量认领（手动） - POST /receipt-flow/claim ▶ 本地落库（claim + 分摊 + 流水 claimed_amount/claim_status 刷新 + 结算单收款汇总） - ▶ 本地完成即结束，**不调金蝶**（认领本地化★） +阶段二 流水详情/批量认领（手动，只登记本地） + POST /receipt-flow/claim ▶ 本地落库（认领主单+结算单分摊+流水 claimed_amount/claim_status 刷新+结算单收款汇总） + ▶ 认领上限=收款金额 actrecamt（unmatchamountrec 未匹配金额仅参考展示，不参与额度控制） + ▶ 不调金蝶（A301-3 下线★） -阶段三 推送金蝶（定时 ReceiptClaimPushTask 默认关每10分钟 / 手动流水行内「推送金蝶」） - pushClaimToKingdee ▶ 按认领人逐人重查 A301-2 → 扫「认领完成未推送」流水按流水归集 - ▶ 逐流水：awrp_src_code=分摊结算单号拼接（重试复用幂等）→ A301-3 推送 - （分录单条：e_receivableamt=全部未推送金额；e_corebillno=第一张结算单金蝶内码，缺内码拦截不推） - ▶ 成功回写 kingdee_bill_no（回执 keys.awrp_src_code 占位）+ kingdee_bill_status=pushed +阶段三 认领事务提交后推合同合规（afterCommit，失败只落标记不回滚） + HcsClaimSyncSupport.pushClaimToHcs ▶ C104-2 按明细流水号定位合规侧流水 ID + ▶ 逐合同：C103-9 履约计划金额累加 → C107-1 认领记录（返回 fdId 落库 blade_receipt_claim_hcs_record）→ C108-1 履约流水 + ▶ 开关：exe-stage.sync-enabled 门禁 C103-9/C107-1；perf-record.sync-enabled 门禁 C108-1 -阶段四 认领记录页「查询金蝶认领结果」（手动） - POST /receipt-claim-record/query-kingdee-result ▶ A301-1 收款单查询（今天回溯 30 天） - ▶ sourcebillnumber==awrp_src_code 匹配 ▶ 真实收款单号覆盖占位单号 + 状态推进（C→approved，D→received 终态） +阶段四 作废（认领记录页，仅本人+已认领记录） + POST /receipt-claim-record/void ▶ 本地回退金额/状态 → afterCommit 逐条推 C107-3（fdStatus=1 已作废，按落库 fdId） + ▶ 单条失败只记日志不回滚作废；无合规记录（曾推送失败）静默跳过；作废不生成金蝶冲销单 ``` ### 6.2 前端入口 | 页面 | 操作 | 后端端点 | 说明 | |---|---|---|---| -| 收款流水（`/payment/receipt-flow`） | 工具栏「流水同步」 | `POST /receipt-flow/sync`（A301-2） | 权限 `receipt_flow_sync` | -| 同上 | 流水详情/批量认领表单「确认」 | `POST /receipt-flow/claim` | 选择审批通过应收结算单按比例分摊；已推送金蝶的认领禁止作废（后端硬校验） | -| 同上 | 行内「推送金蝶」 | `POST /receipt-flow/push-kingdee?flowId=` | 确认弹窗后按流水归集推送 | -| 认领记录（`/payment/receipt-claim-record`） | 工具栏「查询金蝶认领结果」 | `POST /receipt-claim-record/query-kingdee-result`（A301-1） | 手动；窗口内查不到不改状态 | +| 收款流水（`/payment/receipt-flow`） | 工具栏「手动同步流水」 | `POST /receipt-flow/sync`（A301-1） | 权限 `receipt_flow_sync`；前置组织金蝶编码 | +| 同上 | 流水详情/批量认领「确认」 | `POST /receipt-flow/claim` | 应收+审批通过+有剩余可认领金额的结算单；多选须同项目/组织/收付款方；批量认领须同付款人+对方账号 | +| 认领记录（`/payment/receipt-claim-record`） | 行内「作废」 | `POST /receipt-claim-record/void` | 仅本人+已认领；确认提示含「同步作废合同合规系统认领记录」 | + +![收款流水列表（A301-1 数据源）：收款单号即金蝶收款单号（RV-…）、收款金额为认领上限、未匹配金额仅参考；工具栏仅「手动同步流水/批量认领」——原「推送金蝶」按钮与推送状态搜索已随 A301-3 下线删除](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-a301-1-收款流水列表.png) + +![认领记录列表：原「查询金蝶认领结果」按钮已删除（金蝶状态随 A301-1 同步刷新，无需回写）；作废操作同步作废合同合规系统认领记录](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/tms-认领记录页.png) ### 6.3 后端要点 -**金蝶侧效果**： - -![A301-2 对照：金蝶「认领公告列表」（RLTZ 通知单，待认领/部分认领）与 TMS 收款流水「手动同步流水」拉取的同批公告对照](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-2-公告同步对照.png) - -![A301-3 对照：TMS 认领记录（RLTZ-20260612-0073 认领 828.00）推送后，金蝶「认领处理列表」生成认领单 RL-20260929-0058（已确认，认领通知单 0073 对应）](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-认领推送对照.png) - -![A301-3 金蝶侧认领结果详情：收款认领结果行「核心单据编号」=结算单星瀚内码（2586341365516352512，即 e_corebillno 传金蝶内码的落地证据）](./2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.assets/bfi-effect-a301-3-金蝶认领结果.png) - -- 推送闸门：已推送（pushed）流水跳过不重推；`billid`（认领公告 id）缺失拦截「请先同步金蝶收款流水」；结算单金蝶内码缺失拦截不推。 -- 幂等：`awrp_src_code` 重试复用同一编码；作废认领不再生成本地冲单（金蝶单据状态保留原值）。 -- A301-3 字段待金蝶确认项仍在：`recpaytype_number`（常量当前值 "999"，注释示例 101 待确认）、`paymenttype`、`recpayer`（金蝶付款人 master id）。 +- **字段映射与表结构**：`blade_kingdee_receipt_flow` 新增 `org_number/open_org_number`（收款人/核算组织编码）、`match_amount_rec/match_amount_pay/unmatch_amount_pay/settle_amount/unsettle_amount`；`unclaimed_amount` 改名 `unmatch_amount_rec`；`bill_id/payer_id/kingdee_claim_status/claim_me/push_status/push_fail_reason/pushed_time/awrp_src_code` 等 A301-2/A301-3 专属列废弃保留（存量仅展示）。 +- **单据状态映射（随同步刷新）**：A 暂存/B 已提交→pushed、C 已审核→approved、D 已收款→received、G 已退单/E 变更中/其它→failed（需人工在金蝶核查）。 +- **认领额度**：流水维度「累计认领 ≤ 收款金额」；结算单维度「累计认领 ≤ 结算总应收含税金额」。金蝶侧已核销（未匹配金额=0）不影响认领。 +- **合规推送失败不重试**：`blade_receipt_claim_hcs_record` 落 failed+原因，人工在合规侧补录（业务拍板，无定时补偿）。 +- **下线清单**：`pushClaimToKingdee` 等推送方法、`ReceiptClaimPushTask`（10 分钟定时）、`/receipt-flow/push-kingdee`、`/receipt-claim-record/query-kingdee-result`、`awrpSrcCode` 生成、Nacos `claimAnnounce.*/receiptClaimPush.*` 配置全部删除。 --- @@ -459,20 +545,22 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） ▼ 定时 A302-4 勾稽纠偏 + A303-5 开票结果 ─▶ invoiced（终态，发票文件落库） -【收票主线】 定时 A801-1 全票池同步 ─▶ 镜像表 ◀── 选票读镜像（票号未命中窄查回源） - │ 收票登记保存（闸门）/ 结算认领确认（闸门★新增） +【收票主线·先票后款】 定时 A801-1 全票池同步（含明细 items_json）─▶ 镜像表 ◀── 选票/明细/候选读镜像（票号未命中窄查回源） + │ 收票登记保存（闸门）；付款结算单认领收票单（syncSettlementReceiptRelations 关系同步） ▼ - 收票登记审批 ─A102-4 预检─A801-3 预检(登记id)─▶ A303-2 保存 ─▶ pushed ─▶ A302-6 ─▶ assigned - │（本期不锁单；A902 附件联带上传） + 收票登记审批 ─A801-3 预检(登记id)─▶ A303-2 保存（销方供应商代码/CNY/明细行）─▶ pushed（推送终点） + │（本期不锁单；A902 附件联带上传；★不再 A102-4 预检、不再推送时立即 A302-6） ▼ - 定时 A801-3 回写（异常回收/指定补偿/单号补登，按登记 id 匹配★已修） + 付款结算单 A102-2 应付单推送成功 ─▶ 逐单 A302-6 指定应付（手动端点/发票登记弹窗确认）─▶ assigned（终态） + ▼ + 定时 A801-3 回写（异常回收/pushed+已认领补指定/单号补登，按登记 id 匹配） -【收款认领主线】 手动 A301-2 公告同步 ─▶ blade_kingdee_receipt_flow - │ 页面认领（本地化，不调金蝶） +【收款流水与认领主线】 手动 A301-1 收款单同步 ─▶ blade_kingdee_receipt_flow（金蝶单号/状态随同步刷新） + │ 页面认领（只登记本地，上限=收款金额；不调金蝶） ▼ - 定时/手动 A301-3 按流水归集推送（e_corebillno=结算单金蝶内码）─▶ pushed + 认领事务提交后推合同合规：C103-9 → C107-1（fdId 落库）→ C108-1 ▼ - 手动 A301-1 收款单查询 ─▶ 真实收款单号覆盖 + approved/received（终） + 作废：本地回退 + C107-3（fdStatus=1）；金蝶侧不回写 【横切】 审批通过 AFTER_COMMIT 自动同步（4 开关）│ 推送成功→lockBusiData（3 链路） 金蝶删单→unLockNotifyBusiData 回调还原 │ 锁失败定时/手动补偿 @@ -485,50 +573,53 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） |---|---|---| | 1 | 客商档案先于一切推送（本地 customer_code 必须存在） | 查不到直接报错；金蝶侧审核状态不校验（软依赖） | | 2 | 客商提审先过 A801-5 黑名单 | A 类命中/查询异常即阻断提审 | -| 3 | A102-2 先于 A103-1 与 A303-2 | A102-4 硬校验/预检 | -| 4 | A302-2 先于 A303-1 与 A301-3（e_corebillno 需金蝶内码） | A302-4 硬校验；内码缺失拦截不推 | -| 5 | A303-2 先于 A302-6 | 同一次推送内串行 | -| 6 | 推送先于回写（A103-2/A103-4、A302-4 勾稽、A303-5、A801-3、A301-1） | 查询键由推送链写入本地 | +| 3 | A102-2 先于 A103-1 | A102-4 硬校验/预检 | +| 4 | A302-2 先于 A303-1 | A302-4 硬校验 | +| 5 | A303-2（收票单）先于 A302-6（指定应付）；A102-2（应付单）先于 A302-6 | 收票推送终点 pushed；A302-6 由付款结算单侧执行（应付推送成功后逐单指定 / 发票登记弹窗确认 / 手动端点 / A801-3 定时补偿） | +| 6 | 推送先于回写（A103-2/A103-4、A302-4 勾稽、A303-5、A801-3） | 查询键由推送链写入本地 | | 7 | 锁单在推送成功之后、金蝶删单回调可还原 | lockAfterPush 事务提交后执行；unLockNotifyBusiData 免登回调 | | 8 | A801-4 汇率查询先于 A102-2/A302-2（如需携带汇率） | 页面联动维护，未维护不传 | +| 9 | 客商 A901-1 供应商编码先于收票 A303-2 推送（销方供应商代码） | 销方名称匹配本地客商档案 supplier_code；缺失推送前强校验拦截 | **断链恢复语义**：本地失败/远端未落单→unsynced 或 failed 可重推；远端成功本地回滚→重推时预检幂等回填（A102-4/A302-4/A103-2/A303-4/A801-3/awrp_src_code 复用）；推送成功后状态滞后→定时回写；批量语义→整批预热+逐单独立事务+单条失败不中断。 --- -## 9. 状态机汇总（2026-10-14） +## 9. 状态机汇总（2026-10-31） | 表.字段 | 状态集 | 迁移 | 写入方 | |---|---|---|---| | `blade_formal_settlement.kingdee_sync_status` | unsynced / synced / **failed**（★新增写入口） | unsynced→(A102-2/A302-2 成功)→synced；推送异常→failed（独立事务）；failed 可手动/定时重推、A302-4 勾稽纠偏回 synced；金蝶删单回调→voided + unsynced 还原 | FormalSettlementServiceImpl | | `blade_payment_application.kingdee_status` | unsynced / synced / paying / paid(终) / closed(终) / failed | 同前版映射；failed 可纠偏回 synced；**连续 2 轮查不到→消失解锁置 failed**；金蝶删单回调→failed+清单号（不作废源单） | PaymentApplicationServiceImpl + 定时 | | `blade_invoice_application.kingdee_status` | unsynced / synced / invoiced(终) / **failed**（★新增写入口） | unsynced→(A303-1 全部张次成功)→synced→(A303-5 新发票)→invoiced；推送异常→failed；金蝶删单回调→作废还原 | InvoiceApplicationServiceImpl + 定时 | -| `blade_invoice_receipt.kingdee_push_status` | unsynced / pushed / assigned(终) / failed | 同前版；A801-3 回写匹配键已修复为登记 id（异常回收/补偿/补登生效） | InvoiceReceiptServiceImpl + 定时 | -| `blade_customer_archive.kingdee_status` | none / synced / failed / exist(终) | 同前版；提审新增 A801-5 黑名单拦截（不产生状态） | CustomerArchiveServiceImpl + 定时 | +| `blade_invoice_receipt.kingdee_push_status` | unsynced / pushed / assigned(终) / failed | **★先票后款语义变更**：unsynced→(A303-2 成功)→pushed（**收票推送终点**）；pushed→(付款结算单侧 A302-6 成功：应付推送后逐单指定/发票登记确认/手动端点/A801-3 指定补偿)→assigned；failed（A303-2 失败 / A801-3 发票状态异常回收 / 指定失败回收 / 前置拦截）；pushed/assigned 禁止本地作废 | InvoiceReceiptServiceImpl + FormalSettlementServiceImpl + 定时 | +| `blade_customer_archive.kingdee_status` | none / synced / failed / exist(终) | 同前版；提审新增 A801-5 黑名单拦截（不产生状态）；新增 `supplier_code` 字段（A901-1 查询回填，不产生状态） | CustomerArchiveServiceImpl + 定时 | | `blade_kingdee_bill_lock.lock_status` ★新增 | failed / locked / unlocked | 先落 failed 占位→lockBusiData 成功→locked；补偿重试（try_count<5）或金蝶解锁/删单回调→unlocked | KingdeeBillLockServiceImpl + 定时 + 手动端点 | -| `blade_receipt_claim.kingdee_bill_status` | none / pushed / approved / received(终) / failed / voided | none→(A301-3)→pushed→(A301-1: C)→approved→(D)→received；已推送禁止作废 | ReceiptFlowServiceImpl + ReceiptClaimRecordServiceImpl | -| `blade_kingdee_receipt_flow.claim_status` | unclaimed / partial / claimed | 认领分摊→partial/claimed；全部作废→unclaimed；公告同步不覆盖 | ReceiptFlowServiceImpl | +| `blade_receipt_claim.kingdee_bill_no/kingdee_bill_status` | pushed / approved / received / failed | **★语义变更**：认领时从流水冗余快照（A301-1 同步值），认领不再推送金蝶、状态不再推进，仅随流水同步反映金蝶侧进展；作废→本地回退+推 C107-3 | ReceiptFlowServiceImpl + ReceiptClaimRecordServiceImpl | +| `blade_kingdee_receipt_flow.claim_status` | unclaimed / partial / claimed | 认领分摊→partial/claimed（上限=收款金额）；作废回退重算；A301-1 同步不覆盖本地认领字段 | ReceiptFlowServiceImpl | +| `blade_kingdee_receipt_flow.kingdee_bill_status` | pushed / approved / received / failed | 随 A301-1 手动同步刷新：A/B→pushed、C→approved、D→received、G 退单/E 变更中/其它→failed | ReceiptFlowServiceImpl（sync） | +| `blade_receipt_claim_hcs_record.push_status` ★新增 | success / failed / voided | 认领事务提交后推 C107-1：成功落合规 fdId；失败落标记（无自动重试）；作废推 C107-3 成功后置 voided | HcsClaimSyncSupport | --- ## 10. 定时任务与配置开关汇总 -全部在 `blade-transport/task/`，Spring `@Scheduled`，统一 single-flight（`KingdeeSyncLockSupport`，`blade.lock.enabled=false` 降级直跑）。 +全部在 `blade-transport/task/`，Spring `@Scheduled`，统一 single-flight（`KingdeeSyncLockSupport`，`blade.lock.enabled=false` 降级直跑）。**收款认领推送任务 `ReceiptClaimPushTask` 已随 A301-3 下线删除（10-29）。** | 任务类 | 方法 | 覆盖业务（接口） | cron 键（默认） | 开关键（代码默认） | 手动端点 | |---|---|---|---|---|---| -| PaymentKingdeeResultTask | syncKingdeePaymentResult | ① A103-2/A103-4 付款结果 ② A302-4 应收勾稽 ③ A303-5 开票结果 | `thirdParty.bfi.payResult.cron`（`0 */10 * * * ?`） | `thirdParty.bfi.payResult.syncEnabled`（false；**Nacos 样例 dev/prod 已显式 true**） | `/payment-application/sync-kingdee-result`、`/formal-settlement/sync-kingdee-ar-result`、`/invoice-application/sync-kingdee-invoice-result` | -| PaymentKingdeeResultTask | syncKingdeeReceivedInvoiceResult | A801-3 收票结果回写 | `thirdParty.bfi.receivedInvoiceResult.cron`（每10分钟） | `…receivedInvoiceResult.syncEnabled`（false） | `/invoice-receipt/sync-kingdee-result` | -| CustomerKingdeeSyncTask | syncKingdeeCustomerData | A902-1 复查 + A902-2 重推 + 金蝶停用联动 | `thirdParty.bfi.customer.cron`（`0 0 2 * * ?`） | `…customer.syncEnabled`（false；KS000067 残留已移除） | `/customer-archive/sync-kingdee` | -| **ReceiptClaimPushTask** ★新增 | pushClaimToKingdee | A301-3 认领推送（按流水归集，前置重查 A301-2） | `thirdParty.bfi.receiptClaimPush.cron`（每10分钟） | `…receiptClaimPush.syncEnabled`（false） | `/receipt-flow/push-kingdee` | -| **InvoiceReceiptKingdeeSyncTask** ★新增 | syncKingdeeInvoicePool | A801-1 全票池瘦身同步 + 绑定回填 | `thirdParty.bfi.invoiceReceipt.cron`（每30分钟） | `…invoiceReceipt.syncEnabled`（false）；增量窗口 `…incrementDays`(30)；票种白名单 `…invoiceTypes` | `/invoice-receipt/sync-invoice-pool` | -| **KingdeeAutoSyncRetryTask** ★新增 | retryKingdeeFailed | 4 域 failed 单据重推（结算/付款/开票/收票；不扫 unsynced；无次数上限，靠幂等预检防重） | `thirdParty.bfi.autoSync.retryCron`（每10分钟） | `…autoSync.retryEnabled`（false） | 各域 `/sync-kingdee` | -| **KingdeeBillLockRetryTask** ★新增 | retryFailedBillLocks | 锁单失败补偿（failed 且 try_count<5 重调 lockBusiData） | `thirdParty.bfi.billLock.retryCron`（每5分钟） | `…billLock.retryEnabled`（false） | `/formal-settlement/retry-kingdee-bill-lock` | +| PaymentKingdeeResultTask | syncKingdeePaymentResult | ① A103-2/A103-4 付款结果 ② A302-4 应收勾稽 ③ A303-5 开票结果 | `thirdParty.bfi.payResult.cron`（`0 1/10 * * * ?`） | `thirdParty.bfi.payResult.sync-enabled`（false；**Nacos 样例 dev/prod 已显式 true**） | `/payment-application/sync-kingdee-result`、`/formal-settlement/sync-kingdee-ar-result`、`/invoice-application/sync-kingdee-invoice-result` | +| PaymentKingdeeResultTask | syncKingdeeReceivedInvoiceResult | A801-3 收票结果回写（异常回收/**pushed+已认领补指定**/单号补登） | `thirdParty.bfi.receivedInvoiceResult.cron`（`0 8/10 * * * ?`，与付款回写独立调度） | `thirdParty.bfi.receivedInvoiceResult.sync-enabled`（false） | `/invoice-receipt/sync-kingdee-result` | +| CustomerKingdeeSyncTask | syncKingdeeCustomerData | A902-1 复查 + A902-2 重推 + 金蝶停用联动 | `thirdParty.bfi.customer.cron`（`0 0 2 * * ?`） | `thirdParty.bfi.customer.sync-enabled`（false） | `/customer-archive/sync-kingdee` | +| InvoiceReceiptKingdeeSyncTask | syncKingdeeInvoicePool | A801-1 全票池瘦身同步（含明细 items_json）+ 绑定回填 | `thirdParty.bfi.invoiceReceipt.cron`（`0 16/30 * * * ?`） | `thirdParty.bfi.invoiceReceipt.sync-enabled`（false）；增量窗口 `…incrementDays`(30)；票种白名单 `…invoiceTypes` | `/invoice-receipt/sync-invoice-pool` | +| KingdeeAutoSyncRetryTask | retryKingdeeFailed | 4 域 failed 单据重推（结算/付款/开票/收票；不扫 unsynced；无次数上限，靠幂等预检防重）；收票重推不再依赖 A102-4 | `thirdParty.bfi.autoSync.retryCron`（`0 5/10 * * * ?`） | `thirdParty.bfi.autoSync.retry-enabled`（false） | 各域 `/sync-kingdee` | +| KingdeeBillLockRetryTask | retryFailedBillLocks | 锁单失败补偿（failed 且 try_count<5 重调 lockBusiData） | `thirdParty.bfi.billLock.retryCron`（`0 2/5 * * * ?`） | `thirdParty.bfi.billLock.retry-enabled`（false） | `/formal-settlement/retry-kingdee-bill-lock` | **审批自动同步开关（监听器，非定时）**：`thirdParty.bfi.autoSync.settlement / payment / invoiceApply / receipt`（默认全 false）。 -**其他业务键**：`thirdParty.bfi.claimAnnounce.claimusers`（A301-2 认领人，**必配**）、`…claimAnnounce.months`(6)、`thirdparty.bfi.blacklist.blockRiskWarning`(false)、`thirdparty.bfi.material.*`（物料映射）。 +**其他业务键**：`thirdParty.bfi.recBillSync.days`（★新增，A301-1 同步窗口天数，默认 60）、`thirdparty.bfi.blacklist.blockRiskWarning`(false)、`thirdparty.bfi.material.*`（物料映射）。 +**已删除配置**：`thirdParty.bfi.claimAnnounce.*`（A301-2 认领人/窗口）、`thirdParty.bfi.receiptClaimPush.*`（认领推送定时）——代码已不再读取，Nacos 中可清理。 -> ⚠️ Nacos 样例（`doc/nacos/`）仅显式配置了 `payResult.syncEnabled=true`；`receiptClaimPush/invoiceReceipt` 样例仍为 false；`customer/receivedInvoiceResult/autoSync/billLock` 键未出现在样例中——生效值取决于各环境实际 Nacos，缺省走代码 false。**开启生产定时前逐项核对第 12 节风险清单。** +> ⚠️ Nacos 样例（`doc/nacos/`）仅显式配置了 `payResult.sync-enabled=true`；`customer/receivedInvoiceResult/autoSync/billLock/invoiceReceipt` 键未出现在样例中——生效值取决于各环境实际 Nacos，缺省走代码 false。**开启生产定时前逐项核对第 12 节风险清单。** --- @@ -540,7 +631,7 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） |---|---|---| | 1 | 部门金蝶组织编码 | 部门档案维护 `kingdee_dept_code`；未维护的部门推送组织取数会直接拦截 | | 2 | 主数据 SQL | 执行 `doc/sql/transport/kingdee_master_data_init_20260924.sql`（计量单位档案等）；认领链路执行 `blade_receipt_flow_claim_20260924.sql`；10-13 迁移脚本见 `doc/sql/transport/lqj/` | -| 3 | Nacos 业务配置 | `thirdParty.bfi.claimAnnounce.claimusers`（认领人，与金蝶公告 claimusers 一致）、`thirdParty.bfi.invoiceReceipt.invoiceTypes`（票池同步票种白名单）、`thirdparty.bfi.material.*`（物料映射，缺省有默认值但建议显式配置） | +| 3 | Nacos 业务配置 | `thirdParty.bfi.recBillSync.days`（A301-1 同步窗口天数，默认 60，可选）、`thirdParty.bfi.invoiceReceipt.invoiceTypes`（票池同步票种白名单）、`thirdparty.bfi.material.*`（物料映射，缺省有默认值但建议显式配置） | | 4 | 定时开关按需开启 | 见第 10 节表：付款结果回写样例已开；其余按环境显式开启 `syncEnabled/retryEnabled` | | 5 | 审批自动同步开关 | `thirdParty.bfi.autoSync.settlement/payment/invoiceApply/receipt` 按域开启；未开启时走页面「同步金蝶」手动推送 | | 6 | 客商收款账户 | 维护 `blade_customer_receipt_account` 联行号（cnaps_code）——付款申请/预付款/客商推送均取真实联行号，缺失拦截 | @@ -570,17 +661,22 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） → 等 A303-5 定时回写发票结果（或手动端点）→ 状态 invoiced → 正式结算单详情「开票发票」区查看/下载发票文件 -⑤ 收票（进项） - 收票登记表单：发票号放大镜从金蝶票池选票（镜像读，票号未命中自动回源）→ 保存（重查闸门校验可用性） - → 分摊到一张审批通过应付结算单 → 审批通过（autoSync.receipt 开启时自动推送；或「批量同步」） - → A303-2 保存→pushed→A302-6 指定应付→assigned（终态） - → 等 A801-3 定时回写（pushed 断点自动补偿重发 A302-6） +⑤ 收票（进项·先票后款两段式） + 【先票】收票登记表单：发票号放大镜从金蝶票池选票（镜像读，票号未命中自动回源）→ 表单带出发票明细 + → 手选结算组织（合同承办部门）→ 保存（重查闸门校验可用性；销方供应商代码自动回填） + → 提交审批 → 审批通过（autoSync.receipt 开启时自动推送；或「批量同步」） + → A303-2 保存（往来户=销方供应商代码/币别 CNY/分录=发票明细行）→ pushed（收票推送终点） -⑥ 收款认领 - 收款流水页「流水同步」拉取金蝶认领公告 → 流水详情/批量认领：选审批通过应收结算单按比例分摊（本地落库） - → 「推送金蝶」（行内手动，或等 ReceiptClaimPushTask 定时）→ 金蝶生成收款单 - → 认领记录页「查询金蝶认领结果」回写真实收款单号与状态（approved/received） - 注意：已推送金蝶的认领不可作废，需金蝶侧人工处置 + 【后款】付款结算单（应付）编辑或「发票登记」：选择收票单（候选=审批通过+未认领）→ 全额认领 + → 结算单审批通过 → A102-2 应付单推送成功 → 逐单 A302-6 指定应付 → 收票单 assigned（终态） + → 卡在 pushed 不用手动处理：被认领后由 A801-3 定时补偿自动补发指定 + +⑥ 收款流水与认领（认领本地化，不推金蝶） + 收款流水页「手动同步流水」拉取金蝶收款单（A301-1，窗口默认 60 天；前置组织金蝶编码） + → 流水详情/批量认领：选审批通过应收结算单填分摊金额（上限=收款金额，本地落库） + → 认领事务提交后自动推合同合规（C103-9→C107-1→C108-1，失败只落标记） + → 需撤销时认领记录页「作废」：本地回退金额 + 自动同步合规 C107-3 + 注意：金蝶侧认领/收款处理由财务在金蝶直接操作，TMS 只做本地认领登记与合规同步 ⑦ 查看附件 金蝶票池/认领发票/收票附件的「查看/下载」统一走后端 A801-2 代理（PDF 版式优先） @@ -597,13 +693,19 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） | 付款单在金蝶被删且无回调 | A103-2 连续 2 轮（约 20 分钟）查不到 | 自动消失解锁置 failed，按 failed 重推 | | 断链重推（远端已落单本地未同步） | 重推时预检命中 | 自动幂等回填单号跳过重复推送，无需人工清库 | | 收票单发票状态异常 | 定时回写发现红冲/作废 → failed「已回收推送状态」 | 人工在金蝶侧处理后重新登记/推送 | +| 收票推送报「供应商代码/往来户」类错误 | 销方名称未匹配到客商档案 `supplier_code`（A901-1 未回填） | 先完成客商建档/金蝶同步（A901-1 回填供应商编码），或用 `GET /customer-archive/query-supplier-code` 核对后重推 | +| 收票推送报免税/零税率行拦截 | `taxrateid_number` 无法映射（0 税率/免税行） | 人工核实票面，与金蝶约定编码后放开（有意拦截） | +| 收票推送报结算组织/平台公司类错误 | 手选部门沿部门树上溯不到带金蝶组织编码的平台公司 | 管理员维护组织档案金蝶编码后重推 | +| 收票单卡在 pushed 未变 assigned | 未被付款结算单认领，或认领它的结算单应付单未推送成功 | 在付款结算单做「发票登记」/编辑认领收票单，并确认该结算单已 synced；A801-3 补偿只处理「已认领」的 pushed 单 | +| 认领收票单被拦「一张收票单只能被一张付款结算单认领」 | 该收票登记已被其他有效应付结算单认领 | 先在原结算单移除认领（金蝶侧人工解除指定）再认领 | | 票池选不到票 | 镜像无数据 | 检查全票池同步开关与 `invoiceTypes` 白名单；或 `POST /invoice-receipt/sync-invoice-pool` 手动同步；票号精确查会自动回源 | -| 收款流水同步为空 | A301-2 查不到公告 | 检查 Nacos `claimAnnounce.claimusers` 是否与金蝶公告认领人一致 | +| 收款流水同步为空/报组织编码错误 | 组织管理未维护「平台公司」金蝶编码，或窗口内无数据 | 维护组织金蝶编码后重试；需要更早数据时调大 `thirdParty.bfi.recBillSync.days`（支持热更新） | +| 认领/作废合规推送失败 | C103-9/C107-1/C108-1/C107-3 返回异常 | 查 `blade_receipt_claim_hcs_record` 失败原因，人工在合规侧补录（无自动重试）；作废主流程不受影响 | | 定时任务不跑/重复跑 | — | 核对 Nacos 开关键名（第 10 节）；single-flight 锁保证多副本/手动不并发，`blade.lock.enabled=false` 时无锁 | --- -## 12. 风险与待确认清单（2026-10-14） +## 12. 风险与待确认清单（2026-10-31） ### 12.1 已关闭（旧总纲遗留，当前代码已核实修复） @@ -615,27 +717,35 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶） | 客商推送 bankNumber 硬编码 / A103-3 e_bebank_number 取名称字段 | ✅ 均改取客商收款账户联行号 | | 结算/开票失败不落 failed | ✅ 统一落 failed（03b34310） | | 结算单认领无保存重查闸门 | ✅ 已实现 assertInvoicesClaimable | +| 收票推送依赖「恰好分摊 1 张应付结算单」+ A102-4 预检 | ✅ 已随先票后款改造删除（10-31，收票登记不再挂结算单） | +| 收款认领推送金蝶（A301-3 定时+手动） | ✅ 链路整体下线（10-29），认领只登记本地+推合同合规 | -### 12.2 仍需关注 / 联调确认 +### 12.2 仍需关注 / 联调确认（2026-10-31） | # | 事项 | 证据/说明 | |---|---|---| -| 1 | **A103-1 勾稽键口径**：代码传本地组装的应付防重键，`PaymentApplicationServiceImpl:1431-1443` 注释仍写「A102-4 反查 awrp_entry_code_p、禁止自行拼接」——注释与代码矛盾，金蝶侧付款计划分录标识是否等于防重键需联调实测 | 高优先 | -| 2 | **项目编码 999 残留**：全部推送链路（应付/应收/付款/预付款/开票申请）仍传测试值 999；A103-3「取项目档案真实编码」的逻辑已注释停用（详见入参映射表 14-#2） | 上线前处理 | -| 3 | **计量单位不送**：分录 DTO 有字段无赋值——需与金蝶确认不送计量单位是否影响单据校验 | 联调确认 | -| 4 | **A301-3 字段待金蝶确认**：`recpaytype_number`(101)/`paymenttype`/`recpayer` 取值口径 | 联调确认 | -| 5 | **A301-2 claimusers 未配置风险**：缺省空串调 A301-2 查不到数据（无报错），需在 Nacos 必配 | 配置项 | -| 6 | **其他链路不校验客商 kingdee_status**：客商未推送/未审核也会带编码推单（软依赖） | 既有风险 | -| 7 | **正式结算单作废未接 checkEditable**：仅靠前端锁状态标签禁用，接口层可绕过 | 建议补拦截 | -| 8 | **failed 重推无次数上限**：`KingdeeAutoSyncRetryTask` 每 10 分钟扫全量 failed，持续失败的单据会反复调金蝶（靠预检防重但不封顶） | 观察线上量 | -| 9 | **付款申请前端单笔「同步金蝶」按钮未绑定**（`handleSyncRow` 死代码）：单笔入口仅剩审批自动同步 | 前端待补 | -| 10 | **旅客运输/代收车船税单据体**：DTO 已建未接（仅 freights 接入） | 按需迭代 | -| 11 | **方案 vs 代码差异（沿旧总纲）**：付款多次下推未实现（单分录单次）；附件已落地（A902 4 链路）✅；收款流水同步已有定时（receiptClaimPush）✅；黑名单 A801-5 已实现 ✅ | — | +| 1 | **A103-1 勾稽键口径**：代码传本地组装的应付防重键，`PaymentApplicationServiceImpl` 注释仍写「A102-4 反查 awrp_entry_code_p、禁止自行拼接」——注释与代码矛盾，金蝶侧付款计划分录标识是否等于防重键需联调实测 | 高优先 | +| 2 | **项目编码 999 残留**：应付/应收/付款/预付款/开票申请链路仍传测试值 999（收票 A303-2 无项目字段） | 上线前处理 | +| 3 | **应付/应收计量单位不送**：分录 DTO 有字段无赋值——需与金蝶确认；收票 A303-2 明细行送镜像数量/单价 | 联调确认 | +| 4 | **先票后款免税/零税率行**：`taxrateid_number` 无法映射，推送时报错人工核实（如业务出现需与金蝶约定编码后放开） | 有意拦截 | +| 5 | **先票后款币别固定 CNY**：收票登记不挂合同后 `currency_number` 固定 CNY，出现外币进项票需补充取值来源 | 上线前确认 | +| 6 | **A303-2 明细时点**：分录取镜像最新值，登记→推送间金蝶侧修正明细行会被跟随；红冲/作废由回写回收兜底 | 联调观察 | +| 7 | **收票反向操作不同步金蝶**：结算单作废/认领移除不调 A302-6 解除指定，需金蝶侧人工解除后重推（已拍板） | 操作约定 | +| 8 | **销方供应商代码依赖客商档案**：`queryCustomerCode` 只按销方名称匹配本地 `blade_customer_archive.supplier_code`（A901-1 建档/同步时落库），不实时调金蝶；客商档案缺数据会推送拦截 | 数据前提 | +| 9 | **A301-1 明细流水号同源性**：`bei_detailid` 须与原 A301-2 `detailid`、合规侧 `fdDetailSerialNumber` 同值，否则 C104-2 定位失败 → C107-1 跳过（需联调真实报文核对） | 高优先 | +| 10 | **合规履约计划金额不回退**：认领 C103-9 累加，作废仅同步 C107-3，不回退履约计划行金额（与改造前口径一致） | 既有口径 | +| 11 | **其他链路不校验客商 kingdee_status**：客商未推送/未审核也会带编码推单（软依赖） | 既有风险 | +| 12 | **正式结算单作废未接 checkEditable**：仅靠前端锁状态标签禁用，接口层可绕过 | 建议补拦截 | +| 13 | **failed 重推无次数上限**：`KingdeeAutoSyncRetryTask` 每 10 分钟扫全量 failed，持续失败的单据会反复调金蝶（靠预检防重但不封顶） | 观察线上量 | +| 14 | **付款申请前端单笔「同步金蝶」按钮未绑定**（`handleSyncRow` 死代码）：单笔入口仅剩审批自动同步 | 前端待补 | +| 15 | **旅客运输/代收车船税单据体**：DTO 已建未接（仅 freights 接入） | 按需迭代 | --- ## 附：文档关系 -- 本文为新总纲（基线 2026-10-13 `805ca9d3`，2026-10-15 增补），替代 09-27 版；单链路细节仍以 `doc/docs/业务流程/` 对应专项文档为深入参考，冲突处以本文 + 当前代码为准。 +- 本文为新总纲（基线 2026-10-31 `933fb37d`，分支 feature/20261031-bfi-收票收款改造），替代 09-27 版；单链路细节仍以 `doc/docs/业务流程/` 对应专项文档为深入参考，冲突处以本文 + 当前代码为准。 - **各推送接口的逐字段入参取值映射（页面字段→表字段/配置对照）见《2026-10-15-金蝶（星瀚）BFI推送入参取值映射表（页面字段-表字段-配置对照）.md》**，其第 14 节含与本文记载不一致的代码级核对结论。 -- 09-27 版中被本文修订的关键结论：A801-3 回写缺陷、票池「实时回源无定时」架构、收款认领「全手动无定时」、分录调试覆盖、物料映射常量、failed 落库口径、A801-5/A801-2/A902「未实现」状态。 +- **收票先票后款专项**：《2026-10-31-先票后款改造方案V2（收票登记A303-2+付款结算单A102-2+A302-6指定应付·实现流程与逻辑）》。 +- **收款流水改造专项**：《2026-10-29-收款流水菜单改造（数据源A301-2改A301-1-认领只登记本地并推送合规C107-1与C107-3作废同步）》《2026-10-29-收款流水认领操作流程（收款金额本地额度·单条批量与作废）》《2026-10-16-收款流水多次认领与作废口径梳理》。 +- 09-27/10-14 版中被本文修订的关键结论：**A301-2/A301-3 链路已下线（10-14 版第 6 节口径作废）**、收票推送终点 pushed + A302-6 后置（10-14 版「同一次推送内串行」作废）、A901-1/A905-3 已实现（10-14 版「未实现」作废）、HCS 付款履约计划推送时点改为金蝶实付后。 diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-同步与推送.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-同步与推送.png deleted file mode 100644 index 80280656..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-同步与推送.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-手动同步流水.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-手动同步流水.png new file mode 100644 index 00000000..c663dc22 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-手动同步流水.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-列表.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-列表.png new file mode 100644 index 00000000..1b51c52e Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-列表.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-查询金蝶认领结果.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-查询金蝶认领结果.png deleted file mode 100644 index 60b481e2..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-查询金蝶认领结果.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/13-收票登记-先票后款表单.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/13-收票登记-先票后款表单.png new file mode 100644 index 00000000..dba51689 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/13-收票登记-先票后款表单.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/14-付款结算单-发票登记.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/14-付款结算单-发票登记.png new file mode 100644 index 00000000..b5402258 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/14-付款结算单-发票登记.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/15-客商档案-供应商编码.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/15-客商档案-供应商编码.png new file mode 100644 index 00000000..c231ebf1 Binary files /dev/null and b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/15-客商档案-供应商编码.png differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-2-公告同步对照.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-2-公告同步对照.png deleted file mode 100644 index 4b16d08d..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-2-公告同步对照.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-认领推送对照.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-认领推送对照.png deleted file mode 100644 index 2ecd50fa..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-认领推送对照.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-金蝶认领结果.png b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-金蝶认领结果.png deleted file mode 100644 index 022c9a96..00000000 Binary files a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-金蝶认领结果.png and /dev/null differ diff --git a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md index 270be3fa..9debf183 100644 --- a/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md +++ b/doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md @@ -1,10 +1,18 @@ # 金蝶（星瀚）BFI 对接操作手册（纯操作版） -> 整理日期：2026-10-14 +> 整理日期：2026-10-14（2026-10-31 修订） > 适用对象：TMS 业务操作人员（财务/业务）、系统管理员、实施运维。 > 本文只讲**怎么操作**：在哪个页面、点什么按钮、前提是什么、成功的标志是什么、失败了怎么处理。 > 接口与代码细节见同目录《2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）》。 +## 修改记录 + +| 日期 | 修订内容 | +|---|---| +| 2026-10-14 | 初版 | +| 2026-10-19 | 核对并补充 4.2 定时任务运转逻辑（cron 默认值、错峰、终态不轮询、防呆与自愈行为） | +| 2026-10-31 | ① **3.6 收票登记改「先票后款」**：收票登记只选票推金蝶收票单（不再关联结算单，新增手选结算组织/发票明细），「认领收票单+指定应付」移到付款结算单（编辑器选收票单 / 行内「发票登记」）；② **3.7 收款流水与认领改口径**：数据源改金蝶收款单（A301-1）、「推送金蝶」「查询金蝶认领结果」按钮下线、认领只登记本地、作废同步合同合规；③ **3.1 客商建档**：新增供应商编码自动获取与收款信息开户行带出联行号操作；④ 2 节准备事项、4 节定时任务清单、5 节 FAQ、6 节速查表同步更新；⑤ 截图更新（收票登记先票后款表单、发票登记弹窗、收款流水新列表、认领记录、客商供应商编码） | + --- ## 1. 全局须知 @@ -23,10 +31,11 @@ | unsynced | 未推送金蝶 | 会（推送成功变 synced） | | synced | 已推送金蝶，金蝶受理 | 会（继续走后续状态） | | failed | 推送失败（有失败原因） | 会（重推成功变 synced） | +| pushed | 金蝶收票单已生成（收票推送到此为止）；已推送金蝶（收款流水） | 会（收票被付款结算单认领且应付单推送后变 assigned；收款流水状态随同步刷新） | | paying | 金蝶付款中（仅付款申请） | 会（付款完成变 paid） | | paid / closed | 已付款 / 已关闭（终态） | 不变 | | invoiced | 已开票（终态，开票申请） | 不变 | -| assigned | 已指定应付（终态，收票） | 不变 | +| assigned | 已指定应付（终态，收票——由付款结算单侧认领并在应付单推送后指定） | 不变 | | exist | 金蝶已有该客商且审核通过（终态，客商） | 不变 | ### 1.2 「金蝶锁定」标签是什么 @@ -36,7 +45,7 @@ ### 1.3 两条推送路径 - **自动**：审批「通过」时系统自动推送金蝶（需管理员开启对应开关，见第 4 节）；开启后审批接口会直接返回推送结果，失败时页面提示「审批通过，但自动同步金蝶失败：xxx」。 -- **手动**：列表勾选单据点工具栏「同步金蝶 / 批量同步 / 推送金蝶」按钮。开关没开时用这条路径。 +- **手动**：列表勾选单据点工具栏「同步金蝶 / 批量同步」按钮。开关没开时用这条路径。（收款流水认领没有推送动作——认领只登记本地并自动推合同合规，见 3.7。） 两条路径效果完全一样，重复点不会重复推送（系统自动查重）。 @@ -49,7 +58,7 @@ | 1 | 部门金蝶组织编码 | 管理员 | 在部门档案维护「金蝶组织编码」字段 | 该部门单据推送时直接报错拦截 | | 2 | 客商收款账户联行号 | 财务 | 客商档案维护收款账户（账号/开户行，**联行号必填**） | 付款推送、客商推送报错拦截 | | 3 | 主数据初始化 SQL | 运维 | 执行 `doc/sql/transport/` 下金蝶相关脚本（计量单位等主数据、认领表、10-13 迁移脚本 `lqj/`） | 对应链路数据缺失 | -| 4 | 认领人配置 | 运维 | Nacos 配 `thirdParty.bfi.claimAnnounce.claimusers`（值须与金蝶认领公告的认领人一致） | 收款流水同步查不到数据（不报错） | +| 4 | 平台公司金蝶组织编码 | 管理员 | 组织管理维护「是否平台公司=是」并填**金蝶编码** | 收款流水同步直接报错拦截；收票按手选部门上溯平台公司取组织编码失败也会推送拦截 | | 5 | 票池票种白名单 | 运维 | Nacos 配 `thirdParty.bfi.invoiceReceipt.invoiceTypes`（要同步的发票种类编码，逗号分隔） | 票池同步不到对应票种 | | 6 | 物料映射 | 运维 | Nacos 配 `thirdparty.bfi.material.*`（有默认值，建议显式确认） | 推送报「运输方式未配置」类拦截 | | 7 | 定时任务开关 | 运维 | 按第 4 节清单逐项开启 | 只能全靠手动按钮 | @@ -66,8 +75,10 @@ ![客商档案列表：行内「同步金蝶」链接仅在审批通过且推送失败（failed）的单据上显示；审批通过的客商由系统自动推送](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/01-客商档案列表.png) 1. 点「新增」，录入**统一社会信用代码**（满 18 位自动查金蝶回填工商信息并锁定相关字段）。 + - 表单「供应商编码」字段自动从金蝶获取（金蝶侧建档/同步后回显），无需手填。 - 若提示金蝶侧该客商「审核中」——等金蝶审核完再保存/推送。 -2. 维护**收款账户（联行号必填）**和发票信息（纳税人识别号用于黑名单校验）。 +2. 维护**收款账户**和发票信息（纳税人识别号用于黑名单校验）。 + - 收款信息「开户行」输入后失焦，系统自动按行名从金蝶**带出联行号**；带不出时可手动填写，保存时系统会按联行号反查金蝶校验，查不到会拦截保存。 3. 提交审批：系统自动做**黑名单校验**。 - 提交被拦「命中黑名单」→ 该客商为国资委黑名单 A 类，**不能提交**，走线下处置。 4. 审批「通过」→ 系统自动推送金蝶 → 列表 `kingdee_status` 变 **synced**。 @@ -80,7 +91,9 @@ ![TMS 客商档案与金蝶客户档案对照：编码一致、以统一社会信用代码为关联键](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a902-客商编码对照.png) -![新增客商档案：统一社会信用代码录入满 18 位自动到金蝶查询并回填工商信息](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/02-客商档案新增-信用代码自动查询.png) +![新增客商档案：统一社会信用代码录入满 18 位自动到金蝶查询并回填工商信息；「供应商编码」字段由系统自动获取（金蝶 A901-1）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/02-客商档案新增-信用代码自动查询.png) + +![客商档案表单：基础信息含「供应商编码」（金蝶供应商编码，系统自动获取）；收款信息 tab 维护开户行/联行号（开户行失焦按行名从金蝶带出联行号，保存前按行号校验）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/15-客商档案-供应商编码.png) > 注意：审批通过后的**档案变更不会重新推送金蝶**。改了信用代码等关键信息需人工确认金蝶侧一致性。 @@ -115,7 +128,7 @@ - 按钮是单选操作，一次推一张。 3. 成功标志：列表出现**金蝶单号**，状态变 **synced**，并出现「金蝶锁定中」标签。 4. 失败处理：状态变 failed → 看失败原因 → 常见原因： - - 「请先同步金蝶应付单」类 → 关联结算单还没推（应付/应收/收票有先后依赖，见 3.6）； + - 「请先同步金蝶应付单」类 → 关联结算单还没推（付款/开票依赖结算单先推，见 3.6 后款步骤）； - 客商编码取不到 → 先完成 3.1； - 部门金蝶组织编码缺失 → 找管理员维护。 5. 纠偏：如果怀疑推送实际成功但本地状态没更新，等定时勾稽（或联系运维手动触发），系统会自动核对金蝶侧并纠正状态/补单号。 @@ -174,63 +187,75 @@ ![开票申请按发票张次拆分：TMS 开票内容第1张/第2张分别生成金蝶开票申请单，购销方、不含税金额逐项对应](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a303-1-开票张次对照.png) -### 3.6 收票登记（进项发票） +### 3.6 收票登记（进项发票·先票后款） -**页面：收付款管理 → 收票管理** +**页面：收付款管理 → 收票管理（先票）+ 结算管理 → 付款结算单（后款）** -![收票管理：工具栏「批量同步」推送收票单并指定应付](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/06-收票管理-批量同步.png) +收票改成**两段式**： -**硬性前提**：一张票只能登记一次；推送前必须已分摊到**恰好一张审批通过的应付结算单**，且该结算单已推送金蝶。 +- **先票（收票登记）**：只做「收票」——从金蝶票池选发票推金蝶收票单，**不再关联结算单/合同**； +- **后款（付款结算单）**：在付款结算单上认领收票单，应付单推送金蝶后系统自动完成「指定应付」。 -1. 选票：表单里点发票号放大镜 → 弹出「查询金蝶票据池」→ 勾选 → 确认（带出票面信息）。 +![收票管理：工具栏「批量同步」推送收票单（终态 pushed）；不再需要先关联结算单](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/06-收票管理-批量同步.png) + +**第一步：先票——收票登记** + +**硬性前提**：一张票只能登记一次；表单「结算组织」必选（一般选合同的承办部门）；发票销方需已在客商建档（系统按销方名称取金蝶供应商代码，取不到推送会被拦）。 + +1. 选票：点「新增」→ 表单里点发票号放大镜 → 弹出「查询金蝶票据池」→ 勾选 → 确认（带出票面信息，并自动带出**发票明细**区块）。 ![查询金蝶票据池弹窗：按发票号/日期/税号/票种等筛选；每行可「查看/下载」发票原件（PDF 优先）；点「选择」带出到表单](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/07-收票登记-金蝶票池选票.png) - - ![img.png](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/img.png) + + ![金蝶侧收票管理·全票池查询：TMS 票池选票的数据源头](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/img.png) - 票池数据来自定时同步（默认每 30 分钟）；票号精确搜索时若本地没有会**自动去金蝶现查**。 - 查不到票 → 等同步或让运维检查票种白名单配置/手动触发同步（见 4.2）。 -2. 保存：系统自动**重查金蝶票池校验可用性**——票已被别人登记/认领/红冲/作废会保存失败并提示原因。 -3. 分摊应付结算单后提交审批。 -4. 推送：审批「通过」自动推送，或勾选 → 工具栏「批量同步」。 -5. 状态流转：synced→（系统内）→ **pushed**（金蝶收票单已生成）→ **assigned**（已指定应付，终态）。 - - 卡在 pushed 不用管：定时任务会自动补发「指定应付」。 +2. 选**结算组织**（合同承办部门）——推送金蝶时按它确定结算组织编码，必填。 +3. 保存：系统自动**重查金蝶票池校验可用性**——票已被别人登记/认领/红冲/作废会保存失败并提示原因。 +4. 提交审批 → 审批「通过」自动推送，或勾选 → 工具栏「批量同步」。 +5. 成功标志：状态 **pushed**（金蝶收票单已生成）。**到这里收票就完成了**——指定应付由付款结算单负责（见第二步）。 - failed 且提示发票状态异常（红冲/作废）→ 该票在金蝶已不可用，需人工处理，不要重推。 + - failed 且提示「供应商代码/往来户」→ 发票销方未建档或未同步金蝶，先完成 3.1 客商建档再重推。 + - failed 且提示免税/零税率行 → 该票存在系统无法映射的税率行，人工核实后联系金蝶方约定编码。 6. 附件：表单附件区可查看/下载发票原件（系统自动从金蝶取，PDF 优先）。 +![收票登记表单（先票后款改造后）：发票号码选金蝶票据池发票带出票面与「发票明细」；新增「结算组织（合同承办部门）」必选；「结算信息」区只读——认领关系由付款结算单侧维护](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/13-收票登记-先票后款表单.png) + +**第二步：后款——付款结算单认领收票单并指定应付** + +前提：收票登记已审批通过且已推送（pushed）；付款结算单（正式结算单应付 Tab）为审批通过状态。 + +1. **编辑/新增时认领**：结算单编辑页发票信息区点「选择收票单」→ 候选为**审批通过且未被认领**的收票登记 → 选择后按**发票金额全额认领**（不再校验发票合计是否超过结算金额）→ 保存。 +2. **审批后补认领（发票登记）**：列表行内「发票登记」→ 选收票单 → 保存认领 → 弹窗「是否将发票匹配数据推送金蝶?」→ 确认后系统调金蝶「指定应付」。 + ![付款结算单「发票登记」弹窗：结算基本信息（已匹配发票金额/金蝶同步状态）+ 认领收票单（选择收票单 → 发票号/开票单位（销方）/发票金额/匹配结算单金额）→ 保存认领](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/14-付款结算单-发票登记.png) +3. **系统自动指定应付**：结算单推送金蝶（应付单生成）后，系统对**本单认领且已推送**的收票单逐张执行「指定应付」，收票状态推进为 **assigned**（已指定应付，终态）。指定失败不影响结算单推送，定时任务会自动补发。 + - 一张收票单只能被一张付款结算单认领（重复认领会拦截）。 + - 收票单一直卡在 pushed：说明还没被任何付款结算单认领（或认领它的结算单应付单还没推送成功），认领并推送后自动接上。 + - 结算单作废/移除认领**不会**自动通知金蝶解除指定，需金蝶侧人工处理后重推。 + 推送成功后金蝶侧状态与效果（供确认推送结果时对照）： ![收票管理列表「金蝶状态」列：已指定应付（终态）/推送失败（含失败原因）/未推送](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-收票金蝶状态列表.png) ![推送的单据附件已上传到金蝶侧单据的「附件」区](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a902-附件上传金蝶侧.png) -![正式结算单详情「发票信息」区：认领的发票可 查看/下载（系统从金蝶取原件，PDF 优先）；付款信息区回显付款申请金蝶单号](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a801-2-发票查看下载.png) +![结算单详情「发票信息」区：认领的发票可 查看/下载（系统从金蝶取原件，PDF 优先）；付款信息区回显付款申请金蝶单号](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a801-2-发票查看下载.png) -### 3.7 收款认领 +### 3.7 收款流水与认领 **页面：收付款管理 → 收款流水、认领记录** -这是「金蝶收到钱 → TMS 认领到结算单 → 回推金蝶」的流程： +> 2026-10-29 口径变更：数据源改为**金蝶收款单（A301-1 收款单查询）**；认领**只登记本地，不再推送金蝶**（金蝶收款单在认领前就已存在）；认领后自动推送**合同合规系统**（履约计划/认领记录/履约流水），作废自动同步合规作废。原「推送金蝶」「查询金蝶认领结果」按钮已下线。 -1. **同步流水**：收款流水页 → 工具栏「**手动同步流水**」→ 拉取金蝶认领公告。 - ![收款流水：工具栏「手动同步流水」拉取金蝶认领公告、「批量认领」进入认领；列表展示认领通知单/付款人/对方户名等](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-同步与推送.png) - - 查不到数据先检查认领人配置（第 2 节 #4）。 -2. **认领**：点流水进入详情（或工具栏「批量认领」）→ 选择**审批通过且已推送金蝶的应收结算单**、填分摊金额 → 确认。 - - 认领此时只落本地，不推金蝶。 - - 分摊总额不能超过该流水未认领金额。 -3. **推送金蝶**： - - 手动：流水详情/符合条件的行内「推送金蝶」； - - 自动：定时任务（默认每 10 分钟，开关开启时）自动推送认领完成的流水。 - - 成功标志：流水显示金蝶收款单号、推送状态 pushed。 -4. **回写结果**：认领记录页 → 工具栏「**查询金蝶认领结果**」→ 状态推进 approved（金蝶已审核）/ **received**（已收款，终态）。 - ![认领记录：工具栏「查询金蝶认领结果」回写金蝶收款单状态](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-查询金蝶认领结果.png) -5. **作废限制**：已推送金蝶的认领**不能作废**（提示去金蝶侧人工处置）。未推送的可以作废。 - -推送成功后金蝶侧效果（供确认推送结果时对照）： - -![金蝶认领公告与 TMS 收款流水对照：「手动同步流水」拉取的就是金蝶认领公告列表里的 RLTZ 通知单](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-2-公告同步对照.png) - -![TMS 认领记录推送后，金蝶「认领处理列表」生成对应认领单（认领通知单单号一致）](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-认领推送对照.png) - -![金蝶认领单详情：认领结果行的核心单据编号=TMS 分摊结算单对应的金蝶单据](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/bfi-effect-a301-3-金蝶认领结果.png) +1. **同步流水**：收款流水页 → 工具栏「**手动同步流水**」→ 拉取金蝶收款单（按业务日期窗口，默认今天倒推 60 天，全公司口径）。 + ![收款流水：工具栏「手动同步流水」拉取金蝶收款单、「批量认领」进入认领；列表展示收款单号（即金蝶收款单号）/收款金额（认领上限）/未匹配金额（仅参考）等，无推送相关列](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/08-收款流水-手动同步流水.png) + - 报错「组织管理中未维护平台公司金蝶编码」→ 找管理员维护组织档案（第 2 节 #4）。 + - 需要更早的历史流水 → 让运维调大同步窗口天数配置后重新同步。 +2. **认领**：点流水「认领」进入详情（或勾选多条「批量认领」，要求同付款人+对方账号）→ 选择**审批通过的应收结算单**、填分摊金额 → 确认。 + - 认领只落本地，不推金蝶；认领后系统自动把本次认领推送到**合同合规系统**（失败只记标记，不影响认领）。 + - 分摊总额不能超过「剩余可认领金额」（=收款金额−已认领金额）；「未匹配金额」是金蝶参考值，**为 0 不影响认领**。 +3. **查看进度**：金蝶收款单状态（已推送/审核通过/已收款）随每次「手动同步流水」自动刷新，无需回写操作。 +4. **作废**：认领记录页 → 本人记录行内「作废」→ 确认（提示含"同步作废合同合规系统认领记录"）→ 本地回退金额 + 自动同步合规作废。 + ![认领记录：仅显示本人认领记录；行内「作废」回退金额并同步作废合同合规系统认领记录；原「查询金蝶认领结果」按钮已删除](./2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.assets/09-认领记录-列表.png) + - 作废不会影响金蝶收款单本身（金蝶侧红冲由财务人工处置）。 ### 3.8 汇率维护（非人民币结算） @@ -251,21 +276,22 @@ | 任务 | 干什么 | 开关键 | cron 键（默认值） | 手动替代按钮 | |---|---|---|---|---| | 付款结果回写 | 付款状态（paid/closed）+ 付款记录/凭证回写；顺带应收勾稽纠偏、开票结果回写 | `thirdParty.bfi.payResult.syncEnabled`（样例已开） | `…payResult.cron`（默认 `0 1/10 * * * ?`） | 付款「同步付款结果」、开票结果手动端点、结算勾稽手动端点 | -| 收票结果回写 | 收票单状态回写、pushed 断点补发指定应付 | `…receivedInvoiceResult.syncEnabled` | `…receivedInvoiceResult.cron`（默认 `0 8/10 * * * ?`） | 收票「同步金蝶结果」 | +| 收票结果回写 | 收票单状态回写、pushed+已认领自动补发指定应付 | `…receivedInvoiceResult.syncEnabled` | `…receivedInvoiceResult.cron`（默认 `0 8/10 * * * ?`） | 收票「同步金蝶结果」 | | 客商同步 | 金蝶审核状态复查（synced→exist）、停用联动、failed 重推 | `…customer.syncEnabled` | `…customer.cron`（默认 `0 0 2 * * ?`） | 客商「同步金蝶」 | -| 收款认领推送 | 自动推送认领完成的流水到金蝶 | `…receiptClaimPush.syncEnabled` | `…receiptClaimPush.cron`（默认 `0 4/10 * * * ?`） | 流水行内「推送金蝶」 | -| 全票池同步 | 拉金蝶全票池发票到本地镜像、补绑定 | `…invoiceReceipt.syncEnabled` | `…invoiceReceipt.cron`（默认 `0 16/30 * * * ?`） | 手动端点 `POST /invoice-receipt/sync-invoice-pool` | +| 全票池同步 | 拉金蝶全票池发票到本地镜像（含发票明细）、补绑定 | `…invoiceReceipt.syncEnabled` | `…invoiceReceipt.cron`（默认 `0 16/30 * * * ?`） | 手动端点 `POST /invoice-receipt/sync-invoice-pool` | | failed 重推 | 自动重推所有推送失败的结算/付款/开票/收票单 | `…autoSync.retryEnabled` | `…autoSync.retryCron`（默认 `0 5/10 * * * ?`） | 各页面「同步金蝶」 | | 锁单补偿 | 推送成功但金蝶锁定失败的自动补锁（≤5 次） | `…billLock.retryEnabled` | `…billLock.retryCron`（默认 `0 2/5 * * * ?`） | 手动端点 `POST /formal-settlement/retry-kingdee-bill-lock` | +> 收款认领推送定时任务（原 `receiptClaimPush`）已于 2026-10-29 随 A301-3 链路下线删除；相关 Nacos 配置 `claimAnnounce.*`、`receiptClaimPush.*` 可清理。 + ### 4.2 各任务的运转逻辑 **共性规则（先读这个）** -- **终态不轮询**：付款 paid（已付款）/closed（已关闭）、开票 invoiced（已开票）、收票 assigned（已指定应付）、客商 exist（金蝶已审核）、认领流水 pushed（已推送金蝶）后自动退出扫描范围——任务只处理「还没走完」的单据，越跑越轻，不会重复处理。 +- **终态不轮询**：付款 paid（已付款）/closed（已关闭）、开票 invoiced（已开票）、客商 exist（金蝶已审核）后自动退出扫描范围；收票 assigned（已指定应付，终态）仅剩补登单号——任务只处理「还没走完」的单据，越跑越轻，不会重复处理。 - **定时与手动同一套逻辑**：每个任务与它的「手动替代按钮」调用同一个服务方法，效果完全一致；区别只是触发方式。 -- **单条失败不拖批次**：一轮里某条单据失败只记录原因，同批其余照常处理；失败的下轮自动再试（兜底见 ⑥ failed 重推）。 -- **默认执行时间错峰**（付款 ：01、认领 ：04、failed 重推 ：05、收票 ：08、锁补偿每 5 分钟的 ：02、票池每 30 分钟的 ：16），互不挤占；自行改 cron 时建议保留错峰。 +- **单条失败不拖批次**：一轮里某条单据失败只记录原因，同批其余照常处理；失败的下轮自动再试（兜底见 ⑤ failed 重推）。 +- **默认执行时间错峰**（付款 ：01、failed 重推 ：05、收票 ：08、锁补偿每 5 分钟的 ：02、票池每 30 分钟的 ：16），互不挤占；自行改 cron 时建议保留错峰。 **① 付款结果回写（10 分钟）** 扫「审批通过且已推送 / 付款中 / 推送失败」的付款申请 → 到金蝶查付款申请单和付款处理单 → 推进 synced（已推送受理）→ paying（金蝶付款中）→ **paid（已付款）/ closed（已关闭）**，paid 时回写付款记录/凭证，并联动刷新预结算垫资、结算付款记录（3.4 第 3 步的「正常等定时回写」就是它）。 @@ -276,7 +302,7 @@ **② 收票结果回写（10 分钟）** 扫 pushed（金蝶收票单已生成）/ assigned（已指定应付）的收票登记，按近 **30 天**回看窗口查金蝶收票单，一轮处理三种情况： - 票在金蝶被作废/红冲 → 置 failed（推送失败）并提示人工处理（**不要重推**，见 3.6）； -- 卡在 pushed → 自动补发「指定应付」推进 **assigned（已指定应付，终态）**（3.6 说的「卡在 pushed 不用管」就是它）； +- pushed 且**已被付款结算单认领** → 自动补发「指定应付」推进 **assigned（已指定应付，终态）**；pushed 且未被认领 → 跳过不动（认领后自动接上，见 3.6 第二步）； - assigned 但缺金蝶收票单号 → 自动补登单号。 窗口内查不到的保持现状不动（不判删除），由人工重推兜底。 @@ -286,17 +312,14 @@ - **已推送（synced，已推送受理）** → 金蝶审核通过自动升级 **exist（金蝶已审核，终态）**（3.1 第 5 步的定时升级就是它）； - **金蝶侧停用（enable=0）** → TMS 档案联动停用；金蝶恢复可用**不会**自动启用（单向联动，需人工启用）。 -**④ 收款认领推送（10 分钟）** -扫「认领完成（claimed）且未推送/推送失败」的收款流水 → 按认领人逐人拉最新认领公告**对账**（本地认领金额与公告未认领金额一致才推）→ 推送成功回写金蝶收款单号、流水置 **pushed（已推送金蝶）**（3.7 第 3 步的「自动」就是它）。失败的下一轮自动重试，防重码按分摊结算单生成、重试不变，不会在金蝶重复生成收款单。 +**④ 全票池同步（30 分钟）** +按近 **30 天**增量窗口分页拉取金蝶全票池发票到本地镜像表（含发票明细行），收票选票、发票明细带出、票池查询全部走本地镜像——所以**刚在金蝶开的票要等同步后才能选到**；急用可让运维手动触发同步端点，或用票号精确搜索（会自动去金蝶现查，见 3.6）。 -**⑤ 全票池同步（30 分钟）** -按近 **30 天**增量窗口分页拉取金蝶全票池发票到本地镜像表，收票选票、票池查询全部走本地镜像——所以**刚在金蝶开的票要等同步后才能选到**；急用可让运维手动触发同步端点，或用票号精确搜索（会自动去金蝶现查，见 3.6）。 - -**⑥ failed 重推（10 分钟）** -只重推 **failed（推送失败）** 单据（结算 → 付款 → 开票 → 收票四个域依次处理）；**unsynced（审批通过但从未推送）不会自动推**——历史存量单不会被上线后批量补推，仍走手动按钮。前置没就绪（如上游应付单还没生成）会再次 failed、下轮继续；前置就绪后自动续推成功。 +**⑤ failed 重推（10 分钟）** +只重推 **failed（推送失败）** 单据（结算 → 付款 → 开票 → 收票四个域依次处理）；**unsynced（审批通过但从未推送）不会自动推**——历史存量单不会被上线后批量补推，仍走手动按钮。前置没就绪（如销方供应商代码缺失、镜像明细缺失）会再次 failed、下轮继续；前置就绪后自动续推成功。 ⚠️ 重推**没有次数上限**：根因不修（联行号缺失、组织编码缺失等）会每 10 分钟失败一次刷日志，修复根因是唯一正解（呼应 4.4）。 -**⑦ 锁单补偿（5 分钟）** +**⑥ 锁单补偿（5 分钟）** 扫「推送成功但金蝶锁定失败」的锁记录，重试加锁，**最多 5 次**；超过 5 次放弃，需运维调手动补偿端点 `POST /formal-settlement/retry-kingdee-bill-lock`（对应 FAQ 的「锁定失败」标签）。 ### 4.3 审批自动同步开关（按业务域独立） @@ -317,7 +340,7 @@ |---|---|---| | 推送结算单不带汇率 | 正式结算单没维护汇率（预结算单的汇率**不自动继承**到正式结算单） | 在正式结算单编辑页重选汇率日期自动带出后再推 | | 推送报「客商编码」类错误 | 客商未推送金蝶或档案缺数据 | 先完成客商同步（3.1），再推单据 | -| 推送报「请先同步金蝶应付单/应收单」 | 前置单据未推送 | 顺序：结算单(应付/应收) → 付款/开票/收票；先把前置结算单推送 | +| 推送报「请先同步金蝶应付单/应收单」 | 前置单据未推送 | 顺序：结算单(应付/应收) → 付款/开票（收票登记已不依赖结算单，仅付款结算单指定应付需要应付单先推送） | | 推送报组织/部门编码类错误 | 部门没维护金蝶组织编码 | 管理员补维护后重推 | | 推送报联行号类错误 | 客商收款账户联行号缺失 | 财务补维护收款账户后重推 | | 提交客商审批被拦黑名单 | 纳税人识别号命中国资委黑名单（A 类） | 不可提交，走线下处置；B 类提示仅告警默认放行 | @@ -328,11 +351,14 @@ | 开票申请 synced 但没发票信息 | 开票结果未回写 | 等定时/联系运维手动触发；确认金蝶票易通已开票 | | 票池选票查不到 | 镜像未同步到该票种 | 检查票种白名单配置；运维手动触发全票池同步；票号精确搜索可触发自动现查 | | 保存收票登记被拦「可用金额为0」 | 票已被占用/认领/红冲 | 换票或在金蝶确认票据状态 | -| 收票卡在 pushed 不动 | 「指定应付」步骤未完成 | 开启收票回写定时自动补发，或重推一次 | -| 收款流水同步为空 | 认领人配置与金蝶不一致 | 检查 Nacos `claimAnnounce.claimusers` | -| 认领推送报「认领公告id缺失」 | 流水没同步过就认领了 | 先「流水同步」再操作 | -| 认领推送报金蝶内码缺失 | 分摊的结算单没推送金蝶 | 先完成结算单(应收)推送（3.3） | -| 已推送认领想作废 | 金蝶已生成收款单 | 不能作废，去金蝶侧人工处置 | +| 收票推送报「供应商代码/往来户」类错误 | 发票销方未建档或未同步金蝶（取不到金蝶供应商代码） | 先完成客商建档与同步（3.1），再重推 | +| 收票推送报免税/零税率行 | 系统无法映射该税率行编码 | 人工核实票面，联系金蝶方约定编码后放开 | +| 收票推送报结算组织/平台公司类错误 | 手选部门上溯不到带金蝶编码的平台公司 | 找管理员维护组织金蝶编码后重推 | +| 收票卡在 pushed 不动 | 未被付款结算单认领，或认领它的结算单应付单未推送成功 | 在付款结算单「发票登记」/编辑认领收票单并确保结算单已 synced；已认领的由定时自动补发指定 | +| 认领收票单被拦「一张收票单只能被一张付款结算单认领」 | 已被其他有效付款结算单认领 | 先在原结算单移除认领（金蝶侧人工解除指定）再认领 | +| 收款流水同步为空/报组织编码错误 | 组织管理未维护「平台公司」金蝶编码，或窗口内无数据 | 找管理员维护组织金蝶编码；需要更早流水时调大同步窗口天数配置 | +| 认领/作废后合规侧没有记录 | 合同合规推送失败（只落标记不重试） | 让运维查合规推送记录失败原因，人工在合规侧补录；认领/作废本身不受影响 | +| 想作废认领 | — | 认领记录页本人记录直接「作废」：本地回退金额并自动同步合规作废；金蝶收款单本身不受影响（红冲由金蝶财务人工处置） | | 断网/金蝶宕机期间推了一半 | 部分单据 failed | 恢复后 failed 重推任务（或手动）自动续推，系统查重不会重复生成金蝶单据 | --- @@ -341,28 +367,31 @@ | 页面 | 按钮/操作 | 作用 | |---|---|---| -| 客商档案 | （表单）录信用代码 | 自动查金蝶回填工商信息 | +| 客商档案 | （表单）录信用代码 | 自动查金蝶回填工商信息 + 金蝶供应商编码 | +| 客商档案 | （表单）收款信息开户行 | 失焦按行名从金蝶带出联行号；保存前按行号校验 | | 客商档案 | 行内「同步金蝶」 | 失败重推客商 | | 预结算单 | 工具栏「预付申请」/「尾款结算」 | 审批通过后发起进度预付 / 生成尾款结算号（预结算本身不推金蝶） | | 正式结算单 | 新建时选择来源预结算单 | 预结算转正式结算（转后预结算锁定） | | 正式结算单 | 工具栏「同步金蝶」（单选） | 推送应付/应收单到金蝶 | | 正式结算单 | （编辑）汇率日期 | 自动带出金蝶汇率 | -| 正式结算单 | （编辑）发票认领「查询/确认识领」 | 从金蝶票池选票认领到结算单 | +| 付款结算单 | （编辑）发票信息「选择收票单」 | 候选=审批通过未认领的收票登记，全额认领 | +| 付款结算单 | 行内「发票登记」 | 审批后补认领收票单，可确认推送「指定应付」 | | 付款申请 | 工具栏「批量同步」 | 下推付款申请/预付款到金蝶 | | 付款申请 | 工具栏「同步付款结果」 | 立即回写付款状态与付款记录 | | 开票申请 | 工具栏「批量同步」 | 按发票张次推送开票申请 | -| 收票登记 | （表单）发票号放大镜 | 从金蝶票池选票 | -| 收票登记 | 工具栏「批量同步」 | 推送收票单+指定应付 | +| 收票登记 | （表单）发票号放大镜 | 从金蝶票池选票（带出发票明细） | +| 收票登记 | （表单）结算组织 | 手选合同承办部门（必选） | +| 收票登记 | 工具栏「批量同步」 | 推送金蝶收票单（终态 pushed；指定应付由付款结算单完成） | | 收票登记 | （表单）附件查看/下载 | 从金蝶取发票原件（PDF 优先） | -| 收款流水 | 工具栏「手动同步流水」 | 拉取金蝶认领公告 | -| 收款流水 | （详情/工具栏「批量认领」）认领 | 本地认领到结算单 | -| 收款流水 | 行内「推送金蝶」 | 推送认领结果到金蝶 | -| 认领记录 | 工具栏「查询金蝶认领结果」 | 回写金蝶收款单状态 | +| 收款流水 | 工具栏「手动同步流水」 | 拉取金蝶收款单（A301-1，窗口默认 60 天） | +| 收款流水 | （详情/工具栏「批量认领」）认领 | 本地认领到结算单（不推金蝶，自动推合同合规） | +| 认领记录 | 行内「作废」 | 回退认领金额并同步作废合同合规系统认领记录 | | 运维专用 | `POST /invoice-receipt/sync-invoice-pool` | 手动全票池同步 | | 运维专用 | `POST /formal-settlement/retry-kingdee-bill-lock` | 手动补偿锁单 | | 运维专用 | `POST /formal-settlement/sync-kingdee-ar-result` | 手动应收勾稽纠偏 | | 运维专用 | `POST /invoice-application/sync-kingdee-invoice-result` | 手动开票结果回写 | +| 运维专用 | `POST /formal-settlement/invoice-assign-kingdee` | 手动触发结算单认领收票单的指定应付 | --- -> 本文基于 2026-10-14 代码现状整理；2026-10-19 依据当前代码核对并补充 4.2 定时任务运转逻辑（cron 默认值、错峰、终态不轮询、防呆与自愈行为）。系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档的更新说明。 +> 本文基于 2026-10-14 代码现状整理；2026-10-19 核对补充 4.2 定时任务运转逻辑；**2026-10-31 按先票后款改造（收票登记两段式）与收款流水 A301-1 改造修订 3.1/3.6/3.7、4 节、5 节、6 节**。系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档的更新说明。