247 行
11 KiB
Markdown
247 行
11 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8127"
|
||
title: "应付款付款支持冲抵供应商预付款（差额付款 + 占用/付讫/回冲状态机）"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "not_required"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "d0a264ec33214617f5ee3ca500b0f9ebd76b4bb6"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-22"
|
||
status_note: "backend_status: deployed - hl-order-service-v3 已部署测试服（dev-v3，含 finance 同进程），E2E 全链路 PASS（改单加冲抵→审批→出纳差额付款，往来净额/预付余额/冲抵明细 SETTLED 全对，2026-09-22 取证）; gateway_status: not_required - 零网关改动，/admin/finance/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，后端不代填。 前端核验(2026-09-22): 已交付 hl-admin d0a264ec——payable.js 加 getOffsettablePrepayments+PREPAY_OFFSET_STATUS meta+4 写口 JSDoc(单笔 create 前端无调用方仅补文档);新共享组件 PrepayOffsetPicker(勾选+金额≤availableAmount+598812/598813 前置校验);PaymentDetailPanel 详情冲抵金额/实付金额+offsets 状态机明细卡、编辑草稿冲抵区块(回显仅 OCCUPYING,整体置换恒传,空数组清占用);GroupPayPanel 按供应商分组上送、SupplierPayPanel 单元素分组;出纳页零改动(#7815 锁 actualAmount 槽位);598812-598817 透 message;原型 pay-adv 冲抵记录子 tab 契约无列表读口,未造数留痕待后端;Vitest 23/23+checkpoint 全量 13 项全绿。"
|
||
updated_at: "2026-09-22"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 财务：应付款付款支持冲抵供应商预付款（Epic #8127）
|
||
|
||
> 应付款付款时可用「该供应商已付讫且有余额的预付款」冲抵，出纳只付差额现金。涉及 4 个建单/改单接口入参新增、付款单详情出参新增、新增 1 个可冲抵预付查询接口。
|
||
|
||
## ① 接口背景
|
||
|
||
供应商常有预付（先打款后结算）。此前预付款与应付款是两条独立线，应付款付款只能全额现金支出，无法用已预付的余额抵扣，资金占用高。本变更让应付款付款单可勾选「该供应商的预付款」做冲抵：冲抵部分无现金流出，出纳仅按「应付金额 − 冲抵金额 = 实付金额」付差额。
|
||
|
||
三个口径决策（后端已定）：
|
||
- **冲抵算 paid**：冲抵部分随现金一并计入应付台账已付，清偿方式不影响应付债务的付讫认定。
|
||
- **占用时点=建单时**：建单/改单（PENDING 草稿）即扣减预付可用余额并落「占用中」明细，驳回/删改草稿回冲，付讫转「已冲抵」。
|
||
- **往来差额归零**：付讫时补一对抵销分录，付款单文档净额=0、预付单文档净额=剩余可用余额，供应商往来对账自清。
|
||
|
||
## ② 变更清单
|
||
|
||
| 类型 | 接口 | 变更 |
|
||
|---|---|---|
|
||
| 修改 | `POST /admin/finance/payments` 创建付款单 | 入参新增 `prepayOffsets[]` |
|
||
| 修改 | `POST /admin/finance/payments/batch` 按订单批量创建 | 入参新增 `prepayOffsets[]`（按供应商分组） |
|
||
| 修改 | `POST /admin/finance/payments/batch-by-supplier` 按供应商合并创建 | 入参新增 `prepayOffsets[]`（按供应商分组） |
|
||
| 修改 | `PUT /admin/finance/payments/{id}` 编辑草稿 | 入参新增 `prepayOffsets[]`（整体置换语义） |
|
||
| 修改 | `GET /admin/finance/payments/{id}` 付款单详情 | 出参新增 `offsets[]`；`prepayOffsetAmount`/`actualPayAmount` 由恒 0 真值化 |
|
||
| 新增 | `GET /admin/finance/payments/offsettable-prepays` 可冲抵预付查询 | 新接口 |
|
||
|
||
## ③ 接口详情
|
||
|
||
### 3.1 新增：可冲抵预付查询
|
||
|
||
```
|
||
GET /admin/finance/payments/offsettable-prepays?supplierId={supplierId}
|
||
```
|
||
|
||
供付款申请页勾选「用哪笔预付冲抵」。返回该供应商下**已付讫（PAID）且可用余额 > 0** 的预付款，按付款日期升序。
|
||
|
||
### 3.2 创建/编辑付款单（冲抵）
|
||
|
||
在既有入参基础上加 `prepayOffsets`，提交即占用预付余额；不冲抵则该字段不传或传空数组（行为与旧版完全一致）。
|
||
|
||
### 3.3 付款单详情
|
||
|
||
详情返回本单的冲抵明细 `offsets[]` 及冲抵状态；`actualPayAmount`（实付）为出纳真正付现的金额。
|
||
|
||
## ④ 入参
|
||
|
||
### 4.1 `prepayOffsets[]`（创建/编辑付款单新增，可空）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `prepayId` | Long(string) | 是 | 预付款申请单 ID（须为本供应商 PAID 且余额充足） |
|
||
| `offsetAmount` | number | 是 | 该笔预付冲抵金额（>0，≤预付可用余额） |
|
||
|
||
> 批量接口（按订单批量/按供应商合并）按供应商分组传：`prepayOffsets: [{ supplierId, offsets: [{ prepayId, offsetAmount }] }]`。
|
||
> 编辑草稿为**整体置换语义**：传入的 `prepayOffsets` 全量替换旧占用（先回冲旧占用再按新入参重占）。
|
||
|
||
### 4.2 可冲抵预付查询入参
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `supplierId` | Long(string) | 是 | 供应商 ID（查询其可冲抵预付） |
|
||
|
||
## ⑤ 出参
|
||
|
||
### 5.1 付款单详情 `GET /admin/finance/payments/{id}`（新增/真值化字段）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `amount` | number | 应付金额（= Σ明细行，不随冲抵变化） |
|
||
| `prepayOffsetAmount` | number | **冲抵金额合计**（= Σoffsets.offsetAmount；原恒 0，本期真值化） |
|
||
| `actualPayAmount` | number | **实付金额 = amount − prepayOffsetAmount**（出纳按此现金付款；原恒等于 amount） |
|
||
| `offsets` | array | **本单冲抵明细列表**（新增，无冲抵时为 `[]`） |
|
||
|
||
`offsets[]` 元素：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `offsetId` | Long(string) | 冲抵明细 ID |
|
||
| `prepayId` | Long(string) | 预付款申请单 ID |
|
||
| `prepayNo` | string | 预付款单号（YF- 前缀） |
|
||
| `offsetAmount` | number | 该笔冲抵金额 |
|
||
| `status` | string | 冲抵状态：`OCCUPYING` 占用中 / `SETTLED` 已冲抵（付讫）/ `CANCELLED` 已取消（驳回/删改草稿回冲） |
|
||
| `settleTime` | string(datetime) | 付讫冲抵时间（仅 SETTLED 有值，否则 null） |
|
||
|
||
### 5.2 可冲抵预付查询 `offsettable-prepays` 出参（数组）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `prepayId` | Long(string) | 预付款申请单 ID |
|
||
| `prepayNo` | string | 预付款单号 |
|
||
| `amount` | number | 预付本金 |
|
||
| `availableAmount` | number | 可用余额（可被冲抵的上限） |
|
||
| `payDate` | string(date) | 付款日期 |
|
||
| `supplierId` | Long(string) | 供应商 ID |
|
||
| `supplierName` | string | 供应商名称 |
|
||
|
||
## ⑥ 枚举/数据字典
|
||
|
||
**冲抵明细状态 `offsets[].status`**：
|
||
|
||
| 值 | 含义 |
|
||
|---|---|
|
||
| `OCCUPYING` | 占用中（建单~付讫前） |
|
||
| `SETTLED` | 已冲抵（付讫，终态） |
|
||
| `CANCELLED` | 已取消（驳回/删草稿/改草稿回冲，留痕） |
|
||
|
||
`paymentType` 仍走既有 `fin_payment_type` 字典标签（住宿/门票·游玩/餐食/车辆/导游/摄影/保险/其他支出/退款/其他应付），本次未新增。
|
||
|
||
## ⑦ 错误码
|
||
|
||
| 码 | 语义 |
|
||
|---|---|
|
||
| 598812 | 冲抵入参非法（金额≤0 / 同一预付单重复传） |
|
||
| 598813 | 冲抵合计超应付金额（Σoffset > amount） |
|
||
| 598814 | 预付单不可用（不存在 / 非已付讫 / 可用余额不足 / 金额非法） |
|
||
| 598815 | 预付单冲抵单位与付款供应商不一致（跨供应商拦截） |
|
||
| 598816 | 预付可冲抵余额并发不足（CAS 扣减失败，整批回滚） |
|
||
| 598817 | 冲抵回冲账实不符（回冲 CAS 失败，fail-fast） |
|
||
|
||
## ⑧ 示例
|
||
|
||
### 8.1 典型：创建付款单并冲抵预付
|
||
|
||
请求 `POST /admin/finance/payments`：
|
||
|
||
```json
|
||
{
|
||
"supplierId": "2096854417461403650",
|
||
"payeeAccountId": "2096854417490763777",
|
||
"amount": 800.00,
|
||
"paymentType": "住宿",
|
||
"reason": "9月羊和远方住宿结算",
|
||
"orderId": "2100482290093039617",
|
||
"prepayOffsets": [
|
||
{ "prepayId": "2100473583917580290", "offsetAmount": 500.00 }
|
||
]
|
||
}
|
||
```
|
||
|
||
响应（`data.paymentId` 为新单 ID）。此时预付 `available_amount` 1000→500，`prepayOffsetAmount=500`、`actualPayAmount=300`，offset 行 `OCCUPYING`。
|
||
|
||
详情出参（付讫后）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"id": "2100485199803359234",
|
||
"paymentNo": "FK-202609170057",
|
||
"amount": 800.00,
|
||
"prepayOffsetAmount": 500.00,
|
||
"actualPayAmount": 300.00,
|
||
"status": "PAID",
|
||
"offsets": [
|
||
{
|
||
"offsetId": "2102204...",
|
||
"prepayId": "2100473583917580290",
|
||
"prepayNo": "YF-202609170002",
|
||
"offsetAmount": 500.00,
|
||
"status": "SETTLED",
|
||
"settleTime": "2026-09-22 09:15:35"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 边界：可冲抵预付查询
|
||
|
||
请求 `GET /admin/finance/payments/offsettable-prepays?supplierId=2096854417461403650`：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": [
|
||
{
|
||
"prepayId": "2100473583917580290",
|
||
"prepayNo": "YF-202609170002",
|
||
"amount": 1000.00,
|
||
"availableAmount": 500.00,
|
||
"payDate": "2026-09-17",
|
||
"supplierId": "2096854417461403650",
|
||
"supplierName": "呼伦贝尔羊和远方牧业有限公司"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
（该预付已被冲抵 500，故 `availableAmount` 由 1000 降为 500。）
|
||
|
||
### 8.3 异常：冲抵超应付 / 跨供应商
|
||
|
||
```json
|
||
{ "code": 598813, "message": "冲抵合计超应付金额", "success": false }
|
||
{ "code": 598815, "message": "预付单冲抵单位与付款供应商不一致", "success": false }
|
||
{ "code": 598814, "message": "预付单不可用（不存在/非已付讫/余额不足）", "success": false }
|
||
```
|
||
|
||
## ⑨ 业务边界
|
||
|
||
- **可冲抵资格**：预付单须 `status=PAID`（钱真出了）且 `availableAmount>0` 且其「冲抵单位」= 付款供应商；未付讫（APPROVED 未出钱）不可勾选。
|
||
- **出纳只付差额**：付款金额锁死 = `actualPayAmount`，冲抵部分无现金流出、无资金流水。
|
||
- **回冲时机**：仅 PENDING 草稿可编辑/删除；驳回（REJECTED）、删除、改草稿均回冲预付余额并置 offset 行 CANCELLED。**付讫（PAID）后无回冲**——已消耗预付不回退（供应商退回走退回形态，只退现金）。
|
||
- **台账外手工单**：无台账锚点的手工付款单同样支持冲抵，行级/头表回写跳过（WARN），不影响付款主流程。
|
||
|
||
## ⑩ 修改前后对比
|
||
|
||
| 项 | 修改前 | 修改后 |
|
||
|---|---|---|
|
||
| 付款方式 | 只能全额现金 | 可勾选预付冲抵，出纳付差额 |
|
||
| `prepayOffsetAmount` | 恒 0 | 真值化 = Σ冲抵 |
|
||
| `actualPayAmount` | 恒等于 amount | = amount − 冲抵 |
|
||
| 详情 `offsets` | 无 | 返回冲抵明细及状态机 |
|
||
|
||
## ⑪ 影响评估 / 回滚
|
||
|
||
- **向后兼容**：不冲抵（不传 `prepayOffsets` 或传空）时行为与旧版完全一致（offset=0、actualPay=amount），旧前端不感知。
|
||
- **回滚**：代码回滚即恢复全额现金逻辑；已产生的冲抵数据（fin_prepay_offset）保留不影响。
|
||
|
||
## ⑫ 注意事项
|
||
|
||
- 列表行 `PaymentRowRespVO` 暂未加 `prepayOffsetAmount`，列表「实付」列如需区分冲抵单，另提需求（详情已全量返回）。
|
||
- 冲抵不改变应付台账 `applied` 占用口径（建单占全额，付讫全额转 paid）。
|
||
|
||
## ⑬ 关联 / 联系人
|
||
|
||
- Issue：https://git.1814.love:8443/wx/HL/issues/8127
|
||
- PR：#8134（地基）/ #8144（建单链路）/ #8145（付讫+回冲）/ #8146（收尾）
|
||
- 负责人：yst
|