docs: 金蝶（星瀚）BFI与合同合规系统（HCS）组合操作手册修订

- 合并 HCS 操作内容（项目立项/合同/特批/客商风险/履约四场景），项目与合同置于客商章节后
- 新增第 2 节全链路总览：12 条环节流程链（【系统】→步骤→▼，含落库表与接口号）与通用规则
- 场景分流/拦截提示原文/解决方法在 4.x 对应小节补齐
- 第 5 节新增 5.5 HCS 定时任务与六任务逐项运转逻辑
- 按 11-04/11-05 代码更新：应付单 preentry 预付抵扣分录、分录送税率、公司代码术语、已指定应付列范围、付款处理单内码回写、新增准备配置项（税率映射/推送内容开关/接口超时）

doc/docs/业务流程/2026-10-14-金蝶（星瀚）BFI对接操作手册（纯操作版）.md

@@ -16,6 +16,7 @@
 | 2026-10-31 | ① 收票登记改「先票后款」：收票登记只选票推金蝶收票单（不再关联结算单，新增手选结算组织/发票明细），「认领收票单+指定应付」移到付款结算单；② 收款流水与认领改口径：数据源改金蝶收款单（A301-1）、「推送金蝶」「查询金蝶认领结果」按钮下线、认领只登记本地、作废同步合同合规；③ 客商建档新增供应商编码自动获取与收款信息开户行带出联行号操作；④ 准备事项、定时任务清单、FAQ、速查表同步更新 |
 | 2026-11-03 | **四文档汇总修订（合并《2026-10-17 结算调整单》《2026-10-18 预付与项目预付》两本手册 + 按 11-01/11-02 代码与界面更新）**：① 全篇菜单更名对齐系统实际（预付结算单/付款结算单/收款结算单，新增 1.4 页面名称对照）；② 1.1 状态表补页面显示别名与「已指定应付」列；③ 新增 4.5 进度预付、4.6 项目预付（含客商风险与付款特批）、4.7 项目预付核销、4.8 尾款结算、4.12 结算调整单、4.16 作废与撤销；④ 开票申请按「剩余可开票金额」累计控制（放开必须未开票限制）、分摊发票金额系统自动分摊；⑤ **收票后款认领按 11-02 改造更新**：发票登记移到付款结算单工具栏、弹窗回显已认领收票单、「匹配结算单金额」支持手动修改、查看页新增「是否已指定应付」列与「重新推送」入口、列表指定失败悬浮展示原因；⑥ **A302-6 指定应付定时自动补偿改开关控制（默认关闭）改人工兜底**；⑦ 4/5/6 节同步更新，截图全面更新（付款结算单列表与发票登记弹窗、选择收票单、查看页发票信息、指定失败悬浮、付款管理已指定应付列、收票登记表单去税率） |
 | 2026-11-04 | **合并合同系统（HCS）操作内容，形成金蝶+合同系统组合手册（并入《HCS合同管理操作手册（纯操作版）》《履约计划与履约记录四场景业务说明》《客商黑名单与风险等级业务说明》）**：① **新增第 2 节「全链路总览」**（**12 条环节流程链**【系统】→步骤→▼ 格式逐环节梳理、两条通用规则与三条先后依赖；场景分流/拦截提示原文/成功提示在 4.x 对应小节体现），原第 2–6 节顺延为第 3–7 节，日常操作小节相应重排为 4.1–4.18；② 新增 1.5–1.8（HCS 是什么与合规状态、特批状态、三条推送路径、客商风险与黑名单口径），1.4 页面对照补客商/项目/合同顺序；③ 第 3 节新增合同系统准备清单；④ **项目立项推合规、合同管理与推送合规（含合同特批/变更/归档）置于 4.2/4.3（客商章节后）**；付款特批操作细节不单独成节（`spec-pay.enabled` 开关口径保留在 4.6）；⑤ 新增 4.17 客商风险查看与筛选、4.18 履约计划与履约记录四场景；⑥ 4.6/4.10/4.14 补合同系统联动与金蝶实付门禁口径；⑦ 第 5 节新增 5.5 HCS 定时任务与开关及**六任务逐项运转逻辑**（判重/更新分流、特批兜底查询、金蝶实付门禁、开票自愈、收票合同回溯、风险分批刷新）；⑧ 第 6/7 节补 HCS 常见问题与操作入口；⑨ 合同支持甲乙丙多方客商（2026-11-02）已写入 4.3；⑩ 新增截图 41/42/43（付款结果回写列表效果，FKD2026110300003↔FKSQ-000000282 对照），引用 HCS 手册现有截图 |
+| 2026-11-05 | **按 11-04/11-05 代码修订**：① **4.9 应付单推送新增 preentry 预付抵扣分录**（进度预付已付额/项目预付核销额→金蝶付款处理单，自动合并同单；未付款/内码未回写/实付不足拦截整单，付款管理「同步付款结果」后自动续推；历史已推单不补）；② **应付单分录送税率与税率编码**（Nacos `thirdparty.bfi.taxrate` 映射，未维护拦截）；③ 第 3 节准备清单加 税率编码映射/推送内容开关（项目编码真实化 `project-real-code-enabled`、合同引用 `contract-ref-enabled`，默认关）/金蝶接口超时（读超时默认 120 秒），「金蝶组织编码」术语更名「金蝶公司代码」；④ 4.10 付款记录回写金蝶付款处理单内码说明；⑤ 「已指定应付」列范围修正：仅付款结算单列表与付款管理列表显示，**收款结算单不显示** |
 
 ---
 
@@ -46,7 +47,7 @@
 | assigned | 已指定应付 | 已指定应付（终态，收票——由付款结算单侧认领并在应付单推送后指定） | 不变 |
 | exist | 金蝶已有该客商且审核通过 | 金蝶已审核（终态，客商） | 不变 |
 
-结算单列表、付款管理列表还有一列「**已指定应付**」（聚合本单认领收票单的指定状态）：**已指定应付**（绿）/ **指定失败**（红，悬浮展示聚合的各票失败原因）/ **未指定**（灰）/ `-`（本单未认领收票单）。
+**付款结算单**列表、付款管理列表还有一列「**已指定应付**」（聚合本单认领收票单的指定状态）：**已指定应付**（绿）/ **指定失败**（红，悬浮展示聚合的各票失败原因）/ **未指定**（灰）/ `-`（本单未认领收票单）。**收款结算单不显示该列**（指定应付仅应付侧参与）。
 
 ### 1.2 「金蝶锁定」标签是什么
 
@@ -255,7 +256,8 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）
    │  ① 审批通过；外币先重选汇率日期带出结算汇率（预付结算单汇率不自动继承）
    ▼
 推送（审批自动开关 / 工具栏「同步金蝶」）
-   │  ② 应付 A102-2 / 应收 A302-2 按结算类型自动分流
+   │  ② 应付 A102-2 / 应收 A302-2 按结算类型自动分流；应付单自动带预付抵扣分录
+   │     （preentry：进度预付已付额/项目预付核销额→对应金蝶付款处理单，未回写内码拦截）与税率分录
    │  ③ 成功：金蝶单据号回填 + 状态已同步 + 金蝶锁定（不可改/不可作废）
    │  ④ 应付单生成后，系统自动对本单认领的收票单执行「指定应付」（见⑩）
    ▼
@@ -363,7 +365,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）
 
 | # | 事项 | 操作人 | 操作内容 | 不做的后果 |
 |---|---|---|---|---|
-| 1 | 部门金蝶组织编码 | 管理员 | 在部门档案维护「金蝶组织编码」字段 | 该部门单据推送时直接报错拦截 |
+| 1 | 部门金蝶公司代码 | 管理员 | 在组织/部门档案维护「**金蝶公司代码**」字段（原金蝶组织编码） | 该部门单据推送时直接报错拦截 |
 | 2 | 客商收款账户联行号 | 财务 | 客商档案维护收款账户（账号/开户行，**联行号必填**） | 付款推送、客商推送报错拦截 |
 | 3 | 主数据初始化 SQL | 运维 | 执行 `doc/sql/transport/` 下金蝶相关脚本（计量单位等主数据、认领表、10-13 迁移脚本 `lqj/`） | 对应链路数据缺失 |
 | 4 | 平台公司金蝶组织编码 | 管理员 | 组织管理维护「是否平台公司=是」并填**金蝶编码** | 收款流水同步直接报错拦截；收票按手选部门上溯平台公司取组织编码失败也会推送拦截 |
@@ -371,6 +373,9 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）
 | 6 | 物料映射 | 运维 | Nacos 配 `thirdparty.bfi.material.*`（有默认值，建议显式确认） | 推送报「运输方式未配置」类拦截 |
 | 7 | 定时任务开关 | 运维 | 按第 5 节清单逐项开启 | 只能全靠手动按钮 |
 | 8 | 审批自动同步开关 | 运维 | 按第 5 节 `autoSync.*` 按域开启 | 审批通过后不自动推送，走手动 |
+| 9 | 税率编码映射 | 运维 | Nacos `thirdparty.bfi.taxrate.*`：税率数值→金蝶税率.编码（默认 0/1/3/6/9/13→V0…V13，可加小数税率如 `"[6.5]"`） | 应付单分录带该税率时推送直接拦截报错 |
+| 10 | 推送内容开关（默认全关） | 运维 | `project-real-code-enabled`（项目编码取真实 `project_code`，前提金蝶项目档案编码一致，未关联项目兜底 999）；`contract-ref-enabled`（应付/应收送上游合同号、开票送合同三件套） | 关闭时维持原口径（项目编码送 999、不送合同引用） |
+| 11 | 金蝶接口超时 | 运维 | `connect-timeout-seconds`（默认 10）/`read-timeout-seconds`（默认 **120**，BFI 接口较慢勿调回小值） | 大单推送超时失败率上升 |
 
 **合同系统（HCS）准备**（Nacos 前缀 `thirdParty.hcs.*`，与上表金蝶准备相互独立）：
 
@@ -648,12 +653,18 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）
 1. **自动路径**：审批「通过」时自动推送（开关开启时）。
 2. **手动路径**：勾选一条或多条单据 → 工具栏「同步金蝶」。
    - 应付单（A102-2）/ 应收单（A302-2）按结算类型自动分流，无需选择。
+   - **推送时系统自动附带**（无需操作）：① 明细分录带**税率与税率编码**（按第 3 节 #9 映射，未维护的税率直接拦截）；② 应付单带**预付抵扣分录（preentry）**——把本单抵扣的进度预付（按已付金额）与项目预付核销金额逐笔登记到对应金蝶付款处理单，同一处理单自动合并；③ 开关开启时项目编码送真实编码、送上游合同号（第 3 节 #10）。
 3. 成功标志：列表出现**金蝶单据号**，状态变 **已同步**，并出现「金蝶锁定中」标签。
-4. 失败处理：状态变 **同步失败** → 鼠标悬浮状态标签看失败原因 → 常见原因：
+4. 失败处理：状态变 **同步失败** → 鼠标悬浮状态标签看失败原因 → 常见原因与解决：
    - 「请先同步金蝶应付单」类 → 关联结算单还没推（付款/开票依赖结算单先推，见 4.10/4.11）；
    - 客商编码取不到 → 先完成 4.1；
-   - 部门金蝶组织编码缺失 → 找管理员维护。
+   - 部门金蝶公司代码缺失 → 找管理员在组织/部门档案维护（第 3 节 #1）；
+   - 税率未维护映射类 → 运维在第 3 节 #9 税率映射里补该税率后重推；
+   - 「预付单[XXX]尚未付款完成，预付须金蝶付款完成后方可抵扣」→ 等该预付金蝶付款完成（4.10 回写）后自动续推；
+   - 「预付单[XXX]金蝶付款处理单内码未回写，请先在付款管理执行【同步付款结果】后再推送应付单」→ 到付款管理勾选该预付执行「同步付款结果」，内码回写后下一轮自动重推成功；
+   - 「预付单[XXX]付款处理单实付金额不足」→ 核对付款处理单实付金额与抵扣额，异常时联系运维核对 A103-4 回写数据。
 5. 纠偏：如果怀疑推送实际成功但本地状态没更新，等定时勾稽（或联系运维手动触发），系统会自动核对金蝶侧并纠正状态/补单号。
+6. 注意：**历史已推送的应付单不会补 preentry**（幂等预检直接返回）；preentry 相关失败会落 failed 与原因，修复前置后由 failed 重推自动续推成功。
 
 推送成功后金蝶侧效果（供确认推送结果时对照）：
 
@@ -677,7 +688,7 @@ TMS 合同审批通过后，合同会推送到桂物合同合规系统（HCS）
 3. 查付款结果：
    - 正常等定时任务回写（默认每 10 分钟，开关开启时）；
    - 急用点工具栏「**同步付款结果**」（勾选单据后显示；若未见到该按钮，说明当前环境以定时回写为主，等下一轮即可）。
-4. 结果状态流转：已生成 → **付款中** → **已付款**（含付款记录/凭证信息）/ **已关闭**（关闭）。
+4. 结果状态流转：已生成 → **付款中** → **已付款**（含付款记录/凭证信息）/ **已关闭**（关闭）。付款记录同步回写**金蝶付款处理单内码**（供 4.9 应付单预付抵扣分录 preentry 引用）。
 5. 失败与特殊场景：
    - **生成失败** → 鼠标悬浮状态标签看失败原因，修复后重推（批量同步按钮即可，系统会自动跳过金蝶已有的）；系统每 10 分钟也会自动重推。
    - 单据在金蝶被删：回调后自动置生成失败并清单号，直接重推；