feat(changelog): 出纳待付款队列补 amount 与 fee 字段（#7815 / PR #7818）

2026-09-16 16:05:16 +08:00
@@ -0,0 +1,107 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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 测试全绿无回归。"
+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