From 6e685d3440dccb1ed238dbc4e44c3921470480c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com>
Date: Sun, 18 Oct 2026 15:23:12 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E9=A2=84=E4=BB=98?=
 =?UTF-8?q?=E8=BD=AC=E6=AD=A3=E5=BC=8F=E7=BB=93=E7=AE=97=E5=8D=95=E4=B8=8E?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E9=A2=84=E4=BB=98=E6=93=8D=E4=BD=9C=E6=B5=81?=
 =?UTF-8?q?=E7=A8=8B=E8=AF=B4=E6=98=8E=EF=BC=88=E5=88=86=E5=9C=BA=E6=99=AF?=
 =?UTF-8?q?=C2=B7=E5=89=8D=E7=AB=AF=E5=90=8E=E7=AB=AF=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�结算�与项目预付�作�程说明（分场景·�端�端）.md | 363 ++++++++++++++++++
 1 file changed, 363 insertions(+)
 create mode 100644 doc/docs/业务�程/2026-10-18-预付转正�结算�与项目预付�作�程说明（分场景·�端�端）.md

diff --git a/doc/docs/业务�程/2026-10-18-预付转正�结算�与项目预付�作�程说明（分场景·�端�端）.md b/doc/docs/业务�程/2026-10-18-预付转正�结算�与项目预付�作�程说明（分场景·�端�端）.md
new file mode 100644
index 00000000..a61724d0
--- /dev/null
+++ b/doc/docs/业务�程/2026-10-18-预付转正�结算�与项目预付�作�程说明（分场景·�端�端）.md
@@ -0,0 +1,363 @@
+# 预付转正�结算�与项目预付�作�程说明（分场景·�端�端）
+
+> 整�日期：2026-10-18
+> 定�：���作者与实施/�调人员的**分场景�作手册 + 逻辑说明**。讲清「�在哪个页�点什么 → �端�生什么 → 数�表/金���什么 → 怎么校验�功�。
+> ��代�现状梳�（`tms-api` / `tms-erp-web`）。关�文档（�目录）：
+> - 《2026-10-18-预付完整�程梳�（进度预付-项目预付-正�结算�-付款-金�回写）.md》——改造�现状
+> - 《2026-10-18-正�结算�预付整�设计（进度预付+项目预付核销·金��径与记录�转）.md》——v2 设计与决策
+> - 《2026-10-18-预付与正�结算�全链路逻辑梳�（进度预付-项目预付核销·�端到�端�环节）.md》——改造�全链路
+> - 《2026-09-21-应收结算与开票申请�步金�全链路业务�程（A302-2�存-A302-4勾稽-A303-1新增-A303-4预检-A303-5回写）.md》——开票链
+> - 《2026-09-29-预结算开票（预开票）金�推�方案.md》——预开票（**方案，尚未�地**）
+
+---
+
+## 〇�先看全局：两�预付线 + 一�开票线
+
+### 0.1 术语
+
+| 术语 | �义 |
+|---|---|
+| 预结算�（PreSettlement） | 结算�的费用��，审批通过�作为预付/尾款结算的��。有 **应付（payable）/应收（receivable）** 两�。 |
+| 进度预付（progress_advance） | 挂在**预结算�**上的预付，属**应付**侧（我方付出去）。 |
+| 项目预付（project_advance） | 挂在**项目 + 承�商��**上的预付，�挂结算�，属**应付**侧。 |
+| 核销 | 项目预付金在�续结算�上"抵扣"，� `SettlementProjectAdvanceWriteOff` 行。**仅金�已付款（paid）的项目预付�核销**。 |
+| 容纳 / 纳入 | 预结算�转正�结算�时，其**预付�账快照**（进度预付）与**核销行**（项目预付）被正�结算�继承，计入正��的"已付/已申请/剩余�付"。 |
+| 尾款 | 正�结算�扣除已付（�预付�核销）�的剩余部分，走�独付款申请（settlement_payment）。 |
+| 开票 | **应收**侧动作：正�结算� → 开票申请 → 金�开票�。**应付**侧对应的是**收票**，两者共用 `formal_settlement.invoice_status` 字段，�称按结算方�区分。 |
+
+### 0.2 全景图
+
+```
+�应付线 · 预付】                                        �应收线 · 开票】
+
+预结算�(应付) approved                                  预结算�(应收) approved
+  │                                                        │
+  ├─ 预付申请(进度预付 progress_advance)                    └─ 尾款结算
+  │    └ 审批 → A103-3 直推金�付款 → 回写 paid                 └→ 应收正�结算�
+  │         └ ��建档 PreSettlementAdvance                      ├ 审批 → �步金� A302-2 财务应收�
+  │                                                              └ 开票申请(选应收正�结算�)
+项目预付(project_advance)  � 付款申请页「预付申请�                    └ 审批 → A303-1 开票申请�
+  ├ 选 项目 + 承�商��（校验项目�度/客户�度）                          └ A303-5 回写�票 → 开票完�
+  ├ 审批 → A103-3 → 金�付款 → 回写 paid
+  └ �续在结算�上「项目预付核销�
+
+              ▼ �线在「正�结算��汇�
+     预结算�(应付) ──「尾款结算�──→ 应付正�结算�(容纳预付快照 + 核销行)
+                                       ├ 审批 → �步金� A102-2 财务应付�（全� settlementAmount）
+                                       └「付款申请�→ 尾款付款 → A103-1 应付下推
+```
+
+### 0.3 金�接�速查
+
+| 接� | 用途 | 触�方 |
+|---|---|---|
+| A103-3 | 预付款直接�存金�付款申请�（�绑应付�） | 付款申请（progress_advance / project_advance）�步金� |
+| A103-1 | 应付下推生�金�付款申请� | 付款申请（settlement_payment）�步金� |
+| A103-2 / A103-4 | 付款申请�查询 / 付款处�查询 | 推��幂等预检�定时回写（� 10 分钟） |
+| A102-2 / A102-4 | 财务应付��存 / 查询（防�预检） | 应付正�结算�「�步金�� |
+| A302-2 / A302-4 | 财务应收��存 / 查询（勾稽） | 应收正�结算�「�步金�� |
+| A303-1 / A303-4 / A303-5 | 开票申请��存 / 幂等预检 / 开票结果查询 | 开票申请「�步金��与定时回写 |
+| lockBusiData | 金����定 | 推��功事务�交� |
+| A902 | 附件上传 | 主�推��功��带 |
+
+---
+
+## 一�应付侧：预付转正�结算�（被"容纳"）
+
+### 场景 A1：�起进度预付（挂预结算�）
+
+**��**：预结算� `approvalStatus=approved`�`settlementType=payable`�未转正�结算（`formalSettlementNo` 为空）。
+
+**�端�作**
+1. ��进「预结算��列表 → 勾选 1 �或多�预结算�（**必须�一��**）。
+2. 点工具�「**预付申请**�。
+   - 校验�通过时的�示：缺�� ID / 多�� / � payable / � approved / 已转正�。
+3. 跳转「付款申请�表�，页�类型已�定为**进度预付**：结算��读�结算金�与�付款金�自动带出。
+4. 填「申请付款金��「付款方��→「�存�→ 详情页「�交�→ 列表「通过�。
+
+**�端动作**
+
+| 步骤 | 接�/方法 | 结果 |
+|---|---|---|
+| �付金� | `GET /payment-application/reference-amount` | `�付 = 预结算金� − 累计已申请 − 项目预付核销�` |
+| �存 | `POST /payment-application/save` → `saveDraft` | 生� `FKD+日期+��` ��；写 `PaymentApplicationSettlement` 关系表 |
+| �交 | `POST /payment-application/submit` | `draft/returned → reviewing` |
+| 审批 | `POST /payment-application/approve` | `→ approved`，刷新预结算付款汇总，�布 `KingdeeBillApprovedEvent` |
+| 自动推� | `KingdeeApprovalSyncListener`（AFTER_COMMIT，开关 `thirdParty.bfi.autoSync.payment`） | A103-3 直推金�付款申请�；**��建档** `PreSettlementAdvance`（`advanceNo = FKD ��`）；刷新预结算预付汇总并�动正�结算� |
+
+> 说明：`PreSettlementController` 的 `/apply-advance`�`/update-advance-paid`�`/void-advance` 为**�留接�**，�端已��调用，�账改由付款申请�程�动维护。
+
+**结果校验**：预结算�列表「申请预付金� / 已预付金���化；付款申请 `kingdeeStatus` 从 `unsynced → synced`。
+
+### 场景 A2：�起项目预付（挂项目 + 承�商��）
+
+**��**：项目已建�承�商��已建；�超过项目�度与客户�度。
+
+**�端�作**
+1. ��进「付款申请�列表 → 点工具�「**预付申请**�（注�：与 A1 的入���，本入�从付款申请页进）。
+2. 表�页类型为**项目预付**，填写：
+   - **所属项目**（必选，下拉）
+   - **���称**（必选，**仅承�商��**，选项目���选）
+   - 申请付款金��付款方��付款方/收款方等
+   - �挂结算�，�展示�票信�与付款记录
+3. 「�存�→「�交�→「通过�。
+
+**�端动作**
+
+| 步骤 | 接�/方法 | 结果 |
+|---|---|---|
+| �存 | `saveDraft` → `validateQuota` | 项目�度�客户�度��校验（�下） |
+| �交/审批 | `submit` / `approve` | �上，审批��事件推 A103-3 |
+| 推� | A103-3 | 金�生�付款申请�，`kingdeeStatus=synced` |
+| 回写 | `PaymentKingdeeResultTask`（A103-2/A103-4，� 10 分钟） | `synced → paying → paid`；回填实付金�与付款记录 |
+
+**�度校验�径**（`PaymentApplicationServiceImpl.validateQuota`，悲观� `FOR UPDATE`）
+
+```
+项目�度 = (项目 fundLimit + Σ有效期内 approved 临时�度) × 10000
+客户�度 = 客商 maxCreditLimit × 10000
+申请付款金� > �度 → 分别报"申请付款金��能超过项目�度 / 客户�度"
+```
+
+**结果校验**：付款申请列表 `kingdeeStatus=已付款(paid)`，金����已回填。**�有 paid �能进入�续核销**。
+
+### 场景 A3：项目预付核销（在结算�上选� + 录�）
+
+**��**：存在 `approvalStatus=approved` 且 `kingdeeStatus=paid` 的项目预付，与结算�**�一��**，且有剩余�核销余�。
+
+**�端�作**
+1. 打开**预结算�编辑器**（或�续的**正�结算�编辑器**）→「**项目预付核销**�分区 → 点「**选择**�。
+2. 弹窗「选择项目预付��列出�核销�（��� + 已审批 + **已付款** + 有余�），已选行����勾选。
+3. 勾选「确定�→ 默认按"�核销金�"预填「本次核销金��，�手工改�。
+4. 「�存�（或�存�稿）。
+
+**校验链（�端 → �端一致）**
+
+| 层级 | 规则 | �示 |
+|---|---|---|
+| �端 | 金� > 0 | 预付� X 本次核销金�必须大于 0 |
+| �端 | 金� ≤ �核销金� | 本次核销金��能超过�核销金� |
+| �端 | 核销�计 ≤ 结算�金� | 项目预付核销�计�能超过结算�金� |
+| �端 | ��一致 | 项目预付�与结算����一致 |
+| �端 | 仅项目预付 | 仅�核销项目预付� |
+| �端 | approved | 仅�选择审核通过的项目预付� |
+| �端 | **paid**（本次新增） | 预付� X 尚未付款，项目预付须金�付款完��方�核销 |
+| �端 | �一预付���� | �一项目预付�����核销 |
+| �端 | 有余� / �计 ≤ 结算金� | 超出�核销金� / 核销�计�能超过结算�金� |
+
+**结果校验**：正�/预结算�「已付金��立�包�核销�（核销行必对应已付款预付，计入实付�径），列表「申请付款金�（�预付）/已收已付�计（�预付）/剩余�付��步�化。
+
+### 场景 A4：预结算转正�结算�（容纳预付）
+
+**��**：预结算� `approved`�**�一项目**；此时其预付（进度预付�账�项目预付核销行）将被正��继承。
+
+**�端�作（两�路径）**
+1. 「预结算��列表勾选 → 工具�「**尾款结算**�→ 跳「正�结算��表�，��预结算明细与费用项自动�并。
+2. 或在正�结算�表�里通过弹窗「追加��预结算�。
+
+**表�上的三处关键呈现（应付侧）**
+- **结算�计（原金�）**：Σ 费用项 = `settlementAmount`，**始终全�，�扣预付/核销**（开票匹�上��金�应付�金�基线）。
+- **汇总�**「已付金�（�预付�核销）/ 剩余未付金��：
+  - 编辑�实时算：`已付 = Σ��预结算.advancePaidAmount + Σ核销行.writeOffAmount`；
+  - �读���库值 `form.paidAmount`（已�尾款 + 进度预付 + 核销）。
+- **项目预付核销**：从预结算��带入的核销行会**自动预填**，�增删改。
+
+**�端动作（`FormalSettlementServiceImpl.saveDraft`，�一事务）**
+1. ���并校验（�������）→ 写 `FormalSettlementSource` 快照（�预付汇总 `advanceAppliedAmount / advancePaidAmount`）。
+2. `refreshSettlementAmount`：以费用项�算 `settlementAmount`，并刷一次汇总。
+3. **转移��核销行**：`deleteBySettlementIds(PRE, ��预结算ids)` —— 先释放���用，�续"�超�核销余�"校验�能通过预填金�。
+4. `replaceWriteOffs`：�务端�校验�� **FORMAL** 核销行。
+5. `refreshPaymentSummary` �刷一次（核销�库�必须�算，第 2 步覆盖�到核销行）。
+
+> 原则：**�一笔预付的核销在链路上�存在一份** —— 预结算转正� = 删� PRE 行 + � FORMAL 行。
+> 轻�标记路径（`PreSettlementController /formal-settlement`）：仅回写正�结算��，无正��实体，PRE 核销行原地�留，待真正建�时�转移。**��：无在途预付申请**（存在 reviewing/approved 预付会拦截）。
+
+**结果校验**：正�结算�「申请付款金�（�预付）�「已收已付�计（�预付）�「剩余�付�「收付款状��四列直接�映预付与核销；�一预付在 PRE / FORMAL 侧无�份核销。
+
+### 场景 A5：正�结算��步金�（A102-2 财务应付�）
+
+**�端�作**：正�结算�列表 → **应付** tab → 勾选 1 �（按钮�求�选）→ 工具�「**�步金�**�。
+
+**�端动作**：`POST /formal-settlement/sync-kingdee` → 按结算方�路由：
+- 应付 → **A102-2 财务应付�**（A102-4 幂等预检 / �查，一张结算�一张应付�），金� = **全� settlementAmount**；
+- �功�回写 `kingdeeSyncStatus=synced` + 金����/内� → `lockBusiData` �� → A902 附件上传。
+
+**结果校验**：列表「金��步状��= 已�步�「金��定状��= 已�定 / �定中；附件未全部上传时页�追加�示"��推补传"。
+
+**审批时自动推�**：正�结算�「通过��也会 AFTER_COMMIT 自动推；若推�失败，审批结果为 `false` + 具体原因以 warning �示，审批本身�失败，走「�步金��手动兜底或定时�推。
+
+### 场景 A6：尾款付款（正�结算�之�）
+
+**��**：正�结算� `approved`�`payable`��一���有剩余�付金�。
+
+**�端�作**：正�结算�（应付）列表勾选 1 �或多� → 工具�「**付款申请**�→ 弹窗确认��申请金�（默认 = 剩余�付，已扣核销）→「�交�。
+
+**�端动作**
+1. `saveDraft`：�挂多张���正�结算�，按�付金�比例分摊；`submit` 时 `validateNoTailPayment` 防��尾款申请。
+2. **推�路由��**：尾款走 **A103-1 应付下推**，�置对�张正�结算�� A102-4 预检——**未在金�生�财务应付�则拦截**（�示先在正�结算�页�步金�）；下推生�金�付款申请�，���� + 附件。
+3. 回写 `paid` → 生� `FormalSettlementPayment(paymentType=final)` → `refreshPaymentSummary` �算 `appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus`（unpaid → partial → paid）。
+
+**金��径（全系统唯一定义）**
+
+```
+settlementAmount   = Σ 结算�计费用项（全�，�扣预付/核销）
+appliedPaymentAmount = 尾款申请中(reviewing) + Σ��预结算 advanceAppliedAmount + Σ核销行
+paidAmount           = 尾款已付(approved 实付) + Σ��预结算 advancePaidAmount + Σ核销行
+remainingPayableAmount = max(settlementAmount − paidAmount, 0)
+paymentStatus        = unpaid / partial / paid
+```
+
+---
+
+## 二�应收侧：正�结算�推�开票
+
+> 开票是**应收**方�：给客户开票 → 金�开票�。与应付侧的"收票"共用 `invoice_status` 字段，文案按方�区分（未开票 / 部分开票 / 已开票，未收票 / 部分收票 / 已收票）。
+
+### 场景 B1：应收正�结算��步金�（A302-2 财务应收�）
+
+**�端�作**：正�结算�列表切到「**应收**�tab → 勾选 1 � → 工具�「**�步金�**�。
+
+**�端动作**：`POST /formal-settlement/sync-kingdee` → **A302-2 财务应收�**（防�键 `正�结算��_结算明细���`）→ 回写���/内� + `synced` → �� + A902 附件。
+�有定时勾稽 `syncKingdeeArResult`（A302-4）：对已�步/生�失败的应收结算�批��查金�应收�并纠�回填，�手动触� `POST /formal-settlement/sync-kingdee-ar-result`。
+
+**结果校验**：应收正�结算� `kingdeeSyncStatus=已�步`，列表��金����。
+
+> **开票�置**：正�结算开票�求**先有财务应收�**。开票申请推�时按 A302-4 �结算�预检，未生�则拦截并�示"请先在正�结算�页��步金�"。
+
+### 场景 B2：开票申请创建与推�（A303-1 / A303-5）
+
+**��**：存在 `approved`�未作废�**未收票/未开票（invoiceStatus=unreceived）** 的**应收**正�结算�。
+
+**�端�作**
+1. ��进「**开票申请**�列表 → 点「**新增**�。
+2. 「开票基本信��区点「结算���侧「**选择**�→ 弹窗「选择应收正�结算��（�按结算���项目����索）→ 勾选 → 「确定�。
+   - 项目�开票��（= 结算�收款方）自动带出；「**�开票金�**�= Σ �结算�剩余�开票�；�票方开票信�按�票方客商档案带出。
+3. 填「�票类型�（电�专票时纳税人识别�/开户行/开户账�/注册地�必填）��票方�邮箱�「开票内容�（�票张次与商�行）→ 系统自动算「本次开票金��= 行�计。
+4. 「结算信��表中填�结算�的**分摊开票金�**（≤ 该�剩余�开票金�）。
+5. 「开票明细�勾选明细 → 「�存�（�稿）→ 「�交�→ 列表「通过�。
+
+**�端动作**
+
+| 步骤 | 接�/方法 | 规则 |
+|---|---|---|
+| �存 | `POST /invoice-application/save` → `saveDraft` | ① 仅�选择**应收�审批通过�未作废�未收票**的正�结算�；② 结算�需兼容（�项目/开票方等）；③ 分摊金� ≤ 剩余�开票金�；④ 行�计 > 0；⑤ �票方须有客商档案与有效开票信�；⑥ 电�专票四�素必填；⑦ �存�刷新��结算�开票状�，写�更记录 |
+| �交 | `/invoice-application/submit` | `draft/returned → reviewing`，写申请日期 |
+| 审批 | `/invoice-application/approve` | `→ approved`，�布事件 → AFTER_COMMIT 推金� |
+| 推� | `syncKingdee` → `doSyncKingdee` | ① **必须关�正�结算�**；② �结算� A302-4 预检应收�已生�；③ A303-4 幂等预检（已生�的张次跳过并回填）；④ 按�票张次拆分 `billno = ��-张次` �张推 A303-1；⑤ �功��� + A902 附件 |
+| 回写 | 定时 `syncKingdeeInvoiceResult`（A303-5，按 `serialNo=billno` 分批 ≤50）或手动 `POST /invoice-application/sync-kingdee-invoice-result` | 查到�票 → � `InvoiceApplicationInvoice` �票记录并推进 `invoiced` 终�；�时刷新��结算� `invoice_status`（部分开票 → 已开票） |
+
+**结果校验**：开票申请 `kingdeeStatus=已�步 / 开票完�`，详情页���票结果（�票��开票日期�价税�计�文件）；��正�结算�「�票状��从未开票 → 部分开票 → 已开票。
+
+**边界与�制（现状）**
+- 已推�（`synced/invoiced`）**����改**；仅审批通过且未�定时�「作废�。
+- 数电票已开出�能红冲（�走本系统作废）。
+- **预付/核销�影�开票**：开票按**全� `settlementAmount`** 匹�，预付与核销�影�应付侧的已付/剩余�付。
+
+### 场景 B3：预开票（预结算�直接开票）——**方案，尚未�地**
+
+按《2026-09-29-预结算开票（预开票）金�推�方案》，预结算（应收）�**�推 A303-1 开票申请�**��校验应收�，新增 `invoice_source=pre` 与预结算关�表区分。
+
+**当�代�状�**：`InvoiceApplicationServiceImpl.doSyncKingdee` �硬校验"必须关�正�结算�"，创建入�也��许选应收正�结算� ⇒ **预开票目�推�出去**，需按上述方案改造��能�作。本文�列为�执行场景。
+
+---
+
+## 三�状�机与字段�径
+
+### 3.1 付款申请（PaymentApplication）
+
+| 字段 | �值 | 说明 |
+|---|---|---|
+| `paymentType` | `progress_advance` / `project_advance` / `settlement_payment` | 进度预付 / 项目预付 / 尾款付款 |
+| `approvalStatus` | `draft / reviewing / approved / returned / voided` | �交� reviewing；仅 approved �作废 |
+| `kingdeeStatus` | `unsynced / synced / paying / paid / closed / failed` | **paid 是项目预付�核销的�置** |
+| `kingdeeLockStatus` | `locked / …` | 已�定的���止编辑/作废 |
+
+### 3.2 正�结算�（FormalSettlement）
+
+| 字段 | �值 |
+|---|---|
+| `approvalStatus` | `draft / reviewing / approved / returned / voided` |
+| `paymentStatus` | `unpaid / partial / paid` |
+| `kingdeeSyncStatus` | `unsynced / synced / failed` |
+| `invoiceStatus` | 应付=收票状�，应收=开票状�：`unreceived / partial / completed` |
+
+### 3.3 预付记录��状��（`src/utils/settlementStatus.js`，两个编辑器共用）
+
+| 值 | �称 |
+|---|---|
+| `reviewing` | 审批中 |
+| `approved` | 审批通过 |
+| `paid` | 已付款 |
+| `returned` | 已驳回 |
+| `voided` | 已作废 |
+| `draft` | �稿 |
+
+### 3.4 正�结算�付款记录�并表（�读）
+
+一张表三类型，按「付款类型�列区分：**进度预付**（��预结算 `PreSettlementAdvance` �账）/ **项目预付核销**（核销行，金�=本次核销�）/ **结算尾款**。列�统一为「**申请/核销金�**�；创建时间统一�**底层付款申请创建时间**。
+
+---
+
+## 四�逆�与异常场景
+
+| 场景 | 触� | 系统行为 |
+|---|---|---|
+| 付款申请作废（仅 approved） | 付款申请列表「作废�（�金��定） | 金���中�止作废；汇票付款释放票�余�；**�动作废未付预付记录 + 删除其核销行并刷新�影�正�结算�汇总**（已付事实�回退） |
+| 正�结算�作废 | 结算�列表「作废� | 删本� FORMAL 核销行，�度释放�详情无残留 |
+| 金�删�回调（`voidByKingdee`） | 金�侧�审核删除 | �上，删本�核销行 |
+| 预结算�作废 | 预结算列表「作废� | 存在关�预付申请需先作废预付；删 PRE 核销行 |
+| 预付记录作废 | 预付�账 | 已付款的�能作废 |
+| 金��审核（解�） | A103-2 连续两轮查�到已推�� | 判定金�侧已删 → `unlockBill` 置 `failed`�清空金���/内��**�动作废未付预付记录**（已付�回退）；�推��新建档。**此场景�删核销行**（预付申请� approved，核销继续计入），人工作废��回� |
+| 推�失败 | A103-2/A102-2/A302-2/A303-1 报错 | � `failed` → `KingdeeAutoSyncRetryTask` � 10 分钟自动�推；页�「�步金��/「批��步�手动兜底；审批接�把失败原因带回�端 warning，审批结果��影� |
+| 结算调整（金��更） | 「结算调整�� | 调整�库�校验**核销�计 ≤ 新结算金�**，超出拒�并�示先调�核销；�库� `refreshPaymentSummary` �算。调整�推：核销行**�移到新�**（克隆 + 删原�行 + 批�刷新两�），原�作历�存档，收付�径以新�为准 |
+| 全�核销 / 已结清 | `paymentStatus=paid` | `isSettlementCompleted` 拦截，��许��起结算调整（已确认"全�抵扣�结清"） |
+
+---
+
+## 五�接�与数�表索引
+
+### 5.1 �端接�
+
+| 模� | 主�接�（`/blade-transport` 网关�缀） |
+|---|---|
+| 预结算� | `GET /pre-settlement/list|detail`；`POST /pre-settlement/save|submit|approve|return|void`；`POST /pre-settlement/formal-settlement`（轻�标记转正�） |
+| 付款申请 | `GET /payment-application/list|detail|reference-amount|project-advance-write-off-options`；`POST /payment-application/save|submit|approve|return|void|sync-kingdee|sync-kingdee-batch|sync-kingdee-result` |
+| 正�结算� | `GET /formal-settlement/list|detail|candidate-pre-settlements|contract-options`；`POST /formal-settlement/save|submit|approve|return|void|sync-kingdee|sync-kingdee-ar-result|retry-kingdee-bill-lock|apply-payment|apply-payments|claim-invoices` |
+| 开票申请 | `GET /invoice-application/list|detail|settlement-candidates|settlement-details|receiver-information`；`POST /invoice-application/save|remove|submit|approve|return|void|sync-kingdee|sync-kingdee-invoice-result` |
+
+### 5.2 核心数�表
+
+| 表/实体 | 作用 |
+|---|---|
+| `PreSettlement` | 预结算�；预付汇总 `advanceNo / advanceAppliedAmount / advancePaidAmount`�`formalSettlementNo` |
+| `PreSettlementAdvance` | 预结算预付�账；`advanceNo`（=FKD ��）�`billStatus`�`kingdeeAdvanceNo` |
+| `PaymentApplication` | 付款申请（三� paymentType） |
+| `PaymentApplicationSettlement` | 付款申请 ↔ 结算�关系�分摊 |
+| `PaymentApplicationRecord` | 付款记录（A103-4 回填，`voucherJson` 留档） |
+| `FormalSettlement` | 正�结算�；`settlementAmount / appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus / kingdeeSyncStatus / invoiceStatus` |
+| `FormalSettlementSource` | ��预结算/明细快照，冗余预付汇总 |
+| `FormalSettlementPayment` | 正�结算�尾款付款记录（`paymentType=final`） |
+| `SettlementProjectAdvanceWriteOff` | 项目预付核销行（`settlementType`：PRE / FORMAL） |
+| `InvoiceApplication` / `InvoiceApplicationSettlement` / `InvoiceApplicationSheet` / `InvoiceApplicationLine` / `InvoiceApplicationInvoice` | 开票申请主� / 结算�关�与分摊 / �票张次 / 商�行 / 金�回写�票 |
+
+### 5.3 �端页�
+
+| 页� | 路径 |
+|---|---|
+| 预结算�列表/表� | `src/views/settlement/pre-settlement.vue`�`pre-settlement-form.vue`�`components/pre-settlement-editor.vue` |
+| 正�结算�列表/表� | `src/views/settlement/formal-settlement.vue`�`formal-settlement-form.vue`�`components/formal-settlement-editor.vue` |
+| 项目预付核销组件 | `src/views/settlement/components/project-advance-write-off.vue` |
+| 付款申请列表/表� | `src/views/payment/payment-application.vue`�`payment-application-form.vue` |
+| 开票申请列表/表� | `src/views/payment/invoice-application.vue`�`invoice-application-form.vue` |
+| 状��公共工具 | `src/utils/settlementStatus.js`�`src/option/settlement/formalSettlementSearch.js` |
+
+---
+
+## 六�已知�径与风险
+
+1. **尾款默认�付�** = 结算金� − 累计尾款申请 − 核销，**�扣进度预付已付部分**（既有�径）。进度预付�大头时默认��能�大，由审批环节把关。
+2. **正�结算� `paidAmount` 现�核销**，下游消费该字段的报表/对账��径�之�化（对账已确认接�）。
+3. **金�侧预付抵扣字段**（`y_billtype / y_billid / y_settleamt`）本期**�传**，金�报表与本系统"已付�核销"存在时间差（待业务确认�迭代）。
+4. **预开票未�地**：预结算直接开票需先按方案改造 `doSyncKingdee` 门�与数�模型。
+5. 存�"approved 未 paid"的核销行未�数�修正（`replaceWriteOffs` �约�新�存），如需清洗�出脚本。
+6. 应收侧预收/收款认领（ReceiptClaim）与收票�程未在本文展开。