diff --git a/changelogs-v2/2026-09/30_8655_资金明细页补筛选控件对接指引-修改接口-管理后台.md b/changelogs-v2/2026-09/30_8655_资金明细页补筛选控件对接指引-修改接口-管理后台.md new file mode 100644 index 00000000..f0b20f02 --- /dev/null +++ b/changelogs-v2/2026-09/30_8655_资金明细页补筛选控件对接指引-修改接口-管理后台.md @@ -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>`) + +每行流水字段(前端直接渲染,**业务类型中文、账户名后端已带,无需前端再翻译**): + +| 字段 | 类型 | 说明 | +|------|------|------| +| `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