108 行
4.5 KiB
Markdown
108 行
4.5 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "finance-cashier-queue-amount-fee"
|
||
title: "出纳待付款队列补透出 amount 付款金额 + fee 手续费（列表金额列有值）"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "merged"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "98f6b17e69dcec0821bd5bc06497f4c379f0f4d5"
|
||
target_release: ""
|
||
verified_at: "2026-09-16"
|
||
status_note: "出纳待付款队列 GET /admin/finance/cashier/queue 出参两处补值（纯补值，无存量变更）：①amount 付款金额由恒 null 补为各线审批应付基准（此前从未映射，列表金额列全空）；②fee 手续费 NONBIZ 映实列、其余 5 线默认 0（前端实付=amount−fee 口径统一，避免 null 特判）。金额锁死 598610 走 actualAmount 侧不受影响。已合并 dev-v3（PR #7818），4 测试全绿无回归。；前端 hl-admin 98f6b17e 已实现：列表 amount/fee 列本就读该二字段自动有值；openPay 锁死金额摘 REIMBURSE 分叉六线统一取 actualAmount(=598610 基准),spec 11/11,checkpoint 全绿。"
|
||
updated_at: "2026-09-16"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 出纳待付款队列补透出 amount 付款金额 + fee 手续费
|
||
|
||
> **服务**: hl-order-service-v3（hl-finance 模块）
|
||
> **类型**: ✏️ 修改接口（**纯出参字段补值**，由 null → 有值，无存量字段/路径/语义变更，向后兼容）
|
||
> **日期**: 2026-09-16
|
||
> **接口**: `GET /admin/finance/cashier/queue`（出纳待付款队列，按 payType 路由）
|
||
> **关联**: Issue #7815 / PR #7818
|
||
|
||
---
|
||
|
||
## 🔴 一句话给前端
|
||
|
||
出纳待付款队列列表行的 `amount`（付款金额）和 `fee`（手续费）两个字段，**之前一直是 null，现在补上了值**。列表「金额」列请用 `amount` 渲染。
|
||
|
||
| 字段 | 之前 | 现在 |
|
||
|---|---|---|
|
||
| `amount` | 恒 null | 各线审批应付金额（有值） |
|
||
| `fee` | 恒 null | NONBIZ=实列值 / 其余 5 线=0 |
|
||
|
||
---
|
||
|
||
## 一、amount 字段口径（按 payType 分线）
|
||
|
||
`amount` = 该单的**审批应付金额**（金额列应显示的值），各线取值基准：
|
||
|
||
| payType | amount 取值 | 说明 |
|
||
|---|---|---|
|
||
| `NONBIZ` 业务外支出 | `amount` | 收支单应付金额 |
|
||
| `EXPENSE` 费用报销 | `payableAmt` | 审批应付（已含冲销借款差额） |
|
||
| `PAYMENT` 应付款 | `actualPayAmount` | 审批实付 |
|
||
| `PREPAY` 预付款 | `amount` | 预付金额 |
|
||
| `STAFF_LOAN` 员工借款 | `amount` | 借款金额 |
|
||
| `REIMBURSE` 报账款 | `settleAmount` | 结算金额=\|净额\|（推送时冻结） |
|
||
|
||
## 二、fee 字段口径
|
||
|
||
| payType | fee 取值 |
|
||
|---|---|
|
||
| `NONBIZ` | 实列值（登记付款时可填手续费率/手续费，公司额外承担） |
|
||
| 其余 5 线 | 恒 `0`（无手续费概念） |
|
||
|
||
## 三、三字段关系
|
||
|
||
```
|
||
actualAmount = amount − fee （实付）
|
||
```
|
||
|
||
- `amount`：应付金额（本金）
|
||
- `fee`：手续费（挂本单，公司额外承担）
|
||
- `actualAmount`：实付 = amount − fee（**金额锁死 598610 校验基准**，付款时入参 amount 须等于它）
|
||
|
||
> 对无手续费的 5 条线（fee=0）：`amount == actualAmount`，两值相等。
|
||
|
||
## 四、示例（队列行出参节选）
|
||
|
||
```json
|
||
{
|
||
"id": "2100084841021145090",
|
||
"bizNo": "BZ-202609160003",
|
||
"payType": "REIMBURSE",
|
||
"payTypeName": "报账款",
|
||
"unitName": "刘大山",
|
||
"category": "报账款",
|
||
"categoryName": "报账款",
|
||
"amount": 975.00,
|
||
"fee": 0,
|
||
"actualAmount": 975.00,
|
||
"status": "APPROVED"
|
||
}
|
||
```
|
||
|
||
## 五、前端对接建议
|
||
|
||
- 待付款列表「金额」列统一用 `amount` 渲染（此前 null 需空态，现可直接显示）。
|
||
- 若列表/详情要显示「实付」，用 `actualAmount`；要显示手续费用 `fee`（恒 0 的线可不显示该列）。
|
||
- 付款动作入参 `amount` 须填 `actualAmount`（金额锁死基准），不是 `amount`——注意别填错。
|
||
|
||
## 六、影响评估 / 回滚
|
||
|
||
- **纯出参补值**（null → 有值），无存量字段/路径/语义变更，向后兼容，无回滚负担。
|
||
- 已合并 dev-v3 并 4 测试全绿（FinCashierConverterTest 补 4 线金额口径断言），CashierPayService/Controller 测试无回归。
|
||
|
||
## 七、关联 / 联系人
|
||
|
||
- Issue：[#7815](https://git.1814.love:8443/wx/HL/issues/7815)
|
||
- PR：[#7818](https://git.1814.love:8443/wx/HL/pulls/7818)
|
||
- 前置：[报账款模块接入指引](16_7721_报账款模块接入指引-新增接口-管理后台.md)
|
||
- 负责人：腰苏图（yst）｜ 反馈：财务域后端对接群 / 直接 @yst
|