145 行
6.6 KiB
Markdown
145 行
6.6 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "finance-reimburse-partial-receive"
|
||
title: "报账款支持部分收款（司导组合还款分多次，新增 PARTIAL_RECEIVED 状态）"
|
||
consumer: "admin"
|
||
author: "yst(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "merged"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "76adad4b2788de1a7f9cb35a7d6b6c4ec1155289"
|
||
target_release: ""
|
||
verified_at: "2026-09-17"
|
||
status_note: "报账款收款确认入账 confirm-in 支持部分收款（司导组合还款分多次：如 600 银行卡+300 现金+100 微信）。①confirm-in 入参加必填 amount（本次收款额，此前无金额字段默认全额）；②状态机新增 PARTIAL_RECEIVED 部分收讫中间态（没付齐保持未完结，收齐翻 RECEIVED）；③报账详情/队列出参补 receivedAmount/remainingAmount/receivedAt；④资金流水接口加 bizId 过滤（按单据捞收款明细）；⑤超额硬拦新错误码 598611。付款侧 pay 不动。已合并 dev-v3（PR #7840），657 测试全绿。 前端 hl-admin 2026-09-17 done：收款入账弹窗加 amount 必填框(默认剩余待收,规则 >0 且 ≤ 剩余),状态字典补 PARTIAL_RECEIVED「部分收款」且该态可续收不可反审,详情补已收/剩余/最后收款时间。"
|
||
updated_at: "2026-09-17"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 报账款支持部分收款（司导组合还款分多次）
|
||
|
||
> **服务**: hl-order-service-v3（hl-finance 模块）
|
||
> **类型**: ✏️ 修改接口（**入参加必填字段 + 出参加字段 + 状态枚举新增 + 新错误码**）
|
||
> **日期**: 2026-09-16
|
||
> **接口**: `POST /admin/finance/cashier/confirm-in`（收款确认入账）+ `GET /admin/finance/reimburses/{id}` + `GET /admin/finance/cashier/queue` + `GET /admin/finance/fund-flows/page`
|
||
> **关联**: Issue #7838 / PR #7840
|
||
|
||
---
|
||
|
||
## 🔴 一句话给前端
|
||
|
||
司导还款（报账款 RECEIVABLE 方向）现在**支持分多次组合收款**：一笔应收可以拆成「600 银行卡 + 300 现金 + 100 微信」分次登记，没付齐单据保持「部分收款」未完结，收齐才完结。
|
||
|
||
**前端必改**：confirm-in 入参**新增必填 `amount`**（本次收款金额），不再默认全额。
|
||
|
||
---
|
||
|
||
## 一、收款确认入账 confirm-in 入参变化
|
||
|
||
`POST /admin/finance/cashier/confirm-in`（bizType=REIMBURSE 时）：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `amount` | number | **✅ 新增必填** | 本次收款金额（>0，≤ 剩余待收）。**此前无此字段（默认全额 settle_amount），现在必传** |
|
||
|
||
其余入参（bizType/bizId/payAccountId/payMethod/payChannel/voucherNo/voucherUrl/payDate）不变。
|
||
|
||
### 典型场景（组合还款分 3 次）
|
||
|
||
应收 1000（RECEIVABLE 单，settleAmount=1000）：
|
||
|
||
| 次数 | 请求 amount | 方式 | 结果 |
|
||
|---|---|---|---|
|
||
| 第1次 | 600 | 银行卡 | 记流水 +600，已收 600，状态 **PARTIAL_RECEIVED** |
|
||
| 第2次 | 300 | 现金 | 记流水 +300，已收 900，状态 **PARTIAL_RECEIVED** |
|
||
| 第3次 | 100 | 微信 | 记流水 +100，已收 1000=应收，状态翻 **RECEIVED** 完结 |
|
||
|
||
每次收款一个账户一种方式，记一条独立资金流水；同一单可多次调 confirm-in 直到收齐。
|
||
|
||
## 二、新增状态 PARTIAL_RECEIVED
|
||
|
||
报账款单据状态枚举新增中间态：
|
||
|
||
| 状态 | 中文 | 说明 |
|
||
|---|---|---|
|
||
| `PARTIAL_RECEIVED` | **部分收款（新增）** | 已收一部分但未收齐，可继续收款，**非终态** |
|
||
| `RECEIVED` | 已回款 | 收齐终态（原有） |
|
||
|
||
状态流转：`APPROVED →（首次收款，未收齐）→ PARTIAL_RECEIVED →（续收至收齐）→ RECEIVED`；一次收全额则 `APPROVED → RECEIVED` 直达。
|
||
|
||
> ⚠️ PARTIAL_RECEIVED 资金已动（已记流水），**不可反审、不可反确认核单**（同 PAID/RECEIVED）。前端审核操作按钮对该态应禁用。
|
||
|
||
## 三、出参新增字段（报账详情 + 出纳队列行）
|
||
|
||
`GET /admin/finance/reimburses/{id}` 详情 + `GET /admin/finance/cashier/queue` 队列行，均新增：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `receivedAmount` | number | 累计已收金额（部分收款快照，未收过为 0） |
|
||
| `remainingAmount` | number | 剩余待收 = settleAmount − receivedAmount |
|
||
| `receivedAt` | string | 最后收款时间（yyyy-MM-dd HH:mm:ss，未收过为 null） |
|
||
|
||
前端可据此显示「已收 X / 剩余 Y」，并对 remainingAmount=0 的单隐藏「确认到账」入口。
|
||
|
||
## 四、资金流水接口加 bizId 过滤（查收款明细）
|
||
|
||
`GET /admin/finance/fund-flows/page` 入参新增：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `bizId` | number | 否 | 业务单据ID。配合 `bizType=REIMBURSE` 按单据捞该单全部收款流水（收款明细） |
|
||
|
||
**收款明细查询**：`GET /admin/finance/fund-flows/page?bizType=REIMBURSE&bizId={报账单ID}`，返回该单每次收款的流水（方式/账户/金额/凭证/时间，flowAt 倒序）。
|
||
|
||
## 五、新错误码
|
||
|
||
| 错误码 | 触发 | 说明 |
|
||
|---|---|---|
|
||
| `598611` | confirm-in 金额 > 剩余待收 | 「收款金额超过剩余待收」——本次收款 ≤ settleAmount − receivedAmount，多还走退款链路 |
|
||
| `598605` | amount 缺失/≤0 | 「收款金额非法」（复用既有码） |
|
||
|
||
## 六、示例（confirm-in 请求 + 响应）
|
||
|
||
**请求**（第 1 次收 600 银行卡）：
|
||
|
||
```json
|
||
{
|
||
"bizType": "REIMBURSE",
|
||
"bizId": "2100084841021145090",
|
||
"payAccountId": "70001",
|
||
"payMethod": "BANK",
|
||
"amount": 600.00,
|
||
"payDate": "2026-09-16",
|
||
"voucherNo": "SK001"
|
||
}
|
||
```
|
||
|
||
**响应**（记流水成功，单据翻 PARTIAL_RECEIVED）：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"flowId": "66020",
|
||
"flowNo": "LS202609160020",
|
||
"balanceAfter": 10600.00,
|
||
"bizId": "2100084841021145090"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 七、影响评估 / 回滚
|
||
|
||
- **入参变化（必看）**：confirm-in 新增必填 `amount`——前端**必须传**，否则 598605。原「不传=全额」改为「传全额=全额」（收全额时传 remainingAmount/settleAmount 即可）。
|
||
- **出参新增**：receivedAmount/remainingAmount/receivedAt/bizId 纯新增，老前端不读不影响。
|
||
- **状态枚举新增**：PARTIAL_RECEIVED 新值，前端状态映射表需补中文名「部分收款」。
|
||
- 付款侧 pay 不变。已合并 dev-v3，657 测试全绿。
|
||
|
||
## 八、关联 / 联系人
|
||
|
||
- Issue：[#7838](https://git.1814.love:8443/wx/HL/issues/7838)
|
||
- PR：[#7840](https://git.1814.love:8443/wx/HL/pulls/7840)
|
||
- 前置：[报账款模块接入指引](16_7721_报账款模块接入指引-新增接口-管理后台.md)
|
||
- 负责人：腰苏图（yst）｜ 反馈：财务域后端对接群 / 直接 @yst
|