# 资金概览 — 前端技术方案

> **依据：** 《资金概览功能需求.md》v1.0、《资金概览技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台端** **全平台总览**、**店铺余额排行**、**资金变动明细**（只读）；**不含** 提现审核、手工调账、商家账户维护。  
> **实现状态：** `index.vue`、`api/agri/finance/fundOverview.js` **已按 v1.0 落地**；待菜单配置及 `/agri/finance/fundOverview` 联调。

---

## 1. 技术栈与写法约定

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request`（**无** `X-Shop-Id`；平台全平台可见） |
| 参考页面 | `agri/seller/finance/overview/index.vue`（总览/流水格式）、`agri/org/shop/index.vue`（平台列表） |
| 布局 | 总览 `el-card` + `<br/>` + 排行 `el-card` + `border` 表格 |
| 资金日志 | `el-drawer` width=72%；内嵌检索 + 表格 + 分页 |
| 图片 | 全局 `image-preview` |

---

## 2. 业务要点（前端需体现）

| 项 | 说明 |
|----|------|
| 只读 | **无** 改余额/冻结、审核提现 |
| 总览 | 总余额 / 待结算总额 / 冻结总额（全平台 Σ） |
| 排行 | 店名+LOGO、状态（开业/停业/已删除）、三金额列、开店时间 |
| 列排序 | 店铺余额 / 待结算 / 冻结 **可 sortable**；默认余额 **降序** |
| 资金日志 | 排行行「查看资金日志」；默认 **仅该 shopId** |
| 日志检索 | 店铺名称模糊、变动时间区间；**店名有值时忽略 shopId** |
| 重置日志 | 恢复 **入口店铺** 默认范围 |
| 变动展示 | 与商家端一致「±变更值（余额/冻结：变更后）」 |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/finance/fundOverview/index.vue` | 总览 + 排行 + 日志抽屉 |
| API | `ruoyi-ui/src/api/agri/finance/fundOverview.js` | summary、shops、logs |

**组件 name（keep-alive）：** `AgriFinanceFundOverview`

**不提供：** 排行店名检索、流水原因/编号筛选、导出、跳转提现审核。

---

## 4. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 资金概览 | `agri/finance/fundOverview/index` | `finance/fundOverview` | 见下表 |

**上级菜单：** 平台管理端 → **财务管理**

| 能力 | 权限 | 页面落点 |
|------|------|----------|
| 全平台总览 | `agri:finance:fundOverview:summary` | 顶部三块指标 |
| 店铺排行 | `agri:finance:fundOverview:ranking` | 排行表格 |
| 资金日志 | `agri:finance:fundOverview:log` | 「查看资金日志」、抽屉内列表 |

---

## 5. 页面结构（与代码一致）

```text
平台资金概览 index.vue
├── 全平台资金总览 overview-card
│   ├── 总余额 totalBalance
│   ├── 待结算总额 pendingSettleTotal
│   └── 冻结总额 frozenTotal
├── <br/>
├── 店铺余额排行 table-card
│   ├── el-table border（sortable 三列）
│   │   ├── 店铺名称（LOGO + 名称）
│   │   ├── 店铺状态
│   │   ├── 店铺余额 availableBalance
│   │   ├── 待结算金额 pendingSettleAmount
│   │   ├── 冻结金额 frozenAmount
│   │   ├── 开店时间 openTime
│   │   └── 操作：查看资金日志
│   └── pagination
└── 资金日志 el-drawer 72%
    ├── 检索：店铺名称 shopName、变动时间 daterange
    ├── el-table border（六列，同商家收支概况）
    └── pagination
```

---

## 6. 全平台总览

**GET** `/agri/finance/fundOverview/summary`

| 字段 | 说明 |
|------|------|
| totalBalance | 总余额 |
| pendingSettleTotal | 待结算总额 |
| frozenTotal | 冻结总额 |

展示：`formatMoney`（¥ + 两位小数 + 千分位）。

---

## 7. 店铺余额排行

**GET** `/agri/finance/fundOverview/shops`

| Query | 说明 |
|-------|------|
| pageNum / pageSize | 分页 |
| orderByColumn | `availableBalance` / `pendingSettleAmount` / `frozenAmount` |
| isAsc | `asc` / `desc`（前端由 `sort-change` 转换） |

**默认：** `orderByColumn=availableBalance`，`isAsc=desc`。

**店铺状态：**

| 条件 | 展示 | Tag |
|------|------|-----|
| deleted=true | 已删除 | info |
| shopStatus=0 | 开业 | success |
| shopStatus=1 | 停业 | info |

---

## 8. 资金变动明细

**GET** `/agri/finance/fundOverview/logs`

| Query | 说明 |
|-------|------|
| shopId | 排行入口传入；店名检索时 **不传** |
| shopName | 模糊；**有值覆盖 shopId 范围** |
| beginChangeTime / endChangeTime | `yyyy-MM-dd` |
| pageNum / pageSize | 分页 |

**入口逻辑：**

- 从排行进入：固定 `defaultLogShopId`；重置恢复该 shopId；
- 填写店名搜索：清除 shopId，可跨店对账。

**行字段：** 复用 `FundLogListRowVO`（shopName、changeTime、bizNo、balanceChange/After、frozenChange/After、changeReasonText）。

---

## 9. API 封装

**模块：** `@/api/agri/finance/fundOverview.js`

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `getPlatformFundOverviewSummary` | GET | `/summary` | summary |
| `listPlatformFundOverviewShops` | GET | `/shops` | ranking |
| `listPlatformFundOverviewLogs` | GET | `/logs` | log |

---

## 10. 空状态与错误提示

| 场景 | 文案 |
|------|------|
| 排行无数据 | 「暂无店铺资金数据」 |
| 日志无数据 | 「暂无资金变动记录」 |
| 日志检索无结果 | 「未找到符合条件的资金变动记录」 |

---

## 11. 与兄弟模块边界（前端）

| 模块 | 关系 |
|------|------|
| **商家 · 资金概览** | 同 shopId 指标/流水 **须一致** |
| **提现审核** | 审核写流水；本页 **只读** |
| **店铺管理** | 排行展示店名/LOGO/状态/开店时间 |

---

## 12. 联调检查清单

- [ ] 菜单挂载 `agri/finance/fundOverview/index`
- [ ] 总览三块与 Σ 排行 **口径一致**
- [ ] 排行默认余额降序；三列排序切换
- [ ] 从某店打开日志默认仅该店
- [ ] 店名检索可跨店；重置恢复单店
- [ ] 变动列格式与商家端一致
- [ ] 权限：summary/ranking/log 分权生效

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：全平台总览 + 店铺排行 + 资金日志抽屉 + API 封装 |

---

*文档版本：v1.0 · 依据《资金概览功能需求.md》v1.0、《资金概览技术方案.md》v1.0*
