---
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