docs: 新增付款申请生成即回显预付信息改造文档

2026-10-16 00:15:49 +08:00
parent 2ddee7c895
commit 591b93f157
1 changed files with 53 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 付款申请金蝶生成即回显预结算预付信息：synced 提前建档 + 作废联动清理
+
+> 日期：2026-10-16
+> 关联文档：
+> - `doc/docs/业务流程/2026-09-29-预付款申请A103-3金蝶链路补齐方案（e_bebank_number统一-消失解锁-回写默认开启）.md`（A103-3 推送与 A103-2 消失解锁）
+> - `doc/docs/业务流程/2026-09-17-付款管理金蝶付款结果定时回写（A103-2付款申请单查询+A103-4付款处理查询）技术文档.md`（回写任务与 `applyPayApplyResult`）
+> - `doc/docs/业务流程/2026-09-20-应付申请与付款申请同步处理全链路业务流程（A102-2下推-A102-4查询-A103-1生成-A103-2回写）.md`
+
+## 1. 背景与问题
+
+排查预结算单 YJ2026101500001（已完成预结算审批、付款申请 FKD2026101500001 审批、金蝶付款申请单生成 FKSQ-00000229）：预结算单详情页"预付信息"卡片始终空白。
+
+根因：`blade_pre_settlement_advance`（预付记录表，详情接口 `advances` 字段的数据源）此前**只在金蝶回写"付款完成"（`kingdeeStatus=paid`）时才写入**（`applyPayApplyResult` → `syncPreSettlementAdvance`）。付款申请推进到"已生成"（synced）阶段不落记录，页面预付信息必须等付款完成才可见；且基本信息区的预付申请/已付金额来自付款申请实时汇总（`fillPaymentApplicationAmounts`），金额有值、明细卡片空白，容易误判。
+
+## 2. 改造内容（`PaymentApplicationServiceImpl`）
+
+| # | 变更点 | 变更前 | 变更后 |
+|---|---|---|---|
+| 1 | `syncPreSettlementAdvance` | 无参方法，写死 `billStatus="paid"`、已付=申请全额 | 参数化 `(entity, billStatus, paidAmount)`，建档与付款完成共用；按付款申请单号查重幂等 |
+| 2 | `doSyncKingdee` synced 落库处 | 仅更新付款申请状态 | **生成成功即建档**：`approved` / 已付 0，同事务落库，预付信息提前回显 |
+| 3 | `applyPayApplyResult` paid 分支 | 调原方法 | `paid` / 申请全额（语义不变），已建档时更新为已付款 |
+| 4 | `applyPayApplyResult` 勾稽分支（新增） | failed 单据经 A103-2 勾稽确认 synced/paying 时不落预付记录 | 与推送成功同语义，`approved` / 已付 0 建档 |
+| 5 | 新增 `voidPreSettlementAdvance` | 无 | 按付款申请单号将未付预付记录置 `voided`（`paid` 记录不联动，付款完成事实不回退），并刷新预结算汇总 |
+| 6 | `voidBill`（付款申请作废） | 不清理预付记录 | 联动作废，避免残留记录阻断预结算作废（`PreSettlementServiceImpl#voidBill` 的"存在关联预付申请"拦截） |
+| 7 | `unlockBill`（金蝶反审核解锁，含 A103-2 连续两轮消失判定） | 不清理预付记录 | 联动作废，重推生成新单后重新建档 |
+
+建档/作废后的联动刷新（`refreshPreSettlementAdvanceSummary` 预结算 advance_no/预付金额列、`formal_settlement_source` 预付金额、正式结算付款汇总）复用原有尾部逻辑，无需额外改动。转正式结算时来源表预付金额不再恒为 0。
+
+## 3. 状态与联动时序
+
+| 付款申请阶段 | 预付记录（blade_pre_settlement_advance） | 页面预付信息 |
+|---|---|---|
+| 审批通过、未推送 | 不存在 | 空白 |
+| 金蝶付款申请单生成成功（synced） | `approved` / 已付 0（提前建档） | **回显**（状态"审批通过"） |
+| 付款中（paying）/ 勾稽确认已生成 | `approved`（补建或维持） | 回显 |
+| 付款完成（paid 回写） | `paid` / 已付全额 | 回显（状态"已付款"） |
+| 付款申请作废 / 金蝶反审核解锁 | 未付记录置 `voided`（`paid` 不动） | 消失（汇总同步扣减） |
+
+前端零改动：`pre-settlement-editor.vue` 的 `advanceStatusName` 已含 `approved→审批通过` 映射。
+
+## 4. 定时任务影响
+
+- **付款结果回写任务（`syncKingdeePaymentResult`）**：零改动。轮询条件基于付款申请自身状态，不依赖预付记录表；paid 回写时命中已有记录更新，不产生重复。
+- **失败重推（`retryKingdeeFailed`）**：failed 阶段未建档，重推成功经 synced 建档一次，幂等查重兜底。
+- **A103-4 付款记录回填、金蝶单据锁补偿**：不涉及预付记录表，无影响。
+
+## 5. 行为变化与存量数据
+
+| 项 | 说明 |
+|---|---|
+| 预结算作废拦截提前 | "存在关联预付申请，请先作废预付申请"从付款完成后提前到金蝶生成即生效——作废预结算前需先作废付款申请（预期收紧） |
+| 存量单据不自动补 | 改造上线前已 synced 的付款申请（如 FKD2026101500001）不会重推（状态门禁跳过 synced），预付记录要等 paid 回写补建；需立即回显的，手工补一条 `blade_pre_settlement_advance`（`advance_no=付款申请单号`、`bill_status='approved'`、已付 0） |
+| 金额模糊匹配触发提前 | synced 建档时同额未付记录的兜底匹配与 paid 阶段同一逻辑，仅触发时点提前；如出现误绑定，可将模糊匹配收敛到 paid 分支 |