docs: 先票后款手册与业务说明按11-02改造修订并重截配图

2026-11-03 00:31:52 +08:00
parent 6c5169eae5
commit ada300835b
7 changed files with 81 additions and 39 deletions
@@ -1,6 +1,6 @@
 # 先票后款业务流程与逻辑状态说明（收票登记 A303-2 + 付款结算单 A102-2 + A302-6）

-> 更新日期：2026-11-01　|　适用系统：运输 TMS（业财融合·金蝶星瀚）　|　读者：业务/产品/开发
+> 更新日期：2026-11-03　|　适用系统：运输 TMS（业财融合·金蝶星瀚）　|　读者：业务/产品/开发
 >
 > 关联文档：《先票后款纯操作手册》（同目录，纯操作步骤+截图）、《先票后款改造方案V2》（方案与改造清单）
 >
@@ -8,6 +8,15 @@

 ---

+## 修改记录
+
+| 日期 | 版本 | 修订内容 | 依据 |
+| --- | --- | --- | --- |
+| 2026-11-01 | V1.0 | 初版：先票后款全链路（A303-2/A102-2/A302-6）流程、状态机与遗留项 | 代码至 933fb37d（10-31） |
+| 2026-11-03 | V1.1 | ① A303-2 分录定稿：送税收分类编码（行商品编码），不送物料编码/税率表编码/税额，§6 移除物料编码与免税零税率遗留项；② 匹配结算单金额支持手动修改（默认发票全额，0≤金额≤发票金额，未匹配回退全额），§2/§3.2 同步；③ 新增查看页重推（/repush-claimed-invoice，A303-2+A302-6 一步式，failed/pushed 通吃）；④ A801-3 指定补偿增加开关 assignCompensationEnabled 默认关闭，改人工入口兜底；⑤ 接口表补充 claimed-list 回显、候选分页、列表指定失败悬浮（kingdeeAssignFailReason）等 | 代码 c82ce7ec、6c5169ea、49ccb435、34e90301/746fd3e9、b7d417f3、fe0ba8e8、da1ddf7b/2943a7c3（11-02） |
+
+---
+
 ## 1. 一页总览

 收票登记不再强制关联结算单，拆成两段：**先票**（收票登记只负责把发票推进金蝶收票单），**后款**（付款结算单认领收票单，推财务应付单后完成"发票指定应付"勾稽）。
@@ -29,7 +38,7 @@ flowchart TD
        B5 --> B6[assigned 已指定应付]
    end
    A6 -.收票单已推.pushed.-> B1
-    B4 -.推送失败/漏指定.-> C[A801-3 定时回写<br/>指定补偿自动重试] --> B5
+    B4 -.推送失败/漏指定.-> C[A801-3 定时回写<br/>指定补偿（开关默认关闭<br/>默认人工重推兜底）] --> B5
 ```

 ## 2. 名词与状态字典
@@ -40,10 +49,11 @@ flowchart TD
 | assigned（已指定应付） | 金蝶侧已与财务应付单完成勾稽（A302-6 成功）。历史数据终态，新链路由结算单侧驱动 |
 | failed（推送失败） | A303-2 保存失败 / 金蝶侧发票异常回收。列表"推送"按钮或定时任务自动重推 |
 | unsynced（未推送） | 审批通过但尚未推送（存量历史单不自动补推，走手动按钮） |
-| unreceived / partial / completed | 结算单收票状态：未收票 / 认领金额未覆盖结算金额 / **认领金额 ≥ 结算金额即完成**（全额认领，允许超过） |
+| unreceived / partial / completed | 结算单收票状态：未收票 / 匹配合计未覆盖结算金额 / **匹配合计（各票匹配金额之和）≥ 结算金额即完成**（允许超过） |
+| 匹配结算单金额 | 认领时每张发票的认领金额，**默认=发票金额全额，支持手动修改**（0 ≤ 匹配金额 ≤ 发票金额）；未传时分摊金额回退发票全额 |
 | 往来户 | A303-2 主表 receivablessupp_number = **发票销售方**在金蝶的供应商代码（客商档案 supplier_code） |
 | 结算组织 | 收票登记页面**手选部门**（合同承办部门口径），沿部门树上溯平台公司取金蝶组织编码 |
-| 一票一结算单 | 一张收票单只能被一张付款结算单认领；认领即**全额**（认领金额=发票金额，可超过结算金额） |
+| 一票一结算单 | 一张收票单只能被一张付款结算单认领；认领金额=匹配结算单金额（默认发票全额，可改） |

 ## 3. 各环节业务规则

@@ -51,6 +61,7 @@ flowchart TD

 - **不挂结算单、不挂合同**：表单无"关联结算单"；结算组织=页面必选手选部门。
 - **选票即带明细**：从金蝶票池（A801-1 镜像）选发票后，明细区块按票号带出发票明细行（goodsCode/数量/单价/金额/税额/税率），与推送分录同源。
+- **分录口径（联调已定）**：分录送税收分类编码（取行商品编码去尾部 0，填 `eTaxclassNumber`），**不送物料编码、税率表编码、税额**；税额仅参与价税合计；单价按 4 位小数舍入。
 - **往来户回填**：保存时按销方名称查客商档案回填 `supplier_code`（尽力回填，不阻断保存）。
 - **推送前置**：审批通过 + 已绑定镜像 + 查验通过 + 已选结算组织；往来户供应商代码缺失时**推送时实时重查档案**，仍缺失报错阻断。
 - **推送成功即终态 pushed**：删除了旧链路的"应付单已生成预检（A102-4）"和"立即指定应付"。
@@ -60,26 +71,28 @@ flowchart TD

 - **两条路径，同一套关系同步**：
  - 路径 A：新增/编辑结算单时"选择收票单"（编辑器）；
-  - 路径 B：审批通过后列表"发票登记"→选票→保存认领→确认推送。
- **候选范围**：审批通过 + 未被有效应付结算单认领（关联仍指向作废结算单的票可重新选）。
+  - 路径 B：审批通过后列表**工具栏**【发票登记】（选中一条审批通过的付款结算单）→弹窗选票→【保存认领】。
+- **候选范围**：审批通过 + 未被有效应付结算单认领（关联仍指向作废结算单的票可重新选）；候选弹窗为**分页查询**，行上悬浮展示该票推送失败原因。
 - **一票一结算单**：认领时校验，已挂其他有效应付结算单的票拦截（行锁防并发认领）。
- **全额认领**：匹配金额固定=发票金额，**允许合计超过结算金额**；收票状态"≥ 结算金额即 completed"。
+- **匹配结算单金额可手动修改**：默认=发票金额全额；手动修改范围 0 ≤ 匹配金额 ≤ 发票金额（后端兜底校验）；结算单侧分摊金额取发票行匹配结算单金额，未匹配到的行回退发票全额；**匹配合计允许超过结算金额**，收票状态"匹配合计 ≥ 结算金额即 completed"。
 - **双边落关系**：结算单侧 FormalSettlementInvoice（发票信息区）+ 收票登记侧 InvoiceReceiptSettlement（"结算信息"区展示）。
+- **路径 B 先确认后保存**：发票登记弹窗打开即回显本单已认领票（"已认领"标记，不可移除）；【保存认领】后弹出确认"确认认领并推送金蝶指定应付？"——**确定=认领保存与推送指定应付一步完成；取消=不保存任何数据**（不存在只认领不推送的中间态）。
 - 历史兼容：编辑历史结算单仍走原增量认领；收票登记传 settlements 的老入参仍走原分摊校验。

 ### 3.3 财务应付单与指定应付

 - 结算单审核通过 →"同步金蝶"推 A102-2 → **成功后自动对本单认领且收票单为 pushed 的逐单调 A302-6** → assigned。
- 收票单尚未推送（unsynced/failed）：跳过不报错；等收票侧推成 pushed 后由 A801-3"指定补偿"自动补指定。
+- 收票单尚未推送（unsynced/failed）：跳过不报错；收票侧推成 pushed 后由**人工入口**（发票登记推送/查看页重推）指定，或开启 A801-3 补偿开关后自动补指定。
 - **单笔指定失败不阻断结算同步**，失败明细进日志；已指定的幂等跳过。
 - 路径 B 的"发票登记"确认推送（`/invoice-assign-kingdee`）前置：付款结算单 + 审批通过 + 应付单已同步（synced）。
+- **查看页重推认领收票单**（`/formal-settlement/repush-claimed-invoice`，A303-2+A302-6 一步式）：前置=付款结算单 + 审批通过 + 应付单已同步 + 该票认领在本单名下；**failed/pushed 通吃**（已 assigned 拦截），failed 行可同步修改匹配结算单金额随重推生效；收票单重推复用 A303-2 状态机（A801-3 幂等预检防重复保存），成功后按应付单防重键指定应付。

 ### 3.4 定时回写与补偿（A801-3）

 | 场景 | 处理 |
 | --- | --- |
 | 金蝶侧发票状态异常（作废/红冲） | 回收本地状态为 failed，提示人工删除/解除指定后重推 |
-| pushed + 已认领 | **指定补偿（重试引擎）**：按认领关系自动补发 A302-6 |
+| pushed + 已认领 | **指定补偿（重试引擎）**：按认领关系自动补发 A302-6——受开关 `thirdParty.bfi.receivedInvoiceResult.assignCompensationEnabled` 控制，**默认关闭**；关闭时 pushed 单据由人工入口（发票登记推送/查看页重推按钮）指定 |
 | pushed + 未认领 | 跳过，**不再置 failed**（未指定不属异常） |
 | assigned 缺收票单号 | 仅补登单号 |

@@ -93,15 +106,15 @@ flowchart TD
 ### 4.1 收票登记 kingdeePushStatus

 ```
-unsynced ──推送成功(A303-2)──▶ pushed ──结算单A102-2成功/A801-3补偿/发票登记确认──▶ assigned
+unsynced ──推送成功(A303-2)──▶ pushed ──结算单A102-2成功自动指定/发票登记确认/查看页重推/A801-3补偿(开关默认关)──▶ assigned
    │                            │
    ├──手动/自动推送失败──▶ failed ◀──金蝶侧异常回收（作废/红冲）
    │                            │
-    └────────────重推（列表按钮/定时）◀──┘
+    └────────────重推（列表按钮/定时/查看页重推）◀──┘
 ```

- pushed 是新链路推送终点；assigned 只能由结算单侧指定动作或 A801-3 补偿到达。
- failed 重推不再依赖结算单/A102-4，仅需镜像明细 + 往来户编码 + 结算组织齐备。
+- pushed 是新链路推送终点；assigned 只能由结算单侧指定动作（A102-2 成功自动指定、发票登记确认、查看页重推）或 A801-3 补偿（开关默认关闭）到达。
+- failed 重推不再依赖结算单/A102-4，仅需镜像明细 + 往来户编码 + 结算组织齐备；查看页重推对 failed/pushed 均可一步完成收票单重推+指定应付。

 ### 4.2 结算单收票状态（invoice_status）

@@ -116,19 +129,21 @@ unreceived ──首次认领──▶ partial ──Σ认领金额 ≥ 结算
 | 端点/任务 | 说明 |
 | --- | --- |
 | GET `/invoice-receipt/invoice-detail-query?invoiceNo=` | 发票明细区块取数（镜像 items_json，缺则回源 A801-1） |
-| GET `/invoice-receipt/claim-candidates?keyword=` | 认领候选（approved+未认领，limit 200） |
+| GET `/invoice-receipt/claim-candidates?keyword=&page=` | 认领候选**分页**（approved+未认领） |
+| GET `/invoice-receipt/claimed-list?formalSettlementId=` | 结算单已认领收票登记列表（发票登记弹窗回显） |
 | POST `/formal-settlement/invoice-assign-kingdee?id=` | 发票登记确认推送（A302-6） |
+| POST `/formal-settlement/repush-claimed-invoice?id=&invoiceNo=` | 查看页重推认领收票单（A303-2+A302-6 一步式，failed/pushed 通吃，携带匹配金额校验） |
 | POST `/invoice-receipt/push-kingdee` | 收票登记推送（A303-2，终态 pushed） |
 | 定时 A801-1 票池同步 | 镜像含明细 items_json；明细变化即刷新（含金额未变场景） |
-| 定时 A801-3 收票结果回写 | 异常回收 / 指定补偿 / 单号补登 |
-| 表 | `blade_invoice_receipt.supplier_code`（新列）、`blade_invoice_receipt_settlement`（认领关系）、`blade_formal_settlement_invoice`（结算单发票区） |
+| 定时 A801-3 收票结果回写 | 异常回收 / 指定补偿（开关默认关）/ 单号补登 |
+| 列表展示 | 结算单/付款申请单列表"金蝶指定状态"标签（未指定/已指定应付/指定失败，failed 悬浮展示失败原因 `kingdeeAssignFailReason`）；付款申请单列表增加"已指定应付"聚合列；结算单发票明细回显收票单推送状态（`kingdeePushStatus`/`kingdeePushMsg`） |
+| 表 | `blade_invoice_receipt.supplier_code`（新列）、`blade_invoice_receipt_settlement`（认领关系）、`blade_formal_settlement_invoice`（结算单发票区，含匹配金额/推送状态回显） |

 ## 6. 已知边界与联调遗留

 | 项 | 说明 |
 | --- | --- |
-| 物料编码口径 | A303-2 分录物料编码暂送税收分类码，金蝶基础资料不认——**待金蝶确认**（默认物料 or 金蝶建档） |
-| 税收分类基础资料 | 金蝶环境不认国标码——待金蝶初始化/分配 |
-| 免税/零税率行 | 税率表无法映射（V+整数），推送报错人工核实 |
+| ~~物料编码口径~~ | **已解决（2026-11-02）**：分录不送物料编码，改送税收分类编码（行商品编码） |
+| ~~免税/零税率行~~ | **已解决（2026-11-02）**：税率表编码不再上送，无税率表映射报错 |
 | 币别 | 固定 CNY（不挂合同，数电票人民币） |
-| 付款申请单 A103-1 | 本期不动 |
+| 付款申请单 A103-1 | 本期不动（仅列表新增"已指定应付"聚合列与指定失败悬浮展示） |
@@ -1,11 +1,20 @@
 # 先票后款纯操作手册（收票登记 → 结算单认领 → 发票登记）

-> 更新日期：2026-11-01　|　适用系统：运输 TMS　|　读者：业务/财务操作人员
+> 更新日期：2026-11-03　|　适用系统：运输 TMS　|　读者：业务/财务操作人员
 >
 > 配套阅读：《先票后款业务流程与逻辑状态说明》（同目录）
 >
 > 菜单路径：**收付款管理 → 收票管理**（收票登记）；**结算管理 → 付款结算单**（认领与发票登记）
-> 按钮权限：收票登记新增/编辑/提交/推送；付款结算单"发票登记"（payment_settlement_invoice_register）
+> 按钮权限：收票登记新增/编辑/提交/推送；付款结算单"发票登记"（invoice_register）
+
+---
+
+## 修改记录
+
+| 日期 | 版本 | 修订内容 |
+| --- | --- | --- |
+| 2026-11-01 | V1.0 | 初版：收票登记→结算单认领→发票登记操作手册（8 图） |
+| 2026-11-03 | V1.1 | ① 场景二/三：认领金额改"匹配结算单金额"口径（默认发票全额，可手动修改）；② 场景三重写：发票登记入口移至列表**工具栏**（勾选一条审批通过付款结算单），弹窗自动回显已认领票，确认后认领+推送一步完成（取消不保存任何数据）；③ 新增场景四"查看页重推认领收票单"（指定失败/漏指定补救，失败行可改匹配金额随重推生效），原异常补偿顺延为场景五；④ 场景五：指定应付自动补偿默认关闭改人工重推，"指定失败"标签悬浮查看原因，失败对照表移除已消除的物料编码/税率表映射报错；⑤ 截图重截 05-08 并新增 09 查看页重推图（收票登记 01-04 无变化） |

 ---

@@ -46,8 +55,8 @@

 1. 菜单进入【结算管理 → 付款结算单】，【新增】。
 2. 填写结算基本信息与明细后，在**发票信息**区点【选择收票单】。
-3. 候选弹窗列出**审批通过且未被其他结算单认领**的收票单（支持发票号/销方/购方关键字查询），勾选后【确定】。
-4. 认领金额固定=**发票金额全额**（不可改），一张收票单只能被一张付款结算单认领。
+3. 候选弹窗**分页**列出**审批通过且未被其他结算单认领**的收票单（支持发票号/销方/购方关键字查询，行上可悬浮查看推送失败原因），勾选后【确定】。
+4. 认领金额即"**匹配结算单金额**"：默认=**发票金额全额**，支持手动修改（不能为负、不能超过发票金额），一张收票单只能被一张付款结算单认领。
 5. 保存结算单 → 提交 → 审批通过。
 6. 审批通过后点【同步金蝶】推财务应付单（A102-2）；**应付单推送成功后，系统自动把本单认领的收票单逐单指定应付（A302-6）**，收票登记状态随之变为"已指定应付"。

@@ -61,13 +70,15 @@

 适用：结算单**已审批通过**，事后才拿到发票/收票单。

-1. 付款结算单列表，目标单（审批通过）行点【发票登记】。
-2. 弹窗上半部为结算基本信息（只读），下半部"认领收票单"区点【选择收票单】勾选票后【确定】。
-3. 点【保存认领】——认领关系即时写入（结算单发票信息区 + 收票登记结算信息区同步可见）。
-4. 系统弹窗询问 **"是否将发票匹配数据推送金蝶？"**：
-   - 【确定】：逐单执行收票单指定应付（A302-6）；
-   - 【取消】：只保存认领不推送，可稍后在列表再次点【发票登记】推送。
-5. 已指定的收票单重复推送会自动跳过（幂等），失败的单据修复后可重试。
+1. 付款结算单列表，**勾选一条**目标单（审批通过的付款结算单），点列表上方工具栏【发票登记】。
+2. 弹窗上半部为结算基本信息（只读），下半部"认领收票单"区**自动回显本单已认领的收票单**（"已认领"标记，不可移除）。
+3. 点【选择收票单】，候选弹窗**分页**列出审批通过且未被其他结算单认领的收票单，勾选后【确定】（选票先暂存在弹窗表格里，点保存认领才落库）。
+4. 核对/修改每张票的"匹配结算单金额"（默认=发票金额全额，可手动改，不能为负、不能超过发票金额；不需要的暂存票点【移除】）。
+5. 点【保存认领】→ 系统弹窗"**确认认领并推送金蝶指定应付?**"：
+   - 【确定】：认领保存 + 逐单执行收票单指定应付（A302-6）**一步完成**，成功提示带结算单号；
+   - 【取消】：**不保存任何数据**（已勾选的票不会认领）。
+6. 已认领过票的结算单再次打开发票登记，可直接【保存认领】对漏指定的票补推送；已指定的收票单重复推送自动跳过（幂等）。
+7. 指定失败的票：结算单列表"金蝶指定状态"列显示红色"指定失败"标签，**鼠标悬浮可见失败原因**；修复后按场景四重推。

 ![付款结算单列表-发票登记入口](./2026-11-01-先票后款操作手册.assets/05-付款结算单列表-发票登记入口.png)

@@ -75,13 +86,29 @@

 ---

-## 场景四：异常与补偿
+## 场景四：查看页重推认领收票单（指定失败/漏指定的补救）
+
+适用：付款结算单已同步金蝶应付单，但名下收票单**指定失败（failed）或未指定（pushed）**。
+
+1. 打开付款结算单**查看页**，"发票信息"区每行展示收票单推送状态（"是否已指定应付"列：未指定 / 已指定应付 / 指定失败）。
+2. 未指定应付的行（推送失败/未指定）操作列有【重新推送】链接；**指定失败的行还可直接编辑"匹配结算单金额"**，修改随重推一并生效。
+3. 点【重新推送】：系统一步完成收票单重推金蝶（A303-2）+ 指定应付（A302-6），完成后刷新详情查看状态。
+4. 前置条件（不满足时按钮不可用/报错）：付款结算单 + 审批通过 + 金蝶应付单已同步 + 该票认领在本单名下；已指定应付的票重复重推会被拦截。
+
+> 补充：系统定时回写任务（A801-3）的"指定应付自动补偿"**默认关闭**，漏指定的票不会自动补推，需按本场景人工重推（或由管理员开启补偿开关）。
+
+![查看页-发票信息重推入口](./2026-11-01-先票后款操作手册.assets/09-结算单查看页-发票信息重推.png)
+
+---
+
+## 场景五：异常与补偿

 | 情况 | 系统行为 | 操作人要做的事 |
 | --- | --- | --- |
 | 收票推送失败（pushed 前任何一步） | 状态置"推送失败"，定时任务自动重推 | 按失败原因处理（常见见下表），或列表手动重推 |
-| 结算单同步应付单时收票单还没推送 | 自动跳过，不影响结算单同步 | 无需操作；收票推送成功后系统自动补指定 |
-| 收票单已推送但漏了指定 | 每轮 A801-3 回写自动补指定（指定补偿） | 无需操作 |
+| 结算单同步应付单时收票单还没推送 | 自动跳过，不影响结算单同步 | 收票推送成功后，按场景四【重推】或重新点【发票登记】推送 |
+| 收票单已推送但漏了指定 | 自动补偿**默认关闭**，不会自动补推 | 按场景四在查看页【重推】，或再次【发票登记】推送 |
+| 指定应付失败 | 列表"金蝶指定状态"红色"指定失败"标签 | **悬浮标签查看失败原因**，修复后按场景四重推 |
 | 金蝶侧发票被作废/红冲 | 回收为"推送失败"并提示 | 在金蝶删除/解除指定后，处理完重推 |
 | 结算单作废 / 认领移除 | **不同步金蝶** | 需要时在金蝶人工解除指定 |
 | 金蝶收票单已生成后本地作废 | 禁止作废 | 先在金蝶删除收票单/解除指定 |
@@ -91,10 +118,10 @@
 | 报错关键字 | 原因 | 处理 |
 | --- | --- | --- |
 | 未建档金蝶供应商编码 | 发票销售方未维护客商档案/未金蝶建档 | 客商档案新增销方（登记税号）→ 金蝶建档/同步 → 列表直接重推 |
-| 物料编码…导入不成功 | 金蝶物料基础资料无对应编码 | 待金蝶确认口径（联调遗留，见业务说明 §6） |
-| 税收分类…导入不成功 | 金蝶税收分类基础资料缺码 | 待金蝶初始化基础资料 |
+| 税收分类…导入不成功 | 金蝶税收分类基础资料缺对应编码 | 联系金蝶侧初始化/分配基础资料后重推 |
 | 单价格式不正确 | 明细单价小数超 4 位 | 已由系统按 4 位舍入，如仍出现请联系开发 |
-| 免税/零税率行，无法映射税率表 | 税率 0 行无法转税率表编码 | 与金蝶约定编码后放开，或人工核实票面 |
+
+> 物料编码、税率表映射两类历史报错已随分录口径调整（2026-11-02：不送物料编码/税率表编码/税额）消除，不再出现。

 ---

@@ -102,6 +129,6 @@

 ```
 票池选票 → 收票登记(选结算组织) → 审批通过 → 金蝶收票单[pushed]
-   → 付款结算单认领(全额) → 审批通过 → 金蝶财务应付单
-   → 自动指定应付 → [assigned] 金蝶勾稽完成
+   → 付款结算单认领(匹配金额默认全额可改) → 审批通过 → 金蝶财务应付单
+   → 自动指定应付(失败/漏指定→查看页重推) → [assigned] 金蝶勾稽完成
 ```