96 行
4.0 KiB
Markdown
96 行
4.0 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7003"
|
||
title: "资金流水（分页 + 详情，只读）"
|
||
consumer: "admin"
|
||
author: "yst"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "21540997"
|
||
target_release: ""
|
||
verified_at: "2026-09-09"
|
||
status_note: "后端已合 dev-v3（account 资金账户域）并部署测试服。只读；balanceAfter 勾稽；列表行+详情补 remark 字段（#7133）。"
|
||
updated_at: "2026-09-09"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 资金流水
|
||
|
||
## 1. 接口背景
|
||
财务域「资金流水」：资金账户每笔出入账的流水记录（只读）。来源包括付款、预付、报销、收款、业务外、互转、盘盈盘亏、期初调整等。本期列表行与详情补充 remark 字段（互转备注/盘盈盘亏/期初调整原因，#7133）。
|
||
|
||
## 2. 变更清单
|
||
| 类型 | 接口 | 说明 |
|
||
|---|---|---|
|
||
| 新增 | GET `/admin/finance/fund-flows/page` | 流水分页（flowAt 倒序） |
|
||
| 新增 | GET `/admin/finance/fund-flows/{id}` | 流水详情 |
|
||
|
||
## 3. 接口详情
|
||
|
||
### 3.1 分页 GET /page
|
||
入参（Query + 分页，均可选）：`fundAccountId` / `accountType` / `direction` / `bizType` / `flowNo`（模糊）/ `flowAtStart` / `flowAtEnd`（yyyy-MM-dd）/ pageNo / pageSize。
|
||
|
||
出参行（FundFlowRowRespVO，Long ID 序列化为 String）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | String | 流水ID |
|
||
| flowNo | String | 流水号（日期前缀） |
|
||
| fundAccountId | String | 资金账户ID |
|
||
| accountName | String | 账户名称 |
|
||
| accountType | String | 账户类型 |
|
||
| direction | String | OUT 出 / IN 入 |
|
||
| amount | BigDecimal | 金额 |
|
||
| bizType | String | 业务类型 |
|
||
| bizId | String | 业务单据ID（可空） |
|
||
| bizNo | String | 业务单号（手写动作 TRANSFER/INVENTORY/OPENING 恒为 null） |
|
||
| balanceAfter | BigDecimal | 本笔记完后结存快照（勾稽） |
|
||
| transferGroupId | String | 互转组ID（仅 TRANSFER） |
|
||
| fee | BigDecimal | 手续费（仅 TRANSFER，挂转出行） |
|
||
| counterparty | String | 对方账户/往来（脱敏） |
|
||
| flowAt | String | 记账时间（yyyy-MM-dd HH:mm:ss） |
|
||
| voucherUrl | String | 佐证影像 |
|
||
| remark | String | 备注（互转备注/盘盈盘亏/期初调整原因） |
|
||
|
||
### 3.2 详情 GET /{id}
|
||
出参 = 行全字段 + `pairedFlowId`（互转对侧流水ID，仅 TRANSFER）+ `operatorName`（经办人）。
|
||
|
||
## 4. 枚举 / 数据字典
|
||
| 字段 | 取值 |
|
||
|---|---|
|
||
| accountType | BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL |
|
||
| direction | OUT 出账 / IN 入账 |
|
||
| bizType | PAYMENT 付款 / PREPAY 预付 / EXPENSE 费用 / REIMBURSE 报销 / RECEIPT 收款 / STAFF_LOAN 员工借款 / COMPANY_LOAN 公司借款 / NONBIZ 业务外 / ADVANCE 预支 / TRANSFER 互转 / ORDER_PAY 订单支付 / INVENTORY 盘盈盘亏 / OPENING 期初调整 |
|
||
|
||
## 5. 错误码（段位 595100-595199）
|
||
| 码 | 含义 |
|
||
|---|---|
|
||
| 595101 | 流水不存在（查询路径仅见此码） |
|
||
| 595102-595106 | 写入侧（金额无效/余额不足/并发冲突/期初调整非法/盘盈盘亏方向无效），查询不触发 |
|
||
|
||
## 6. 示例
|
||
**按账户+方向查**
|
||
```
|
||
GET /admin/finance/fund-flows/page?fundAccountId=2097...&direction=OUT&pageNo=1&pageSize=20
|
||
→ 200 {"records":[{"flowNo":"LS20260909...","direction":"OUT","amount":100.00,"balanceAfter":4900.00,"bizType":"PAYMENT",...}],"total":N}
|
||
```
|
||
**详情（互转带对侧）**
|
||
```
|
||
GET /admin/finance/fund-flows/{id}
|
||
→ 200 {..., "bizType":"TRANSFER","transferGroupId":"...","pairedFlowId":"...","remark":"银行取现"}
|
||
```
|
||
|
||
## 7. 注意事项
|
||
- 流水只读，无新增/修改/删除端点（由业务动作产生）。
|
||
- balanceAfter 为该笔记完后的结存快照，可用于逐笔勾稽。
|
||
- 手写动作（互转/盘盈盘亏/期初）无关联业务单号，bizNo 为 null。
|
||
- 长整型 ID 序列化为字符串。
|
||
|
||
## 8. 关联 / 联系人
|
||
- Issue：https://git.1814.love:8443/wx/HL/issues/7003 ｜ remark 出参 #7133
|
||
- Commit：https://git.1814.love:8443/wx/HL/commit/b46269a4d4
|
||
- 负责人：腰苏图（yst）
|