diff --git a/changelogs-v2/2026-09/18_7928_资金流水分页详情出参补业务类型中文名bizTypeName-修改接口-管理后台.md b/changelogs-v2/2026-09/18_7928_资金流水分页详情出参补业务类型中文名bizTypeName-修改接口-管理后台.md new file mode 100644 index 00000000..1cc967ad --- /dev/null +++ b/changelogs-v2/2026-09/18_7928_资金流水分页详情出参补业务类型中文名bizTypeName-修改接口-管理后台.md @@ -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>`（仅列变更字段，其余字段不变） + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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` + +在列表行同名字段基础上新增 `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