docs(changelog): 报账款查看明细页对接指引（复用现成接口拼装，零接口变更）（#7838）

2026-09-17 00:05:19 +08:00
@@ -0,0 +1,94 @@
+---
+schema: "hl-changelog/v2"
+ticket: "finance-reimburse-detail-view-guide"
+title: "报账款「查看明细」页对接指引（复用现成接口拼装，零接口变更）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-17"
+status_note: "报账款已付款/已收款列表的「查看明细」页对接指引——非接口变更，后端零改动，前端复用两个现成接口拼装：①详情接口拿单据头+支出行明细+审核记录；②资金流水接口按 bizType=REIMBURSE&bizId 捞收款明细（组合/部分多次收款逐笔）。本篇为对接指引（怎么用现成接口拼明细页），接口本身无新增/修改。"
+updated_at: "2026-09-17"
+base: "dev-v3"
+---
+
+# 报账款「查看明细」页对接指引（零接口变更）
+
+> **服务**: hl-order-service-v3（hl-finance 模块）
+> **类型**: 📖 对接指引（**接口零变更**，纯前端拼装说明）
+> **日期**: 2026-09-17
+> **适用**: 报账款已付款/已收款列表的「查看」明细页（含组合付款 / 部分多次收款场景）
+> **关联**: Issue #7838 / PR #7840（部分收款）、[报账款模块接入指引](16_7721_报账款模块接入指引-新增接口-管理后台.md)、[部分收款 changelog](16_7838_报账款支持部分收款-修改接口-管理后台.md)
+
+---
+
+## 🔴 一句话给前端
+
+报账单「查看明细」页**不用等新接口**——用两个现成接口拼：详情接口拿单据和支出行，流水接口拿每次收款明细。
+
+| 调用 | 接口 | 拿什么 |
+|---|---|---|
+| ① | `GET /admin/finance/reimburses/{id}` | 单据头 + 支出行明细 + 审核记录 |
+| ② | `GET /admin/finance/fund-flows/page?bizType=REIMBURSE&bizId={id}` | 收款明细（每次一条） |
+
+---
+
+## 一、明细页区块 → 接口字段映射
+
+### ① 单据头 + 支出行 + 审核记录：`GET /admin/finance/reimburses/{id}`
+
+| 明细页区块 | 字段 | 说明 |
+|---|---|---|
+| 单据头 | `reimburseNo` / `reporterName` / `direction` / `status` | 单号 / 报账人 / 方向 / 状态 |
+| 金额概览 | `settleAmount` / `receivedAmount` / `remainingAmount` / `receivedAt` | 应收 / 已收 / 剩余 / 最后收款时间 |
+| 支出行明细（垫付了啥） | `lines[]` | 每笔支出：category/itemName/amount/reimburseAmount/voucherUrls 凭证 |
+| 审核记录 | `reviewLogs[]` | 复核批准/退回/反审留痕（action/operatorName/opinion/createTime） |
+
+### ② 收款明细：`GET /admin/finance/fund-flows/page?bizType=REIMBURSE&bizId={id}`
+
+每次收款一条流水（flowAt 倒序），字段：
+
+| 字段 | 说明 |
+|---|---|
+| `flowNo` | 流水号 |
+| `amount` | 本次收款金额 |
+| `payMethod` / `payChannel` | 方式（CASH 现金/BANK 银行卡/THIRD_PARTY 第三方）/ 渠道（WXPAY/ALIPAY） |
+| `accountName` | 入账账户名 |
+| `voucherNo` / `voucherUrl` | 凭证号 / 凭证影像 |
+| `flowAt` | 收款时间 |
+| `balanceAfter` | 该笔后账户结存 |
+
+## 二、组合/部分多次收款怎么显示
+
+司导组合还款（600 银行卡 + 300 现金 + 100 微信）时，接口②返回 **3 条流水**，逐笔渲染成明细表：
+
+| 流水号 | 方式 | 账户 | 本次金额 | 凭证 | 时间 |
+|---|---|---|---|---|---|
+| LS...020 | 银行卡 | 对公账户 | 600.00 | SK001 | 09-16 10:00 |
+| LS...021 | 现金 | 现金账户 | 300.00 | SK002 | 09-16 11:00 |
+| LS...022 | 微信 | 微信商户 | 100.00 | SK003 | 09-16 14:00 |
+
+单据头 `receivedAmount`=1000、`remainingAmount`=0、`status`=RECEIVED（收齐完结）。未收齐时 status=PARTIAL_RECEIVED、remainingAmount>0。
+
+## 三、前端拼装建议
+
+1. 列表「查看」按钮 → 明细页/弹窗。
+2. 进页先调①拿单据头+支出行+审核记录渲染。
+3. 再调②（bizType=REIMBURSE&bizId=单据ID）拿收款明细渲染「收款记录」表格。
+4. 部分收款中间态（PARTIAL_RECEIVED）显示「已收 X / 剩余 Y」进度；收齐（RECEIVED）显示全额。
+
+## 四、影响评估
+
+- **接口零变更**，本篇纯对接指引，无回滚负担。
+- 两个接口均已上线并验证（详情接口 #7721 起、流水接口 bizId 过滤 #7838 补）。
+
+## 五、关联 / 联系人
+
+- 部分收款：[#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