Merge remote-tracking branch 'origin/feature/20261019-bfi-all' into feature/hcs-api-p0
# Conflicts: # blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/PaymentApplicationServiceImpl.java
This commit is contained in:
刘泉佳
@@ -131,7 +131,8 @@ TMS 付款申请审核通过
|
||||
| --- | --- | --- | --- |
|
||||
| awrp_src_code | 来源单据号（防重键） | `paymentNo` | 付款申请单号 |
|
||||
| awrp_src_sys | 外部系统编号（防重键） | 配置 `payApply.srcSys` | 默认 `WLTMS` |
|
||||
| settleorg_number / applyorg_number / payorg_number / purorg_number | 结算/申请/付款/采购组织编码 | 合同所属组织 | `organizationId` → 组织编码 `deptCode`，为空回退组织名称；缺失报错 |
|
||||
| settleorg_number / applyorg_number / payorg_number | 结算/申请/付款组织编码 | 合同关联项目业务部门上溯平台公司 | `kingdeeOrgNumber` → 平台公司 `blade_dept.kingdee_dept_code`；缺失报错 |
|
||||
| awrp_department_number | 部门编码 | 项目业务部门自身 | `kingdeeDeptNumber` → 业务部门 `blade_dept.kingdee_dept_code`（部门级编码，不上溯平台公司）；未维护报错 |
|
||||
| billtype_number | 单据类型编码 | 配置 `payApply.billtype` | 默认 `ap_payapply_oth_BT_S` 其他付款申请 |
|
||||
| applydate | 申请日期 | `applyDate` | yyyy-MM-dd，空取当天 |
|
||||
| applycause | 请款事由 | paymentType 映射 | 见 5.1 |
|
||||
@@ -158,7 +159,7 @@ TMS 付款申请审核通过
|
||||
| awrp_entry_code | 对方唯一行 id（防重） | `paymentNo + "-1"` | 不得重复 |
|
||||
| e_remark | 备注 | `remark` | 可选 |
|
||||
|
||||
未传的可选字段：purdept_number、awrp_department_number、e_duedate、e_settlementtype_number、e_costcenter_number、awrp_src_con_eno、awrp_splb_number。
|
||||
未传的可选字段：purorg_number、purdept_number、e_duedate、e_settlementtype_number、e_costcenter_number、awrp_src_con_eno、awrp_splb_number。
|
||||
|
||||
> 前置校验：推送前按 `contractId` 加载合同，未关联合同、合同不存在、所属组织编码为空、结算币种为空时，同步失败并标记 `kingdeeStatus = failed`。
|
||||
|
||||
@@ -222,7 +223,7 @@ TMS 付款申请审核通过
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| 单笔同步 `syncKingdee` | 校验失败/推送失败置 `failed` 并抛 `ServiceException`，前端提示原因（含金蝶 errors 明细） |
|
||||
| 批量同步 `syncKingdeeBatch` | 逐单循环，**单条失败不中断批次**；失败单标记 `failed` 后继续下一单；返回结果列表中附 `付款申请[id]同步失败：原因` |
|
||||
| 批量同步 `syncKingdeeBatch` | 逐单循环，**单条失败不中断批次**；失败单标记 `failed` 后继续下一单；返回结果列表中附 `付款申请[付款申请单号]同步失败：原因` |
|
||||
| 金蝶接口级失败（status=false / errorCode≠0） | `BfiServiceImpl.commonCall` 抛 `BfiException`，同上处理 |
|
||||
| 金蝶单据级失败（billStatus=false） | 以 `errors` 拼接抛出 |
|
||||
| 重复点击同步 | 已 `synced` 单据跳过；`failed`/`unsynced` 允许重推（防重键保证金蝶侧幂等） |
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 适用系统：TMS（BladeX 微服务平台，服务：blade-transport）
|
||||
> 对接系统：金蝶云·星瀚（业财融合 BFI，经 iPaaS 网关）
|
||||
> 关联文档：`doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`、`doc/docs/业财融合系统接口文档.xlsx`、`doc/docs/业务流程/付款申请同步金蝶（星瀚）技术文档.md`（A103-3 预付款路径）
|
||||
> 关联文档：`doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`、`doc/docs/业财融合系统接口文档.xlsx`、`doc/docs/业务流程/2026-09-16-付款申请同步金蝶（星瀚）技术文档.md`（A103-3 预付款路径）
|
||||
> 最后更新：2026-09-18（字段映射与联调默认值按当前代码重新梳理）
|
||||
|
||||
---
|
||||
@@ -15,7 +15,7 @@
|
||||
- 对接接口：
|
||||
- **A102-2 财务应付单保存** `POST /ierp/kapi/v2/awrp/ap/ap/ap_finapbill/save`
|
||||
- **A103-1 付款申请保存（应付下推）** `POST /ierp/kapi/v2/awrp/ap/ap/ap_finapbill/push`
|
||||
- 路径划分：**正式付款**（settlement_payment）走本文档 A102-2 → A103-1 两步链路；**预付款**（project_advance / progress_advance）维持原 A103-3 直推付款申请单，见《付款申请同步金蝶（星瀚）技术文档》
|
||||
- 路径划分：**正式付款**（settlement_payment）走本文档 A102-2 → A103-1 两步链路；**预付款**（project_advance / progress_advance）维持原 A103-3 直推付款申请单，见《2026-09-16-付款申请同步金蝶（星瀚）技术文档》
|
||||
- 调用方式：前端 → TMS 后端转发 → 星瀚（OAuth2 凭证仅存后端，前端不持有）
|
||||
- 落库结果：A103-1 返回的付款申请单 id 写入 `kingdee_bill_no`（既有字段）；**A102-2 返回的应付单 id 不落库**，仅校验保存成功，后续如需可经 A102-4 按防重键（`awrp_src_sys` + `awrp_src_code`）查询（`BfiServiceImpl.queryApBill` 已封装），本次无表结构变更
|
||||
|
||||
@@ -216,7 +216,7 @@ A102-2 所需的金蝶侧固定档案编码**不进 Nacos 配置**，统一定
|
||||
| --- | --- |
|
||||
| 单笔同步 `syncKingdee` | 校验失败/推送失败置 `failed` 并抛 `ServiceException`，前端提示原因（含金蝶 errors 明细） |
|
||||
| ①成功②失败 | `kingdeeStatus = failed`；重推时①按防重键走更新语义，继续② |
|
||||
| 批量同步 `syncKingdeeBatch` | 逐单循环，**单条失败不中断批次**；返回结果列表附 `付款申请[id]同步失败：原因` |
|
||||
| 批量同步 `syncKingdeeBatch` | 逐单循环，**单条失败不中断批次**；返回结果列表附 `付款申请[付款申请单号]同步失败：原因` |
|
||||
| 货物类型未维护档案编码 / 计量单位为空 | 分录解析（`collectEntryGroups`）时拦截，报错提示补充档案 |
|
||||
| 合同乙方为空 / 客商档案未维护客商编码 | 往来户取值（`bfiAsstactNumber`）时拦截，报错提示合同号与乙方名称 |
|
||||
| 金蝶接口级失败 | `BfiServiceImpl.commonCall` 抛 `BfiException`，同上处理 |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 适用系统：TMS（BladeX 微服务平台，服务：blade-transport）
|
||||
> 对接系统：金蝶云·星瀚（业财融合 BFI，经 iPaaS 网关）
|
||||
> 关联文档：`doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`（4.3 节步骤 11）、`付款申请同步金蝶（星瀚）技术文档.md`、`2026-09-16-付款管理正式付款同步金蝶（财务应付单+付款申请下推）技术文档.md`、`2026-09-17-BFI分页查询通用翻页工具（BfiUtil-queryAllPages）技术文档.md`
|
||||
> 关联文档：`doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`（4.3 节步骤 11）、`2026-09-16-付款申请同步金蝶（星瀚）技术文档.md`、`2026-09-16-付款管理正式付款同步金蝶（财务应付单+付款申请下推）技术文档.md`、`2026-09-17-BFI分页查询通用翻页工具（BfiUtil-queryAllPages）技术文档.md`
|
||||
> 最后更新：2026-09-17
|
||||
|
||||
---
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
> 关联文档：
|
||||
> - `doc/docs/TMS业财融合-集成流程图文字版与业务流程梳理.md`（图03 财务应付及付款，步骤4 推送金蝶 / 步骤13 异常回收）
|
||||
> - `doc/adr/0005-B901事件驱动双表锁单模型.md`（UNLOCK 置失败态不自动重推；A103-2 连续两轮查询消失兜底复用 `unlockBill()`）
|
||||
> - `doc/docs/业务流程/付款申请同步金蝶（星瀚）技术文档.md`（A103-3 接口定义）
|
||||
> - `doc/docs/业务流程/2026-09-16-付款申请同步金蝶（星瀚）技术文档.md`（A103-3 接口定义）
|
||||
> - `doc/docs/业务流程/2026-09-17-付款管理金蝶付款结果定时回写（A103-2付款申请单查询+A103-4付款处理查询）技术文档.md`
|
||||
> - `doc/docs/业务流程/2026-09-18-付款管理金蝶同步全链路逻辑梳理（推送链路与回写链路连贯性）.md`
|
||||
|
||||
|
||||
+73
-23
@@ -1,6 +1,7 @@
|
||||
# 金蝶单据锁定与解锁业务流程（lockBusiData 锁定 - unLockNotifyBusiData 回调 - 失败补偿 - 删单还原）
|
||||
|
||||
- 日期：2026-10-09（2026-10-10 变更：① lockBusiData 确认为 1对1 接口，不支持逗号拼接批量，锁定/补偿改为逐张调用；② 付款申请单纳入锁单范围并完成接线）
|
||||
- 日期：2026-10-09（2026-10-10 变更：① lockBusiData 确认为 1对1 接口，不支持逗号拼接批量，锁定/补偿改为逐张调用；② 付款申请单纳入锁单范围并完成接线。
|
||||
2026-10-15 联调修正：③ 回调方向与锁定相反，解锁定位改为「金蝶单号+我方单号」双条件反查（targetBillType 回调为空不参与匹配）；④ 回调处理批量化去 N+1；⑤ 付款申请 DELETE 还原链路实测通过；⑥ 解锁终态页面标识通用方案（KingdeeUnlockMark））
|
||||
- 范围：正式结算单（应付 A102-2 / 应收 A302-2）、开票申请单（A303-1）、付款申请单（A103-1 应付下推 / A103-3 直接保存，2026-10-10 新纳入）推送金蝶成功后的单据锁定、金蝶解锁/删单回调、锁定失败定时补偿
|
||||
- 设计文档：`docs/superpowers/specs/2026-10-09-kingdee-bill-lock-unlock-design.md`
|
||||
- 锁记录表：`blade_kingdee_bill_lock`（一行 = 一张金蝶目标单）
|
||||
@@ -46,31 +47,71 @@
|
||||
|
||||
### 2. 金蝶侧解锁回调（金蝶 → WLTMS）
|
||||
|
||||
金蝶在星瀚侧对单据解锁或删单后，回调 `POST /kingdee-bfi/unLockNotifyBusiData`（`UNLOCK`；targetBillNo 兼容单张/逗号拼接）：
|
||||
金蝶在星瀚侧对单据解锁或删单后，回调 `POST /kingdee-bfi/unLockNotifyBusiData`（`UNLOCK`）。
|
||||
|
||||
**回调方向与锁定相反（2026-10-15 真实报文确认）**：lockBusiData 由 WLTMS 发起（source=我方、target=金蝶），
|
||||
unLockNotifyBusiData 由金蝶发起（source=金蝶、target=我方）。因此回调报文中：
|
||||
`sourceBillNo`=金蝶单号（即锁记录 `targetBillNo`）、`targetBillNo`=WLTMS 单号（即锁记录 `sourceBillNo`）、
|
||||
`targetBillType` **实测为空**（不参与匹配）。真实报文示例：
|
||||
|
||||
```json
|
||||
{"lockAction":"UNLOCK","operationType":"DELETE","operator":"刘泉佳","sourceBillNo":"FKSQ-00000227",
|
||||
"sourceBillType":"ap_payapply","sourceSystem":"XH","targetBillNo":"FKD2026101400001",
|
||||
"targetBillType":"","targetSystem":"WLTMS","time":"2026-10-15 10:10:56"}
|
||||
```
|
||||
|
||||
处理逻辑（`KingdeeBillLockServiceImpl.onUnlockNotify`）：
|
||||
|
||||
```
|
||||
校验：sourceSystem=XH、targetSystem=WLTMS、lockAction=UNLOCK（否则应答失败）
|
||||
│
|
||||
├─ operationType=SAVE（仅解锁，没删单）
|
||||
│ └─ 锁记录 → unlocked，记录回调操作人/时间，解锁动作留痕
|
||||
│
|
||||
└─ operationType=DELETE（金蝶把单删了）
|
||||
├─ 锁记录 → unlocked（同上）
|
||||
└─ 按 targetBillType 反查 WLTMS 单据类型，分发还原：
|
||||
├─ SETTLEMENT → 结算单作废（当前节点→已作废），
|
||||
│ 同步信息还原推送前状态：kingdeeSyncStatus→unsynced、
|
||||
│ 清 kingdeeBillNo/kingdeeBillId/syncedTime
|
||||
│ 变更流水记"金蝶删单回调自动废除"，操作人=金蝶报文 operator
|
||||
├─ INVOICE_APPLY → 开票申请作废，kingdeeStatus→unsynced、清单据编号，
|
||||
│ 刷新关联结算单开票状态，动作流水记 kingdee_delete
|
||||
└─ PAY_APPLY → 付款申请复用 unlockBill(id, "金蝶删单回调")（ADR-0005 口径）：
|
||||
kingdeeStatus→生成失败、清 kingdeeBillId/kingdeeBillNo（原值日志留档），
|
||||
不作废源单、不自动重推，人工核实后重推（A103-2 勾稽预检防重复推单）
|
||||
校验：sourceSystem=XH、targetSystem=WLTMS、lockAction=UNLOCK、sourceBillNo/targetBillNo 非空（否则应答失败）
|
||||
│
|
||||
├─ 一次 IN 查询：target_bill_no in (回调sourceBillNo拆分, 支持逗号批量) and source_bill_no = 回调targetBillNo，
|
||||
│ 按 id 降序取回，内存归并出各金蝶单号最新一条锁记录（避免逐张查询 N+1）
|
||||
│
|
||||
├─ 逐张匹配：无记录或非 locked → 幂等跳过（warn 留痕，重复通知防金蝶重试风暴）
|
||||
│
|
||||
├─ 命中 locked → 解锁状态批量落库：lock_status→unlocked、operationType、unlockTime、notifyOperator
|
||||
│ （updateBatchById 一次批量更新，避免逐张 update N+1）
|
||||
│
|
||||
└─ operationType=DELETE（金蝶把单删了）→ 按「锁记录自身 targetBillType」反查 WLTMS 单据类型，分发还原：
|
||||
├─ SETTLEMENT → 结算单作废（当前节点→已作废），
|
||||
│ 同步信息还原推送前状态：kingdeeSyncStatus→unsynced、
|
||||
│ 清 kingdeeBillNo/kingdeeBillId/syncedTime
|
||||
│ 变更流水记"金蝶删单回调自动废除"，操作人=金蝶报文 operator
|
||||
├─ INVOICE_APPLY → 开票申请作废，kingdeeStatus→unsynced、清单据编号，
|
||||
│ 刷新关联结算单开票状态，动作流水记 kingdee_delete
|
||||
└─ PAY_APPLY → 付款申请复用 unlockBill(id, "金蝶删单回调")（ADR-0005 口径）：
|
||||
kingdeeStatus→生成失败、清 kingdeeBillId/kingdeeBillNo（原值日志留档），
|
||||
不作废源单、不自动重推，人工核实后重推（A103-2 勾稽预检防重复推单）
|
||||
|
||||
应答：{updateCount: 处理张数, updateResultList: [1]}
|
||||
```
|
||||
|
||||
重复回调幂等：单据已作废或锁记录已 unlocked → 该张跳过，不重复还原。
|
||||
|
||||
**事务语义**：整个回调处理在 `onUnlockNotify` 单一事务内（还原分支 `voidByKingdee`/`unlockBill` 均为 REQUIRED 传播加入同事务）——
|
||||
任一张还原失败，**整批回滚**（包括已批量落库的解锁状态），应答失败触发金蝶重试，重试时按幂等口径从头重处理。
|
||||
不存在"部分成功"中间态；若单张问题单阻塞整批回调，需人工处理后金蝶重试自动闭环。
|
||||
|
||||
**解锁后数据变化**（2026-10-15 实测口径）：
|
||||
|
||||
锁记录（三类单据通用，`blade_kingdee_bill_lock`）：
|
||||
|
||||
| 字段 | 变化 |
|
||||
| --- | --- |
|
||||
| lock_status | locked → unlocked（终态） |
|
||||
| operation_type | 回调报文 operationType（SAVE-金蝶锁单（保存触发解锁，单据仍在）/ DELETE-金蝶删单） |
|
||||
| unlock_time | WLTMS 处理时间（注意：非金蝶报文 time，金蝶侧操作时间以日志为准） |
|
||||
| notify_operator | 回调报文 operator（金蝶侧操作人） |
|
||||
|
||||
业务单据（按类型）：
|
||||
|
||||
| 业务单据 | 作废状态 | 金蝶同步信息 | 其他 |
|
||||
| --- | --- | --- | --- |
|
||||
| 正式结算单（SETTLEMENT） | approval_status → voided（已作废，终态），当前节点→已作废 | kingdeeSyncStatus → unsynced，清 kingdeeBillNo/kingdeeBillId/syncedTime | 变更流水记"金蝶删单回调自动废除"，操作人=金蝶报文 operator |
|
||||
| 开票申请（INVOICE_APPLY） | approval_status → voided（作废） | kingdeeStatus → unsynced，清单据编号 | 刷新关联结算单开票状态；动作流水记 kingdee_delete |
|
||||
| 付款申请（PAY_APPLY） | **不作废**，approval_status 不变 | kingdeeStatus synced/paying → failed（仅这两态可变，幂等守卫），清 kingdeeBillId/kingdeeBillNo（原值日志留档） | 不自动重推，人工核实后重推；页面靠解锁标识区分金蝶删单与推送失败 |
|
||||
|
||||
### 3. 锁定失败补偿（定时兜底，不依赖人工）
|
||||
|
||||
```
|
||||
@@ -100,7 +141,7 @@ failed（锁定失败，待补偿）→ locked（金蝶锁定中）→ unlocked
|
||||
│ │
|
||||
│ ├─ 锁定成功：locked（冻结，不可动）
|
||||
│ │ │
|
||||
│ │ ├─ 金蝶解锁(SAVE)：unlocked，流水留痕
|
||||
│ │ ├─ 金蝶锁单(SAVE)：unlocked，流水留痕
|
||||
│ │ └─ 金蝶删单(DELETE)：作废 + 同步信息还原 unsynced
|
||||
│ │ （结算明细/付款/开票关联的后续动作
|
||||
│ │ 由各自前置校验自然拦截重推）
|
||||
@@ -113,8 +154,9 @@ failed（锁定失败，待补偿）→ locked（金蝶锁定中）→ unlocked
|
||||
1. **先占位再锁**：锁记录落库先于远程调用，补偿任务扫 `failed` 就是完整的待重试集合，不漏单
|
||||
2. **锁失败不回滚推送**：金蝶单已生成，本地回滚只会制造断链；代价是短暂"已推未锁"窗口，由补偿任务闭合
|
||||
3. **1对1逐张锁**：lockBusiData 单次仅支持一个源单号对一个金蝶单号，逐张调用互不连坐；成败结果 updateBatchById 批量落库，避免逐张 update
|
||||
4. **回调幂等**：按 targetBillType+targetBillNo 找最新 locked 记录，找不到/已 unlocked 直接跳过应答成功，防金蝶重试风暴
|
||||
5. **DELETE 还原口径**：作废源单 + 清金蝶同步信息 + 关联状态刷新；作废是终态，重推需新单重走流程（口径待业务联调确认）
|
||||
4. **回调幂等**（2026-10-15 修正）：回调方向与锁定相反，按「金蝶单号（回调 sourceBillNo）+ 我方单号（回调 targetBillNo）」双条件找最新 locked 记录（targetBillType 回调为空不参与匹配），找不到/已 unlocked 直接跳过应答成功，防金蝶重试风暴；
|
||||
批量回调一次 IN 查询 + updateBatchById 批量落库，无逐张 N+1
|
||||
5. **DELETE 还原口径**：作废源单 + 清金蝶同步信息 + 关联状态刷新（结算单/开票申请）；付款申请不作废源单，走生成失败+人工重推（2026-10-15 联调实测通过）；作废是终态，重推需新单重走流程
|
||||
6. **前端锁状态展示**（2026-10-10 新增）：结算单/开票申请列表与详情 VO 填充 `kingdeeLockStatus`/`kingdeeLockFailReason`/`kingdeeTryCount`
|
||||
（后端 `mapActiveLocks` 每页一次批量查锁表，无 N+1；unlocked 终态不返回即 null=无锁/已解锁）。
|
||||
前端渲染：`locked` 红 tag「金蝶锁定中」并禁用编辑/作废（后端守卫是权威）；`failed` 且 `tryCount<5` 橙 tag「锁定失败·补偿中」tooltip 显示原因；
|
||||
@@ -123,6 +165,12 @@ failed（锁定失败，待补偿）→ locked（金蝶锁定中）→ unlocked
|
||||
DELETE 还原不作废源单，复用既有 `unlockBill`（ADR-0005：生成失败+清编号内码+人工重推），与 A103-2 反审核删除兜底同口径；
|
||||
推送结果即时回填 kingdeeBillNo（`requireBfiBillIdAndFillNo`），推送事务提交后即以该单号 `lockAfterPush`；
|
||||
锁定失败摘要拼入「同步金蝶」返回值（与开票申请同款），页面直接可见
|
||||
8. **解锁终态页面标识**（2026-10-15 新增，通用方案）：付款申请解锁后不作废（仅 kingdeeStatus=failed），与推送失败无法区分；
|
||||
结算单/开票申请虽变已作废，但看不出是金蝶删单导致。统一方案：
|
||||
VO 实现 `KingdeeUnlockMark` 展示契约（解锁时间/操作人/动作名称三字段），
|
||||
`KingdeeBillLockService.fillUnlockMarks` 对无活跃锁的行一次 IN 反查最新 unlocked 锁记录（`mapUnlockedLocks`）统一回填；
|
||||
前端三个页面（付款申请/开票申请/正式结算单）金蝶锁状态列渲染：`kingdeeUnlockTime` 非空 →
|
||||
「金蝶删单」红 tag /「金蝶锁单」橙 tag，tooltip 显示操作人+时间；后续单据（如收票单）接入锁单时 VO 实现契约即可复用
|
||||
|
||||
## 五、代码落点速查
|
||||
|
||||
@@ -131,6 +179,7 @@ failed（锁定失败，待补偿）→ locked（金蝶锁定中）→ unlocked
|
||||
| 锁单 Feign/DTO/应答 VO | `blade-bfi-api`：`BfiBillLockDTO`、`BfiBillLockResultVO`、`IBfiClient.lockBusiData`、`IBfiService.lockBusiData` |
|
||||
| 锁类型常量与映射 | `transport/constant/KingdeeLockConstant`（PAY_APPLY/ap_payapply_oth_BT_S 已进 TARGET_TO_SOURCE_MAP） |
|
||||
| 锁状态展示填充 | `IKingdeeBillLockService.mapActiveLocks`（批量查活跃锁）+ `FormalSettlementServiceImpl/InvoiceApplicationServiceImpl/PaymentApplicationServiceImpl.fillKingdeeLockStatus`（列表/详情填充）+ 三个 VO 的 `kingdeeLockStatus/kingdeeLockFailReason/kingdeeTryCount` 字段 |
|
||||
| 解锁终态标识（2026-10-15） | 展示契约 `KingdeeUnlockMark`（三 VO 实现）+ `IKingdeeBillLockService.mapUnlockedLocks/fillUnlockMarks`（批量反查 unlocked 留痕并回填）；VO 字段 `kingdeeUnlockTime/kingdeeUnlockOperator/kingdeeUnlockOperationName`；前端 `payment-application.vue`/`invoice-application.vue`/`formal-settlement-table-panel.vue` 的 `lockTag` 渲染金蝶删单/解锁标签 |
|
||||
| 锁记录实体/服务 | `KingdeeBillLock`、`IKingdeeBillLockService` + `KingdeeBillLockServiceImpl` |
|
||||
| 回调端点 | `KingdeeBfiPublicController`：`POST /kingdee-bfi/unLockNotifyBusiData`（PERMIT_ALL + TenantIgnore） |
|
||||
| 补偿定时任务 | `KingdeeBillLockRetryTask`（`thirdParty.bfi.billLock.retryEnabled`，默认每5分钟） |
|
||||
@@ -150,4 +199,5 @@ failed（锁定失败，待补偿）→ locked（金蝶锁定中）→ unlocked
|
||||
Nacos 实际配置已核对一致；环境级 blade-dev/test/prod.yaml 无 secure 段覆盖。
|
||||
联调验证：服务启动后无令牌 POST 应返回业务参数校验错误（JSON），返回 401「请求未授权」即白名单未生效
|
||||
4. 与金蝶确认 WLTMS 单据类型编码（SETTLEMENT/INVOICE_APPLY/PAY_APPLY）与 DELETE 还原口径
|
||||
（付款申请 DELETE 不作废源单、走生成失败+人工重推，与 A103-2 反审核删除兜底同口径，待业务确认）
|
||||
（付款申请 DELETE 不作废源单、走生成失败+人工重推，与 A103-2 反审核删除兜底同口径；
|
||||
2026-10-15 付款申请链路已联调实测通过：回调方向反转定位、DELETE 还原、解锁标识均验证 OK）
|
||||
|
||||
@@ -419,7 +419,7 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶）
|
||||
|
||||
- 推送闸门：已推送（pushed）流水跳过不重推；`billid`（认领公告 id）缺失拦截「请先同步金蝶收款流水」；结算单金蝶内码缺失拦截不推。
|
||||
- 幂等：`awrp_src_code` 重试复用同一编码；作废认领不再生成本地冲单（金蝶单据状态保留原值）。
|
||||
- A301-3 字段待金蝶确认项仍在：`recpaytype_number`（示例 101）、`paymenttype`、`recpayer`（金蝶付款人 master id）。
|
||||
- A301-3 字段待金蝶确认项仍在：`recpaytype_number`（常量当前值 "999"，注释示例 101 待确认）、`paymenttype`、`recpayer`（金蝶付款人 master id）。
|
||||
|
||||
---
|
||||
|
||||
@@ -621,7 +621,7 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶）
|
||||
| # | 事项 | 证据/说明 |
|
||||
|---|---|---|
|
||||
| 1 | **A103-1 勾稽键口径**：代码传本地组装的应付防重键，`PaymentApplicationServiceImpl:1431-1443` 注释仍写「A102-4 反查 awrp_entry_code_p、禁止自行拼接」——注释与代码矛盾，金蝶侧付款计划分录标识是否等于防重键需联调实测 | 高优先 |
|
||||
| 2 | **项目编码 999 残留**：A102-2/A302-2/A103-1/开票申请仍传测试值 999（仅 A103-3 已用真实项目编码） | 上线前处理 |
|
||||
| 2 | **项目编码 999 残留**：全部推送链路（应付/应收/付款/预付款/开票申请）仍传测试值 999；A103-3「取项目档案真实编码」的逻辑已注释停用（详见入参映射表 14-#2） | 上线前处理 |
|
||||
| 3 | **计量单位不送**：分录 DTO 有字段无赋值——需与金蝶确认不送计量单位是否影响单据校验 | 联调确认 |
|
||||
| 4 | **A301-3 字段待金蝶确认**：`recpaytype_number`(101)/`paymenttype`/`recpayer` 取值口径 | 联调确认 |
|
||||
| 5 | **A301-2 claimusers 未配置风险**：缺省空串调 A301-2 查不到数据（无报错），需在 Nacos 必配 | 配置项 |
|
||||
@@ -636,5 +636,6 @@ iPaaS 网关（/gwzh/BFI，不直连金蝶）
|
||||
|
||||
## 附：文档关系
|
||||
|
||||
- 本文为新总纲（基线 2026-10-13 `805ca9d3`），替代 09-27 版；单链路细节仍以 `doc/docs/业务流程/` 对应专项文档为深入参考，冲突处以本文 + 当前代码为准。
|
||||
- 本文为新总纲（基线 2026-10-13 `805ca9d3`，2026-10-15 增补），替代 09-27 版；单链路细节仍以 `doc/docs/业务流程/` 对应专项文档为深入参考，冲突处以本文 + 当前代码为准。
|
||||
- **各推送接口的逐字段入参取值映射（页面字段→表字段/配置对照）见《2026-10-15-金蝶（星瀚）BFI推送入参取值映射表（页面字段-表字段-配置对照）.md》**，其第 14 节含与本文记载不一致的代码级核对结论。
|
||||
- 09-27 版中被本文修订的关键结论：A801-3 回写缺陷、票池「实时回源无定时」架构、收款认领「全手动无定时」、分录调试覆盖、物料映射常量、failed 落库口径、A801-5/A801-2/A902「未实现」状态。
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 246 KiB |
@@ -8,6 +8,13 @@
|
||||
---
|
||||
|
||||
## 1. 全局须知
|
||||
金蝶测试环境地址：https://cqcs-test.gxwuzi.com:8022/ierp/login.html
|
||||
|
||||
账号密码：
|
||||
|
||||
13545909224 liuquanjia@123
|
||||
|
||||
13737128880 websoft5386339
|
||||
|
||||
### 1.1 金蝶单据状态含义（列表里看到的字段）
|
||||
|
||||
@@ -177,6 +184,8 @@
|
||||
|
||||
1. 选票：表单里点发票号放大镜 → 弹出「查询金蝶票据池」→ 勾选 → 确认（带出票面信息）。
|
||||
|
||||
|
||||
|
||||
- 票池数据来自定时同步（默认每 30 分钟）；票号精确搜索时若本地没有会**自动去金蝶现查**。
|
||||
- 查不到票 → 等同步或让运维检查票种白名单配置/手动触发同步（见 4.2）。
|
||||
2. 保存：系统自动**重查金蝶票池校验可用性**——票已被别人登记/认领/红冲/作废会保存失败并提示原因。
|
||||
@@ -239,21 +248,62 @@
|
||||
|
||||
### 4.1 任务清单（Nacos `thirdparty.bfi.*` 配置）
|
||||
|
||||
| 任务 | 干什么 | 开关键 | cron 键（默认频率） | 手动替代按钮 |
|
||||
| 任务 | 干什么 | 开关键 | cron 键（默认值） | 手动替代按钮 |
|
||||
|---|---|---|---|---|
|
||||
| 付款结果回写 | 付款状态（paid/closed）+ 付款记录/凭证回写；顺带应收勾稽纠偏、开票结果回写 | `thirdParty.bfi.payResult.syncEnabled`（样例已开） | `…payResult.cron`（10 分钟） | 付款「同步付款结果」、开票结果手动端点、结算勾稽手动端点 |
|
||||
| 收票结果回写 | 收票单状态回写、pushed 断点补发指定应付 | `…receivedInvoiceResult.syncEnabled` | 每 10 分钟 | 收票「同步金蝶结果」 |
|
||||
| 客商同步 | 金蝶审核状态复查（synced→exist）、停用联动、failed 重推 | `…customer.syncEnabled` | 每天 02:00 | 客商「同步金蝶」 |
|
||||
| 收款认领推送 | 自动推送认领完成的流水到金蝶 | `…receiptClaimPush.syncEnabled` | 每 10 分钟 | 流水行内「推送金蝶」 |
|
||||
| 全票池同步 | 拉金蝶全票池发票到本地镜像、补绑定 | `…invoiceReceipt.syncEnabled` | 每 30 分钟 | 手动端点 `POST /invoice-receipt/sync-invoice-pool` |
|
||||
| failed 重推 | 自动重推所有推送失败的结算/付款/开票/收票单 | `…autoSync.retryEnabled` | 每 10 分钟 | 各页面「同步金蝶」 |
|
||||
| 锁单补偿 | 推送成功但金蝶锁定失败的自动补锁（≤5 次） | `…billLock.retryEnabled` | 每 5 分钟 | 手动端点 `POST /formal-settlement/retry-kingdee-bill-lock` |
|
||||
| 付款结果回写 | 付款状态（paid/closed）+ 付款记录/凭证回写；顺带应收勾稽纠偏、开票结果回写 | `thirdParty.bfi.payResult.syncEnabled`（样例已开） | `…payResult.cron`（默认 `0 1/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` |
|
||||
| failed 重推 | 自动重推所有推送失败的结算/付款/开票/收票单 | `…autoSync.retryEnabled` | `…autoSync.retryCron`（默认 `0 5/10 * * * ?`） | 各页面「同步金蝶」 |
|
||||
| 锁单补偿 | 推送成功但金蝶锁定失败的自动补锁（≤5 次） | `…billLock.retryEnabled` | `…billLock.retryCron`（默认 `0 2/5 * * * ?`） | 手动端点 `POST /formal-settlement/retry-kingdee-bill-lock` |
|
||||
|
||||
### 4.2 审批自动同步开关（按业务域独立）
|
||||
### 4.2 各任务的运转逻辑
|
||||
|
||||
**共性规则（先读这个）**
|
||||
|
||||
- **终态不轮询**：付款 paid（已付款）/closed（已关闭）、开票 invoiced（已开票）、收票 assigned（已指定应付）、客商 exist（金蝶已审核）、认领流水 pushed（已推送金蝶）后自动退出扫描范围——任务只处理「还没走完」的单据，越跑越轻，不会重复处理。
|
||||
- **定时与手动同一套逻辑**：每个任务与它的「手动替代按钮」调用同一个服务方法，效果完全一致；区别只是触发方式。
|
||||
- **单条失败不拖批次**：一轮里某条单据失败只记录原因，同批其余照常处理；失败的下轮自动再试（兜底见 ⑥ failed 重推）。
|
||||
- **默认执行时间错峰**（付款 ：01、认领 ：04、failed 重推 ：05、收票 ：08、锁补偿每 5 分钟的 ：02、票池每 30 分钟的 ：16），互不挤占；自行改 cron 时建议保留错峰。
|
||||
|
||||
**① 付款结果回写（10 分钟）**
|
||||
扫「审批通过且已推送 / 付款中 / 推送失败」的付款申请 → 到金蝶查付款申请单和付款处理单 → 推进 synced（已推送受理）→ paying（金蝶付款中）→ **paid（已付款）/ closed（已关闭）**，paid 时回写付款记录/凭证，并联动刷新预结算垫资、结算付款记录（3.4 第 3 步的「正常等定时回写」就是它）。
|
||||
- 自愈一（应收勾稽）：已推送但失败、或缺金蝶单号的**应收结算单**，查金蝶有则自动补单号、纠回 synced——「实际推成功但本地显示失败」的场景自动痊愈；
|
||||
- 自愈二（开票结果）：已受理的开票申请自动落发票信息并推进 **invoiced（已开票，终态）**（3.5 第 3 步的定时回写就是它）；
|
||||
- 防呆（金蝶删单）：synced（已推送受理）/paying（金蝶付款中）的单据**连续 2 轮（约 20 分钟）在金蝶查不到** → 判定金蝶侧已删，自动解锁置 failed（推送失败）并清空金蝶单号，等人工核实后重推；重推带幂等预检，金蝶单据其实还在时会自动回填，不会重复生成。
|
||||
|
||||
**② 收票结果回写（10 分钟）**
|
||||
扫 pushed（金蝶收票单已生成）/ assigned（已指定应付）的收票登记，按近 **30 天**回看窗口查金蝶收票单，一轮处理三种情况：
|
||||
- 票在金蝶被作废/红冲 → 置 failed（推送失败）并提示人工处理（**不要重推**，见 3.6）；
|
||||
- 卡在 pushed → 自动补发「指定应付」推进 **assigned（已指定应付，终态）**（3.6 说的「卡在 pushed 不用管」就是它）；
|
||||
- assigned 但缺金蝶收票单号 → 自动补登单号。
|
||||
窗口内查不到的保持现状不动（不判删除），由人工重推兜底。
|
||||
|
||||
**③ 客商同步（每天 02:00）**
|
||||
一次扫全部审批通过客商，干三件事：
|
||||
- **未推送/推送失败** → 先复查金蝶：已有且已审核的直接置 **exist（金蝶已有该客商且审核通过，终态）**（不重复建档）；金蝶侧审核中则置 failed（推送失败）提示稍后；确实没有才推送；
|
||||
- **已推送（synced，已推送受理）** → 金蝶审核通过自动升级 **exist（金蝶已审核，终态）**（3.1 第 5 步的定时升级就是它）；
|
||||
- **金蝶侧停用（enable=0）** → TMS 档案联动停用；金蝶恢复可用**不会**自动启用（单向联动，需人工启用）。
|
||||
|
||||
**④ 收款认领推送（10 分钟）**
|
||||
扫「认领完成（claimed）且未推送/推送失败」的收款流水 → 按认领人逐人拉最新认领公告**对账**（本地认领金额与公告未认领金额一致才推）→ 推送成功回写金蝶收款单号、流水置 **pushed（已推送金蝶）**（3.7 第 3 步的「自动」就是它）。失败的下一轮自动重试，防重码按分摊结算单生成、重试不变，不会在金蝶重复生成收款单。
|
||||
|
||||
**⑤ 全票池同步（30 分钟）**
|
||||
按近 **30 天**增量窗口分页拉取金蝶全票池发票到本地镜像表，收票选票、票池查询全部走本地镜像——所以**刚在金蝶开的票要等同步后才能选到**；急用可让运维手动触发同步端点，或用票号精确搜索（会自动去金蝶现查，见 3.6）。
|
||||
|
||||
**⑥ failed 重推（10 分钟）**
|
||||
只重推 **failed（推送失败）** 单据（结算 → 付款 → 开票 → 收票四个域依次处理）；**unsynced（审批通过但从未推送）不会自动推**——历史存量单不会被上线后批量补推，仍走手动按钮。前置没就绪（如上游应付单还没生成）会再次 failed、下轮继续；前置就绪后自动续推成功。
|
||||
⚠️ 重推**没有次数上限**：根因不修（联行号缺失、组织编码缺失等）会每 10 分钟失败一次刷日志，修复根因是唯一正解（呼应 4.4）。
|
||||
|
||||
**⑦ 锁单补偿（5 分钟）**
|
||||
扫「推送成功但金蝶锁定失败」的锁记录，重试加锁，**最多 5 次**；超过 5 次放弃，需运维调手动补偿端点 `POST /formal-settlement/retry-kingdee-bill-lock`（对应 FAQ 的「锁定失败」标签）。
|
||||
|
||||
### 4.3 审批自动同步开关（按业务域独立）
|
||||
|
||||
`thirdParty.bfi.autoSync.settlement`（结算单）/ `…payment`（付款）/ `…invoiceApply`（开票）/ `…receipt`（收票），默认全关。**代码默认全部关闭，必须在 Nacos 显式开启**；客商档案审批推送不受此开关控制（始终自动）。
|
||||
|
||||
### 4.3 运维注意
|
||||
### 4.4 运维注意
|
||||
|
||||
- 所有定时任务带**分布式锁**：多实例部署只跑一份；手动按钮和定时共用锁，定时运行中手动触发会直接跳过（属正常）。
|
||||
- 开了「failed 重推」后，持续失败的单据每 10 分钟会重试一次，**修复根因**（配置/数据）比反复观察更重要。
|
||||
@@ -315,4 +365,4 @@
|
||||
|
||||
---
|
||||
|
||||
> 本文基于 2026-10-14 代码现状整理；系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档的更新说明。
|
||||
> 本文基于 2026-10-14 代码现状整理；2026-10-19 依据当前代码核对并补充 4.2 定时任务运转逻辑（cron 默认值、错峰、终态不轮询、防呆与自愈行为）。系统升级后按钮与提示如有出入，以页面实际为准，并核对全链路总纲文档的更新说明。
|
||||
|
||||
@@ -0,0 +1,409 @@
|
||||
# 金蝶（星瀚）BFI 推送入参取值映射表：页面字段 → 数据库表字段 / 配置对照
|
||||
|
||||
> 整理日期：2026-10-15
|
||||
> 代码基线：`tms-api` 当前 master（分支 `feature/payment-apply-bfi-sync`，提交 `259407c3` 之后）。
|
||||
> 用途：给联调/实施/排查用——每个送金蝶的入参，**页面上是哪个字段、落库在哪张表哪个字段、或来自哪个配置/常量**。逐字段核对代码（文件+行号见各节备注）。
|
||||
> 配套文档：《2026-10-14-金蝶（星瀚）BFI全链路梳理（前端-后端-定时任务·业务域汇总与操作手册）.md》。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [0. 公共取数与通用规则](#0-公共取数与通用规则)
|
||||
- [1. A100-1 获取令牌](#1-a100-1-获取令牌)
|
||||
- [2. A902-2 客户保存](#2-a902-2-客户保存)
|
||||
- [3. A801-5 黑名单查询](#3-a801-5-黑名单查询)
|
||||
- [4. A102-2 财务应付单保存](#4-a102-2-财务应付单保存)
|
||||
- [5. A302-2 财务应收单保存（与应付差异）](#5-a302-2-财务应收单保存与应付差异)
|
||||
- [6. A103-1 付款申请下推](#6-a103-1-付款申请下推)
|
||||
- [7. A103-3 预付款申请保存](#7-a103-3-预付款申请保存)
|
||||
- [8. A303-1 开票申请单保存](#8-a303-1-开票申请单保存)
|
||||
- [9. A303-2 收票单保存 + A302-6 指定应付](#9-a303-2-收票单保存--a302-6-指定应付)
|
||||
- [10. A301-3 收款认领结果推送](#10-a301-3-收款认领结果推送)
|
||||
- [11. lockBusiData 单据锁定](#11-lockbusidata-单据锁定)
|
||||
- [12. A902 附件上传](#12-a902-附件上传)
|
||||
- [13. 查询类接口入参简表](#13-查询类接口入参简表)
|
||||
- [14. 与总纲记载不一致的核对结论](#14-与总纲记载不一致的核对结论)
|
||||
|
||||
---
|
||||
|
||||
## 0. 公共取数与通用规则
|
||||
|
||||
### 0.1 配置前缀（两套并存，勿混）
|
||||
|
||||
| 前缀 | 归属 | 内容 |
|
||||
|---|---|---|
|
||||
| `third-party.bfi.*` | bfi-api 客户端（令牌/网关） | baseUrl、authorization、clientId、clientSecret、username、accountId、language |
|
||||
| `thirdparty.bfi.*` | blade-transport 业务 | srcSys、各业务开关/cron、payApply.*、invoiceApply.*、receivedInvoice.*、material.*、claimAnnounce.*、blacklist.*、billLock.*（宽松绑定兼容 camelCase） |
|
||||
|
||||
### 0.2 通用取数
|
||||
|
||||
| 项 | 规则 | 代码 |
|
||||
|---|---|---|
|
||||
| awrp_src_sys / systemsource / sourceSystem | Nacos `thirdparty.bfi.srcSys`，默认常量 `WLTMS` | BfiProperties(srcSys) |
|
||||
| 组织 org/结算/付款/收款组织（核算/资金类） | **统一取公司级编码**：项目业务部门沿部门树向上反查平台公司（`is_platform_company=1`）→ 平台公司 `blade_dept.kingdee_dept_code`；未归属平台公司/未维护编码直接拦截 | `kingdeeOrgNumber`（KingdeeApBillSyncSupport L976-999），项目经 `blade_project_apply.business_dept_id` |
|
||||
| 申请部门类字段（A303-1 awrp_orgfield） | 申请部门自身 `kingdee_dept_code`（部门级业务单元编码，星瀚允许） | 申请单 dept_id → `blade_dept.kingdee_dept_code` |
|
||||
| 币种 | 合同结算币种，`RMB→CNY` | `blade_contract_manage.settlement_currency`（bfiCurrency L952-956） |
|
||||
| 往来户 | 名称 → `blade_customer_archive` 按 `full_name/short_name` 匹配（limit 1）取 `customer_code`，查不到报错 | queryCustomerCode L966-984 |
|
||||
| 日期文本 | 统一 `yyyy-MM-dd HH:mm:ss` | bfiDateTimeText L922-925 |
|
||||
| 防重键 awrp_src_code | `ExternalSrcCodeSupport.buildSrcCode`：下划线拼接、去空白、去重保序 | ExternalSrcCodeSupport L54-63 |
|
||||
|
||||
### 0.3 分录拆分规则（A102-2/A302-2/A303-2 共用 `resolveEntryGroups`）
|
||||
|
||||
- 拆分维度：**货物 → 费用大类（装卸/运输）→ 税率** 三级分组，各组成一条分录；手动合计费用项（manual_flag=1）每行一条。
|
||||
- 物料编码：装卸大类/手动非运费杂费 → `thirdparty.bfi.material.loading`（默认 XDWL11002004）；项目业务模式或业务类型含「国际」→ `.international`（Item-00001081）；国内按运单运输方式 → `.domestic.公路运输`=XDWL11010001 / `.铁路运输`=XDWL11010002 / `.水路运输`=XDWL11010003 / `.航空运输`=Item-00001082；运输方式未配置直接拦截。
|
||||
- 税率：货物费用行按合同计费方案规则分组（`blade_contract_manage.billing_plan_json` 的 `rules[].feeType/feeItem/taxRate`）；税率未配置并入无税率组。
|
||||
- 数量：运输类=结算明细运输量（≤0 兜底 1，同税率拆多行每行都取运输量）；装卸/合计费用项行=1；单价=金额÷数量反算（2 位 HALF_UP）。
|
||||
- 0 元费用项（signum==0）与 0 元货物行整行跳过。
|
||||
- 计量单位**当前不送**（DTO 有字段无赋值）。
|
||||
|
||||
---
|
||||
|
||||
## 1. A100-1 获取令牌
|
||||
|
||||
| 入参 | 含义 | 来源：配置键 / 生成方式 |
|
||||
|---|---|---|
|
||||
| client_id | 应用编码 | `third-party.bfi.clientId` |
|
||||
| client_secret | 认证密钥 | `third-party.bfi.clientSecret` |
|
||||
| username | 访问用户名 | `third-party.bfi.username` |
|
||||
| accountId | 数据中心 ID | `third-party.bfi.accountId` |
|
||||
| language | 语言 | `third-party.bfi.language`（默认 `zh_CN`） |
|
||||
| nonce | 随机数 | 每次生成 `UUID` |
|
||||
| timestamp | 时间戳（±5 分钟校验） | 每次生成 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
> 令牌缓存 Redis `blade:third:bfi:token`，TTL=expires_in−120s；`setIfAbsent` 写入。代码：BfiServiceImpl L136-156、BfiTokenDTO L44-65。
|
||||
|
||||
---
|
||||
|
||||
## 2. A902-2 客户保存
|
||||
|
||||
调用链：`CustomerArchiveServiceImpl.syncKingdee → pushCustomerToKingdee → CustomerBfiConverter.buildSaveDTO`
|
||||
|
||||
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 常量 |
|
||||
|---|---|---|---|
|
||||
| number | 客户编码（不传由星瀚生成） | 客商编号（提交时生成 KS+6 位） | blade_customer_archive.customer_code |
|
||||
| name【必】 | 名称 | 客商名称 | blade_customer_archive.full_name |
|
||||
| societycreditcode【必】 | 统一社会信用代码（金蝶候选键） | 统一社会信用代码 | blade_customer_archive.unified_credit_code |
|
||||
| tx_register_no | 纳税人识别号 | 同上（同一字段） | blade_customer_archive.unified_credit_code |
|
||||
| artificialperson | 法人代表 | 企业法人 | blade_customer_archive.legal_person |
|
||||
| type【必】 | 伙伴类型（1~17） | 客商性质字典 | blade_customer_archive.customer_nature + 字典 `nature_of_client` dictKey（文本值反查 dictKey，无效抛异常） |
|
||||
| bizpartner_address | 详细地址 | 注册地址 | blade_customer_archive.registered_address |
|
||||
| bizpartner_phone | 联系电话 | 联系电话 | blade_customer_archive.contact_phone |
|
||||
| businessterm | 营业期限 | 营业期限类型=长期→「长期」；否则「至 yyyy-MM-dd」 | blade_customer_archive.business_term_type / business_end_date |
|
||||
| businessscope | 经营范围 | 经营范围多选 → 字典 `scope_of_business` 文本「、」拼接 | blade_customer_archive.business_scope |
|
||||
| bizfunction | 业务职能 | 固定全选 | 常量 `"1,2,3,4"` |
|
||||
| fcusbeizhu | 备注 | 备注（空不传） | blade_customer_archive.remark |
|
||||
| awrp_datasourcesys | 数据来源 | 配置 | `thirdparty.bfi.srcSys` |
|
||||
| awrp_cusfortrade【必】 | 是否贸易客商 | 固定 | 常量 `"A"` |
|
||||
| entry_groupstandard[].standardid_number【必】 | 分类标准 | 固定 | 常量 `"JBFLBZ"` |
|
||||
| entry_groupstandard[].groupid_number【必】 | 客户分组 | 客户类型：internal→1101，其余→1102 | blade_customer_archive.customer_kind + 常量 1101/1102 |
|
||||
| entry_bank[].bankaccount | 银行账号（金蝶候选键） | 收款账号 | blade_customer_receipt_account.bank_account |
|
||||
| entry_bank[].accountname | 账户名称 | **传开户行名称** | blade_customer_receipt_account.bank_name |
|
||||
| entry_bank[].bank_number | 开户银行.编码（联行号） | 联行号 | blade_customer_receipt_account.cnaps_code |
|
||||
| entry_bank[].currency_number【必】 | 币种 | 固定 | 常量 `"CNY"` |
|
||||
| entry_bank[].isdefault_bank | 默认银行 | 固定 | `true` |
|
||||
| entry_linkman[].contactperson | 联系人 | 客商负责人（空则整组分录不传） | blade_customer_archive.principal |
|
||||
| entry_linkman[].phone | 电话 | 联系电话 | blade_customer_archive.contact_phone |
|
||||
| entry_linkman[].isdefault_linkman | 默认联系人 | 固定 | `true` |
|
||||
|
||||
不传字段：status、linkman、establishdate、postal_code、createorg_number（已注释）等。
|
||||
> 代码：CustomerBfiConverter L67-280、常量 CustomerBfiConstants / BfiConstant L288-313。
|
||||
|
||||
---
|
||||
|
||||
## 3. A801-5 黑名单查询
|
||||
|
||||
| 入参 | 含义 | 来源 |
|
||||
|---|---|---|
|
||||
| enable | 使用状态 | 固定 `"1"`（可用） |
|
||||
| number | 企业税号数组 | 客商发票信息所有纳税人识别号，`trim().toUpperCase()` 去重 → blade_customer_invoice_info.tax_no |
|
||||
| pageNo / pageSize | 分页 | 自动翻页（50 页保护）/ 固定 `2000` |
|
||||
| name | 企业名称数组 | 不传 |
|
||||
|
||||
> 命中判定按应答 awrpCombofield：A 硬拦截；B 默认放行告警（`thirdparty.bfi.blacklist.blockRiskWarning=true` 时拦截）；查询异常上抛阻断提审。代码：CustomerArchiveServiceImpl L1043-1092、BfiConstant L90。
|
||||
|
||||
---
|
||||
|
||||
## 4. A102-2 财务应付单保存
|
||||
|
||||
### 4.1 单据头
|
||||
|
||||
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| awrp_src_code【必·候选键】 | 来源单据号（防重键） | 结算单号+结算明细单据号 | blade_formal_settlement.formal_settlement_no + blade_formal_settlement_detail.document_no（document_no 空兜底明细行 id）下划线拼接 |
|
||||
| awrp_src_sys【必】 | 外部系统编号 | 配置 | `thirdparty.bfi.srcSys`（WLTMS） |
|
||||
| awrp_src_type【必】 | 外部单据类型 | — | 常量 `TMS财务应付单` |
|
||||
| billtypeid_number【必】 | 单据类型.编码 | — | 常量字典「服务采购应付」→ `ApFin_service_BT_S` |
|
||||
| org_number / payorg_number【必】 | 结算/付款组织.编码 | 合同关联项目业务部门上溯平台公司 | kingdeeOrgNumber → 平台公司 `blade_dept.kingdee_dept_code`（公司级核算组织编码） |
|
||||
| bizdate【必】 | 单据日期 | 同步当日 | LocalDate.now() |
|
||||
| asstacttype【必】 | 往来类型 | — | 常量 `bd_customer`（固定，供应商分支已注释） |
|
||||
| asstact_number【必】 | 往来户.编码 | 合同乙方 | blade_contract_manage.party_b → blade_customer_archive.customer_code |
|
||||
| purmode【必】 | 付款方式 | — | 常量 `CASH`（现购） |
|
||||
| currency_number【必】 | 结算币别 | 合同结算币种 | blade_contract_manage.settlement_currency（RMB→CNY） |
|
||||
| payproperty_number【必】 | 款项性质.编码 | — | 常量 `2001`（材料采购） |
|
||||
| isincludetax / ispricetotal | 含税价/总价录入 | — | `true` / `true` |
|
||||
| isintax | 按应付金额分配 | — | `false` |
|
||||
| exratedate / exchangerate | 汇率日期/汇率 | 结算单页面「汇率日期/结算汇率」，未维护不送 | blade_formal_settlement.exchange_rate_date / .exchange_rate |
|
||||
| settlementtype_number | 结算方式 | **不送**（仅 A103-1 分录需要） | — |
|
||||
| taxrateid_number / purorg_number / exratetable_number / planentity 等 | 可选 | **均不送**（planentity 由金蝶按分录自动汇总付款计划） | — |
|
||||
|
||||
### 4.2 明细分录 detailentry
|
||||
|
||||
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| awrp_entry_code【必·候选键】 | 分录标识 | 拆分行=`明细单据号-货物序号-大类-税率`；合计费用项行=`结算单号-费用类型-费用项` | blade_formal_settlement_detail.document_no / blade_formal_settlement_summary_fee.fee_type+fee_item |
|
||||
| material_number【必】 | 物料编码.编码 | 按拆分规则映射（见 0.3） | 配置 `thirdparty.bfi.material.loading / international / domestic.公路运输 / .铁路运输 / .水路运输 / .航空运输`；判定字段 blade_project_apply.business_mode / business_type、blade_formal_settlement_detail.transport_type |
|
||||
| awrp_transport | 运输货物 | 货物名称（合计费用项行不传） | blade_formal_settlement_detail.cargo_name（一车多货取 blade_formal_settlement_detail_fee.cargo_name） |
|
||||
| awrp_lpn | 车号 | 车号（合计费用项行不传） | blade_formal_settlement_detail.vehicle_no |
|
||||
| quantity【必】 | 数量 | 运输量（≤0 兜底 1；装卸/合计行=1） | blade_formal_settlement_detail.transport_quantity（一车多货取 detail_fee.transport_quantity） |
|
||||
| price | 单价 | 金额÷数量反算 | 派生值 |
|
||||
| e_pricetaxtotal【必】 | 应付金额（含税） | 结算金额 | blade_formal_settlement_detail.settlement_amount_tax / blade_formal_settlement_summary_fee.settlement_amount |
|
||||
| e_amount | 金额（不含税） | 不含税结算金额（仅运输类携带；合计行不传） | blade_formal_settlement_detail.settlement_amount_no_tax |
|
||||
| project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
|
||||
| taxrateid_number | 税率.编码 | 不送（税率只作拆行依据） | blade_contract_manage.billing_plan_json |
|
||||
|
||||
---
|
||||
|
||||
## 5. A302-2 财务应收单保存（与应付差异）
|
||||
|
||||
分录与应付**同源同口径**（复用 resolveEntryGroups，分录字段名前缀 e_：e_material_number/e_quantity/e_unitprice/e_recamount(含税)/e_amount(不含税)）。头字段差异：
|
||||
|
||||
| 金蝶入参 | 应收取值 | 来源 |
|
||||
|---|---|---|
|
||||
| awrp_src_type | `TMS财务应收单` | 常量 |
|
||||
| billtype_number | 「服务销售应收」→ `arfin_sersal_BT_S` | 常量映射 |
|
||||
| recorg_number | 收款组织=结算组织 | 同 org_number |
|
||||
| asstact_number | **结算单付款方**（非合同乙方） | blade_formal_settlement.payer_name → blade_customer_archive.customer_code |
|
||||
| paymode | 现销 `CASH` | 常量 |
|
||||
| payproperty_number | `1001`（一般销售） | 常量 |
|
||||
| bizdate | 同步当日 | LocalDate.now() |
|
||||
| settlementtype_number / duedate 等 | 不送（TODO 待金蝶确认） | — |
|
||||
|
||||
---
|
||||
|
||||
## 6. A103-1 付款申请下推
|
||||
|
||||
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| awrp_src_code【必·候选键】 | 来源单据号 | 付款申请单号 | blade_payment_application.payment_no |
|
||||
| awrp_src_sys【必】 | 外部系统 | 配置 | `thirdparty.bfi.srcSys` |
|
||||
| applydate【必】 | 申请日期 | 付款申请页-申请日期（空取当天） | blade_payment_application.apply_date |
|
||||
| entry[].e_paymenttype_number【必】 | 付款类型 | 正式付款 | 常量 `201` |
|
||||
| entry[].e_settlementtype_number | 结算方式 | 付款方式含「汇票」→`012-02`（电子银行承兑汇票），其余→`02`（银行转账） | 字典 `pay_method` + blade_payment_application.payment_method |
|
||||
| entry[].awrp_finapbill_entryid【必】 | 勾稽应付单分录标识 | 主结算单应付单防重键（本地组装） | blade_formal_settlement.formal_settlement_no + blade_formal_settlement_detail.document_no（主结算单=blade_payment_application.settlement_id，空取关联明细首个结算单） |
|
||||
| entry[].awrp_entry_code【必】 | 行 id | 付款申请号-1 | payment_no + "-1" |
|
||||
| entry[].e_assacct【必】 | 往来账户（收款账号） | 收款账号 | blade_payment_application.bank_account |
|
||||
| entry[].e_bebank_number【必】 | 往来银行.编码（联行号） | 收款账户联行号（缺失拦截；兜底按合同乙方客商+收款账号匹配） | blade_customer_receipt_account.cnaps_code（按 blade_payment_application.receipt_account_id 直查） |
|
||||
| entry[].e_applyamount【必】 | 申请金额 | 申请付款金额（2 位 HALF_UP） | blade_payment_application.applied_amount |
|
||||
| entry[].project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
|
||||
| entry[].awrp_src_type【必】 | 外部单据类型 | 配置 | `thirdparty.bfi.payApply.srcType`（默认 `0KzXs`） |
|
||||
| exratetable_number / awrp_textfield1 | 汇率表/付款渠道 | **实际不送**（仅 A103-3 送；配置 exratetable=01 在此接口不生效） | — |
|
||||
|
||||
---
|
||||
|
||||
## 7. A103-3 预付款申请保存
|
||||
|
||||
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| billtype_number【必】 | 单据类型 | 配置 | `thirdparty.bfi.payApply.billtype`（默认 `ap_payapply_oth_BT_S`） |
|
||||
| settleorg/applyorg/payorg_number【必】 | 结算/申请/付款组织.编码 | 合同关联项目业务部门上溯平台公司 | kingdeeOrgNumber → 平台公司 `blade_dept.kingdee_dept_code`（公司级核算组织编码） |
|
||||
| awrp_department_number【必】 | 部门.编码 | 项目业务部门自身 | kingdeeDeptNumber → 业务部门 `blade_dept.kingdee_dept_code`（部门级编码，不上溯平台公司；未维护拦截） |
|
||||
| paycurrency/settlecurrency_number【必】 | 币种 | 合同结算币种（RMB→CNY） | blade_contract_manage.settlement_currency |
|
||||
| applycause | 请款事由 | 按付款类型映射文案：项目垫资→「项目预付款申请」、进度垫资→「进度预付款申请」、结算付款→「结算付款申请」 | blade_payment_application.payment_type |
|
||||
| exratetable_number【必】 | 汇率表 | 配置（**此接口实际送**） | `thirdparty.bfi.payApply.exratetable`（默认 `01`） |
|
||||
| exratedate【必】 | 汇率日期 | 关联结算单维护值，兜底申请日期 | blade_formal_settlement.exchange_rate_date → blade_pre_settlement.exchange_rate_date → blade_payment_application.apply_date |
|
||||
| awrp_textfield1 | 付款渠道 | 付款方式字典标签（**此接口实际送**） | 字典 `pay_method` 翻译 blade_payment_application.payment_method |
|
||||
| entry[].e_paymenttype_number【必】 | 付款类型 | 结算付款→`201`；项目垫资/进度垫资→`202` | 常量 BFI_PAYMENT_TYPE_FORMAL / BFI_PAYMENT_TYPE_PREPAY |
|
||||
| entry[].e_asstacttype / e_asstactnumber【必】 | 往来类型/户 | 固定客户 / 合同乙方→客商编码 | `bd_customer`；blade_contract_manage.party_b → customer_code |
|
||||
| entry[].e_assacct / e_bebank_number【必】 | 账号/联行号 | 同 A103-1 | blade_payment_application.bank_account / blade_customer_receipt_account.cnaps_code |
|
||||
| entry[].e_applyamount【必】 | 申请金额 | 申请付款金额 | blade_payment_application.applied_amount |
|
||||
| entry[].project_number【必】 | 项目.编码 | **实际固定 999**（取项目档案真实编码的逻辑已注释停用） | 常量 `"999"`（备用：blade_project_apply.project_code） |
|
||||
| entry[].e_remark | 备注 | 付款申请备注（空不传） | blade_payment_application.remark |
|
||||
| entry[].awrp_entry_code / awrp_src_type【必】 | 行 id / 单据类型 | payment_no-1 / 配置 | `thirdparty.bfi.payApply.srcType` |
|
||||
|
||||
---
|
||||
|
||||
## 8. A303-1 开票申请单保存（每张发票张次一单）
|
||||
|
||||
### 8.1 主表
|
||||
|
||||
| 金蝶入参 | 含义 | 页面字段 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| billno【必·候选键】 | 单据编号 | 开票申请单号（多张加张次序号） | blade_invoice_application.application_no（多张 + "-" + blade_invoice_application_sheet.sheet_no） |
|
||||
| orgid_number【必】 | 组织.编码 | 申请关联项目业务部门上溯平台公司 | kingdeeOrgNumber → 平台公司金蝶组织编码（绑定税号的核算组织） |
|
||||
| awrp_orgfield_number【必】 | 申请部门.编码 | 申请部门 | blade_invoice_application.dept_id → blade_dept.kingdee_dept_code（部门级业务单元编码） |
|
||||
| billdate【必】 | 单据日期 | 申请日期（空取当天） | blade_invoice_application.application_date |
|
||||
| billproperties / taxationstyle / buyerproperty | 单据性质/征税方式/购方类型 | 固定 | `"1"` / `"0"` / `"0"` |
|
||||
| invoicetype【必】 | 发票种类 | 发票类型：数电专票→`08xdp`，其余→`10xdp` | blade_invoice_application.invoice_type |
|
||||
| buyeremail【必】 | 推送邮箱 | 部门邮箱（空拦截） | blade_invoice_application.department_emails |
|
||||
| buyertaxno / buyername【必】 | 购方税号/名称 | 受票方快照 | blade_invoice_application.taxpayer_no / receiver_name |
|
||||
| buyeraddr / buyerbank | 购方地址电话/开户行账号 | 受票方快照 | blade_invoice_application.registered_address+contact_phone / bank_name+bank_account |
|
||||
| salername【必】 | 销方名称 | 开票单位（空拦截） | blade_invoice_application.issuer_name |
|
||||
| salertaxno【必】 | 销方税号 | 开票单位→客商档案 | blade_customer_archive.unified_credit_code（按 issuer_name 匹配） |
|
||||
| saleraddr / salerbank | 销方地址电话/开户行账号（数电专票强制） | 客商档案（启用开票信息优先） | blade_customer_archive.registered_address+contact_phone；blade_customer_invoice_info.bank_name+bank_account |
|
||||
| totalamount【必】 | 申请价税合计 | 本张开票金额 | blade_invoice_application_sheet.invoice_amount |
|
||||
| hsbz | 是否含税 | 固定不含税 | 常量 `"0"` |
|
||||
| specialtype | 特殊票种 | 本张商品行**全部**为货物运输类→`E04`，否则→`00`（名称/分类含「运费/货物运输」关键字） | 常量 BFI_INVOICE_SPECIAL_TYPE_FREIGHT / NONE + BFI_INVOICE_FREIGHT_KEYWORDS |
|
||||
| freights[] | 货物运输单据体（E04 报送） | 结算明细快照，见 8.2 | blade_invoice_application_detail |
|
||||
| customnameid_number【必】 | 客户.编码 | 受票方客户 | blade_invoice_application.receiver_customer_id → blade_customer_archive.customer_code |
|
||||
| awrp_project_number【必】 | 项目.编码 | 联调临时值 | 常量 `"999"` |
|
||||
| awrp_src_bt | 上游单据类型 | 固定 | `ar_finarbill` |
|
||||
| awrp_src_con_no | 上游单据号 | 首张关联结算单金蝶应收防重键 | blade_formal_settlement.formal_settlement_no + detail.document_no（经 blade_invoice_application_settlement 关联） |
|
||||
| systemsource | 来源系统 | 配置 | `thirdparty.bfi.srcSys` |
|
||||
| showbuyeraddresstel / showbuyerbank | 票面展示开关 | 固定 | `true` |
|
||||
|
||||
### 8.2 freights[]（按「车牌×起运×到达×货物×种类」去重归并，全空行剔除）
|
||||
|
||||
| 入参 | 来源：blade_invoice_application_detail 字段 |
|
||||
|---|---|
|
||||
| transporttype 运输工具种类 | transport_type（字典 `transport_type` 翻译，不在合法枚举兜底「其它运输工具」） |
|
||||
| licenseplate 牌号 | vehicle_no |
|
||||
| transportgoods 货物名称 | cargo_name |
|
||||
| startplace 起运地 | departure_address |
|
||||
| endplace 到达地 | arrival_address |
|
||||
|
||||
### 8.3 sim_original_bill_item[] 分录（blade_invoice_application_line 商品行，line_no 升序）
|
||||
|
||||
| 入参 | 来源：blade_invoice_application_line 字段 |
|
||||
|---|---|
|
||||
| awrp_entry_code【必】 | id（雪花 id） |
|
||||
| rowtype / benchmark【必】 | 常量 `"2"`（商品行）/ `"0"`（数量基准） |
|
||||
| goodsname【必】 | goods_name（货物或服务简称） |
|
||||
| goodssimplename【必】 | goods_category（商品和服务分类） |
|
||||
| taxratecodeid_number / goodscode【必】 | tax_classification_code（税收分类编码，空拦截） |
|
||||
| num / unit | quantity（0 兜底 1）/ unit（空兜底「个」） |
|
||||
| unitprice / amount / tax | unit_price_no_tax / amount_no_tax / tax_amount |
|
||||
| taxrate | tax_rate（百分数÷100 转小数，0 送 "0.00"） |
|
||||
| remark | remark |
|
||||
| awrp_src_type【必】 | 配置 `thirdparty.bfi.invoiceApply.srcType`（默认 `0KzXs`） |
|
||||
|
||||
（specification 规格型号、含税金额等本期不传。）
|
||||
|
||||
---
|
||||
|
||||
## 9. A303-2 收票单保存 + A302-6 指定应付
|
||||
|
||||
### A303-2 收票单批量保存
|
||||
|
||||
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| awrp_src_code【必·候选键】 | 来源单据号 | 收票登记 id（一票一登记） | blade_invoice_receipt.id |
|
||||
| awrp_src_sys / awrp_src_type【必】 | 系统/单据类型 | 配置 / 常量 | `thirdparty.bfi.srcSys`；`TMS收票登记` |
|
||||
| invoiceno | 发票号码 | 收票登记发票号 | blade_invoice_receipt.invoice_no |
|
||||
| receivedate【必】 | 收票日期 | 推送当日 | LocalDate.now() |
|
||||
| issuedate【必】 | 开票日期 | 票池镜像票面 | blade_kingdee_invoice_pool.invoice_date |
|
||||
| biztype【必】 | 业务类型 | 固定采购 | `PUR` |
|
||||
| invoicetypef7_number【必】 | 发票类型.编码 | 票易通原始编码（缺失拦截并按票号回源 A801-1 补填） | blade_kingdee_invoice_pool.invoice_type_code |
|
||||
| paymenttype【必】 | 付款方式 | 固定现购 | `CASH` |
|
||||
| asstacttype【必】 | 往来类型 | 统一固定客户（与应付单/付款申请同口径） | `bd_customer` |
|
||||
| org_number / currency_number【必】 | 组织/币种 | 分摊应付结算单关联合同 → 项目业务部门上溯平台公司 | kingdeeOrgNumber → 平台公司编码 / settlement_currency |
|
||||
| receivablessupp_number【必】 | 往来户.编码 | 合同乙方→客商编码 | blade_contract_manage.party_b → customer_code |
|
||||
| exratetable_number【必】 | 汇率表 | 固定 | `"01"` |
|
||||
| asstactname / buyertin / sellertin【必】 | 销方名称/购销方税号 | 票池镜像票面 | blade_kingdee_invoice_pool.issuer_name / buyer_tax_no / saler_tax_no |
|
||||
| buyername【必】 | 购方名称 | 镜像受票单位 | blade_kingdee_invoice_pool.receiver_name |
|
||||
| sellertel / sellerbank / selleracct | 销方电话/开户行/账号 | 镜像 | blade_kingdee_invoice_pool.phone / bank_name / bank_account |
|
||||
| isincludetax | 含税录入 | 固定 | `true` |
|
||||
| entry[] | 分录 | 与 A102-2 同源同口径（复用 resolveEntryGroups） | 同 4.2 |
|
||||
|
||||
### A302-6 收票指定应付
|
||||
|
||||
| 入参 | 来源 |
|
||||
|---|---|
|
||||
| op | 常量 `"assign"` |
|
||||
| ap_invoice[0].awrp_src_code / awrp_src_sys | blade_invoice_receipt.id / `thirdparty.bfi.srcSys` |
|
||||
| ap_finapbill[0].awrp_src_code / awrp_src_sys | 应付防重键（结算单号_明细单据号）/ 同上 |
|
||||
|
||||
---
|
||||
|
||||
## 10. A301-3 收款认领结果推送
|
||||
|
||||
| 金蝶入参 | 含义 | 来源 | 表.字段 / 配置 / 常量 |
|
||||
|---|---|---|---|
|
||||
| billid【必】 | 认领公告 id | 流水同步落库（缺失拦截「请先同步金蝶收款流水」） | blade_kingdee_receipt_flow.bill_id |
|
||||
| awrp_src_sys【必】 | 来源系统 | 配置 | `thirdparty.bfi.srcSys` |
|
||||
| awrp_src_code【必】 | 来源单据编码 | 该流水全部分摊结算单号去重下划线拼接（推送时生成落库，分摊不变重试复用） | blade_receipt_claim_settlement.formal_settlement_no（status=1，结算单 id 升序）→ 回写 blade_kingdee_receipt_flow.awrp_src_code |
|
||||
| recpaytype_number【必】 | 收款类型 | **常量当前值 `"999"`**（注释「示例 101 待金蝶确认」） | KingdeeBfiConstant.BFI_CLAIM_REC_PAY_TYPE |
|
||||
| paymenttype【必】 | 付款人类型 | 固定 | `bd_customer` |
|
||||
| recviewpayer / recpayer【必】 | 付款人名称/id | 流水付款方 | blade_kingdee_receipt_flow.payer_name / payer_id |
|
||||
| entryentity[0].e_receivableamt【必】 | 应收金额（单条分录） | 全部有效认领分摊金额合计 | SUM(blade_receipt_claim_settlement.allocated_receipt_amount) |
|
||||
| entryentity[0].seq / e_corebillno【必】 | 行序/核心单据编号 | 第一张分摊结算单 id / 其金蝶星瀚内码（缺失拦截「未同步金蝶」） | blade_receipt_claim_settlement.formal_settlement_id / blade_formal_settlement.kingdee_bill_id |
|
||||
| entryentity[0].e_corebilltype | 核心单据类型 | **注释不传** | — |
|
||||
|
||||
---
|
||||
|
||||
## 11. lockBusiData 单据锁定
|
||||
|
||||
| 入参 | 含义 | 来源 |
|
||||
|---|---|---|
|
||||
| lockAction【必】 | 操作 | 常量 `LOCK` |
|
||||
| sourceSystem【必】 | 源系统 | `thirdparty.bfi.srcSys`（默认 WLTMS） |
|
||||
| targetSystem【必】 | 目标系统 | 常量 `XH` |
|
||||
| operationType【必】 | 操作类型 | 常量 `SAVE` |
|
||||
| sourceBillType【必】 | 源单据类型 | 见下表常量 |
|
||||
| sourceBillNo【必】 | 本地单据号 | 见下表 |
|
||||
| targetBillType【必】 | 金蝶单据类型 | 见下表 |
|
||||
| targetBillNo【必】 | 金蝶单号（逐张） | 见下表 |
|
||||
| operator | 操作人 | 当前用户名（定时/补偿兜底 `system`；补偿取 blade_kingdee_bill_lock.lock_operator） |
|
||||
| time | 操作时间 | 当前时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
| sourceBillType | sourceBillNo | targetBillType | targetBillNo |
|
||||
|---|---|---|---|
|
||||
| `SETTLEMENT` | blade_formal_settlement.formal_settlement_no | receivable→`arfin_other_BT_S`；否则 `ApFin_other_BT_S` | 推送返回 billNo（多张逗号拆分逐张锁） |
|
||||
| `PAY_APPLY` | blade_payment_application.payment_no | `ap_payapply_oth_BT_S` | blade_payment_application.kingdee_bill_no |
|
||||
| `INVOICE_APPLY` | blade_invoice_application.application_no | `cdm_paybill_bank_elect_BT_S` | 推送返回 billNo（多张逗号拆分） |
|
||||
| `RECEIVED_INVOICE` | — | `cdm_recbill_bank_BT_S` | 预留，**本期不锁** |
|
||||
|
||||
> 锁记录表 blade_kingdee_bill_lock（lock_status: failed/locked/unlocked，try_count≤5）；开关 `thirdparty.bfi.billLock.enabled`（默认 true）。代码：KingdeeBillLockServiceImpl L331-344、KingdeeLockConstant L24-87。
|
||||
|
||||
---
|
||||
|
||||
## 12. A902 附件上传
|
||||
|
||||
multipart 上传：`file`=文件流，`args`=JSON `{entityNumber, billPkId, controlKey}`。
|
||||
|
||||
| 入参 | 来源 |
|
||||
|---|---|
|
||||
| entityNumber（星止单据类型） | biz_type 映射：`pay_application`→ap_payapply；`formal_settlement_ap`→ap_finapbill；`formal_settlement_ar`→ar_finarbill；`invoice_application`→sim_original_bill；`invoice_receipt`→ap_invoice |
|
||||
| billPkId（星瀚内码） | 推送落库的金蝶内码：blade_payment_application.kingdee_bill_id / blade_invoice_application.kingdee_bill_id / 结算单与收票推送返回内码（为空整单跳过待重推补传） |
|
||||
| controlKey | 常量 `attachmentpanel` |
|
||||
| 文件名 | 业务表 attachments_json 行内 originalName/name/fileName（空兜底 attachment；票池镜像兜底「发票文件」） |
|
||||
| 文件流 | 业务表 attachments_json 的 url 下载；收票票池镜像按 path 经 A801-2 下载 |
|
||||
|
||||
- 附件存储：各业务单据 `attachments_json` 列（非 blade_attachment 表）；同步流水落 `blade_kingdee_attachment_sync`（biz_type/biz_id/attachment_key/kingdee_path/sync_status/fail_reason）。
|
||||
- 单文件软限制 20MB，超限拦截（重推时跳过该件继续其余）。
|
||||
- 调用时机：推送成功事务提交后联带上传，失败不污染主单状态；重推补传。
|
||||
> 代码：KingdeeAttachmentConstant L45-108、KingdeeAttachmentSyncSupport L125-264、BfiServiceImpl L613-638。
|
||||
|
||||
---
|
||||
|
||||
## 13. 查询类接口入参简表
|
||||
|
||||
| 接口 | 关键入参 | 取值来源 / 常量 / 配置 |
|
||||
|---|---|---|
|
||||
| A102-4 应付单查询 | awrp_src_code 多值（50/批）、awrp_src_sys、pageSize 200 | 应付防重键批次；`thirdparty.bfi.srcSys` |
|
||||
| A302-4 应收单查询 | 同上（50/批、200） | 应收防重键批次 |
|
||||
| A103-2 付款申请单查询 | awrp_src_code=paymentNo（50/批）、pageSize 200 | blade_payment_application.payment_no |
|
||||
| A103-4 付款处理查询 | org_number（优先取 A103-2 返回 payorg_number，兜底合同组织）、业务日期今天回溯 1 个月、200/页 | A103-2 返回值 → blade_dept.kingdee_dept_code |
|
||||
| A303-4 开票申请查询 | billno 多值（application_no、-张次序号）、pageSize=max(张数,10) | blade_invoice_application(.sheet) |
|
||||
| A303-5 开票发票查询（openApi） | serialNo=金蝶单号逗号拆分（≤50/批）、sellerTaxpayerId=开票单位税号、请求体 Base64 | blade_invoice_application.kingdee_bill_no；blade_customer_archive.unified_credit_code |
|
||||
| A801-3 收票单查询 | buyername（按镜像受票单位分组）、modifytimeS/E=回看 30 天、200/页；本地按 srcCode=登记 id 匹配 | blade_kingdee_invoice_pool.receiver_name；`thirdparty.bfi.receivedInvoice.queryWindowDays/resultWindowDays`（默认 30）；blade_invoice_receipt.id |
|
||||
| A801-1 票池查询 | invoiceStatus=`0`（正常票）；invoiceType 单值（白名单逐轮）；updateTime 窗口=incrementDays 增量、2.5 万触顶二分；500/页。**expenseStatus 不下推**（可用性本地过滤 amount_use_status=0 且 available_amount>0） | `thirdparty.bfi.invoiceReceipt.invoiceTypes / incrementDays`(30)；本地表 blade_kingdee_invoice_pool |
|
||||
| A801-2 附件下载 | path=文件地址（镜像优先、实时回源兜底；优先级 pdfurl→taxPdfUrl→downloadUrl，fileType=4 判 OFD） | blade_kingdee_invoice_pool.attachments_json |
|
||||
| A301-1 收款单查询 | 业务日期今天回溯 30 天、200/页；勾稽 sourcebillnumber==awrp_src_code | blade_kingdee_receipt_flow.awrp_src_code |
|
||||
| A301-2 认领公告查询 | claimusers=**Nacos 配置值**（登录人入参已废弃）、modifytimeS/E=回溯 months 个月、200/页；billstatus 字段存在但不传 | `thirdParty.bfi.claimAnnounce.claimusers`（必配）、`.months`(6) |
|
||||
|
||||
---
|
||||
|
||||
## 14. 与总纲记载不一致的核对结论（已按代码核实）
|
||||
|
||||
| # | 事项 | 代码事实 |
|
||||
|---|---|---|
|
||||
| 1 | A103-1 的 exratetable_number / awrp_textfield1 | **实际不送**（L1245/L1249 注释）；配置 `payApply.exratetable=01` 只在 A103-3 生效 |
|
||||
| 2 | A103-3 项目编码 | **实际固定 999**，「取项目档案 projectCode 真实编码」逻辑已注释停用（bfiProjectNumber L1508-1513）——总纲 12.2-#2「仅 A103-3 用真实编码」的说法作废，全部链路均为 999 |
|
||||
| 3 | A301-3 recpaytype_number | 常量当前值 **"999"**（非旧文档写的 101；注释「示例 101 待金蝶确认」） |
|
||||
| 4 | A301-2 claimusers | 只读 Nacos 配置，方法入参（当前登录人姓名）已不参与取值；billstatus 字段存在但不传 |
|
||||
| 5 | A801-1 expenseStatus | 同步**不下推**（常量已定义未使用），「在用/已用票随窗口刷新」，可选票过滤在本地 SQL |
|
||||
| 6 | 应付 asstact_number | 取**合同乙方 party_b**（payer_name 仅应收侧使用） |
|
||||
| 7 | 组织编码层级 | 核算/结算/付款/收款/开票**组织类字段已统一改为公司级编码**：`kingdeeOrgNumber`（L976-999）按项目业务部门沿部门树上溯 `is_platform_company=1` 平台公司取其 `kingdee_dept_code`；仅 A303-1 申请部门（awrp_orgfield）保留部门级编码。部门级编码（如工业物流中心 01.02.05.06.01.015）不再直接作为结算/付款组织送出，自动替换为其平台公司编码（如国安运输 01.02.05.06.01）；前置数据要求见《2026-10-16-金蝶组织编码部门数据维护清单》 |
|
||||
|
||||
> 校验提醒：以上配置键的**环境实际值**以 Nacos 为准（本文只列键名与代码默认值）；blade_* 表列名按 Entity 驼峰↔下划线约定标注，个别快照列以建表 SQL 为准。
|
||||
@@ -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 分支 |
|
||||
@@ -0,0 +1,130 @@
|
||||
# 收款流水（认领通知单）多次认领与作废口径梳理
|
||||
|
||||
> 日期：2026-10-16
|
||||
> 范围：`tms-api` blade-transport 收款流水认领、认领记录模块；`tms-erp-web` 认领记录页面
|
||||
|
||||
---
|
||||
|
||||
## 一、结论速览
|
||||
|
||||
| 问题 | 结论 |
|
||||
| --- | --- |
|
||||
| 一个通知单能被多次认领，每次认领生成一条还是多条认领记录？ | **每次认领操作生成一条认领主单**（`blade_receipt_claim`），多次认领即多条主单；每次认领同时按所选拆分生成 N 条结算单分摊明细（`blade_receipt_claim_settlement`） |
|
||||
| 认领记录页面是一条一条显示还是只显示一条？ | **一条认领主单一行，逐条显示**，不按通知单合并；同一通知单认领 3 次就显示 3 行，每行"认领金额"只是该次认领的金额 |
|
||||
| 作废是逐条作废归还金额，还是整个通知单全部作废？ | **逐条作废、按条归还金额**：作废入口在单条认领记录上，回退金额 = 该条认领主单的 `claim_amount`，流水已认领金额只减这一条；其余认领记录不受影响 |
|
||||
|
||||
---
|
||||
|
||||
## 二、数据模型
|
||||
|
||||
```
|
||||
blade_kingdee_receipt_flow（收款流水 / 认领通知单，1）
|
||||
│ receipt_flow_id
|
||||
├─< blade_receipt_claim（认领主单，N） ← 每次认领一条
|
||||
│ claim_amount 本次认领总金额
|
||||
│ claimer_id 认领人（记录页面按本人过滤）
|
||||
│ claim_status claimed / voided
|
||||
│ voided_by / voided_time 作废人 / 作废时间
|
||||
│
|
||||
└─< blade_receipt_claim_settlement（分摊明细，N × M） ← 每次认领按结算单拆行
|
||||
receipt_claim_id 归属哪次认领
|
||||
formal_settlement_id/no 关联应收正式结算单
|
||||
allocated_receipt_amount 本次分摊金额
|
||||
claimed_receipt_amount 认领前该结算单已认领金额
|
||||
status 1 有效 / 0 无效（作废置 0，不物理删除）
|
||||
```
|
||||
|
||||
关键点：**认领主单的粒度是"一次认领操作"**，不是通知单。通知单维度只有累计金额（`claimed_amount`）和状态（`claim_status`：unclaimed / partial / claimed），由每次认领/作废累加回退得出。
|
||||
|
||||
---
|
||||
|
||||
## 三、认领：一次操作生成一条主单 + N 条分摊
|
||||
|
||||
代码：`ReceiptFlowServiceImpl#claim(ReceiptClaimRequest)`
|
||||
|
||||
1. 锁定流水（通知单）与所选结算单。
|
||||
2. 校验两条累计上限：
|
||||
- 每张结算单：已有累计认领 + 本次分摊 ≤ 结算总应收含税金额；
|
||||
- 流水：已有累计认领（`flowClaimedAmount`，只算未作废记录）+ 本次总额 ≤ 公告未认领金额（`unclaimed_amount`，A301-2 口径）。
|
||||
3. **插入一条** `ReceiptClaim` 主单：`claim_amount` = 本次分摊总额，`claim_status = claimed`。
|
||||
4. 按所选结算单逐张**插入 N 条** `ReceiptClaimSettlement` 分摊明细。
|
||||
5. 累加流水 `claimed_amount`，按累计值重算流水状态（< 未认领金额 → partial，= → claimed）。
|
||||
6. 只登记本地，不推送金蝶；推送由定时任务/手动按钮触发。
|
||||
|
||||
所以：**同一通知单第二次认领是再插一条新主单**，不存在"找已有主单合并金额"的逻辑；校验全部按"未作废记录累计"实时计算，天然支持多次认领。
|
||||
|
||||
### 认领按钮的显示条件（为什么有些行没有"认领"）
|
||||
|
||||
收款流水列表操作列（`receipt-flow.vue` → `canClaim(row)`）：
|
||||
|
||||
```js
|
||||
canClaim(row) {
|
||||
return this.hasPermission('receipt_flow_claim') && Number(row.remainingAmount || 0) > 0;
|
||||
}
|
||||
```
|
||||
|
||||
两个条件同时满足才显示"认领"按钮：
|
||||
|
||||
1. **按钮权限**：当前用户拥有 `receipt_flow_claim` 按钮权限（admin 直接放行，普通用户取决于菜单按钮配置）；
|
||||
2. **剩余可认领金额 > 0**：`remainingAmount` 由后端 `ReceiptFlowWrapper` 统一计算：
|
||||
|
||||
```
|
||||
remainingAmount = max(公告未认领金额 unclaimed_amount − 累计认领金额 claimed_amount, 0)
|
||||
```
|
||||
|
||||
按认领状态换算：
|
||||
|
||||
| 流水认领状态 | remainingAmount | 认领按钮 |
|
||||
| --- | --- | --- |
|
||||
| unclaimed 未认领（公告金额 > 0） | = 公告未认领金额 > 0 | 显示 |
|
||||
| partial 部分认领 | > 0 | 显示 |
|
||||
| claimed 认领完成 | = 0（累计 ≥ 公告金额） | **不显示** |
|
||||
| 公告未认领金额为 0 的流水 | = 0 | **不显示** |
|
||||
| 无 `receipt_flow_claim` 权限 | — | **不显示** |
|
||||
|
||||
即：**按钮显隐只看金额余额与权限，不看认领状态字段本身**；`claimed` 状态的行因为剩余额度为 0 自然不显示按钮。按钮不显示且不满足"推送金蝶"条件时，操作列显示"-"。
|
||||
|
||||
注意：顶部"批量认领"按钮只判断权限与是否勾选行（`receipt_flow_claim` + `selectedRows.length`），**不按行剩余金额过滤**；对无剩余额度的流水发起批量认领时，进入批量页面后由提交校验/后端 `claim()` 兜底拦截。
|
||||
|
||||
---
|
||||
|
||||
## 四、认领记录页面：逐条显示
|
||||
|
||||
后端：`ReceiptClaimMapper.xml#selectClaimRecordPage` → `FROM blade_receipt_claim c JOIN blade_kingdee_receipt_flow f`，固定条件 `c.claimer_id = 当前用户`。
|
||||
|
||||
- **列表一行 = 一条认领主单**，无按流水/通知单的 GROUP BY 合并；
|
||||
- 同一通知单多次认领 → 多行，各行的认领金额、认领日期、金蝶单号都是当次认领自己的；
|
||||
- 关联结算单列用 `GROUP_CONCAT(分摊明细.结算单号)` 拼成一串展示（只展示，不参与合并）；
|
||||
- 详情页（`selectClaimRecordDetail` + 分摊明细列表）展示的也是**该次认领**的分摊明细，明细里的"认领前已认领金额"记录的是认领那一刻结算单的累计值，可还原多次认领的先后关系；
|
||||
- 前端 `receipt-claim-record.vue` 列表 + 行级"作废"按钮（`api.voidClaim(row.id)`），确认文案为"作废后将回退本次认领金额"——与逐条口径一致。
|
||||
|
||||
另：收款流水列表的详情弹窗里有一个"认领记录"区块，展示的是该流水的**操作日志**（`blade_receipt_flow_record`，action_type = claim/push），按时间线展示每次认领/推送动作，同样不是合并视图。
|
||||
|
||||
---
|
||||
|
||||
## 五、作废：逐条作废、按条归还金额
|
||||
|
||||
代码：`ReceiptClaimRecordServiceImpl#voidClaim(Long id)`，入参就是**单条认领主单 id**。
|
||||
|
||||
流程（单事务）：
|
||||
|
||||
1. 锁定该条认领主单，校验：本人记录、`claim_status = claimed`（已作废不可再作废）。
|
||||
2. 锁定关联流水，校验：**未推送金蝶**——已推送的不允许作废，提示"请在金蝶侧人工处置"。
|
||||
3. 取该主单名下有效分摊明细（status=1），全部置 `status = 0`（保留审计，不删行）。
|
||||
4. 批量刷新相关结算单收款汇总（`refreshPaymentSummaries`）。
|
||||
5. **流水 `claimed_amount` 只减去本条主单的 `claim_amount`**（下限 0），并按减后累计重算流水认领状态（0 → unclaimed，< 未认领金额 → partial，≥ → claimed）。
|
||||
6. 主单置 `voided`，记录作废人、作废时间；写 `void_claim` 操作日志（金额 = 本次回退金额）。
|
||||
7. **不生成金蝶认领冲单**：金蝶单号/状态保留原值，金蝶侧冲销/红红由人工处置；冲单逻辑代码已注释保留（`buildKingdeeBillNo`），后续迭代可放开。
|
||||
|
||||
边界与影响：
|
||||
|
||||
- 作废某一条，只归还这一条的金额，**同一通知单的其他认领记录不受影响**，仍正常显示、仍可单独作废；
|
||||
- 作废后该条记录仍在列表中（状态"已作废"），不允许再改附件、不可重复作废；
|
||||
- 归还后的金额空间立即可被再次认领（认领校验按未作废累计实时计算）；
|
||||
- 附件/操作日志/分摊明细均保留，金额回退可追溯。
|
||||
|
||||
---
|
||||
|
||||
## 六、一句话总结
|
||||
|
||||
通知单（收款流水）是"累计额度"维度，认领记录是"每次操作"维度：**认领一次记一条、页面逐条展示、作废按条回退金额**；整单性质的只有流水上的累计已认领金额与认领状态，由各条记录的认领/作废实时推导，没有任何"按通知单整体作废"的入口。
|
||||
@@ -0,0 +1,290 @@
|
||||
# 结算调整单接入金蝶设计（未推送自动推 · 已推送手工冲销后重推新单）
|
||||
|
||||
> 整理日期：2026-10-16
|
||||
> 目标：把「结算调整单」正式接入金蝶链路。核心约束——**原正式结算单一旦推送过金蝶，其本地数据一律冻结不动**；调整后的数据落在重推时新建的一张正式结算单上，用它向金蝶生成**全新**的财务应付/应收单。
|
||||
> 依据：`2026-09-20-应付单与付款申请同步金蝶全链路业务流程（A102-2保存-A102-4查询-A103-1下推-A103-2回写）.md`、`2026-09-21-应收结算与开票申请同步金蝶全链路业务流程（A302-2保存-A302-4勾稽-A303-1新增-A303-4预检-A303-5回写）.md`、`2026-10-05-审批通过自动同步金蝶设计（事件触发+定时重推+手动兜底）.md`、`2026-10-09-金蝶单据锁定与解锁业务流程（...）.md`、当前代码（探索核实）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
结算调整单（`blade_settlement_adjustment`）用于在正式结算单审批通过后调整其费用项目与金额。目前它只有本地审批与一个假的 `repush`（拼 `K3AP+时间戳`），并未真正接入金蝶。
|
||||
|
||||
需要落地的三段操作：
|
||||
|
||||
| 操作 | 内容 |
|
||||
|---|---|
|
||||
| 操作 1 新增调整单 | 只允许选**审核通过**且**未下推付款申请**的正式结算单；自动回带客商、调整类型、合同等 |
|
||||
| 操作 2 审批通过 | 回写/记录调整 → 按原结算单金蝶状态分流（未推送→推原单；已推送→不动金蝶，提示财务手工冲销） |
|
||||
| 操作 3 重新推送（高危） | 旧应付/应收单已在金蝶冲销后，把**调整后的数据**以**全新来源单据号**推成一张新的财务应付/应收单 |
|
||||
|
||||
> 全程交互使用中文。
|
||||
|
||||
## 2. 名词与接口速查
|
||||
|
||||
| 代号 | 含义 |
|
||||
|---|---|
|
||||
| A102-2 | 财务应付单**保存**（推送） |
|
||||
| A102-4 | 财务应付单**查询**（幂等预检；返回 `BfiApBillVO`，含 `iswrittenoff` / `hadwrittenoff`） |
|
||||
| A302-2 | 财务应收单**保存**（推送） |
|
||||
| A302-4 | 财务应收单**查询**（幂等预检，同上） |
|
||||
| 防重键 | 金蝶来源单据号 `awrp_src_code`，由 `ExternalSrcCodeSupport.buildSrcCode(mainCode, partCodes)` 下划线拼接，规则 `结算单号_明细单据号` |
|
||||
| 正式结算单 | `blade_formal_settlement`，单号 `FJS`(应付)/`SJS`(应收) + `yyyyMMdd` + 4 位流水（`nextNo`） |
|
||||
| 结算调整单 | `blade_settlement_adjustment` |
|
||||
|
||||
## 3. 现状与差距（代码核实）
|
||||
|
||||
| # | 位置 | 现状 | 差距 |
|
||||
|---|---|---|---|
|
||||
| 1 | `SettlementAdjustmentServiceImpl.approve()`（约 221-261） | 仅改本地：回写原结算单费用、写变更记录、置 `approved`；`setKingdeeSyncStatus(formal.getKingdeeSyncStatus())`（推送前快照） | 未触发金蝶推送；未回填推送后的真实状态，导致前端「重新推送」按钮（条件 `approved && kingdeeSyncStatus='synced'`）不出现 |
|
||||
| 2 | `SettlementAdjustmentServiceImpl.repush()`（约 207-217） | 假实现：拼 `K3AP+时间戳` 直接置 synced | 未校验冲销、未生成新单、未真正推送 |
|
||||
| 3 | `FormalSettlementServiceImpl.syncKingdee/doSyncKingdee`（640/805） | 真实推送 + 落锁 + 失败重推链路；`doSyncKingdee` 在 `synced` 时**幂等早退** | 重推前须重置状态，否则被早退 |
|
||||
| 4 | `KingdeeApBillSyncSupport.pushApBill`（220）/`queryApBillExistNos`（157） | A102-4 预检**不区分是否已冲销** | 冲销后同键重推会被预检判为"已存在"而跳过 |
|
||||
| 5 | `BfiApBillVO` | 已含 `iswrittenoff`（154）/`hadwrittenoff`（158） | 尚未用于冲销判定 |
|
||||
| 6 | `SettlementAdjustment` 实体 / `SettlementAdjustmentVO` | 实体无 `kingdeeBillNo`；VO 有（20） | 金蝶单号无处落库 |
|
||||
| 7 | `IKingdeeBillLockService` | `lockAfterPush` / `checkEditable`；**冲销不触发解锁回调** | 原单锁记录会一直停在 `locked` |
|
||||
| 8 | `IKingdeeBillLockService.checkEditable` | 仅开票申请、付款申请调用；**正式结算单未调用** | 正式结算单的编辑保护主要在前端 + `voidBill` 的 `synced` 拦截 |
|
||||
|
||||
## 4. 关键决策（已确认）
|
||||
|
||||
| 决策 | 结论 |
|
||||
|---|---|
|
||||
| **A 原单去向** | 已推送场景下**原单业务数据零改动**（费用/金额/状态全不动），只加 1 条变更记录 + 标记 + 解锁；新单是**全新独立单**，原单的下游关联（开票申请/收款认领/对账）**不迁移**，留在原单 |
|
||||
| **B 展示标记** | 原单标「已调整」；新单标「调整后单」并显示原单号 |
|
||||
| **B1 建单时机** | 「重新推送」时新建，审批阶段不动 |
|
||||
| **B2 新单编号** | 走 `nextNo` 正式流水（`FJS`/`SJS` + 日期 + 4 位），**不**加后缀 |
|
||||
| **B3 原单处理** | 保持原状，不做作废/删除 |
|
||||
| **B4 调整单挂载** | 重推后调整单**改挂新单** |
|
||||
| **B5 来源预结算** | 新单**重建** `FormalSettlementSource` 行（接续原单来源） |
|
||||
| **B6 范围** | 应付、**应收都要做**（应付 A102-2/A102-4，应收 A302-2/A302-4） |
|
||||
| **B7 列表** | 新旧两张单并存，带标识展示 |
|
||||
| **C 冲销判定** | 只认 `hadwrittenoff=true`；部分冲销也放行 |
|
||||
| **D 原单旧锁** | 重推时把原单旧锁标记为 `unlocked`，不改其它 |
|
||||
| **E 未推送场景** | 审批通过后**自动推**（复用既有 `KingdeeBillApprovedEvent` 机制） |
|
||||
| 新单状态 | 克隆后直接置 `approvalStatus=approved`，不再走审批 |
|
||||
| 原单变更记录/unlock 时机 | 变更记录审批时写；`unlock` + `已调整`标记在**重推时**执行（审批时财务可能还没冲销） |
|
||||
| **选单预检** | 操作 1 选定结算单后**预检**其金蝶冲销状态（软提示，不硬拦截）；金蝶不可用时降级放行 |
|
||||
| **重推冲销闸门** | 真正的**硬拦截**保留在操作 3 重推；预检不替代闸门 |
|
||||
|
||||
## 5. 总体方案
|
||||
|
||||
### 5.1 流程图
|
||||
|
||||
> 操作 1 选单后会先做一次金蝶冲销**预检（软提示，不阻断）**，见第 6.2 节。
|
||||
|
||||
```
|
||||
┌── 原结算单 kingdeeSyncStatus ──┐
|
||||
操作2 调整单审批通过 ──────────┤ │
|
||||
▼ ▼
|
||||
未推送(unsynced) 已推送(synced)
|
||||
│ │
|
||||
① 回写原单费用/金额 ① 原单业务数据【零改动】
|
||||
② 原单写变更记录 ② 原单仅写 1 条变更记录
|
||||
③ 发布 KingdeeBillApprovedEvent ③ 调整单置 approved
|
||||
(formal-settlement, 原单id) ④ toast：原结算单已推送金蝶，
|
||||
④ AFTER_COMMIT → syncKingdee(原单) 请财务在金蝶手工完成旧应付单冲销处理
|
||||
⑤ 回填调整单 synced + kingdee_bill_no
|
||||
│ │
|
||||
│ 【财务在金蝶手工冲销旧应付/应收单】
|
||||
│ │
|
||||
│ 操作3 重新推送（高危）
|
||||
│ │
|
||||
│ ① 校验调整单 approved
|
||||
│ ② 旧键查 A102-4/A302-4 → 要求 hadwrittenoff=true
|
||||
│ ③ 克隆原单 → 新正式结算单（+应用调整明细、重建 source）
|
||||
│ ④ 新单号组新键推 A102-2/A302-2
|
||||
│ ⑤ 新单落锁 + 附件
|
||||
│ ⑥ 调整单改挂新单 + 回填 kingdee_bill_no/synced
|
||||
│ ⑦ 原单：标记「已调整」+ 旧锁 unlocked
|
||||
│ ⑧ 写变更记录；失败置 failed 可重试
|
||||
▼ ▼
|
||||
金蝶应付/应收单 金蝶【全新】应付/应收单
|
||||
（同原单号来源） （新单号来源，旧单已冲销）
|
||||
```
|
||||
|
||||
### 5.2 三条不变式
|
||||
|
||||
1. **原单一经推送金蝶即冻结**：已推送场景下原单除「变更记录 / 标记 / 解锁」外，任何业务字段与状态均不改。
|
||||
2. **调整后的金额只体现在新单**：未推送场景作用于原单；已推送场景作用于重推时克隆出的新单。两者共用同一段「应用调整到结算单」的逻辑。
|
||||
3. **重推必须锚定金蝶侧已冲销**：以 A102-4/A302-4 的 `hadwrittenoff=true` 为唯一放行条件，避免重复生成应付/应收单。
|
||||
|
||||
## 6. 操作 1｜新增调整单
|
||||
|
||||
### 6.1 选单来源（保持现状）
|
||||
|
||||
选单来源 `candidateFormalSettlements`（`SettlementAdjustmentServiceImpl` 约 98）已符合要求，不改：
|
||||
|
||||
- 仅 `approvalStatus = approved` 的正式结算单；
|
||||
- 排除已下推付款申请的单（`tailPaymentSettlementIds`，约 324）；
|
||||
- 排除收付完成/尾款等不可调整（`adjustableFormalSettlement`，约 295）；
|
||||
- 保存时自动回带客商、调整类型、合同、原结算金额等。
|
||||
|
||||
### 6.2 选单后金蝶冲销预检（新增，软提示）
|
||||
|
||||
选定关联结算单号、回带信息后，前端调后端**预检接口**：
|
||||
|
||||
1. 若结算单**未推送金蝶**（`kingdeeSyncStatus != synced`）→ 返回"未推送"，正常继续，后续按设计文档走审批自动推分支；
|
||||
2. 若**已推送**→ 按防重键（`正式结算单号_结算明细单据号`）批量调 A102-4（应付）/ A302-4（应收），读 `hadwrittenoff`：
|
||||
- `hadwrittenoff = true` → 返回"已推送·旧单已冲销"，提示"旧应付/应收单已冲销，审批后可重新推送新单"；
|
||||
- `hadwrittenoff != true`（含查询不到）→ 返回"已推送·旧单未冲销"，给出**醒目提示**："该结算单已推送金蝶且旧单尚未冲销，审批通过后需先由财务在金蝶完成冲销，才能重新推送"。
|
||||
|
||||
**口径**：
|
||||
|
||||
- 预检为**软提示**，不阻断建单（默认建议）；是否升级为硬拦截由业务另行确认。
|
||||
- **降级**：金蝶查询超时/不可用/接口异常时，预检返回"未校验"，**不阻断**建单与回带，由后续审批分流与重推闸门兜底。
|
||||
- 预检结果**只用于提示**，不作为后续环节的结论缓存：审批（操作 2）、重推（操作 3）各自按**当下**状态重新判定。
|
||||
|
||||
> 为什么不把硬拦截放在选单：冲销是金蝶侧**不可逆/需人工撤销**的对外操作，而审批只是 TMS 内部决策。若选单即要求已冲销，会出现"旧单已冲销、调整单却被驳回/删除"的**应付单空档**（详见第 13 节）。
|
||||
|
||||
## 7. 操作 2｜审批通过
|
||||
|
||||
### 7.1 未推送场景（原单 `kingdeeSyncStatus != synced`）
|
||||
|
||||
沿用现有 `approve()` 逻辑并补推送：
|
||||
|
||||
1. `applyAdjustmentToSettlement(原单, 调整单)`：回写费用项目、明细、合计、重算结算金额（**抽成公共方法**）；
|
||||
2. 原单追加变更记录、挂载调整单；
|
||||
3. 调整单置 `approved`；
|
||||
4. 事务提交后发布 `KingdeeBillApprovedEvent("formal-settlement", 原单id)`，由既有 `KingdeeApprovalSyncListener`（AFTER_COMMIT + 域开关 + 全量 try/catch）调 `formalSettlementService.syncKingdee(原单id)` 完成 A102-2/A302-2 推送 + 落锁；
|
||||
5. 推送成功回填调整单 `kingdeeSyncStatus=synced` + `kingdeeBillNo`；失败置 `failed`（不改「已审批」结果，进入重推循环）。
|
||||
|
||||
> 复用 `2026-10-05-审批通过自动同步金蝶设计` 的事件机制，不另写推送路径；自动推送失败不影响审批结果。
|
||||
|
||||
### 7.2 已推送场景（原单 `kingdeeSyncStatus = synced`）★ 关键约束
|
||||
|
||||
**原单业务数据一律不动**，只做：
|
||||
|
||||
1. 原单追加 1 条变更记录：`结算调整单XX审批通过，调整金额XX，待重推金蝶`；
|
||||
2. 调整单置 `approved`（`kingdeeSyncStatus` 保持 `synced` 快照，前端据状态显示「重新推送」入口）；
|
||||
3. 返回前端 toast 提示：**「原结算单已推送金蝶，请财务人员在金蝶手工完成旧应付单冲销处理」**。
|
||||
|
||||
> 不做：不回写原单费用/金额、不修改旧应付、不自动推送新单、不作废原单。
|
||||
|
||||
## 8. 操作 3｜重新推送（高危）
|
||||
|
||||
`repush(调整单id)` 重写为：
|
||||
|
||||
1. **前置校验**：调整单 `approvalStatus = approved`；原单存在。
|
||||
2. **冲销校验（硬闸门）**：取调整单号 + 原单号，按旧键（`原结算单号_明细单据号`）查 A102-4（应付）/ A302-4（应收）；要求存在且 `hadwrittenoff = true`，否则抛出「原应付/应收单尚未在金蝶冲销，禁止重推」。
|
||||
3. **克隆新正式结算单**：`cloneFormalSettlement(原单, 调整单)`
|
||||
- 新号由 `nextNo` 取正式流水（`FJS`/`SJS`+日期+4 位）；
|
||||
- 克隆明细、明细费项、汇总费项、发票、汇率等；
|
||||
- 调 `applyAdjustmentToSettlement(新单, 调整单)` 应用调整（金额 = 原单 + 调整）；
|
||||
- **重建** `FormalSettlementSource`（接续原单来源预结算）；
|
||||
- `approvalStatus = approved`、`kingdeeSyncStatus = unsynced`、`originFormalSettlementNo = 原单号`；
|
||||
- 附件复制/挂载。
|
||||
4. **推送新单**：新单号天然组成新防重键（`新结算单号_明细单据号`），调 `syncKingdee(新单id)`（内部 A102-2/A302-2），**推前把新单状态置 `unsynced`** 以免被 `doSyncKingdee` 的 `synced` 早退。
|
||||
5. **落锁**：新单 `lockAfterPush`（`TARGET_AP_BILL`/`TARGET_AR_BILL`）+ 附件上传。
|
||||
6. **改挂 + 回填**：调整单 `formalSettlementId/No` 改指新单，回填 `kingdeeBillNo` + `kingdeeSyncStatus=synced`。
|
||||
7. **原单收尾**：标记 `adjustStatus='已调整'` + 旧锁记录置 `unlocked`；追加重推变更记录。业务字段不动。
|
||||
8. **失败处理**：新单 `kingdeeSyncStatus=failed` + 失败原因，支持复用 `retryKingdeeFailed` 重试（重试即从第 4 步继续，克隆已存在则跳过，注意幂等）。
|
||||
|
||||
## 9. 关键机制
|
||||
|
||||
### 9.1 防重键与新单号
|
||||
|
||||
- 金蝶 `awrp_src_code = 结算单号_明细单据号`。因为重推**新建了真实结算单记录**（新 `FJS/SJS` 号），新键天然与原键不同，**无需再额外拼调整单号**——早期「拼调整单号改防重键」的方案已被「新建结算单」覆盖。
|
||||
- 旧键（原结算单号）用于查冲销；新键（新结算单号）用于生成全新应付/应收单。
|
||||
|
||||
### 9.2 冲销判定
|
||||
|
||||
- 只认 `hadwrittenoff = true`（`BfiApBillVO` 158 / `BfiArBillVO` 138）。部分冲销同样放行。
|
||||
- `iswrittenoff` 不单独作为放行依据。落地前需用 Apifox 实测 A102-4/A302-4 确实回传 `hadwrittenoff`。
|
||||
- **两处判定，用途不同**：操作 1 选单预检 = 软提示（第 6.2 节）；操作 3 重推 = **硬闸门**（第 8 节）。预检不替代闸门——冲销在金蝶可被撤销，且建单到重推期间状态可能变化。
|
||||
|
||||
### 9.3 克隆新正式结算单
|
||||
|
||||
- 复用现有「保存/组装」逻辑而非另写：明细、费项、汇总、来源、附件、汇率、收付款单位等按原单快照复制。
|
||||
- 新单不再走审批流（直接 `approved`），因此不写审批变更记录以外的流程痕迹；是否补一条「由调整单XX生成」变更记录可选。
|
||||
|
||||
### 9.4 金蝶锁
|
||||
|
||||
- 新单推送成功 → `lockAfterPush` 落锁，状态与既有一致。
|
||||
- 原单旧锁：重推时置 `unlocked`（决策 D）。因正式结算单未调用 `checkEditable`，解锁主要影响前端标签，不构成后端编辑漏洞。
|
||||
|
||||
### 9.5 失败与重试
|
||||
|
||||
- 复用 `markKingdeeSyncFailed` / `retryKingdeeFailed` 模式：失败落 `failed` + 原因，可被定时重推任务扫描。
|
||||
- 克隆步骤需幂等：以 `originFormalSettlementNo + 调整单` 作为唯一判断，避免重试时重复建单。
|
||||
|
||||
### 9.6 展示标记
|
||||
|
||||
| 对象 | 标记 | 来源 |
|
||||
|---|---|---|
|
||||
| 新正式结算单 | 「调整后单」（并显示原单号） | `origin_formal_settlement_no` 非空 |
|
||||
| 原正式结算单 | 「已调整」 | `adjust_status = 'adjusted'` |
|
||||
| 结算调整单 | 金蝶状态 / 金蝶单据号 | `kingdee_sync_status` / `kingdee_bill_no` |
|
||||
|
||||
## 10. 数据模型改动（DDL）
|
||||
|
||||
新增脚本 `doc/sql/transport/blade_settlement_adjustment_kingdee_20261016.sql`（多数据库脚本同步，排序规则 `utf8mb4_general_ci`）：
|
||||
|
||||
```sql
|
||||
-- 结算调整单：落金蝶单据号
|
||||
ALTER TABLE blade_settlement_adjustment ADD COLUMN kingdee_bill_no VARCHAR(64) NULL COMMENT '金蝶单据号';
|
||||
|
||||
-- 正式结算单：来源原单号（新单） + 调整标记（原单）
|
||||
ALTER TABLE blade_formal_settlement ADD COLUMN origin_formal_settlement_no VARCHAR(64) NULL COMMENT '来源原正式结算单号（结算调整重推生成）';
|
||||
ALTER TABLE blade_formal_settlement ADD COLUMN adjust_status VARCHAR(32) NULL COMMENT '调整状态：adjusted=已被结算调整';
|
||||
```
|
||||
|
||||
推送金蝶与重新推送合并为**单一按钮**（按金蝶状态分流），复用既有「重新推送」菜单，无需新增菜单 SQL。
|
||||
|
||||
## 11. 改动清单（文件级）
|
||||
|
||||
| # | 文件 | 改动 |
|
||||
|---|---|---|
|
||||
| 1 | `blade_service_api/.../pojo/entity/SettlementAdjustment.java` | 加 `kingdeeBillNo` |
|
||||
| 2 | `blade_service_api/.../pojo/entity/FormalSettlement.java` | 加 `originFormalSettlementNo`、`adjustStatus` |
|
||||
| 3 | `blade_service_api/.../pojo/vo/SettlementAdjustmentVO.java`、`FormalSettlementVO.java` | 补展示字段/翻译 |
|
||||
| 4 | `SettlementAdjustmentServiceImpl.approve()` | 未推送→发 `KingdeeBillApprovedEvent` + 回填；已推送→仅变更记录 |
|
||||
| 5 | `SettlementAdjustmentServiceImpl.repush()` | 重写：冲销校验 → 克隆新单 → 推 → 落锁 → 改挂 → 回填 → 原单标记/解锁 → 失败置 failed |
|
||||
| 6 | `SettlementAdjustmentServiceImpl` | 抽公共方法 `applyAdjustmentToSettlement(结算单, 调整单)` |
|
||||
| 7 | `FormalSettlementServiceImpl`（或新 support） | 新增 `cloneFormalSettlement(...)`（含重建 `FormalSettlementSource`） |
|
||||
| 8 | `FormalSettlementServiceImpl` / `KingdeeApBillSyncSupport` | 冲销查询（A102-4/A302-4 读 `hadwrittenoff`）封装 |
|
||||
| 9 | `FormalSettlementWrapper` / 列表 Mapper | 回填 `adjustStatus` / `originFormalSettlementNo` |
|
||||
| 10 | 前端 `settlement-adjustment.vue`、`settlementAdjustment.js` | 金蝶状态/单号列、「推送金蝶 / 重新推送」合并按钮（未同步→推原单；已同步→冲销后重推新单，重推前冲销预检）；选单后调预检接口并展示软提示 |
|
||||
| 11 | 前端 `formal-settlement.vue` / `formal-settlement-table-panel.vue` / 详情 | 「调整后单 / 已调整」标识、查看弹窗补重推入口 |
|
||||
| 12 | `doc/sql/...` | DDL + 菜单 SQL |
|
||||
| 13 | `SettlementAdjustmentServiceImpl` + `SettlementAdjustmentController` | 新增选单预检接口（返回 未推送 / 已推送已冲销 / 已推送未冲销；金蝶异常降级返回未校验） |
|
||||
|
||||
## 12. 边界场景推演
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 调整单未审批就重推 | 前置校验拒绝（要求 approved） |
|
||||
| 旧应付单未冲销 | A102-4 返回 `hadwrittenoff=false`/不存在 → 拒绝，提示先冲销 |
|
||||
| 部分冲销 | `hadwrittenoff=true` → 放行 |
|
||||
| 旧应付单被删除（非冲销） | 查询不到 → 拒绝（不满足 `hadwrittenoff=true`） |
|
||||
| 已推送场景审批后财务未冲销 | 重推被拦；原单与新单均未产生重复应付单 |
|
||||
| 重推推送失败 | 新单置 `failed` + 原因；原单已标「已调整」+ 解锁；重试从推送步骤续上 |
|
||||
| 重推成功但落库前崩溃 | 重试时幂等判断：已存在同一来源新单则跳过克隆，仅补推/补回填 |
|
||||
| 应收结算单（A302-2/A302-4） | 走同一套逻辑，应收侧下游关联不迁移（决策 A） |
|
||||
| 原单锁残留 | 重推时统一置 `unlocked` |
|
||||
| 未推送场景自动推失败 | 审批仍成功；调整单 `failed`，走重推循环 |
|
||||
| 选单时结算单已推送且旧单未冲销 | 预检返回"未冲销"并**软提示**（不阻断建单）；审批后需先冲销再重推 |
|
||||
| 选单时金蝶超时/不可用 | 预检**降级为"未校验"**，不阻断建单；由审批分流与重推闸门判定 |
|
||||
| 建单时未推送、审批时已被推送到金蝶 | 审批按**当下**状态走"已推送"分支：不自动推、提示财务冲销；预检结论不沿用 |
|
||||
| 选单时已冲销、重推前被金蝶撤销冲销 | 重推硬闸门重新查询 `hadwrittenoff` → 拦截，提示先冲销 |
|
||||
|
||||
## 13. 风险与待验证
|
||||
|
||||
1. **A102-4/A302-4 的 `hadwrittenoff` 实际回传**：必须先用 Apifox 实测，否则整套冲销判定可能推翻。
|
||||
2. **克隆新单**：`FormalSettlementSource` 重建会牵动预结算占用（`PreSettlement.formalSettlementNo`），是最易产生脏数据的一步，需单独小步验证。
|
||||
3. **原单下游关联不迁移**（开票申请/收款认领/对账）：新单为全新独立单，应收场景下新单将显示「未开票/未收款」，属已确认口径，但需业务知悉。
|
||||
4. **重推幂等**：克隆需以来源唯一键保证不重复建单，验证重试与并发（同一调整单重复点击）。
|
||||
5. **正式结算单无 `checkEditable`**：解锁不构成后端漏洞，但需确认前端在 `approved` 下仍不暴露编辑入口，避免原单被改。
|
||||
6. **冲销前置到选单的风险（故不做硬拦截）**：冲销是金蝶侧不可逆/需人工撤销的对外操作，审批是 TMS 内部决策。若选单即硬拦截（要求已冲销），会出现"旧单已冲销、调整单却被驳回/删除"的**应付单空档**，需人工在金蝶恢复冲销。故预检仅作软提示，硬闸门留在重推。
|
||||
7. **预检接口不可成为单点**：金蝶不可用时必须降级放行，否则远程依赖会阻断调整单的建单与回带。
|
||||
|
||||
---
|
||||
|
||||
## 14. 落地实现备注（2026-10-16）
|
||||
|
||||
1. **未推送场景回填**：推送成功/失败分别由 `FormalSettlementServiceImpl.doSyncKingdee` / `markKingdeeSyncFailed` 按 `formal_settlement_id + approval_status=approved` 回填调整单 `kingdee_sync_status`（synced/failed）与 `kingdee_bill_no`，复用 §7.1 的事件自动推送链路，未新增推送路径。
|
||||
2. **重推为「非事务编排 + 段内事务」**：`repush` 依次执行 —— 冲销硬闸门（旧键查 A102-4/A302-4，`hadwrittenoff=true`）→ 自代理事务 `cloneAndApplyForRepush`（克隆新单 + 应用调整，原子）→ `syncKingdee(新单)` 推送 → 成功后调整单改挂新单 + 原单标记「已调整」+ 旧锁解锁。推送失败**不回滚已克隆新单**，重试按 `origin_formal_settlement_no = 调整单当前关联单号` 幂等复用，从推送步骤续上（§8.8、§9.5）。
|
||||
3. **改挂时机**：调整单改挂新单在**推送成功之后**，故成功后再点重推会被冲销闸门拦截（无副作用）；如需彻底隐藏，前端按「关联单是否克隆单」判断。
|
||||
4. **新单不克隆发票**：遵循决策 A「下游关联不迁移」，新单 `invoiceStatus=unreceived`、`paymentStatus=unpaid`，`invoiceAmount/paidAmount/appliedPaymentAmount` 归零，发票不复制。
|
||||
5. **按钮与菜单**：「推送金蝶」与「重新推送」合并为**单一入口**（按金蝶状态分流：未同步/失败→推原结算单；已同步→冲销后重推新单），统一复用既有菜单 `settlement_adjustment_repush`，不新增菜单。
|
||||
6. **待实测**：A102-4/A302-4 的 `hadwrittenoff` 实际回传（§13.1）；克隆新单对 `PreSettlement` 占用的影响（§13.2）。
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
# 结算调整单操作流程说明（分场景）
|
||||
|
||||
> 整理日期：2026-10-17
|
||||
> 定位：面向操作者的流程说明，只讲"谁在哪个页面做什么、系统发生什么、结果是什么"，不含代码细节。
|
||||
> 依据：`2026-10-16-结算调整单接入金蝶设计（未推送自动推-已推送冲销后重推新单）.md` 及当前已落地实现。
|
||||
|
||||
---
|
||||
|
||||
## 一、结算调整单是什么
|
||||
|
||||
正式结算单**审批通过后不允许直接改金额**，一切费用调整都必须通过「结算调整单」完成。
|
||||
|
||||
- **作用**：对一张已审批通过的正式结算单，调整其费用项目和金额（调增、调减、新增手工费用）。
|
||||
- **单号规则**：`TZ + 日期 + 4 位流水`，保存草稿时自动生成。
|
||||
- **只能手工新增**：系统不会自动生成调整单，全部由业务人员在页面发起。
|
||||
- **没有作废功能**：调整单一旦提交走审批，不支持作废；错了只能走"驳回 → 修改"或重新建单。
|
||||
- **推送金蝶按钮是高危操作**：点击前有二次确认，请确认金蝶侧状态后再操作。
|
||||
|
||||
---
|
||||
|
||||
## 二、状态与可用操作总览
|
||||
|
||||
### 2.1 状态流转
|
||||
|
||||
```
|
||||
新增/保存草稿 ──→ 草稿 ──提交──→ 审批中 ──审批通过──→ 审批通过（终态）
|
||||
↑ │
|
||||
│ 驳回
|
||||
└──── 已驳回 ←───┘
|
||||
（可改后重新提交）
|
||||
```
|
||||
|
||||
- 草稿、已驳回：可编辑、可删除（草稿）、可提交。
|
||||
- 审批中：只能"通过"或"驳回"。
|
||||
- 审批通过：终态，只剩金蝶推送相关操作。
|
||||
|
||||
### 2.2 各状态下的按钮
|
||||
|
||||
| 状态 | 可用操作 | 说明 |
|
||||
|---|---|---|
|
||||
| 草稿 | 编辑 / 删除 / 提交 | 删除为物理删除，含明细 |
|
||||
| 已驳回 | 编辑 / 提交 | 须先"编辑"保存一次（保存自动回到草稿）才能提交，直接提交会被拒绝 |
|
||||
| 审批中 | 通过 / 驳回 | 审批人操作 |
|
||||
| 审批通过 | 推送金蝶 / 重新推送（合一按钮）| 按金蝶状态自动分流，高危确认 |
|
||||
|
||||
### 2.3 金蝶同步状态（调整单上的展示字段）
|
||||
|
||||
| 状态 | 含义 |
|
||||
|---|---|
|
||||
| 未同步 | 原结算单还没推过金蝶，或推送尚未发生 |
|
||||
| 已同步 | 已在金蝶生成应付/应收单，调整单上可看到金蝶单据号 |
|
||||
| 生成失败 | 推送失败，可用"推送金蝶"重试或等定时重推 |
|
||||
|
||||
---
|
||||
|
||||
## 三、通用操作说明（每个操作：前置条件 → 系统动作 → 结果）
|
||||
|
||||
### 3.1 新增调整单
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 入口 | 结算调整单列表 → 新增 |
|
||||
| 前置 | 必须先选定一张**可调整的正式结算单**，条件缺一不可：① 审批通过；② 未完成收款/付款；③ 非尾款结算；④ 未发起尾款付款/付款申请。不满足的单在选单列表里根本搜不到 |
|
||||
| 系统动作 | 选定结算单后自动回带：客商、调整类型（应收/应付）、合同、原结算金额、原单费用明细；同时做一次**金蝶冲销预检（软提示）** |
|
||||
| 预检提示 | ① 未推送金蝶 → 正常继续；② 已推送且旧单已冲销 → 提示"审批后可重新推送新单"；③ 已推送且旧单未冲销 → 醒目提示"审批后需先由财务在金蝶完成冲销，才能重新推送"；④ 金蝶查不到/超时 → 提示"未校验"，**不阻断建单** |
|
||||
| 结果 | 生成一张草稿，获得单号 |
|
||||
|
||||
> 预检只是提示，不拦人；真正的拦截在"重新推送"那一步。填单时必须至少录入一条调整费用，否则无法提交。
|
||||
|
||||
### 3.2 保存草稿 / 编辑 / 删除
|
||||
|
||||
- 草稿和已驳回的单可反复编辑；删除仅限草稿，删除后单号作废、不留痕迹。
|
||||
- 手工费用行（不对应原单明细的费用）与关联原单明细的费用行在明细里混排，提交时会校验关联完整性。
|
||||
|
||||
### 3.3 提交
|
||||
|
||||
- 草稿 / 已驳回 → 审批中，进入审批人的待办。
|
||||
- 提交后单据锁定，提交人不能再改。
|
||||
|
||||
### 3.4 审批通过 ★ 核心分流点
|
||||
|
||||
审批人点"通过"后，系统按**原结算单是否推送过金蝶**自动走两条完全不同的路（见第四、五节场景 A / B）：
|
||||
|
||||
- **原单未推送**：把调整直接回写到原结算单，然后自动推金蝶。
|
||||
- **原单已推送**：原单数据一律不动，只留一条变更记录，等财务冲销后再人工重推。
|
||||
|
||||
> 注：审批接口会顺带返回自动推送的失败原因（如有），前端直接提示，不用去翻日志。
|
||||
|
||||
### 3.5 驳回
|
||||
|
||||
- 审批中 → 已驳回，驳回原因写入备注。
|
||||
- 驳回后单据解锁，提交人可修改后重新提交，回到审批中。注意：重新提交前必须先点一次「编辑」并保存（保存会把单据重置回草稿），对已驳回单直接点提交会被拒绝。
|
||||
|
||||
### 3.6 推送金蝶 / 重新推送（合一按钮，高危）
|
||||
|
||||
列表和详情里只有一个按钮，系统按金蝶状态自动分流：
|
||||
|
||||
| 调整单金蝶状态 | 按钮实际行为 | 前置闸门 |
|
||||
|---|---|---|
|
||||
| 未同步 / 生成失败 | 推送其关联的**原结算单**到金蝶 | 无冲销要求 |
|
||||
| 已同步 | **重新推送（高危）**：确认金蝶旧单已冲销后，克隆一张新正式结算单并推送 | 硬闸门：金蝶旧单必须已冲销，否则直接拒绝并提示先冲销 |
|
||||
|
||||
按钮点击均有高危二次确认弹窗。
|
||||
|
||||
---
|
||||
|
||||
## 四、分场景流程
|
||||
|
||||
### 场景 A：原结算单未推送金蝶（最常见、全自动）
|
||||
|
||||
适用：正式结算单审批通过了，但还没推到金蝶。
|
||||
|
||||
| 步骤 | 操作人 | 操作 | 系统动作 |
|
||||
|---|---|---|---|
|
||||
| 1 | 业务 | 新增调整单，选定结算单，录调整费用，保存草稿 | 回带信息、生成 TZ 单号 |
|
||||
| 2 | 业务 | 提交 | 草稿 → 审批中 |
|
||||
| 3 | 审批人 | 审批通过 | ① 调整直接回写原结算单（费用、明细、合计、结算金额全部更新）；② 原单追加变更记录；③ 调整单 → 审批通过；④ 事务提交后**自动触发金蝶推送**（走正式结算单既有的推送链路：生成财务应付/应收单 + 单据落锁 + 附件上传） |
|
||||
| 4 | 系统 | — | 推送成功：调整单回填"已同步 + 金蝶单据号"；推送失败：调整单置"生成失败"+ 原因，**审批结果不受影响**，转入场景 D 处理 |
|
||||
|
||||
结束后：原结算单即调整后的金额，金蝶里是一张含调整金额的应付/应收单。
|
||||
|
||||
> 注意：审批后自动推送受系统开关控制。若环境未开启自动同步，审批仍成功，但需人工在列表点"推送金蝶"完成推送。
|
||||
|
||||
### 场景 B：原结算单已推送金蝶（需财务在金蝶冲销后重推）
|
||||
|
||||
适用：正式结算单已在金蝶生成应付/应收单。核心约束：**原单一经推送金蝶即冻结，本地数据一律不动**。
|
||||
|
||||
| 步骤 | 操作人 | 操作 | 系统动作 |
|
||||
|---|---|---|---|
|
||||
| 1 | 业务 | 新增调整单（选单时预检会提示"旧单未冲销"或"已冲销"），提交 | 同场景 A 步骤 1-2 |
|
||||
| 2 | 审批人 | 审批通过 | ① 原结算单业务数据**零改动**，只追加 1 条变更记录（"调整单XX审批通过，调整金额XX，待重推金蝶"）；② 调整单 → 审批通过，金蝶状态保持"已同步"快照（"重新推送"按钮因此亮起）；③ 前端提示：**"原结算单已推送金蝶，请财务人员在金蝶手工完成旧应付/应收单冲销处理"** |
|
||||
| 3 | 财务 | **在金蝶系统内手工冲销**旧的应付/应收单 | TMS 不参与，这是金蝶侧的人工操作 |
|
||||
| 4 | 业务 | 回到 TMS，点"重新推送（高危）"并二次确认 | 系统依次：① 硬闸门——按原结算单号去金蝶查旧单，**必须已冲销**（部分冲销也算已冲销），未冲销直接拒绝；② **克隆一张新的正式结算单**（全新 FJS/SJS 单号），把调整应用上去，直接置为审批通过（新单不再走审批流）；③ 用新单号推送金蝶，生成**全新**的财务应付/应收单 + 落锁 + 附件；④ 调整单改挂到新单，回填"已同步 + 金蝶单据号"；⑤ 原单标记"已调整"，原单在金蝶的旧锁解锁 |
|
||||
| 5 | 系统 | — | 完成。此时列表里**新旧两张正式结算单并存**，带标识区分（见第六节） |
|
||||
|
||||
失败处理：第 4 步若推送失败，已克隆的新单不回滚，新单置"生成失败"；再点"重新推送"会**复用已克隆的新单**从推送步骤继续，不会重复建单（幂等）。调整单已改挂新单后再点重推，会被冲销闸门拦截，无副作用。
|
||||
|
||||
> 为什么第 2 步不自动推：金蝶侧已有一张旧单，直接再推会重复生成应付/应收单；必须先冲销旧单，且冲销只能由财务在金蝶完成，TMS 无法代办。
|
||||
|
||||
### 场景 C：审批驳回 → 修改后重新提交
|
||||
|
||||
1. 审批人在"审批中"单据上点"驳回"，填写驳回原因。
|
||||
2. 单据回到"已驳回"，提交人可编辑（改费用、改金额），重新提交。
|
||||
3. 提交后回到"审批中"，等同重新走审批。
|
||||
4. 若已驳回单不想调了：留置即可（无作废功能），或改对后再次提交。
|
||||
|
||||
> 已审批通过的单**无法驳回、无法作废、无法撤回**，录入时请谨慎；金额确认错的分析原因后新建调整单二次调整。
|
||||
|
||||
### 场景 D：金蝶推送失败
|
||||
|
||||
| 触发 | 现象 | 处理 |
|
||||
|---|---|---|
|
||||
| 场景 A 审批后自动推送失败 | 调整单状态"生成失败"，审批接口直接返回失败原因，原结算单也有失败标记 | ① 等定时重推任务自动扫描重试；② 或人工在调整单列表点"推送金蝶"立即重试 |
|
||||
| 场景 B 重推新单失败 | 新正式结算单"生成失败"，调整单显示失败状态 | 再点"重新推送"，系统复用已克隆的新单从推送步骤续推，不会重复建单 |
|
||||
|
||||
审批结果与推送结果相互独立：推送失败不影响"审批通过"，只影响金蝶侧是否生成单据。
|
||||
|
||||
### 场景 E：边界情况速查
|
||||
|
||||
| 情况 | 系统行为 |
|
||||
|---|---|
|
||||
| 未审批就点重推 | 拒绝，要求先审批通过 |
|
||||
| 金蝶旧单未冲销就点重推 | 硬拦截，提示先冲销 |
|
||||
| 金蝶旧单被删除（非冲销）| 查不到旧单 → 同样拦截 |
|
||||
| 部分冲销 | 视同已冲销，放行重推 |
|
||||
| 审批时原单刚好已被推送到金蝶 | 按**当下**状态走场景 B，选单时的预检结论不作数 |
|
||||
| 选单时金蝶超时/不可用 | 预检降级"未校验"，不阻断建单 |
|
||||
| 重推成功前原单旧锁残留 | 重推成功时统一解锁 |
|
||||
| 应收结算单 | 与应付完全同一套流程，仅接口不同（应收 A302 系 / 应付 A102 系） |
|
||||
|
||||
---
|
||||
|
||||
## 五、单据标识与字段说明（列表里怎么认单）
|
||||
|
||||
| 单据/字段 | 含义 |
|
||||
|---|---|
|
||||
| 正式结算单标"**已调整**" | 该单已被调整单重推过，金额已作废（数据保留），不要再用它做下游业务 |
|
||||
| 正式结算单标"**调整后单**"并显示原单号 | 这是重推克隆出的新单，金额 = 原单 + 调整 |
|
||||
| 调整单"金蝶单据号" | 该调整最终落到金蝶哪张应付/应收单上 |
|
||||
| 调整单"金蝶同步状态" | 见 2.3 |
|
||||
| 调整金额 / 原结算金额 / 调整后金额 | 调整后金额 = 原结算金额 + 调整金额 |
|
||||
|
||||
---
|
||||
|
||||
## 六、重要业务口径（须知）
|
||||
|
||||
1. **原单冻结原则**：原结算单一经推送金蝶，TMS 本地对其零改动；调整金额只体现在重推克隆的新单上。
|
||||
2. **新单是全新独立单**：原单的下游关联（开票申请、收款认领、对账）**不迁移**，留在原单；新单发票状态、收付款状态均从零开始（未收票、未付款）。应收场景下新单会显示"未开票/未收款"，属正常现象。
|
||||
3. **新单不走审批流**：克隆的新正式结算单直接是审批通过状态，无需再审批。
|
||||
4. **冲销是财务的人工操作**：TMS 不自动冲销金蝶单据，也不会因为调整单驳回/删除而自动恢复冲销——所以建单阶段只做软提示，把硬拦截留在重推。
|
||||
@@ -0,0 +1,284 @@
|
||||
# 正式结算单预付整合设计（进度预付 + 项目预付核销）
|
||||
|
||||
> 关联文档：同目录《2026-10-18-预付完整流程梳理（进度预付-项目预付-正式结算单-付款-金蝶回写）.md》（改造前现状梳理）
|
||||
> 设计日期：2026-10-18。范围：正式结算单（FormalSettlement）对两类预付的金额整合与付款记录关联显示。
|
||||
> **落地后全链路逻辑见同目录《2026-10-18-预付与正式结算单全链路逻辑梳理（进度预付-项目预付核销·前端到后端各环节）.md》。**
|
||||
> **v2 修订**：纳入评审意见——核销计入口径改为"仅已付款预付可核销"（待业务确认）、新增核销行迁移设计（预结算转正式 / 调整重推）、作废联动删行补全（含结算单作废/金蝶删单回调/预结算作废）、调整单校验与刷新、列表页 N+1 规避、对账与调整完成判定影响面、细节修正。见文末修订记录。
|
||||
|
||||
## 一、背景与目标
|
||||
|
||||
两条预付线的"单据流"已经打通（进度预付经预结算单继承、项目预付经核销组件落库），但**金额与记录**没有整合进正式结算单：
|
||||
|
||||
| # | 差距 | 现状锚点 |
|
||||
|---|---|---|
|
||||
| 1 | 结算合计区域看不到预付抵扣：原金额、已付金额（含预付/核销）、剩余未付金额 | `formal-settlement-editor.vue` 结算合计区只渲染费用明细合计（L99-180） |
|
||||
| 2 | 项目预付核销金额不计入结算单 `appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus` | `calculatePaymentSummary` payable 分支只加来源预结算的预付快照（`FormalSettlementServiceImpl` L1881-1890） |
|
||||
| 3 | 付款记录只显示尾款（`settlement_payment`）申请，进度预付/项目预付的已付款记录不关联显示 | `detail()` 查询付款申请固定 `paymentType=结算`（L339） |
|
||||
| 4 | 核销行没有"流转"设计：预结算转正式、调整重推时核销行丢失或额度双占 | `cloneFormalSettlement` L641-708 不克隆核销行；编辑器新建固定重置 `[]`（L1410） |
|
||||
| 5 | 各类作废不清理核销行，详情残留、批量刷新会把作废单核销计入已付 | `FormalSettlementServiceImpl.voidBill` L600-609、`voidByKingdee` L613-637、`PreSettlementServiceImpl.voidBill` L443 均无删行 |
|
||||
|
||||
**零表结构变更**：所需字段均已存在（`FormalSettlementSource` 预付快照、`SettlementProjectAdvanceWriteOff` 核销行、`PreSettlementAdvance` 预付台账），本设计只做计算口径、记录流转与展示整合。
|
||||
|
||||
## 二、已确认决策
|
||||
|
||||
| 决策 | 结论 | 状态 |
|
||||
|---|---|---|
|
||||
| D1 结算合计"扣除"的呈现 | `settlementAmount` **保持全额**（费用合计，开票匹配上限、金蝶 A102-2 应付单金额、结算调整单基线都不变）。结算合计卡片下增加汇总栏：**结算合计（原金额）/ 已付金额（含预付、核销）/ 剩余未付金额**，编辑态与只读态都显示。 | ✅ 已确认 |
|
||||
| D2 核销计入口径（修订） | **仅已付款的项目预付可核销**：`listOptions` 选单过滤与 `replaceWriteOffs` 保存校验都增加 `kingdeeStatus='paid'` 条件（当前只要求 `approved`，L157）。核销时点钱已付出，核销金额同时计入 `appliedPaymentAmount` 与 `paidAmount` 属实付口径，不存在"审批未付却推成 paid"的失真，与付款记录行展示的底层实付一致。 | ✅ 已确认（方案②） |
|
||||
| D3 付款记录关联显示 | 后端 detail 新增统一预付付款记录列表 `advancePayments`；前端在只读"付款信息"表格中**合并成一张表**，以"付款类型"列区分：进度预付 / 项目预付核销 / 结算尾款。 | ✅ 已确认 |
|
||||
| D4 范围 | 只做正式结算单（FORMAL）侧汇总；金蝶预付抵扣字段（`y_billtype/y_billid/y_settleamt`）维持本期不传；应收（receivable）侧不动。**但 PRE→FORMAL 的核销行搬运在范围内**（见 D5）。 | ✅ 已确认 |
|
||||
| D5 核销行流转原则 | **同一笔预付的核销在链路上只存在一份**：预结算转正式时来源 PRE 核销行转移为本单 FORMAL 行；调整重推时原单核销行迁移到新单。转移 = 删源行 + 落新行，同一事务。 | ✅ 已确认 |
|
||||
| D6 作废联动删行 | 付款申请作废删其核销行（既有"作废联动"模式）；正式结算单作废（`voidBill`/`voidByKingdee`）与预结算单作废（`voidBill`）补 `deleteBySettlement`，消除详情残留与汇总污染。 | ✅ 已确认 |
|
||||
| D7 结算调整单兜底 | 调整落库（`SettlementAdjustmentServiceImpl` L384-388）后：①校验**核销合计 ≤ 新结算金额**，超出则拒绝并提示先调减核销；②调用 `refreshPaymentSummary` 重算汇总（含核销）。 | ✅ 已确认 |
|
||||
| D8 影响面确认点 | ① 对账单 `copyHeader` 复制 `paidAmount`（`TransportReconciliationServiceImpl` L1325）→ 对账单已付口径将含核销，**按可接受设计**；② `isSettlementCompleted`（`SettlementAdjustmentServiceImpl` L468-471）判定 → 全额核销的结算单 `paymentStatus=paid`，将**不能再发起结算调整**，按"全额抵扣即结清"设计。历史数据问题明确不考虑。 | ✅ 已确认 |
|
||||
|
||||
## 三、金额口径
|
||||
|
||||
前提（D2 修订）：核销行的底层付款申请必为 `kingdeeStatus='paid'`。
|
||||
|
||||
```
|
||||
结算金额 settlementAmount = Σ 结算合计费用项 settlementAmount（不变）
|
||||
已付金额 paidAmount = 尾款已付(直挂+关系表, approved)
|
||||
+ Σ 来源预结算 advancePaidAmount（进度预付，已有）
|
||||
+ Σ 本单核销行 writeOffAmount（项目预付，本次新增；行必对应已付款预付）
|
||||
已申请付款 appliedPaymentAmount = 尾款申请中(直挂+关系表, reviewing)
|
||||
+ Σ 来源预结算 advanceAppliedAmount（已有）
|
||||
+ Σ 本单核销行 writeOffAmount（本次新增）
|
||||
剩余可付 remainingPayableAmount = max(settlementAmount − paidAmount, 0)（已有公式，输入变了）
|
||||
付款状态 paymentStatus = unpaid / partial / paid（已有公式，输入变了）
|
||||
```
|
||||
|
||||
> 与进度预付口径的准确表述：进度预付在结算单上是"申请（advanceAppliedAmount）/ 实付（advancePaidAmount）"两条快照分开跟踪；项目预付在核销时点已完成实付（D2），故核销额计入实付。付款记录行的"已付款金额"（底层实付）与汇总栏"已付金额"必然一致，不存在同屏矛盾。
|
||||
|
||||
## 四、后端改动（tms-api / blade-transport）
|
||||
|
||||
### 4.1 汇总计入核销金额
|
||||
|
||||
**`FormalSettlementServiceImpl.calculatePaymentSummary(settlement, data)`**（L1864-1901）：
|
||||
|
||||
`payable` 分支（L1881-1890）在累加来源预付快照之后追加：
|
||||
|
||||
```java
|
||||
// 项目预付核销计入已付/已申请（D2：核销行底层预付必已付款，核销额即实付抵扣）
|
||||
BigDecimal writeOffAmount = data.writeOffAmounts() != null
|
||||
? data.writeOffAmounts().getOrDefault(settlement.getId(), BigDecimal.ZERO)
|
||||
: this.projectAdvanceWriteOffService.sumBySettlement(
|
||||
TransportBusiConstant.SETTLEMENT_BILL_FORMAL, settlement.getId());
|
||||
appliedAmount = appliedAmount.add(this.money(writeOffAmount));
|
||||
paidAmount = paidAmount.add(this.money(writeOffAmount));
|
||||
```
|
||||
|
||||
**`PaymentSummaryData` record**（L1926-1929）新增组件：
|
||||
|
||||
```java
|
||||
@param writeOffAmounts 结算单id → 核销金额合计（仅应付结算单；null 表示由纯计算按需查询）
|
||||
..., BigDecimal receiptClaimPaid, Map<Long, BigDecimal> writeOffAmounts
|
||||
```
|
||||
|
||||
同步修改两处构造调用：
|
||||
- 批量版 `refreshPaymentSummaries`（L1544-1627）：`hasPayable` 时按 `settledIds` **一次**查询核销行分组求和（4.5 新增方法），按结算单分发，避免 N+1；
|
||||
- 单笔版包装方法（L1839-1858）：传 `null` 走按需查询。
|
||||
|
||||
> 说明：`saveDraft` 保存核销后由 `refreshSettlementAmount`（内部 L1524 刷新）+ 新增的一次 `refreshPaymentSummary` **连续两次完整刷新是有意为之**——核销校验依赖 `refreshSettlementAmount` 重算后的最终结算金额，故 `replaceWriteOffs` 只能排在其后，二次刷新不能合并省略。后续优化前先读此注释。
|
||||
|
||||
### 4.2 保存核销后刷新汇总
|
||||
|
||||
**`FormalSettlementServiceImpl.saveDraft`**（L546-553）：`replaceWriteOffs` 保持在 `refreshSettlementAmount`（L546）之后（校验用最终结算金额），其后追加：
|
||||
|
||||
```java
|
||||
projectAdvanceWriteOffService.replaceWriteOffs(...); // L548-553 原位置不动
|
||||
this.refreshPaymentSummary(settlement.getId()); // 新增：核销行计入汇总
|
||||
```
|
||||
|
||||
### 4.3 核销行流转（D5）
|
||||
|
||||
**通用删行方法**（`ISettlementProjectAdvanceWriteOffService` 新增，事务内逻辑删除）：
|
||||
|
||||
```java
|
||||
/** 删除指定结算单上的核销行（配合转移/作废场景），返回被删行数 */
|
||||
int deleteBySettlementIds(String settlementType, Collection<Long> settlementIds);
|
||||
/** 按付款申请删除核销行，返回受影响的正式结算单id（settlementType=formal，供汇总刷新） */
|
||||
List<Long> deleteByPaymentApplicationIds(Collection<Long> paymentApplicationIds);
|
||||
```
|
||||
|
||||
**预结算转正式（`saveDraft` 完整建单路径）**：
|
||||
1. 前端：编辑器 `confirmCandidates` 选定来源预结算后，对每个新选 `preSettlementId` 复用**既有** `preSettlement.getDetail(id)` 取 `projectAdvanceWriteOffs` 预填进本单核销组件（去重、金额 Number 化），用户可在弹窗中增删改；
|
||||
2. 后端 `saveDraft`：在 `replaceWriteOffs`（L548）**之前**执行 `deleteBySettlementIds("pre", request.getSourcePreSettlementIds())`——先释放来源占用，`replaceWriteOffs` 的"不超可核销余额"校验才能通过预填金额；随后 `replaceWriteOffs` 将预填行落为本单 FORMAL 行。同一事务，失败整体回滚。
|
||||
3. 轻量标记路径（`PreSettlementServiceImpl.formalSettlement(id)`，L550）：不产生正式单实体，PRE 核销行原地保留（预结算实体仍是载体），待后续真正建正式单时按上述规则转移。
|
||||
|
||||
**调整重推（`cloneFormalSettlement`，L641-708）**：与既有"新单付款口径归零"哲学（L658 注释）冲突时以**额度正确性优先**——
|
||||
1. 在来源克隆循环后，克隆原单活跃核销行到新单（`settlementId` 换新、`resetAuditFields`）；
|
||||
2. `deleteBySettlementIds("formal", List.of(sourceSettlementId))` 删原单核销行（原单 `adjustStatus=adjusted` 为历史存档，已付归零以新单为准，文档明示）；
|
||||
3. `refreshPaymentSummaries(List.of(原单id, 新单id))` 一次批量刷新两单（新单头 L662-664 置零的 applied/paid 由重算纠正为核销额）。
|
||||
|
||||
> 新单由克隆直接 `approved`（L647），无草稿编辑机会，故必须迁移而非"让用户重新核销"。
|
||||
|
||||
### 4.4 作废联动删行（D6）
|
||||
|
||||
| 触发点 | 改动 |
|
||||
|---|---|
|
||||
| `PaymentApplicationServiceImpl.voidBill`（L446-460，L458 `voidPreSettlementAdvance` 后） | `deleteByPaymentApplicationIds(List.of(entity.getId()))` → 返回的 formal ids 非空则 `formalSettlementService.refreshPaymentSummaries(ids)` |
|
||||
| `FormalSettlementServiceImpl.voidBill`（L600-609） | `deleteBySettlementIds("formal", List.of(id))` |
|
||||
| `FormalSettlementServiceImpl.voidByKingdee`（L613-637） | 同上 |
|
||||
| `PreSettlementServiceImpl.voidBill`（L443） | `deleteBySettlementIds("pre", List.of(id))`（预结算作废前置"先作废预付"校验不受影响，核销行不阻断） |
|
||||
|
||||
金蝶反审核自动解锁置 `failed`（未作废）的场景**不删行**：预付申请仍是 `approved`，已核销行继续计入；人工作废后经上表路径回落。
|
||||
|
||||
存量数据提示：v2 之前保存的核销行可能对应"approved 未 paid"的预付，本次不做数据修正，如需口径清洗另出脚本（`replaceWriteOffs` 校验只约束新保存）。
|
||||
|
||||
### 4.5 核销服务与 Mapper
|
||||
|
||||
**`ISettlementProjectAdvanceWriteOffService` / `SettlementProjectAdvanceWriteOffServiceImpl`**：
|
||||
- 4.3 两个删除方法（见上）；
|
||||
- `Map<Long, BigDecimal> sumBySettlementIds(String settlementType, Collection<Long> settlementIds)`——一次 group-by，供批量刷新与列表页（4.7）使用。
|
||||
|
||||
**`SettlementProjectAdvanceWriteOffMapper.java`（接口）+ `SettlementProjectAdvanceWriteOffMapper.xml`**：新增 `sumWriteOffBySettlementIds`（`is_deleted=0` + `settlement_type` + `settlement_id in (...)`，`GROUP BY settlement_id`），与既有 `sumWriteOffBySettlement`（XML L27-33）口径一致。
|
||||
|
||||
**选单与校验加 paid 条件（D2）**：
|
||||
- `listOptions`（ServiceImpl L48-81）：查询条件追加 `kingdeeStatus='paid'`；
|
||||
- `replaceWriteOffs`（L124-193）：在 `approvalStatus=approved` 校验（L157-159）后追加 `kingdeeStatus='paid'` 校验，提示文案"项目预付已付款后方可核销"。
|
||||
|
||||
### 4.6 detail 返回统一预付付款记录
|
||||
|
||||
**新 VO `SettlementAdvancePaymentVO`**（`blade-transport-api/pojo/vo/`，仿 `ProjectAdvanceWriteOffOptionVO` 风格，含 BladeX 许可头）：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `recordType` | `progress_advance` 进度预付 / `project_advance` 项目预付核销 |
|
||||
| `paymentNo` | 进度预付 = `PreSettlementAdvance.advanceNo`（FKD 单号）；项目预付 = 核销行 `paymentNo` |
|
||||
| `appliedAmount` | 进度预付 = `appliedAmount`；项目预付 = 核销行 `writeOffAmount`（**本次核销金额**，非付款申请金额） |
|
||||
| `paidAmount` | 进度预付 = `paidAmount`；项目预付 = 底层付款申请 `paidAmount`（D2 下 = 核销额，同屏一致） |
|
||||
| `billStatus` | 进度预付 = 台账 `billStatus`；项目预付 = 付款申请 `approvalStatus` |
|
||||
| `kingdeeBillNo` | 进度预付 = `kingdeeAdvanceNo`；项目预付 = 核销行 `kingdeeBillNo` |
|
||||
| `createUserName` / `createTime` | `UserCache.getUserRealName(createUser)`（AGENTS.md 6.9）；**createTime 统一取底层付款申请创建时间**：项目行用核销行已回填的 `paymentCreateTime`（`listBySettlement` 现成），进度行按 `advanceNo in (...)` 批量反查 `PaymentApplication.createTime`（一次 in 查询）。列表排序与展示均用该时间 |
|
||||
|
||||
**`FormalSettlementVO`** 新增 `@TableField(exist = false) private List<SettlementAdvancePaymentVO> advancePayments;`（L74 `paymentApplications` 旁）。
|
||||
|
||||
**`FormalSettlementServiceImpl.detail`**（L307-352）在加载 `projectAdvanceWriteOffs`（L323-324）后组装：
|
||||
|
||||
```java
|
||||
vo.setAdvancePayments(this.listAdvancePayments(sources, vo.getProjectAdvanceWriteOffs()));
|
||||
```
|
||||
|
||||
`listAdvancePayments` 私有方法：
|
||||
1. **进度预付**：`PreSettlementAdvance` 按 `preSettlementId in 来源预结算ids`、`billStatus != 'voided'` 查询（注入 `PreSettlementAdvanceMapper`，与同类 `sourceMapper` 直连模式一致）；
|
||||
2. **项目预付**：遍历核销行，`paymentApplicationMapper.selectBatchIds` 批量取底层付款申请回填已付金额/状态；
|
||||
3. 合并后按"付款申请创建时间"降序（列表默认排序规范）。
|
||||
|
||||
尾款记录（`paymentApplications`）查询不动。
|
||||
|
||||
### 4.7 列表页 N+1 规避（D8/评审#5）
|
||||
|
||||
`selectPage` L209-210 逐行 `toVO`，而 `toVO`（L1827-1837）内部 `calculatePaymentSummary` 已是每行 3-4 次查询，**不能再叠加每行一次核销求和**：
|
||||
|
||||
- 新增重载 `toVO(FormalSettlement entity, Map<Long, BigDecimal> writeOffAmounts)`，把 map 置入 `PaymentSummaryData`；单参版委托 `toVO(entity, null)`（按需查询，`detail` 等单笔场景不受影响）；
|
||||
- `selectPage`：本页 `payable` 结算单 ids 一次 `sumBySettlementIds` 得 map，`result.convert(item -> this.toVO(item, writeOffMap))`。
|
||||
|
||||
### 4.8 结算调整单兜底（D7）
|
||||
|
||||
**`SettlementAdjustmentServiceImpl`**（L384-388 直改金额处）：
|
||||
1. 落库前校验：`projectAdvanceWriteOffService.sumBySettlement("formal", formal.getId())` ≤ 新 `settlementAmount`，超出抛"核销合计超过调整后结算金额，请先调减项目预付核销"；
|
||||
2. 落库后：`formalSettlementService.refreshPaymentSummary(formal.getId())`（注入 `IFormalSettlementService`，当前仅有 `formalMapper`）。
|
||||
|
||||
### 4.9 后端改动文件清单
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `service/impl/FormalSettlementServiceImpl.java` | `calculatePaymentSummary` 计入核销；`PaymentSummaryData` 加组件；`saveDraft` 补刷新 + 转移来源 PRE 行；`cloneFormalSettlement` 克隆/迁移核销行；`voidBill`/`voidByKingdee` 删行；`detail` 补 `advancePayments` + 新私有 `listAdvancePayments`；`toVO` 加 map 重载；`selectPage` 批量供数；注入 `PreSettlementAdvanceMapper` |
|
||||
| `service/ISettlementProjectAdvanceWriteOffService.java` + `impl` | 新增 `deleteBySettlementIds`、`deleteByPaymentApplicationIds`、`sumBySettlementIds`；`listOptions`/`replaceWriteOffs` 加 `kingdeeStatus='paid'` 条件 |
|
||||
| `mapper/SettlementProjectAdvanceWriteOffMapper.java` + `.xml` | 新增 `sumWriteOffBySettlementIds`（接口 + XML 成对） |
|
||||
| `service/impl/PaymentApplicationServiceImpl.java` | `voidBill` 联动删核销行 + 刷新汇总 |
|
||||
| `service/impl/PreSettlementServiceImpl.java` | `voidBill` 删 PRE 核销行 |
|
||||
| `service/impl/SettlementAdjustmentServiceImpl.java` | 调整落库前核销合计校验 + 落库后刷新汇总；注入 `IFormalSettlementService` |
|
||||
| `pojo/vo/SettlementAdvancePaymentVO.java`（新增） | 统一预付付款记录 VO |
|
||||
| `pojo/vo/FormalSettlementVO.java` | 加 `advancePayments` |
|
||||
|
||||
## 五、前端改动（tms-erp-web）
|
||||
|
||||
### 5.1 结算合计汇总栏
|
||||
|
||||
**`formal-settlement-editor.vue`**：结算合计 section-card（L99-180）表格下方加汇总条（仅 `form.settlementType === 'payable'` 显示）：
|
||||
|
||||
```
|
||||
结算合计（原金额）：form.settlementAmount
|
||||
已付金额（含预付、核销）：见下
|
||||
剩余未付金额：max(结算合计 − 已付, 0)
|
||||
```
|
||||
|
||||
- 编辑态：`Σ sources.advancePaidAmount + Σ projectAdvanceWriteOffs.writeOffAmount`（选预结算 `confirmCandidates` 与勾选核销行时实时联动；草稿态无尾款申请，公式完备；D2 下核销行必对应已付预付，计入实付口径成立）；
|
||||
- 只读态：`form.paidAmount`（已含尾款 + 进度预付 + 核销的落库值）。
|
||||
|
||||
### 5.2 付款记录合并表
|
||||
|
||||
只读"付款信息"应付表格（L580-612）数据源改为合并计算属性：
|
||||
|
||||
```js
|
||||
paymentRecords() {
|
||||
const advance = (this.advancePayments || []).map(r => ({ ...r, typeName: this.recordTypeName(r.recordType) }));
|
||||
const tail = (this.paymentApplications || []).map(r => ({ ...r, typeName: r.paymentTypeName }));
|
||||
return [...advance, ...tail];
|
||||
}
|
||||
// recordTypeName: progress_advance→'进度预付'，project_advance→'项目预付核销'
|
||||
```
|
||||
|
||||
- 列：付款类型（`typeName`，尾款行兼容原 `paymentTypeName`）/ 单据号 / **申请/核销金额**（预付行的"申请金额"实为核销金额，列名合并以免误导）/ 已付款金额 / 单据状态 / 金蝶单据号 / 创建人 / 创建时间（= 付款申请创建时间，见 4.6）。原"付款方式"列预付行无值，显示 `-`；
|
||||
- 单据状态名映射**提取公共工具**（与 `pre-settlement-editor.vue` L2879 `advanceStatusName` 去重）：新建 `src/utils/settlementStatus.js` 导出 `settlementStatusName(value)`（reviewing 审核中、approved 已审批、paid 已付款、returned 已驳回、voided 已作废、draft 草稿），两个编辑器共用，避免状态名不一致；
|
||||
- `loadFormalDetail`（L1360-1379）回填 `this.advancePayments = data.advancePayments || []`，`readonly` 重置时清空。
|
||||
|
||||
### 5.3 转正式预填核销行
|
||||
|
||||
`confirmCandidates`（L1729-1752）选定来源预结算后：对每个新选 `preSettlementId` 调用既有 `preSettlement` detail 接口，取 `projectAdvanceWriteOffs` 预填进本单核销组件（与已有行按 `paymentApplicationId` 去重、金额 Number 化）；保存时随 payload 提交，后端按 4.3 转移来源行。
|
||||
|
||||
### 5.4 前端不动的部分
|
||||
|
||||
- `project-advance-write-off.vue`：选单过滤、本次核销金额校验链路已完整（L198-288），"已付款"过滤条件由后端 `listOptions` 落实，组件不改；
|
||||
- 列表页 `formal-settlement.vue`："申请付款金额（含预付）/已收已付合计（含预付）/剩余可付金额"列直接受益于后端口径修正，不改；
|
||||
- 尾款申请默认可付金额 `payableOfFormalSettlement` 已扣核销额（`PaymentApplicationServiceImpl` L2115-2122），不改。
|
||||
|
||||
## 六、边界场景
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 草稿保存核销 | 已付/已申请/剩余可付/付款状态立即生效（D2，行必对应已付预付），列表可见 |
|
||||
| 底层项目预付申请作废 | 联动删核销行 + 批量刷新 → 已付回落（4.4） |
|
||||
| 底层预付金蝶推送 `failed` / 反审核解锁 | 不删行，核销继续计入（预付申请仍 approved）；人工作废后回落 |
|
||||
| 金蝶付款完成回写（进度预付） | `syncOnePreSettlementAdvance` 刷新来源快照 → `refreshPaymentSummariesForPreSettlement` → 批量版自动计入核销（4.1 供数） |
|
||||
| 正式结算单作废 / 金蝶删单回调 | 删除本单核销行（4.4），额度释放、详情无残留 |
|
||||
| 预结算单作废 | 删除 PRE 核销行（4.4） |
|
||||
| 预结算转正式（尾款结算） | 前端预填 + 后端先删来源 PRE 行再落 FORMAL 行（4.3），额度单份占用 |
|
||||
| 轻量标记转正式（无在途预付） | PRE 核销行原地保留，待建正式单时转移（4.3） |
|
||||
| 结算调整重推 | 核销行迁移到新单，原单删行并以新单为准（4.3） |
|
||||
| 结算调整单调低金额致核销超限 | 落库前拦截，提示先调减核销（4.8） |
|
||||
| 全额核销后发起调整 | `isSettlementCompleted` 拦截（现状逻辑），业务含义=已结清（D8 待确认） |
|
||||
| 对账单生成 | 复制的 `paidAmount` 含核销口径（D8 待确认） |
|
||||
| 核销合计 + 尾款申请超结算金额 | 双向封顶：核销合计 ≤ 结算金额（`replaceWriteOffs` L184-186）；尾款默认额已扣核销额；`remainingPayableAmount` min 0 |
|
||||
| 开票 | `settlementAmount` 全额不变，发票匹配上限（≤结算金额）不受影响（D1） |
|
||||
| 应收（receivable）结算单 | 走收款认领分支，payable 分支的新增逻辑不触达 |
|
||||
|
||||
## 七、测试要点
|
||||
|
||||
1. `saveDraft` 带核销行 → `appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus` 正确；编辑重复保存不重复累计（全删重插）。
|
||||
2. D2：`approved` 未 `paid` 的项目预付不出现在选单（`listOptions`），手工提交被 `replaceWriteOffs` 拒绝。
|
||||
3. 底层预付作废 → 核销行删除、汇总回落、列表金额一致；作废的正式结算单不再出现在批量刷新的已付统计中。
|
||||
4. 预结算转正式：预填行保存成功（先删 PRE 行再校验余额的顺序）；同一预付在 PRE/FORMAL 侧无双份核销。
|
||||
5. 调整重推：新单含核销行且汇总正确（头字段从置零被重算纠正），原单行删除、汇总归零。
|
||||
6. 结算调整单：调低金额低于核销合计被拒；合法调整后 `refreshPaymentSummary` 生效。
|
||||
7. `detail` 返回 `advancePayments`：进度预付行（排除 voided）+ 项目预付行（回填底层实付），按付款申请创建时间倒序。
|
||||
8. 列表页 SQL 次数：本页核销求和恒定 1 次（不随行数增长）。
|
||||
9. 应收结算单、无预付结算单回归：汇总与现状一致。
|
||||
10. 前端：编辑态汇总栏随选预结算/核销行实时变化；只读态合并付款记录表三类型展示、状态名与预结算页一致；应收侧页面不出现汇总栏。
|
||||
|
||||
## 八、范围外（明确不做）
|
||||
|
||||
- 预结算（PRE）侧自身收付汇总计入核销（本次仅 FORMAL）；
|
||||
- 金蝶预付抵扣字段 `y_billtype / y_billid / y_settleamt`（文档 TODO，本期不传）；
|
||||
- 应收侧预收/收款认领汇总；
|
||||
- 存量"approved 未 paid 核销行"的数据修正脚本（如需另出）；
|
||||
- 遗留接口 `/pre-settlement/apply-advance` 等下线评估（见《2026-10-18-预付完整流程梳理》第五节）。
|
||||
|
||||
## 九、修订记录
|
||||
|
||||
| 版本 | 日期 | 内容 |
|
||||
|---|---|---|
|
||||
| v1 | 2026-10-18 | 初版：汇总计入、作废联动（仅付款申请侧）、detail 预付记录、前后端展示。 |
|
||||
| v2 | 2026-10-18 | 评审修订：D2 改为"仅已付款可核销"（待确认）；新增 D5 核销行流转（预结算转正式预填+转移、调整重推迁移）、D6 作废删行补全（结算单作废/金蝶回调/预结算作废）、D7 调整单校验+刷新、D8 对账与调整完成判定影响面（待确认）；列表页 N+1 规避；文件清单补 Mapper 接口；合并表列名"申请/核销金额"；状态名公共工具；createTime 统一为付款申请创建时间；点明 saveDraft 双刷新为有意设计。 |
|
||||
@@ -0,0 +1,129 @@
|
||||
# 改造后全链路逻辑梳理（预付 × 正式结算单）
|
||||
|
||||
> 关联文档：同目录《2026-10-18-预付完整流程梳理（进度预付-项目预付-正式结算单-付款-金蝶回写）.md》（改造前现状梳理）、同目录《2026-10-18-正式结算单预付整合设计（进度预付+项目预付核销·金额口径与记录流转）.md》（v2 设计与决策）
|
||||
> 梳理日期：2026-10-18。本文描述**改造落地后**的完整逻辑，前端到后端各环节。
|
||||
|
||||
## 一、全景
|
||||
|
||||
```
|
||||
【线A 进度预付】付款申请(progress_advance) ─A103-3→ 金蝶付款 ─回写→ 预结算预付汇总
|
||||
└→ 尾款结算建正式单：继承预付快照 → 结算合计(全额)+汇总栏(已付含预付) → 审批 ─A102-2→ 财务应付单
|
||||
└→ 尾款付款(默认额已扣核销) ─A103-1→ 回写paid → 付款记录合并表
|
||||
|
||||
【线B 项目预付】付款申请(project_advance) ─A103-3→ 金蝶付款 ─回写→ kingdeeStatus=paid
|
||||
└→ 正式结算单「核销」(仅paid可选) → 核销计入已付 → 审批 ─A102-2→ 财务应付单(全额)
|
||||
└→ 尾款付剩余 → 后续与正式结算单流程完全一致
|
||||
```
|
||||
|
||||
**核心口径**（`FormalSettlementServiceImpl.calculatePaymentSummary` payable 分支，全系统唯一）：
|
||||
|
||||
```
|
||||
结算金额 settlementAmount = Σ 结算合计费用项（全额，不扣预付/核销——开票与金蝶应付基线）
|
||||
已申请 appliedPaymentAmount = 尾款reviewing(直挂+关系表) + Σ来源预付快照 + Σ核销
|
||||
已付 paidAmount = 尾款approved实付 + Σ来源预付快照 + Σ核销
|
||||
剩余可付 remainingPayableAmount = max(结算金额 − 已付, 0)
|
||||
付款状态 paymentStatus = unpaid / partial / paid
|
||||
```
|
||||
|
||||
D2 决策：仅**金蝶已付款**（`kingdeeStatus='paid'`）的项目预付可核销，核销额计入已付属实付口径。
|
||||
|
||||
---
|
||||
|
||||
## 二、线A：进度预付（挂预结算单）
|
||||
|
||||
### A1 预付与付款（改造前已有）
|
||||
|
||||
- 前端 `pre-settlement.vue`「预付申请」→ `payment-application-form?paymentType=progress_advance`
|
||||
- 后端 `PaymentApplicationServiceImpl`：审批 → AFTER_COMMIT `KingdeeApprovalSyncListener` → A103-3 直推金蝶 → 提前建档 `PreSettlementAdvance`（advanceNo=FKD 单号）
|
||||
- 金蝶付款后 `PaymentKingdeeResultTask`（A103-2/A103-4）回写 paid
|
||||
- 联动：`syncOnePreSettlementAdvance` 刷新预结算预付汇总（`advanceAppliedAmount/advancePaidAmount`）→ 同步刷新引用它的 `FormalSettlementSource` 快照 → `refreshPaymentSummariesForPreSettlement`（正式单已付跟着涨）
|
||||
|
||||
### A2 尾款结算 → 正式结算单表单（前端）
|
||||
|
||||
- `applyInitialSources`（列表跳转带入）/ `confirmCandidates`（弹窗追加）：拉每张预结算 detail，合并明细与费用项 → `summaryTotal` → `form.settlementAmount`（**全额费用合计，不扣预付**）
|
||||
- **汇总栏（新增）**：仅应付显示；编辑态实时 `已付 = Σ来源预结算.advancePaidAmount + Σ核销行`，`剩余 = 原金额 − 已付`；只读态 `已付 = form.paidAmount`（落库值，含尾款）
|
||||
|
||||
### A3 保存 `saveDraft`（后端，同一事务）
|
||||
|
||||
1. 来源合并（同合同同币种校验）→ `FormalSettlementSource` 快照（含预付汇总）
|
||||
2. `refreshSettlementAmount`：settlementAmount=Σ费用项 → 内部刷一次汇总
|
||||
3. **新增**：`deleteBySettlementIds(PRE, 来源预结算ids)`——先转移来源预结算的项目预付核销行（释放额度）
|
||||
4. `replaceWriteOffs`（服务端复校验：paid、同合同、≤可核销余额、合计≤结算金额）→ **新增** `refreshPaymentSummary`（核销落库后必须再刷一次，第 2 步的刷新覆盖不到核销行）
|
||||
|
||||
### A4 审批 → 同步金蝶
|
||||
|
||||
- `approve` → `KingdeeApprovalSyncListener` → **A102-2 财务应付单，金额=全额结算金额** → lockBusiData 锁单 + A902 附件
|
||||
|
||||
### A5 只读详情（付款记录关联显示，本次核心新增）
|
||||
|
||||
- 后端 `detail` 新增 `advancePayments`：进度预付行 = 来源预结算的 `PreSettlementAdvance` 台账（排除 voided；appliedAmount=申请预付、paidAmount=实付；createTime 统一取**付款申请创建时间**，按 advanceNo 反查）
|
||||
- 前端 `paymentRecords` 合并表：**进度预付 / 项目预付核销 / 结算尾款** 三类型一张表；状态名走公共 `src/utils/settlementStatus.js`
|
||||
|
||||
### A6 尾款付款
|
||||
|
||||
- 前端 `formal-settlement.vue`「付款申请」→ `referenceAmount` 默认可付 = **结算金额 − 累计尾款申请 − 核销**
|
||||
- `settlement_payment` → 前置校验已有财务应付单 → A103-1 应付下推 → 回写 paid → `FormalSettlementPayment(final)` + 汇总刷新 → `paymentStatus=paid`
|
||||
|
||||
---
|
||||
|
||||
## 三、线B：项目预付（挂项目+承运商合同）
|
||||
|
||||
| 环节 | 逻辑 |
|
||||
|---|---|
|
||||
| B1 申请 | 付款申请 `project_advance`：选项目+承运商合同、不挂结算单；`validateQuota` 校验项目额度（fundLimit+临时额度）与客户额度（maxCreditLimit） |
|
||||
| B2 付款 | 审批 → A103-3 直推 → 金蝶付款 → A103-2 回写 **`kingdeeStatus='paid'`**（核销前置条件） |
|
||||
| B3 核销·选单（编辑器） | 全新单：核销组件「选择预付单」→ `project-advance-write-off-options`（后端过滤：同合同 + `approved` + **`paid`** + 有余额）；**预结算转正式入口（新增）**：`confirmCandidates`/`applyInitialSources` 选定来源后自动预填来源预结算已保存的核销行，可增删改 |
|
||||
| B3 核销·录额（前端） | 手录本次核销金额：>0、≤可核销余额、合计≤结算金额（`project-advance-write-off.vue` 既有校验链） |
|
||||
| B4 保存 | 同 A3 第 3-4 步：先转移源 PRE 行 → `replaceWriteOffs` 复校验落 FORMAL 行 → 刷新汇总，核销计入已付 |
|
||||
| B5 审批 | A102-2 按全额结算金额生成财务应付单（金蝶预付抵扣字段 `y_billtype/y_billid/y_settleamt` 本期不传） |
|
||||
| B6 付款记录 | 合并表显示项目预付核销行：`申请/核销金额`=本次核销额，`已付款金额`=底层付款申请实付（paid 前置下两者相等，同屏一致） |
|
||||
| B7 尾款 | 默认可付已扣核销 → 已核销部分不会被重复支付；剩余走正常尾款流程 |
|
||||
| B8 差异 | 后续金额差异按既有规则走**结算调整单**（见横切 5） |
|
||||
|
||||
---
|
||||
|
||||
## 四、横切环节
|
||||
|
||||
| # | 环节 | 逻辑 |
|
||||
|---|---|---|
|
||||
| 1 | 列表页 | `selectPage` 本页 payable 一次 `sumWriteOffBySettlementIds`（group-by）→ `toVO(map)` 重算 → 列「申请付款金额（含预付）/已收已付合计（含预付）/剩余可付/收付款状态」直接反映核销；SQL 不随行数增长 |
|
||||
| 2 | 汇总刷新触发点 | 保存、审批、金蝶付款回写、预结算预付快照联动、作废、调整——全部收敛到 `calculatePaymentSummary`，口径唯一 |
|
||||
| 3 | 作废联动（新增） | 付款申请作废 → 删其核销行 + 刷新受影响正式单汇总（已付回落）；正式单作废（`voidBill`）与金蝶删单回调（`voidByKingdee`）→ 删本单核销行（额度释放）；预结算作废 → 删 PRE 核销行 |
|
||||
| 4 | 核销行流转（新增） | 预结算转正式 = 先删源 PRE 行再落 FORMAL 行（同事务，同一预付的核销全链路只存在一份）；调整重推 = 核销行克隆到新单 + 删原单行 + `refreshPaymentSummaries(两单)`（原单为调整存档，收付口径以新单为准） |
|
||||
| 5 | 结算调整单（新增兜底） | 调整落库前校验**核销合计 ≤ 新结算金额**（超出拒绝并提示先调减核销）；落库后 `refreshPaymentSummary` 重算 |
|
||||
| 6 | 对账单 | `copyHeader` 复制 `paidAmount` → 对账单已付口径含核销（已确认接受） |
|
||||
| 7 | 全额核销=结清 | `paymentStatus=paid` → `isSettlementCompleted` 拦截，不允许再发起结算调整（已确认接受） |
|
||||
| 8 | 开票 | 始终按**全额 settlementAmount** 匹配（Σ匹配 ≤ 结算金额），预付/核销不影响发票 |
|
||||
| 9 | 金蝶预付抵扣 | `y_billtype / y_billid / y_settleamt` 本期不传（见《2026-10-18-预付完整流程梳理》TODO） |
|
||||
| 10 | 历史数据 | 本次不考虑存量"approved 未 paid"核销行的清洗 |
|
||||
|
||||
---
|
||||
|
||||
## 五、改动文件索引
|
||||
|
||||
**后端（tms-api）**
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `FormalSettlementServiceImpl` | 汇总计入核销（单笔/批量/toVO 重载）、saveDraft 转移+刷新、cloneFormalSettlement 迁移、voidBill/voidByKingdee 删行、detail.advancePayments、selectPage 批量供数 |
|
||||
| `SettlementProjectAdvanceWriteOffServiceImpl` | listOptions/replaceWriteOffs 加 paid 条件；sumBySettlementIds / deleteBySettlementIds / deleteByPaymentApplicationIds |
|
||||
| `SettlementProjectAdvanceWriteOffMapper.java/.xml` | sumWriteOffBySettlementIds |
|
||||
| `PaymentApplicationServiceImpl` | voidBill 联动删核销行+刷新 |
|
||||
| `PreSettlementServiceImpl` | voidBill 删 PRE 核销行 |
|
||||
| `SettlementAdjustmentServiceImpl` | 调整前核销合计校验 + 调整后刷新汇总 |
|
||||
| `SettlementAdvancePaymentVO`（新）/ `FormalSettlementVO` | 统一预付付款记录 VO / advancePayments 字段 |
|
||||
|
||||
**前端（tms-erp-web）**
|
||||
|
||||
| 文件 | 内容 |
|
||||
|---|---|
|
||||
| `formal-settlement-editor.vue` | 结算合计汇总栏；付款记录合并表；confirmCandidates/applyInitialSources 预填核销行 |
|
||||
| `src/utils/settlementStatus.js`（新） | 状态名/记录类型名公共映射（预结算编辑器同步使用） |
|
||||
|
||||
---
|
||||
|
||||
## 六、已知口径与风险
|
||||
|
||||
1. 尾款默认可付额（`payableOfFormalSettlement`）= 结算金额 − 累计尾款申请 − 核销，**不扣进度预付已付部分**（改造前既有口径，本次未动）；进度预付占大头时默认额可能偏大，提交后由审批环节把关。
|
||||
2. 正式结算单 `paidAmount` 现含核销，下游消费该字段的报表/对账口径随之变化（对账已确认接受）。
|
||||
3. 金蝶侧预付抵扣字段未传，金蝶报表与本系统"已付含核销"存在时间差。
|
||||
@@ -0,0 +1,160 @@
|
||||
# 预付完整流程梳理
|
||||
|
||||
> 范围：预付（进度预付 / 项目预付）→ 正式结算单 → 付款 → 金蝶回写等后续流程，前端到后端全链路。
|
||||
> 依据代码现状梳理（tms-api / tms-erp-web），梳理日期：2026-10-18。
|
||||
|
||||
## 一、总览
|
||||
|
||||
预付有**两条线**，最终在金蝶（星瀚 BFI）汇合：
|
||||
|
||||
```
|
||||
【进度预付线】 【项目预付线】
|
||||
预结算单(审批通过,应付) 付款申请-项目预付(挂项目/合同,不挂结算单)
|
||||
└─「预付申请」→ 付款申请(progress_advance) └─ 校验项目额度/客户额度 → A103-3 → 金蝶付款
|
||||
└─ 审批 → A103-3 直推金蝶付款申请单 └─ 事后在预结算/正式结算单上「项目预付核销」
|
||||
└─ 提前建档 PreSettlementAdvance(approved)
|
||||
└─ 定时回写 A103-2/A103-4 → paid
|
||||
└─ 预付记录置 paid + 预结算单预付汇总刷新
|
||||
└─「尾款结算」→ 正式结算单(继承预付汇总) → 审批 → A102-2 财务应付单
|
||||
└─「申请付款」→ 付款申请(settlement_payment) → A103-1 应付下推
|
||||
└─ 回写 paid → FormalSettlementPayment + 结算单付款汇总(unpaid→partial→paid)
|
||||
```
|
||||
|
||||
### 金蝶接口速查
|
||||
|
||||
| 接口 | 用途 | 触发方 |
|
||||
|---|---|---|
|
||||
| A103-3 | 预付款直接保存金蝶付款申请单（不绑应付单） | 付款申请（progress_advance / project_advance）同步金蝶 |
|
||||
| A103-1 | 应付下推生成金蝶付款申请单 | 付款申请（settlement_payment）同步金蝶 |
|
||||
| A103-2 | 付款申请单查询（幂等预检 + 结果回写） | 推送前预检、定时回写任务 |
|
||||
| A103-4 | 付款处理查询（回填实付款记录） | 定时回写任务 |
|
||||
| A102-2 | 财务应付单保存 | 正式结算单「同步金蝶」 |
|
||||
| A102-4 | 财务应付单查询（防重预检 / 反查） | 推送前预检、下推反查付款计划分录 |
|
||||
| A902 | 附件上传 | 主单推送成功后联带上传 |
|
||||
| lockBusiData | 金蝶单据锁定 | 推送成功事务提交后 |
|
||||
|
||||
## 二、涉及的主要代码与数据表
|
||||
|
||||
### 后端（tms-api / blade-transport）
|
||||
|
||||
| 内容 | 位置 |
|
||||
|---|---|
|
||||
| 预结算单 | `controller/PreSettlementController.java`、`service/impl/PreSettlementServiceImpl.java` |
|
||||
| 付款申请 | `controller/PaymentApplicationController.java`、`service/impl/PaymentApplicationServiceImpl.java` |
|
||||
| 正式结算单 | `controller/FormalSettlementController.java`、`service/impl/FormalSettlementServiceImpl.java` |
|
||||
| 项目预付核销 | `service/impl/SettlementProjectAdvanceWriteOffServiceImpl.java` |
|
||||
| 金蝶同步支撑 | `support/KingdeeApBillSyncSupport.java`（A102-2/A102-4）、`service/impl/KingdeeBillLockServiceImpl.java`（锁单）、`KingdeeAttachmentSyncServiceImpl.java`（附件） |
|
||||
| 审批后自动推送 | `listener/KingdeeApprovalSyncListener.java`（AFTER_COMMIT）+ `event/KingdeeBillApprovedEvent.java` |
|
||||
| 定时任务 | `task/PaymentKingdeeResultTask.java`（付款结果回写，每 10 分钟）、`task/KingdeeAutoSyncRetryTask.java`（失败重推，每 10 分钟）、`task/KingdeeBillLockRetryTask.java`（补锁） |
|
||||
|
||||
### 前端（tms-erp-web）
|
||||
|
||||
| 页面 | 位置 |
|
||||
|---|---|
|
||||
| 预结算单列表/表单 | `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` |
|
||||
| API 层 | `src/api/settlement/preSettlement.js`、`src/api/settlement/formalSettlement.js`、`src/api/payment/paymentApplication.js` |
|
||||
|
||||
### 核心数据表（实体）
|
||||
|
||||
| 表/实体 | 作用 |
|
||||
|---|---|
|
||||
| `PreSettlement`（预结算单） | 含预付汇总字段 `advanceNo / advanceAppliedAmount / advancePaidAmount`、`formalSettlementNo` |
|
||||
| `PreSettlementAdvance`（预结算预付记录） | 预付台账：`advanceNo`（=付款申请单号）、`appliedAmount / paidAmount / billStatus(reviewing/approved/paid/voided) / kingdeeAdvanceNo` |
|
||||
| `PaymentApplication`（付款申请） | `paymentType`：`progress_advance` 进度预付 / `project_advance` 项目预付 / `settlement_payment` 尾款付款；`kingdeeStatus`：`unsynced/synced/paying/paid/closed/failed` |
|
||||
| `PaymentApplicationSettlement` | 付款申请 ↔ 结算单（正式/预结算）多选关系及分摊金额 |
|
||||
| `PaymentApplicationRecord` | 付款记录（金蝶 A103-4 回填，`voucherJson` 留档凭证号/银行流水/电子回单） |
|
||||
| `FormalSettlement`（正式结算单） | 含 `appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus / kingdeeSyncStatus` |
|
||||
| `FormalSettlementSource` | 正式结算单来源预结算单/明细快照，冗余预付汇总 |
|
||||
| `FormalSettlementPayment` | 正式结算单付款记录（尾款 `paymentType=final`） |
|
||||
| `SettlementProjectAdvanceWriteOff` | 项目预付核销记录（`settlementType`：PRE/FORMAL） |
|
||||
|
||||
## 三、阶段详解
|
||||
|
||||
### 阶段一：前置 —— 预结算单审批通过
|
||||
|
||||
- 前端：预结算列表新建/编辑 → 保存草稿 → 提交 → 审批通过（`pre-settlement.vue`，API `/blade-transport/pre-settlement/save|submit|approve`）。
|
||||
- 后端：`PreSettlementController` → `PreSettlementServiceImpl.saveDraft / submit / approve`。
|
||||
- 审批通过（`approved`）后，**应付（payable）**预结算单即可发起预付。
|
||||
|
||||
### 阶段二：发起预付（进度预付）
|
||||
|
||||
1. **前端入口**：预结算列表勾选 →「预付申请」按钮。前端校验：同一合同、`approved`、`payable`、未转正式结算（`pre-settlement.vue` `handleAdvanceApplication`）。
|
||||
2. **跳转付款申请表单** `/payment/payment-application/form?paymentType=progress_advance&preSettlementIds=...`（并非直接建预付单）。
|
||||
3. **表单**（`payment-application-form.vue`）：
|
||||
- 进度预付仅可关联预结算单；不展示发票信息与付款记录；
|
||||
- 可付金额实时调 `/payment-application/reference-amount` = 结算金额 − 累计已申请 − 项目预付核销额。
|
||||
4. **后端**（`PaymentApplicationServiceImpl`）：
|
||||
- `saveDraft`：生成 `FKD+日期+序号` 单号；`fillReference` 回填预结算关联；保存 `PaymentApplicationSettlement` 关系表；
|
||||
- `submit`：`draft/returned → reviewing`（财务审核）；
|
||||
- `approve`：`→ approved`，刷新关联结算单付款汇总，**发布 `KingdeeBillApprovedEvent`**。
|
||||
|
||||
> 说明：`PreSettlementController` 上的 `/apply-advance`、`/update-advance-paid`、`/void-advance` 为遗留接口，前端已不再调用；`PreSettlementAdvance` 台账现由付款申请流程联动维护（见阶段三/四）。
|
||||
|
||||
### 阶段三：同步金蝶（A103-3 预付款直推）
|
||||
|
||||
- 审批事务 **AFTER_COMMIT** → `KingdeeApprovalSyncListener.pushPayment`（Nacos 开关 `thirdParty.bfi.autoSync.payment`）→ `paymentApplicationService.syncKingdee`。
|
||||
- `doSyncKingdee`：预付款走 **A103-3 直接保存金蝶付款申请单（不绑应付单）**；推送前 A103-2 幂等预检防重复；成功后落 `kingdeeStatus=synced` + `kingdeeBillId` → **lockBusiData 锁单** → A902 附件上传。
|
||||
- **提前建档**：`syncPreSettlementAdvance(entity, approved)` —— 按付款申请号在 `PreSettlementAdvance` 生成预付记录（`advanceNo = FKD 单号`），刷新预结算单预付汇总（`advanceNo / advanceAppliedAmount / advancePaidAmount`），并联动刷新关联正式结算单付款汇总（预付信息两边页面即时可见）。
|
||||
- **失败兜底**：`markKingdeeSyncFailed` 落 `failed`；`KingdeeAutoSyncRetryTask` 每 10 分钟自动重推；页面「同步金蝶」按钮手动兜底。审批接口通过 `pollSyncFailure()` 将推送失败原因以警告文案带回前端（审批结果不受推送影响）。
|
||||
|
||||
### 阶段四：金蝶付款 + 结果回写（付款之后）
|
||||
|
||||
定时任务 `PaymentKingdeeResultTask`（每 10 分钟，分布式锁 single-flight）→ `syncKingdeePaymentResult`：
|
||||
|
||||
1. **A103-2 付款申请单查询**：按 `paymentNo`（防重键）分批查询，回填金蝶单号、状态（`synced → paying → paid/closed`）、已付金额（分录 `e_paidamt` 汇总）。
|
||||
2. **付款完成（paid）联动**：`syncPreSettlementAdvance(paid, 全额)` 置预付记录为已付。
|
||||
3. **A103-4 付款处理查询**：回填付款记录 `PaymentApplicationRecord`——实付金额、付款日期、金蝶付款单号；凭证号/银行流水/电子回单整体存 `voucherJson` 留档追溯。
|
||||
4. **异常自愈**：A103-2 连续两轮查不到已推送单据（Redis 计数）→ 判定金蝶侧已反审核删除 → `unlockBill` 置 `failed`、清空金蝶单号/内码、**联动作废未付的预付记录**（已付事实不回退）；重推后重新建档。
|
||||
5. 前端可手动触发：付款申请页「回写金蝶付款结果」按钮 `/sync-kingdee-result`。
|
||||
|
||||
### 阶段五：预结算 → 正式结算单
|
||||
|
||||
- **前端**：预结算列表「尾款结算」→ 校验同项目、`approved` → 跳 `/settlement/formal-settlement/form` 携带预结算数据（`handleFormalSettlement`）。
|
||||
- **后端两条路**：
|
||||
1. **完整建单**：`FormalSettlementServiceImpl.saveDraft` —— 合并多张预结算单（`FormalSettlementSource`）或应收应付明细；**继承预付汇总**（`advanceAppliedAmount / advancePaidAmount`）；支持**项目预付核销** `replaceWriteOffs`（校验：同合同、审批通过、不超可核销余额、合计不超结算单金额）；单号 `ZJS...`。
|
||||
2. **轻量标记**：`PreSettlementController /formal-settlement` → `formalSettlement(id)` —— 预结算单回写 `formalSettlementNo`、源明细置 `formal_settled`；**前提：无在途预付申请**（存在 `reviewing/approved` 预付则拦截）。
|
||||
- **正式结算单审批**：草稿 → 提交 → `approve` → 事件 → `syncKingdee` → **A102-2 财务应付单**（A102-4 预检/反查防重，一张结算单一张应付单）→ 回写 `kingdeeSyncStatus` → 锁单 + 附件。
|
||||
- 列表展示「申请付款金额（含预付）/ 已收已付合计（含预付）」。
|
||||
|
||||
### 阶段六：尾款付款（正式结算单之后）
|
||||
|
||||
1. **前端**：正式结算单列表勾选（`approved`、`payable`、同合同）→「申请付款」→ 付款申请表单 `paymentType=settlement_payment`，默认取剩余可付金额（`openPaymentDialog`）。
|
||||
2. **后端**：`saveDraft` 支持一单挂多张正式结算单（同合同，按可付金额比例分摊）；`submit` 时 `validateNoTailPayment` 防重复尾款申请。
|
||||
3. **同步金蝶路由不同**：结算付款走 **A103-1 应付下推**——前置校验每张正式结算单已在金蝶生成财务应付单（A102-4 预检，未生成则提示"请先在正式付款单页面同步金蝶"），再下推生成金蝶付款申请单；之后锁单、附件同前。
|
||||
4. **回写后**：paid 时 `syncFormalSettlementPayments` 按关系表分摊生成 `FormalSettlementPayment(paymentType=final)` → `refreshPaymentSummary` 重算结算单 `appliedPaymentAmount / paidAmount / remainingPayableAmount / paymentStatus`（unpaid → partial → paid）。金额后续差异走**结算调整单**。
|
||||
|
||||
### 项目预付线（project_advance）
|
||||
|
||||
- 付款申请页「预付申请」按钮 → `project_advance`：选**项目 + 承运商合同**（仅承运商合同），不挂结算单、无发票/付款记录。
|
||||
- `validateQuota` 校验：项目额度（`fundLimit` + 有效期内审批通过的临时额度）、客户额度（`maxCreditLimit`）。
|
||||
- 审批 → A103-3 直推 → 金蝶付款 → 回写 paid。
|
||||
- **后续核销**：预结算单/正式结算单表单中「项目预付核销」组件 → 保存时 `replaceWriteOffs` 写 `SettlementProjectAdvanceWriteOff`；可付金额计算统一扣减核销额（`referenceAmount`）。
|
||||
- 金蝶侧预付抵扣字段（`y_billtype / y_billid / y_settleamt`）**TODO 本期不传**（`KingdeeApBillSyncSupport`，待业务确认后迭代）。
|
||||
|
||||
## 四、逆向流程
|
||||
|
||||
| 操作 | 规则 |
|
||||
|---|---|
|
||||
| 付款申请作废（仅 approved） | 金蝶锁单中禁止作废（`checkEditable`）；汇票付款释放票据余额；**联动作废未付的预付记录**（已付事实不回退）；刷新结算单汇总 |
|
||||
| 预结算单作废 | 存在关联预付申请需先作废预付 |
|
||||
| 预付记录作废 | 已付款的不能作废 |
|
||||
| 金蝶反审核（解锁） | A103-2 连续两轮消失自动解锁置 `failed`，人工核实后重推；解锁时原金蝶单号/内码留档清空，重推生成新单后重新关联附件与预付记录 |
|
||||
|
||||
## 五、遗留接口说明
|
||||
|
||||
`PreSettlementController` 的以下接口前端已不再调用（前端统一走付款申请单流程），`PreSettlementAdvance` 表改由付款申请联动维护，保留兼容：
|
||||
|
||||
- `POST /pre-settlement/apply-advance`（发起预付申请）
|
||||
- `POST /pre-settlement/update-advance-paid`（回写预付付款金额）
|
||||
- `POST /pre-settlement/void-advance`（作废预付申请）
|
||||
|
||||
如需下线，需另行评估权限与存量数据兼容性。
|
||||
|
||||
## 六、风险与未覆盖范围
|
||||
|
||||
- 应收侧预收/收款认领（ReceiptClaim）流程未在本篇展开。
|
||||
- 汇票付款（BillPayment）仅提及票据余额占用/释放联动。
|
||||
- 金蝶 A102/A103 接口报文字段细节未逐项列出，参见 `KingdeeApBillSyncSupport`、`PaymentApplicationServiceImpl.pushBfiPayApply / pushBfiPayApplyPush` 源码注释。
|
||||
@@ -0,0 +1,279 @@
|
||||
# 预付转正式结算单与项目预付操作手册（纯操作·带状态）
|
||||
|
||||
> 整理日期：2026-10-18
|
||||
> 定位：**给操作者和实施/培训用的纯操作手册**。只讲"在哪个页面、点哪个按钮、填什么、会看到什么状态"，不含接口、表名、代码。
|
||||
> 配套逻辑说明见同目录《2026-10-18-预付转正式结算单与项目预付操作流程说明（分场景·前端后端）.md》。
|
||||
|
||||
---
|
||||
|
||||
## 一、先认状态（每个场景都对着这几张表看）
|
||||
|
||||
### 1.1 单据审批状态（所有单据通用）
|
||||
|
||||
```
|
||||
新建/保存 ──→ 草稿 ──提交──→ 审批中 ──通过──→ 审批通过
|
||||
↑ │
|
||||
│ 驳回
|
||||
└── 已驳回 ←────┘ （改完再提交）
|
||||
|
||||
草稿 / 审批中 / 审批通过 ──(可作废时)──→ 已作废（终态）
|
||||
```
|
||||
|
||||
| 状态 | 能做什么 |
|
||||
|---|---|
|
||||
| 草稿 | 编辑 / 删除 / 提交 |
|
||||
| 已驳回 | 编辑（保存后回到草稿）/ 提交 |
|
||||
| 审批中 | 通过 / 驳回（审批人操作） |
|
||||
| 审批通过 | 看后续：同步金蝶、付款申请、开票申请、作废（未锁定时） |
|
||||
| 已作废 | 终态，只读 |
|
||||
|
||||
### 1.2 付款申请的金蝶状态
|
||||
|
||||
```
|
||||
未同步 ──推送──→ 已同步 ──→ 付款中 ──→ 已付款
|
||||
│ │
|
||||
└────────── 生成失败（可重推） └──→ 已关闭
|
||||
```
|
||||
|
||||
- **已付款**：钱已付出。**项目预付只有到"已付款"才能在结算单上核销**。
|
||||
- **生成失败**：系统每 10 分钟自动重推；也可在列表勾选后点「批量同步」手动重推。
|
||||
|
||||
### 1.3 正式结算单上的四个状态
|
||||
|
||||
| 状态位 | 取值 | 看什么 |
|
||||
|---|---|---|
|
||||
| 审批状态 | 草稿 / 审批中 / 审批通过 / 已驳回 / 已作废 | 单据走到哪一步 |
|
||||
| 金蝶同步状态 | 未同步 / 已同步 / 同步失败 | 有没有在金蝶生成应付单（应付）/应收单（应收） |
|
||||
| 收付款状态 | 未收/付款 / 部分收/付款 / 已收/付款 | 收付进度（**已含预付、核销**） |
|
||||
| 发票状态 | 应付=未收票/部分收票/已收票；应收=未开票/部分开票/已开票 | 票开/收到哪一步 |
|
||||
|
||||
### 1.4 金蝶锁定状态
|
||||
|
||||
| 显示 | 含义 | 影响 |
|
||||
|---|---|---|
|
||||
| 锁定中 | 正在向金蝶加锁 | 稍等 |
|
||||
| 已锁定 | 金蝶已锁 | **不可编辑、不可作废** |
|
||||
| 锁定失败·补偿中 / 已达上限 | 加锁未成功 | 定时自动补偿；必要时联系管理员 |
|
||||
|
||||
### 1.5 开票申请的金蝶状态
|
||||
|
||||
```
|
||||
未同步 ──推送──→ 已同步 ──金蝶回写──→ 开票完成
|
||||
│
|
||||
└── 生成失败（可重推）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、应付侧操作（钱付出去）
|
||||
|
||||
### 场景 1：预结算单直接发起「进度预付」
|
||||
|
||||
**前提**：预结算单是**应付**、状态**审批通过**、还没转正式结算。
|
||||
|
||||
1. 进「**预结算单**」列表，勾选预结算单（**同一合同**可多选）。
|
||||
2. 点工具栏「**预付申请**」。
|
||||
3. 自动跳到「付款申请」页面（类型已固定为进度预付）：结算单只读，"结算金额/可付款金额"自动带出。
|
||||
4. 填「申请付款金额」（不超过可付款金额）、「付款方式」→「保存」。
|
||||
5. 回到「付款申请」列表 → 找到该单 →「**提交**」。
|
||||
6. 审批人点「**通过**」。
|
||||
|
||||
**状态变化**：付款申请 `草稿 → 审批中 → 审批通过`；随后系统自动推金蝶，金蝶状态 `未同步 → 已同步 → 已付款`。
|
||||
**同时发生**：预结算单上出现「申请预付金额 / 已预付金额」；预结算单仍然可以继续「尾款结算」。
|
||||
|
||||
> 若提交/通过后看到黄色警告写着金蝶推送失败：审批结果**不受影响**，稍后自动重推，或到付款申请列表点「批量同步」。
|
||||
|
||||
---
|
||||
|
||||
### 场景 2：发起「项目预付」（不挂结算单）
|
||||
|
||||
**前提**：项目已建、**承运商合同**已建；金额不超过项目额度与客户额度。
|
||||
|
||||
1. 进「**付款申请**」列表 → 点工具栏「**预付申请**」（注意：这个入口是从付款申请页进的，和场景 1 从预结算单进不同）。
|
||||
2. 页面类型已固定为项目预付，填写：
|
||||
- **所属项目**（必选）
|
||||
- **合同名称**（必选，**只能选承运商合同**，选了项目后才能选）
|
||||
- 申请付款金额、付款方式、付款方/收款方等
|
||||
- 本类型不挂结算单，不显示发票信息与付款记录
|
||||
3. 「保存」→ 列表「提交」→ 审批人「通过」。
|
||||
|
||||
**会被拦截的情况**：
|
||||
- "申请付款金额不能超过项目额度"（项目额度 = 项目额度 + 有效期内的临时额度）
|
||||
- "申请付款金额不能超过客户额度"
|
||||
|
||||
**状态变化**：同场景 1。**务必等到金蝶状态「已付款」**，否则下一步核销做不了。
|
||||
|
||||
---
|
||||
|
||||
### 场景 3：结算单上「项目预付核销」
|
||||
|
||||
**前提**：有一笔**已付款**的项目预付（金蝶状态=已付款），且与本次结算单**同一合同**，还有剩余可核销金额。
|
||||
|
||||
1. 打开结算单（**预结算单**或**正式结算单**都行）的编辑页。
|
||||
2. 找到「**项目预付核销**」分区 → 点「**选择**」。
|
||||
3. 弹窗「选择项目预付单」里勾选要抵扣的预付单（已选的会灰掉，不能重复选）→「确定」。
|
||||
4. 在「本次核销金额」列：默认已按"可核销金额"填满，可以改小。
|
||||
5. 「保存」。
|
||||
|
||||
**会被拦截的情况（提示文案）**：
|
||||
- "预付单 XXX 本次核销金额必须大于 0"
|
||||
- "本次核销金额不能超过可核销金额"
|
||||
- "项目预付核销合计不能超过结算单金额"
|
||||
- "仅可选择审核通过的项目预付单"
|
||||
- "预付单 XXX 尚未付款，项目预付须金蝶付款完成后方可核销"
|
||||
- "同一项目预付单不可重复核销"
|
||||
- "项目预付单与结算单合同不一致"
|
||||
|
||||
**状态变化**：结算单「**已付金额（含预付、核销）**」立刻增大，「剩余未付金额」减小；列表上"申请付款金额（含预付）/已收已付合计（含预付）/剩余可付/收付款状态"同步变化。
|
||||
|
||||
---
|
||||
|
||||
### 场景 4：预结算单转「正式结算单」（容纳预付）
|
||||
|
||||
**前提**：预结算单**审批通过**，且**同一项目**。
|
||||
|
||||
1. 进「**预结算单**」列表，勾选（可多选，须同项目）→ 点工具栏「**尾款结算**」。
|
||||
2. 系统跳到「正式结算单」新增页，把所选预结算单的明细、费用项合并进来。
|
||||
3. 检查三处金额（**应付结算单才有**）：
|
||||
- **结算合计（原金额）**：费用合计，**始终全额**，不会因为预付/核销而变小；
|
||||
- **已付金额（含预付、核销）**：把来源预结算的已付预付 + 本次核销都算进去；
|
||||
- **剩余未付金额** = 结算合计 − 已付。
|
||||
4. 「项目预付核销」区会**自动带出来源预结算上已核销的行**，可增/删/改金额。
|
||||
5. 「保存」（草稿）→「提交」→ 审批人「通过」。
|
||||
|
||||
**状态变化**：正式结算单 `草稿 → 审批中 → 审批通过`；预结算单会被标记为已转正式结算（来源被锁定）。
|
||||
**注意**：如果预结算单上还有**审批中或已审批但没结束的预付申请**，走"轻量转正式"会被拦住，需要先把预付处理完。
|
||||
|
||||
---
|
||||
|
||||
### 场景 5：正式结算单「同步金蝶」
|
||||
|
||||
**前提**：结算单**审批通过**。
|
||||
|
||||
1. 进「**正式结算单**」列表，切到「**应付**」页签。
|
||||
2. 勾选 **1 条**（按钮只允许选一条）→ 点工具栏「**同步金蝶**」。
|
||||
3. 成功后会提示"同步成功，金蝶单据号：XXX"；列表「金蝶同步状态」变为**已同步**，「金蝶锁定状态」变为**已锁定/锁定中**。
|
||||
|
||||
**生成失败怎么办**：列表金蝶状态显示"同步失败"，重新点「同步金蝶」即可。
|
||||
**提示"该单附件未全部上传，可重推补传"**：单据已同步成功，附件稍后重推会自动补传。
|
||||
|
||||
> 审批通过时系统也会自动推一次；若失败，只弹黄色警告，审批照样通过，按上面手动补推。
|
||||
|
||||
---
|
||||
|
||||
### 场景 6：正式结算单「付款申请」（付尾款）
|
||||
|
||||
**前提**：正式结算单是**应付**、**审批通过**、**同一合同**、还有剩余可付金额。
|
||||
|
||||
1. 「正式结算单」列表（应付）→ 勾选 1 条或多条（同合同）→ 工具栏「**付款申请**」。
|
||||
2. 弹窗里确认各单的「申请付款金额」（默认已填=剩余可申请金额，**已扣掉核销**）→「提交」。
|
||||
3. 到「付款申请」列表「提交」→ 审批人「通过」。
|
||||
|
||||
**会被拦截的情况**：
|
||||
- "仅审批通过的应付正式结算单允许发起付款申请"
|
||||
- "付款申请必须选择同一个合同的正式结算单"
|
||||
- 提示需要先在正式结算单页面同步金蝶（说明该单在金蝶还没有应付单，尾款是从应付单下推的，**必须先做场景 5**）
|
||||
|
||||
**状态变化**：正式结算单「收付款状态」`未付款 → 部分付款 → 已付款`，金额按付款结果自动重算。
|
||||
**金额错了怎么办**：正式结算单**审批通过后不能直接改金额**，走「**结算调整单**」（见《2026-10-17-结算调整单操作流程说明（分场景）.md》）。
|
||||
|
||||
---
|
||||
|
||||
## 三、应收侧操作（票开出去）
|
||||
|
||||
### 场景 7：应收正式结算单「同步金蝶」
|
||||
|
||||
1. 「正式结算单」列表切到「**应收**」页签 → 勾选 1 条 → 工具栏「**同步金蝶**」。
|
||||
2. 列表「金蝶同步状态」变**已同步**，可见金蝶单据号。
|
||||
|
||||
**必须做这一步**：正式结算单开票要求先有金蝶应收单，没做这步，开票申请推不出去。
|
||||
|
||||
---
|
||||
|
||||
### 场景 8：创建并推送「开票申请」
|
||||
|
||||
**前提**：有一张**应收**正式结算单，**审批通过**、未作废、发票状态还是「**未开票**」，且已完成场景 7。
|
||||
|
||||
1. 进「**开票申请**」列表 → 点「**新增**」。
|
||||
2. 「开票基本信息」里点「结算单」右侧的「**选择**」→ 弹窗「选择应收正式结算单」→ 搜索并勾选 →「确定」。
|
||||
- 「项目」「开票单位」自动带出；「**可开票金额**」= 所选结算单剩余可开票额之和。
|
||||
- 受票方开票信息按客商档案自动带出。
|
||||
3. 填「发票类型」等；选**电子专票**时，纳税人识别号、开户行、开户账号、注册地址**必填**。
|
||||
4. 填「开票内容」（发票张次 + 商品行），系统自动算「**本次开票金额**」。
|
||||
5. 在「结算信息」表里给每张结算单填「**分摊开票金额**」（不超过该单剩余可开票金额）。
|
||||
6. 「开票明细」里勾选明细 →「保存」→「提交」→ 审批人「通过」。
|
||||
|
||||
**会被拦截的情况**：
|
||||
- "只能选择审批通过、未作废、未收票的应收正式结算单"
|
||||
- "结算单 XXX 的分摊金额超过剩余可开票金额"
|
||||
- "本次开票金额必须大于 0"
|
||||
- "请选择受票方有效的开票信息"
|
||||
- "未找到正式结算单受票方对应的客商档案"
|
||||
|
||||
**状态变化**
|
||||
| 对象 | 状态变化 |
|
||||
|---|---|
|
||||
| 开票申请 | 审批 `草稿 → 审批中 → 审批通过`；金蝶 `未同步 → 已同步 → 开票完成` |
|
||||
| 来源正式结算单 | 发票状态 `未开票 → 部分开票 → 已开票`（按分摊与回写自动算） |
|
||||
|
||||
**看发票结果**：开票申请详情页的发票信息里能看到发票号、开票日期、价税合计、发票文件。金蝶回写是定时的，没出来可以先等，或在开票申请列表点「**批量同步**」推一把。
|
||||
|
||||
**限制**：开票申请一旦推到金蝶（已同步/开票完成）就**锁定不能改**；数电票已经开出来的只能走红冲，不能在本系统作废。**预付和核销不影响开票金额**，开票始终按结算单的**全额**来匹配。
|
||||
|
||||
---
|
||||
|
||||
## 四、作废与撤销：能做什么、状态怎么变
|
||||
|
||||
| 我想…… | 前提 | 操作位置 | 状态变化 |
|
||||
|---|---|---|---|
|
||||
| 作废付款申请 | 状态=审批通过，且**未被金蝶锁定** | 付款申请列表「作废」 | 单据→已作废；**未付的预付记录联动作废，相关核销行被删除**，受影响结算单的已付金额回落（已付出去的钱不会回退） |
|
||||
| 作废正式结算单 | 未审批通过，或审批通过但**未锁定** | 正式结算单列表「作废」 | 单据→已作废；本单的核销行被删除，可核销额度释放 |
|
||||
| 作废预结算单 | 无关联预付申请（有则先作废预付） | 预结算单列表「作废」 | 单据→已作废；预结算上的核销行被删除 |
|
||||
| 作废开票申请 | 状态=审批通过，且**未锁定**（即还没推金蝶/还没开票） | 开票申请列表「作废」 | 单据→已作废 |
|
||||
| 删除 | 状态=草稿 | 各列表「删除」 | 草稿被删除 |
|
||||
| 金蝶侧反审核删单 | — | 金蝶操作后由系统处理 | 付款申请金蝶状态→生成失败，金蝶单号被清空；**未付的预付记录联动作废**；人工核实后重推，重推成功会重新建档；**已核销的行不会自动删**，需要人工作废该预付款才回落 |
|
||||
|
||||
> 一句话记住：**预付一旦真付出去（已付款），作废不会把钱退回**，只会把台账和核销额度清掉。
|
||||
|
||||
---
|
||||
|
||||
## 五、操作者常见疑问
|
||||
|
||||
| 问题 | 答案 |
|
||||
|---|---|
|
||||
| 为什么选不到某张预结算单发起预付？ | 需要**应付**、**审批通过**、**未转正式结算**、且所选单据**同一合同**。 |
|
||||
| 为什么核销弹窗里找不到那笔项目预付？ | 它必须已**金蝶付款完成（已付款）**，且与结算单**同一合同**、还有剩余可核销额。 |
|
||||
| 为什么新增开票申请时选不到某张应收结算单？ | 需要**审批通过、未作废、发票状态=未开票**；已被别的开票申请占用的会扣掉可开票额。 |
|
||||
| 开票提示要先去同步金蝶？ | 正式结算开票前，必须先在该应收结算单上点「同步金蝶」生成金蝶应收单。 |
|
||||
| 付款申请审批通过了，但金蝶那边没有单？ | 看金蝶状态：若"生成失败"，点「批量同步」重推或等自动重推。 |
|
||||
| 结算单已付金额比我算的多/少？ | 已付金额**含**进度预付、项目预付核销；核销金额同时计入"已付"和"剩余可付"的计算，属正常口径。 |
|
||||
| 结算单金额写错了怎么改？ | 审批通过后不能直接改，走「结算调整单」。 |
|
||||
| 单据上的「作废」是灰的？ | 可能已被金蝶锁定，或状态不满足（只有审批通过且未锁定才能作废）。 |
|
||||
|
||||
---
|
||||
|
||||
## 六、一眼看懂整个流程（操作版）
|
||||
|
||||
```
|
||||
【应付·进度预付】
|
||||
预结算单(审批通过) →「预付申请」→ 付款申请(提交→通过) → 金蝶付款(已付款)
|
||||
└ 预结算单出现"已预付金额"
|
||||
|
||||
【应付·项目预付】
|
||||
付款申请页「预付申请」→ 选项目+承运商合同 → 提交→通过 → 金蝶付款(已付款)
|
||||
|
||||
【预结算 → 正式结算（容纳预付）】
|
||||
预结算单(审批通过·同项目) →「尾款结算」→ 正式结算单
|
||||
结算合计(全额) / 已付(含预付、核销) / 剩余未付
|
||||
项目预付核销自动带入 → 保存 → 提交 → 通过
|
||||
└ 「同步金蝶」(应付单已同步)
|
||||
|
||||
【应付·尾款】
|
||||
正式结算单(应付·审批通过) →「付款申请」→ 付款申请 → 金蝶应付下推 → 已付款
|
||||
└ 结算单收付款状态：未付款 → 部分付款 → 已付款
|
||||
|
||||
【应收·开票】
|
||||
应收正式结算单(审批通过·未开票) →「同步金蝶」(应收单已同步)
|
||||
→「开票申请」新增 → 选结算单 → 填开票内容与分摊 → 提交 → 通过
|
||||
→ 金蝶开票(已同步 → 开票完成) → 结算单发票状态：未开票 → 部分开票 → 已开票
|
||||
```
|
||||
@@ -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）与收票流程未在本文展开。
|
||||
@@ -0,0 +1,116 @@
|
||||
# 开票申请支持结算单重复选择与累计额度控制改造说明
|
||||
|
||||
> 日期：2026-10-19
|
||||
> 模块：收款付账管理 / 开票管理（开票申请）
|
||||
> 涉及工程：`tms-api`（blade-transport）、`tms-erp-web`
|
||||
> 关联功能说明：支持多张结算单合并开票、一张结算单拆分多张发票；审批通过后同步金蝶；单据留痕。
|
||||
|
||||
---
|
||||
|
||||
## 一、背景与现状问题
|
||||
|
||||
开票申请原实现中，选单弹窗与保存校验都要求结算单处于"未收票"（`unreceived`）状态：
|
||||
|
||||
1. 前端选单请求写死 `invoiceStatus: 'unreceived'`；
|
||||
2. 后端候选接口按 `invoice_status = 'unreceived'` 过滤；
|
||||
3. 保存校验：新建申请时若结算单状态不是 `unreceived` 直接报"只能选择审批通过、未作废、未收票的应收正式结算单"；
|
||||
4. 开票申请**保存草稿**时即回写结算单发票状态（`refreshSettlementInvoiceStatus`），状态变为"部分开票 / 全额开票"。
|
||||
|
||||
**结果**：结算单 001、002 在第一张开票申请保存后状态不再是"未收票"，开第二张票时弹窗查不到、后端也拦截，**一张结算单无法拆分多次开票**，与功能说明中"一张结算单拆分多张发票"不符。
|
||||
|
||||
同时原"分摊发票金额"依赖用户手填，且存在口径不一致：单选结算单时自动填满剩余额度（即使本次只开一部分），多选时全部填 0（不占用），累计额度控制实际失效。
|
||||
|
||||
## 二、改造方案（自动分摊口径）
|
||||
|
||||
核心思路：**放开"未收票"过滤让结算单可重复选；"累计开票金额不超结算单金额"由后端按本次开票金额自动分摊登记占用**，复用既有的剩余额度计算与状态回写链路。
|
||||
|
||||
### 2.1 核心规则
|
||||
|
||||
| 规则 | 说明 |
|
||||
| --- | --- |
|
||||
| 可开票金额（剩余） | `结算单总金额 − Σ分摊发票金额`，其中分摊金额只统计**未作废、未删除**的开票申请（`availableAmount`，编辑时排除本申请自身） |
|
||||
| 可选结算单范围 | 审批通过 + 未作废 + 启用 + **剩余可开票金额 > 0** 的应收正式结算单；不再限制"未收票"。开满的（剩余额度为 0）自动从弹窗消失 |
|
||||
| 自动分摊 | 保存申请（含草稿）时，后端将**本次开票金额**（开票内容商品行含税金额合计）按结算单选择顺序**逐单填满**：每单分摊 `min(该单剩余可开票金额, 尚未摊完的金额)`，分摊结果写入关联表 `allocated_invoice_amount` |
|
||||
| 整体兜底校验 | 摊不完（本次开票金额 > Σ剩余可开票金额）时保存报错："本次开票金额不能超过可开票金额"，草稿与提交均生效 |
|
||||
| 结算单发票状态 | 保存/删除/作废申请时自动刷新：占用 ≤ 0 → 未收票；0 < 占用 < 总金额 → 部分开票；占用 = 总金额 → 全额开票（`refreshSettlementInvoiceStatus`，本次未改动） |
|
||||
| 额度释放 | 删除草稿、作废申请时自动释放占用（既有逻辑，本次未改动） |
|
||||
|
||||
### 2.2 分摊示例
|
||||
|
||||
结算单 001 总金额 1000：
|
||||
|
||||
| 步骤 | 操作 | 分摊结果 | 001 状态 | 剩余可开票 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 第 1 张申请 | 选 001，本次开票 600 | 001 分摊 600 | 部分开票 | 400 |
|
||||
| 第 2 张申请 | 弹窗仍可选 001（显示已申请 600 / 可开票 400），本次开票 400 | 001 分摊 400 | 全额开票 | 0 |
|
||||
| 第 3 张申请 | 弹窗不再出现 001（剩余额度 0） | — | — | — |
|
||||
| 第 2 张申请被作废 | 释放 400 | 001 分摊余 600 | 部分开票 | 400 |
|
||||
|
||||
多张结算单（001 剩 1000、002 剩 500）本次开票 1200：001 分摊 1000、002 分摊 200；本次开票 1600 时摊不完，保存报错。
|
||||
|
||||
## 三、改动明细
|
||||
|
||||
### 3.1 后端（tms-api / blade-transport）
|
||||
|
||||
| 文件 | 改动 |
|
||||
| --- | --- |
|
||||
| `IInvoiceApplicationService.java` | `settlementCandidates` 签名删除 `invoiceStatus` 参数 |
|
||||
| `InvoiceApplicationController.java` | `/settlement-candidates` 删除 `invoiceStatus` 请求参数（原默认 `unreceived`） |
|
||||
| `InvoiceApplicationServiceImpl.java` `settlementCandidates` | 删除 `invoice_status = 'unreceived'` 过滤；"剩余可开票金额 > 0"过滤保留，兜住开满的结算单 |
|
||||
| `InvoiceApplicationServiceImpl.java` `settlementCandidateMap` | 候选行新增返回 `invoicedAmount`（已申请开票金额 = 结算总金额 − 剩余可开票） |
|
||||
| `InvoiceApplicationServiceImpl.java` `saveDraft` | ① 删除新建时 `unreceived` 状态硬校验，文案改为"只能选择审批通过、未作废的应收正式结算单"；② 先计算本次开票金额（`validateSheets`），再按 2.1 规则自动分摊并回写 `SettlementRow.allocatedInvoiceAmount`，摊不完报错。关联表保存（`saveRelations`）直接读取分摊结果，无需感知 |
|
||||
| `InvoiceApplicationServiceImpl.java` `detail` | 对已选结算单实时重算剩余可开票金额（`availableAmount` 排除本申请），避免编辑时展示保存时点的过期额度；批量查询结算单避免 N+1 |
|
||||
|
||||
### 3.2 前端（tms-erp-web / `src/views/payment/invoice-application-form.vue`）
|
||||
|
||||
| 位置 | 改动 |
|
||||
| --- | --- |
|
||||
| `loadSettlementCandidates` | 删除 `invoiceStatus: 'unreceived'` 参数 |
|
||||
| 选单弹窗 | 在"结算金额"与"可开票金额"之间新增"已申请开票金额"列（`invoicedAmount`）；"可开票金额"列原本已有 |
|
||||
| `applySettlements` | 选单后分摊金额统一默认 0（删除"单选自动填满剩余额度"逻辑），分摊由后端保存时自动计算 |
|
||||
| 结算信息表格 | "分摊发票金额"列改为只读展示（保存/详情返回的自动分摊结果），不再允许手填 |
|
||||
|
||||
提交前的整体校验"本次开票金额不能超过可开票金额"（`validateAvailableInvoiceAmount`）保留，用于提交时提前拦截；后端保存兜底，草稿同样受限。
|
||||
|
||||
## 四、操作说明
|
||||
|
||||
### 4.1 制单人：首张开票（含草稿）
|
||||
|
||||
1. 开票管理 → 开票申请 → 新增；
|
||||
2. 结算单"选择"：弹窗展示审批通过的应收正式结算单，可见**结算金额 / 已申请开票金额 / 可开票金额**三列，可多选合并开票（需同一合同、项目、组织及收付款方）；
|
||||
3. 勾选开票明细、维护开票内容商品行，本次开票金额由商品行含税金额自动求和；
|
||||
4. 保存/提交：系统自动把本次开票金额按选择顺序分摊到各结算单并登记占用，结算单状态刷新为"部分开票"或"全额开票"。
|
||||
|
||||
### 4.2 制单人：同一结算单拆分开第二张票（本次新增能力）
|
||||
|
||||
1. 再次新增开票申请，选单弹窗中**已开过票的结算单仍会出现**（只要还有剩余额度）；
|
||||
2. "可开票金额"列显示的即为剩余额度（总金额 − 已申请）；
|
||||
3. 本次开票金额超过剩余额度时，保存/提交均提示"本次开票金额不能超过可开票金额"，调低商品行金额后可正常保存；
|
||||
4. 开满后该结算单自动从弹窗消失。
|
||||
|
||||
### 4.3 编辑与释放
|
||||
|
||||
- 编辑已有申请：结算信息中"可开票金额"为实时剩余额度（已排除本申请自身占用），"分摊发票金额"为上次保存的自动分摊结果；再次保存时按新的本次开票金额重新分摊；
|
||||
- 删除草稿 / 作废申请：占用自动释放，对应结算单恢复可开额度并回刷发票状态。
|
||||
|
||||
## 五、兼容性与注意事项
|
||||
|
||||
| 项 | 说明 |
|
||||
| --- | --- |
|
||||
| 存量数据 | 历史"多选分摊=0"的申请未登记占用，其结算单会以"全额可开"出现在弹窗。如需严格口径，上线前可做数据订正：按未作废申请的 `invoice_amount` 回填关联表 `allocated_invoice_amount` 并刷新结算单状态；或明确存量不追溯 |
|
||||
| 草稿即占用 | 保存草稿即登记占用（与原行为一致），长期挂着的草稿会占住额度，需作废/删除释放 |
|
||||
| 明细不去重 | 同一结算单的运单明细可能被多张申请勾选，本次按金额总额控制，不按明细去重（需求未要求） |
|
||||
| 手填分摊失效 | `allocatedInvoiceAmount` 请求字段后端不再采信（自动覆盖），前端已改只读；如有第三方调用直接传该字段，行为变化需知悉 |
|
||||
| 金蝶同步 | 同步链路读取申请主表/商品行，未读取分摊字段，理论无影响；上线后建议回归一次"审批通过 → 同步金蝶"链路 |
|
||||
| 接口变更 | `/invoice-application/settlement-candidates` 删除 `invoiceStatus` 参数、响应新增 `invoicedAmount`，仅开票申请选单使用 |
|
||||
|
||||
## 六、验证清单
|
||||
|
||||
- [ ] 新增申请选择 001 开票 600，保存后 001 状态"部分开票"、已申请 600；
|
||||
- [ ] 第二张申请弹窗可选 001，可开票金额显示 400，已申请开票金额显示 600；
|
||||
- [ ] 第二张本次开票 500，保存报"本次开票金额不能超过可开票金额"；调为 400 保存成功，001 变"全额开票"；
|
||||
- [ ] 第三张申请弹窗不再出现 001；
|
||||
- [ ] 作废第二张申请后，001 恢复可开票 400、状态回到"部分开票"；
|
||||
- [ ] 多结算单合并开票：本次开票金额按顺序分摊到各单，结算信息表格展示各单分摊结果；
|
||||
- [ ] 编辑申请时"可开票金额"为实时额度（扣除其他申请占用、含本申请原分摊回退）；
|
||||
- [ ] 原有链路回归：审批流转、金蝶同步、批量同步状态、留痕记录。
|
||||
Reference in New Issue
Block a user