docs(changelog): #7928 资金流水分页/详情出参补 bizTypeName 中文名-管理后台

ORDER_REFUND 此前因前端硬编码 map 漏配回显英文枚举码。后端两个只读接口 /admin/finance/fund-flows/page 与 /{id} 出参各新增 bizTypeName（枚举 label， 14 业务类型全覆盖），bizType 英文码不变，零入参/零DDL。已部署测试服网关实调 8 项断言全 PASS。
2026-09-18 14:06:51 +08:00
@@ -0,0 +1,212 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7928"
+title: "资金流水分页/详情出参新增业务类型中文名 bizTypeName（ORDER_REFUND 等不再显示英文枚举码）"
+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-18"
+status_note: "财务管理-资金账户-资金流水的列表与详情两个只读接口出参各纯新增一个 bizTypeName（FundFlowBizTypeEnum 中文 label），既有 bizType 英文码一字不改，入参/错误码/枚举值零变化。修复 ORDER_REFUND 因前端硬编码 map 漏配而回显英文的问题；bizTypeName 覆盖全部 14 个业务类型。已合并 dev-v3（PR #7929）并部署测试服，网关实调列表+详情 8 项断言全 PASS。前端把业务类型列渲染切到 bizTypeName 即可，旧后端可用 bizType 兜底。"
+updated_at: "2026-09-18"
+base: "dev-v3"
+---
+
+# 资金流水: 分页 / 详情出参新增业务类型中文名 `bizTypeName`（管理后台）
+
+> **服务**: hl-order-service-v3（hl-finance 模块，端口 8086/8186）
+> **PR**: #7929
+> **Issue**: #7928
+> **日期**: 2026-09-18
+> **影响范围**: 管理后台「财务管理 - 资金账户 - 资金流水」列表的业务类型列、流水详情抽屉；账户详情 / 日结等复用流水行结构的展示同样受益
+
+---
+
+## 一、接口背景
+
+资金流水 `fin_fund_flow.biz_type` 只存英文枚举码（如 `ORDER_PAY` / `ORDER_REFUND`），系统**没有**该字段的数据字典。此前业务类型中文完全靠管理后台前端本地硬编码 map 翻译。新增「订单退款」自动记账（#7905）引入 `ORDER_REFUND` 后，前端 map 未同步补该项，兜底逻辑直接回显英文码，页面业务类型列出现 `ORDER_REFUND` 英文（而 `ORDER_PAY` 正常显示「对公收款」）。
+
+本次后端在出参直接返回中文名 `bizTypeName`，业务类型枚举自身持有中文 label，前端无需再维护硬编码 map。与 finance 域既有做法一致（`CashierPaymentRowRespVO.bizTypeName`、`InvoiceInRelRespVO.bizTypeName`）。
+
+## 二、变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 |
+|---|------|------|------|----------|
+| 1 | 全账户资金流水分页 | GET | `/admin/finance/fund-flows/page` | 出参每行新增 `bizTypeName` |
+| 2 | 资金流水详情 | GET | `/admin/finance/fund-flows/{id}` | 出参新增 `bizTypeName` |
+
+纯出参新增字段，无入参变化、无枚举值增删、无 DDL、无错误码变化。
+
+## 三、接口详情
+
+### 1. 资金流水分页 `GET /admin/finance/fund-flows/page`
+
+#### 入参（本次无变化）
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| pageNo / pageSize | Query | Integer | ❌ | 分页，默认 1 / 10 |
+| fundAccountId | Query | Long | ❌ | 按账户过滤（雪花 ID，字符串传参） |
+| accountType | Query | String | ❌ | BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL |
+| direction | Query | String | ❌ | OUT 出账 / IN 入账 |
+| bizType | Query | String | ❌ | **仍传英文码**，如 ORDER_REFUND（不传中文名） |
+| bizId | Query | Long | ❌ | 业务单据 ID |
+| flowNo | Query | String | ❌ | 流水号模糊 |
+| flowAtStart / flowAtEnd | Query | Date | ❌ | yyyy-MM-dd 收付日期区间 |
+
+#### 出参 `Result<PageResult<FundFlowRowRespVO>>`（仅列变更字段，其余字段不变）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| bizType | String | **不变**：业务类型英文码（筛选/分组仍用它） |
+| **bizTypeName** | String | **本次新增**：业务类型中文名；bizType 为空或历史非法码时为 `null`（不回显英文码） |
+
+`FundFlowRowRespVO` 其余字段（id / flowNo / fundAccountId / accountName / accountType / direction / amount / bizId / bizNo / balanceAfter / transferGroupId / fee / counterparty / flowAt / voucherUrl / remark）一字未动。
+
+#### 出参示例
+
+典型（订单退款行）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "pageNo": 1,
+    "pageSize": 5,
+    "total": 1,
+    "records": [
+      {
+        "id": "2100743195460575234",
+        "flowNo": "LS202609180009",
+        "fundAccountId": "1106110439",
+        "direction": "OUT",
+        "amount": 100.00,
+        "bizType": "ORDER_REFUND",
+        "bizTypeName": "订单退款",
+        "bizId": "2100743195263442946",
+        "counterparty": "H* 订单退款",
+        "balanceAfter": 4400.00
+      }
+    ]
+  }
+}
+```
+
+边界（历史非法 / 空 bizType，存量不报错）：
+
+```json
+{ "bizType": "ALIEN", "bizTypeName": null }
+```
+
+### 2. 资金流水详情 `GET /admin/finance/fund-flows/{id}`
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| id | Path | Long | ✅ | 流水 ID（雪花，字符串） |
+
+#### 出参 `Result<FundFlowDetailRespVO>`
+
+在列表行同名字段基础上新增 `bizTypeName`，口径完全一致；另含详情专有 `pairedFlowId`（互转对侧流水 ID）。`bizType` 英文码保留。
+
+详情示例（实测）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": "2100743195460575234",
+    "flowNo": "LS202609180009",
+    "direction": "OUT",
+    "amount": 100.00,
+    "bizType": "ORDER_REFUND",
+    "bizTypeName": "订单退款",
+    "balanceAfter": 4400.00
+  }
+}
+```
+
+## 四、入参
+
+见各接口「入参」表。**本次零入参变更**。特别强调：列表筛选 `bizType` 仍只认英文码，传中文名（如「订单退款」）筛不到数据。
+
+## 五、出参
+
+见上。本次仅在两个出参 VO 末尾**新增** `bizTypeName: String`，无删除/改名/类型变更，老前端忽略新字段不受影响。
+
+## 六、枚举 / 数据字典
+
+`bizTypeName` 取值来源 = 后端枚举 `FundFlowBizTypeEnum.label`（**非 sys_dict 数据字典**），14 个值全覆盖：
+
+| bizType（英文码，入参/筛选值） | bizTypeName（展示中文） |
+|---|---|
+| PAYMENT | 付款 |
+| PREPAY | 预付 |
+| EXPENSE | 费用 |
+| REIMBURSE | 报账 |
+| RECEIPT | 收款确认 |
+| STAFF_LOAN | 员工借款 |
+| COMPANY_LOAN | 公司借款 |
+| NONBIZ | 业务外收支 |
+| ADVANCE | 司导预支 |
+| TRANSFER | 账户互转 |
+| ORDER_PAY | 对公收款 |
+| ORDER_REFUND | 订单退款 |
+| INVENTORY | 盘盈盘亏 |
+| OPENING | 期初调整 |
+
+> 注：资金流水页用短文案（付款/预付/报账）；出纳台账页「应付款/预付款/报账款」是另一页面语境，不冲突。bizType 为空或不在枚举内时 bizTypeName=null，后端不编造、不回显英文码。
+
+## 七、错误码
+
+本次无新增 / 修改错误码。两接口既有错误码不变，例如详情查无流水：
+
+```json
+{ "code": 595101, "message": "流水不存在", "data": null, "success": false }
+```
+
+## 八、示例
+
+- 典型：见第三节 ORDER_REFUND 列表 / 详情示例。
+- 边界：bizType 为历史非法码或空 → bizTypeName=null，接口仍 200。
+- 异常：未登录 → 网关 401；详情 id 不存在 → 595101。
+
+## 九、业务边界
+
+- 鉴权：管理后台 JWT。
+- `bizTypeName` 是读取时由枚举 label **内存派生**的展示字段，不落库、不查字典、零额外 IO。
+- 只读接口，天然幂等。
+- 对方户名 `counterparty` 仍按既有规则展示层脱敏（首字符 + *），本次未改脱敏口径。
+
+## 十、修改前后对比
+
+| 字段 / 行为 | 修改前 | 修改后 |
+|---|---|---|
+| 列表/详情 `bizType` | 英文码 | **不变**，仍英文码 |
+| 列表/详情 `bizTypeName` | 字段不存在 | 新增，枚举中文 label，可 null |
+| ORDER_REFUND 页面显示 | 前端 map 漏配 → 显示英文 `ORDER_REFUND` | 后端给「订单退款」，前端改用后显示中文 |
+| 入参 / 错误码 / DDL | — | 零变化 |
+
+## 十一、影响评估 / 回滚
+
+- **向后兼容**：纯新增出参字段，老前端不接入则表现与现状一致（ORDER_REFUND 仍英文，其余不受影响）。
+- **前端是否必须同步上线**：否。但要消掉 ORDER_REFUND 英文显示，前端需把业务类型列改为展示 `bizTypeName`（建议 `row.bizTypeName || fundFlowBizLabel(row.bizType)` 兜底，灰度期旧后端不白屏）。
+- **回滚**：后端回滚该 PR 仅使 bizTypeName 字段消失，不影响数据与其它字段；无 DDL，无库表回滚负担。
+
+## 十二、注意事项
+
+- 前端**写入、筛选、分组键一律继续用 `bizType` 英文码**，`bizTypeName` 仅用于展示，不要回传任何写接口。
+- 切换渲染后，前端本地 `FUND_FLOW_BIZ` 硬编码 map 可逐步废弃；兜底建议保留一个发布周期。
+
+## 十三、关联 / 联系人
+
+- Issue: https://git.1814.love:8443/wx/HL/issues/7928
+- PR: https://git.1814.love:8443/wx/HL/pulls/7929
+- Merge commit: https://git.1814.love:8443/wx/HL/commit/6e9b07036a
+- 后端负责人: @yst