From 0f9e87db01b6639bbbe5968bf7ac9dca3631e035 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Wed, 16 Sep 2026 23:48:14 +0800
Subject: [PATCH] =?UTF-8?q?feat(changelog):=20=E6=8A=A5=E8=B4=A6=E6=AC=BE?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=E9=83=A8=E5=88=86=E6=94=B6=E6=AC=BE=EF=BC=88?=
 =?UTF-8?q?=E7=BB=84=E5=90=88=E8=BF=98=E6=AC=BE=E5=88=86=E5=A4=9A=E6=AC=A1?=
 =?UTF-8?q?=EF=BC=8CPARTIAL=5FRECEIVED=20=E4=B8=AD=E9=97=B4=E6=80=81?=
 =?UTF-8?q?=EF=BC=89=EF=BC=88#7838=20/=20PR=20#7840=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...38_报账款支持部分收款-修改接口-管理后台.md | 144 ++++++++++++++++++
 1 file changed, 144 insertions(+)
 create mode 100644 changelogs-v2/2026-09/16_7838_报账款支持部分收款-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-09/16_7838_报账款支持部分收款-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7838_报账款支持部分收款-修改接口-管理后台.md
new file mode 100644
index 00000000..546cfa8d
--- /dev/null
+++ b/changelogs-v2/2026-09/16_7838_报账款支持部分收款-修改接口-管理后台.md
@@ -0,0 +1,144 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-16"
+status_note: "报账款收款确认入账 confirm-in 支持部分收款（司导组合还款分多次：如 600 银行卡+300 现金+100 微信）。①confirm-in 入参加必填 amount（本次收款额，此前无金额字段默认全额）；②状态机新增 PARTIAL_RECEIVED 部分收讫中间态（没付齐保持未完结，收齐翻 RECEIVED）；③报账详情/队列出参补 receivedAmount/remainingAmount/receivedAt；④资金流水接口加 bizId 过滤（按单据捞收款明细）；⑤超额硬拦新错误码 598611。付款侧 pay 不动。已合并 dev-v3（PR #7840），657 测试全绿。"
+updated_at: "2026-09-16"
+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