hl-api-changelog/changelogs-v2/2026-09/30_8655_资金明细页补筛选控件对接指引-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, base, updated_at, status_note

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	base	updated_at	status_note
hl-changelog/v2	8655	资金统计某日资金明细页补筛选控件对接指引（科目/账户/收支），接口已支持零改动	admin	yst(GIT)	修改接口	merged	verified	implemented	hl-admin(claude-opus-4-8)	e4de4c1f600d4a0738be9bbb207407e3823b6f2a	v2.1	2026-09-30	dev-v3	2026-09-30	资金账户→资金统计点某日进明细页目前只有日期+分页，缺科目/账户/收支筛选控件。核对后端明细接口 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}
（无请求体）

响应：

{
  "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
• PR: 无（纯对接指引，无代码改动）

13.2 联系人

• 后端负责人: @yst