---
schema: "hl-changelog/v2"
ticket: "8655"
title: "资金统计某日资金明细页补筛选控件对接指引（科目/账户/收支），接口已支持零改动"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "merged"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "hl-admin(claude-opus-4-8)"
frontend_ref: "e4de4c1f600d4a0738be9bbb207407e3823b6f2a"
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），前端补渲染筛选控件即可。;前端已交付:三筛选控件实证已在,补 FUND_FLOW_BIZ 缺 ORDER_REFUND(14 值)+账户下拉 status=ACTIVE,17 例定向全绿"
---

# 【修改接口·管理后台】资金统计某日资金明细页补筛选控件对接指引（科目/账户/收支） (#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