docs(changelog): #8655 资金明细页补筛选控件对接指引（科目/账户/收支，接口已支持零改动）

2026-09-30 14:58:19 +08:00
@@ -0,0 +1,224 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8655"
+title: "资金统计某日资金明细页补筛选控件对接指引（科目/账户/收支），接口已支持零改动"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-09-30"
+base: "dev-v3"
+updated_at: "2026-09-30"
+status_note: "资金账户→资金统计点某日进明细页目前只有日期+分页，缺科目/账户/收支筛选控件。核对后端明细接口 GET /admin/finance/fund-flows/page：bizType(科目)/fundAccountId(账户)/direction(收支)/flowAtStart/flowAtEnd 等筛选早已支持，出参行已带 bizTypeName/accountName 中文。本文档纯对接指引、接口零改动，告知前端现有筛选参数+三个下拉数据源（科目/收支硬编码枚举、账户调 fund-accounts/page?status=ACTIVE），前端补渲染筛选控件即可。"
+---
+
+# 【修改接口·管理后台】资金统计某日资金明细页补筛选控件对接指引（科目/账户/收支） (#8655)
+
+> **PR**: 无（纯对接指引，接口未改动） | **服务**: hl-finance（编译进 hl-order-service-v3） | **更新时间**: 2026-09-30 14:00
+
+## 1. 接口背景
+
+资金账户 → 资金统计查询，点击某日跳到「资金明细」页时，目前只带了日期（`flowAtStart`/`flowAtEnd`）+ 分页参数，**页面上没有科目、账户、收支的筛选控件**。
+
+经核对后端明细接口，这些筛选条件**接口全部已支持**，后端无需任何改动。本文档是**前端对接指引**：告知明细接口现有可用筛选参数 + 三个下拉的数据源，前端在明细页补渲染筛选控件即可。
+
+> ⚠️ 本接口本次**无任何改动**（入参/出参/枚举/错误码均不变），仅是把「早已支持但前端没用上」的筛选参数同步给前端。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 全账户资金流水分页 | GET | `/admin/finance/fund-flows/page` | 无变更（对接指引） | 现有筛选参数梳理，前端补控件 |
+
+## 3. 接口详情
+
+### 3.1 全账户资金流水分页（逐笔含结存快照）
+
+- **使用场景**：资金账户 → 资金统计 → 点某日 → 查当日资金明细流水；也可按科目/账户/收支组合筛选
+- **认证**：管理后台 JWT
+- **幂等性**：是（GET 查询）
+- **限流**：无
+
+#### 入参（Query）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `flowAtStart` | String(date) | ❌ | 收付日期起 yyyy-MM-dd；点某日明细时与 flowAtEnd 传同一天 |
+| `flowAtEnd` | String(date) | ❌ | 收付日期止 yyyy-MM-dd |
+| `bizType` | String | ❌ | **科目筛选**：业务类型，单值，取值见 §6.1 |
+| `fundAccountId` | String(Long) | ❌ | **账户筛选**：单个账户 ID（下拉数据源见 §6.3） |
+| `accountType` | String | ❌ | 账户类型批量筛选（备选）：`BANK`/`CASH`/`THIRD_PARTY`/`INTERNAL_VIRTUAL`，筛该类账户的全部流水 |
+| `direction` | String | ❌ | **收支筛选**：`IN` 收入（入账）/ `OUT` 支出（出账） |
+| `flowNo` | String | ❌ | 流水号模糊（可选） |
+| `bizId` | String(Long) | ❌ | 业务单据 ID（按单据捞明细，与 bizType 组合，可选） |
+| `pageNo` | Integer | ✅ | 页码，从 1 开始 |
+| `pageSize` | Integer | ✅ | 每页条数 |
+
+> 说明：`fundAccountId`（单账户）与 `accountType`（按类型）二选一即可，都用则同时生效（交集）。
+
+#### 出参（`Result<PageResult<行>>`）
+
+每行流水字段（前端直接渲染，**业务类型中文、账户名后端已带，无需前端再翻译**）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | String | 流水 ID |
+| `flowNo` | String | 流水号 |
+| `fundAccountId` | String | 账户 ID |
+| `accountName` | String | **账户名称（已带，直接渲染）** |
+| `accountType` | String | 账户类型码值 |
+| `direction` | String | 方向 `IN`/`OUT` |
+| `amount` | Number | 金额 |
+| `bizType` | String | 业务类型码值 |
+| `bizTypeName` | String | **业务类型中文名（已带，直接渲染，如 ORDER_REFUND=订单退款）** |
+| `bizId` | String | 关联业务单据 ID |
+| `bizNo` | String | 业务单据号（手写动作 TRANSFER/INVENTORY/OPENING 恒为 null） |
+| `balanceAfter` | Number | 本笔记完后账户结存快照 |
+| `transferGroupId` | String | 互转成对组号（仅 TRANSFER） |
+| `fee` | Number | 手续费（仅 TRANSFER 转出行） |
+| `counterparty` | String | 对方户名（已脱敏） |
+| `flowAt` | String | 收付时间 yyyy-MM-dd HH:mm:ss |
+| `voucherUrl` | String | 回单凭证影像 |
+| `remark` | String | 备注 |
+
+## 6. 枚举 / 数据字典
+
+### 6.1 bizType（科目，FundFlowBizTypeEnum）
+
+**所属字段**：入参 `bizType` / 出参 `bizType`、`bizTypeName` | **类型**：`String` | **必填**：❌
+
+流水无数据字典，中文名后端固定，前端科目下拉**直接硬编码这张映射**（出参 `bizTypeName` 已带中文，列表无需前端 map）：
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `PAYMENT` | 付款 | 应付款 |
+| `PREPAY` | 预付 | 预付款 |
+| `EXPENSE` | 费用 | 费用报销 |
+| `REIMBURSE` | 报账 | 报账款 |
+| `RECEIPT` | 收款确认 | 代收上交 |
+| `STAFF_LOAN` | 员工借款 | 付讫 OUT / 还款 IN |
+| `COMPANY_LOAN` | 公司借款 | 借出 OUT / 借入 IN，归还/收回反向 |
+| `NONBIZ` | 业务外收支 | 收入 IN / 支出 OUT |
+| `ADVANCE` | 司导预支 | 预支出账流水 |
+| `TRANSFER` | 账户互转 | 成对，含商户号提现归集 THIRD_PARTY→BANK |
+| `ORDER_PAY` | 对公收款 | 订单支付流水，自动生成不经出纳 |
+| `ORDER_REFUND` | 订单退款 | OUT 流水，自动生成不经出纳 |
+| `INVENTORY` | 盘盈盘亏 | SURPLUS→IN / DEFICIT→OUT |
+| `OPENING` | 期初调整 | IN=调高 / OUT=调低 |
+
+### 6.2 direction（收支）
+
+**所属字段**：入参/出参 `direction` | **类型**：`String` | **必填**：❌
+
+前端收支下拉固定两项，硬编码：
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `IN` | 收入 | 入账 |
+| `OUT` | 支出 | 出账 |
+
+### 6.3 账户下拉数据源（fundAccountId 选项）
+
+调账户档案列表接口取账户选项：
+
+`GET /admin/finance/fund-accounts/page?status=ACTIVE&pageSize=100`
+
+- `status=ACTIVE` 只拉启用账户（停用账户不出现）
+- 返回行含 `id`（作为 `fundAccountId` 值）、`accountName`、`accountTypeName`（现金/银行/第三方支付），可直接做下拉显示
+- 该接口自身也支持 `accountType`/`nature`/`keyword` 入参，可用于账户下拉的级联筛选
+
+## 7. 错误码
+
+本接口为查询接口，无业务错误码；参数非法（如日期格式错误）返回通用 400。无新增/变更。
+
+## 8. 示例
+
+### 8.1 典型：查某日 + 科目=业务外收支 + 收入
+
+**请求**：
+
+```
+GET /admin/finance/fund-flows/page?flowAtStart=2026-09-30&flowAtEnd=2026-09-30&bizType=NONBIZ&direction=IN&pageNo=1&pageSize=10
+Authorization: Bearer {admin-token}
+（无请求体）
+```
+
+**响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "total": 1,
+    "records": [
+      {
+        "id": "1962000000000000631",
+        "flowNo": "LS202609300001",
+        "fundAccountId": "1962000000000000503",
+        "accountName": "工商银行海拉尔支行基本户",
+        "accountType": "BANK",
+        "direction": "IN",
+        "amount": 990.00,
+        "bizType": "NONBIZ",
+        "bizTypeName": "业务外收支",
+        "bizId": "1962000000000000903",
+        "bizNo": "WS-20260930-001",
+        "balanceAfter": 582995.00,
+        "transferGroupId": null,
+        "fee": null,
+        "counterparty": "某某单位",
+        "flowAt": "2026-09-30 10:00:00",
+        "voucherUrl": null,
+        "remark": null
+      }
+    ]
+  },
+  "message": "success"
+}
+```
+
+### 8.2 边界：按账户类型批量筛 + 支出
+
+**请求**：
+
+```
+GET /admin/finance/fund-flows/page?accountType=BANK&direction=OUT&pageNo=1&pageSize=10
+Authorization: Bearer {admin-token}
+（无请求体）
+```
+
+**响应**：结构同上，`records` 为所有银行账户的支出流水（空则 `records: []`、`total: 0`）。
+
+## 9. 业务边界
+
+- ✅ 所有筛选参数均可选、可任意组合，均不传=全量资金流水分页（flowAt 倒序）
+- ✅ 点某日明细：`flowAtStart` 与 `flowAtEnd` 传同一天
+- ⚠️ `accountType` 筛选是「该类型全部账户的流水」，流水表不存账户类型，后端先反查该类型账户 ID 集再过滤
+- ⚠️ `fundAccountId` 与 `accountType` 同时传时取交集
+
+## 11. 影响评估
+
+- **是否破坏向后兼容**：否（接口零改动）
+- **前端是否必须同步上线**：否（前端按需补筛选控件即可，不补也不影响现有功能）
+
+## 12. 注意事项
+
+- 本接口本次无任何改动，本文档仅为前端补筛选控件提供对接参数与数据源。
+- 科目（bizType）与收支（direction）下拉前端硬编码 §6.1/§6.2 映射即可；账户下拉调 §6.3 接口取启用账户。
+- 流水行出参已带 `bizTypeName`/`accountName` 中文，前端列表直接渲染，无需维护码值→中文 map。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#8655](https://git.1814.love/wx/HL/issues/8655)
+- **PR**: 无（纯对接指引，无代码改动）
+
+### 13.2 联系人
+
+- **后端负责人**: @yst