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

> **依据：** 《资金概览功能需求.md》v1.0、《资金概览技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** 当前店铺 **账户概览**（只读）与 **收支概况流水**（只读分页）；**不含** 提现申请、账户维护、平台审核、导出/筛选。  
> **实现状态：** `index.vue`、`api/agri/seller/finance/overview.js` **已按 v1.0 落地**；待菜单配置及 `/agri/seller/finance/overview` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/shop/index.vue`（概览 stat-block）、`agri/seller/stock/log/index.vue`（只读列表） |
| 布局 | 概览 `el-card` + `<br/>` + 流水 `el-card` + `border` 表格 |
| 店铺切换 | **仅 Navbar**；业务页禁止展示店铺选择器 |

---

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

| 项 | 说明 |
|----|------|
| 只读 | **无** 改余额/冻结、发起提现、维护账户 |
| 概览指标 | 可用余额、待结算、冻结、用户名、银行卡数量 |
| 待结算 | 后端实时汇总订单，**非** wallet 字段 |
| 银行卡数 | **仅** 统计银行卡类型（`account_type=1`） |
| 流水 | 变动时间 **倒序**；四类变动原因与后端文案一致 |
| 变动展示 | 前端格式化「变更值 + 变更后」（需求 §3.4） |
| 业务编号 | **只读展示**；跳转订单/提现 **非本期** |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/seller/finance/overview/index.vue` | 概览 + 收支流水 |
| API | `ruoyi-ui/src/api/agri/seller/finance/overview.js` | summary、logs |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

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

**不提供：** 检索筛选、导出、业务编号下钻、概览指标下钻、提现/账户入口按钮。

---

## 4. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 资金概览 | `agri/seller/finance/overview/index` | `seller/finance/overview` | `agri:seller:finance:overview:query` |

**上级菜单：** 店铺经营管理端 → **财务中心**

| 按钮权限 | 标识 | 页面落点 |
|----------|------|----------|
| 概览 + 流水 | `agri:seller:finance:overview:query` | 进入页面（无分写权限） |

---

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

```text
资金概览 index.vue
├── 账户概览 overview-card（v-loading）
│   ├── 三指标 stat-block
│   │   ├── 可用店铺余额 availableBalance
│   │   ├── 待结算金额 pendingSettleAmount
│   │   └── 冻结金额 frozenAmount
│   └── el-descriptions border
│       ├── 用户名 username
│       └── 银行卡数量 bankAccountCount
├── <br/>
└── 收支概况 table-card
    ├── el-table border（empty-text：暂无收支记录）
    │   ├── 店铺名称 shopName
    │   ├── 变动时间 changeTime
    │   ├── 业务编号 bizNo
    │   ├── 变动余额资金 balanceChange + balanceAfter
    │   ├── 变动冻结资金 frozenChange + frozenAfter
    │   └── 变动原因 changeReasonText
    └── pagination
```

---

## 6. 账户概览

### 6.1 接口

**GET** `/agri/seller/finance/overview/summary`

| 字段 | 说明 |
|------|------|
| availableBalance | 可用店铺余额 |
| pendingSettleAmount | 待结算金额 |
| frozenAmount | 冻结金额 |
| username | 当前登录用户名 |
| bankAccountCount | 银行卡条数 |

无 wallet 时余额/冻结后端返回 `0.00`。

### 6.2 金额展示

| 场景 | 规则 |
|------|------|
| 概览金额 | `formatMoney`：`¥` + 两位小数 + 千分位 |
| null | 展示 `—` |
| 为 0 | **仍展示** `¥0.00` |

---

## 7. 收支概况列表

### 7.1 接口

**GET** `/agri/seller/finance/overview/logs?pageNum=&pageSize=`

**无** 筛选参数（非本期）。

### 7.2 变动列格式化（前端）

```text
{±change}（余额：{after}）
{±change}（冻结：{after}）
```

| 规则 | 说明 |
|------|------|
| change 为 0 或 null | 变更值展示 `0` |
| change > 0 | 前缀 `+` |
| after | 两位小数 + 千分位（无 ¥） |
| after 为 null | `—` |
| 样式 | 正数 `.change-in` 绿色；负数 `.change-out` 红色 |

**示例：**

- 订单收支：`+128.00（余额：1,280.00）` / `0（冻结：200.00）`
- 余额提现：`−500.00（余额：780.00）` / `+500.00（冻结：700.00）`

### 7.3 变动原因

优先 `changeReasonText`；兜底映射：

| changeReason | 文案 |
|--------------|------|
| `1` | 订单收支 |
| `2` | 余额提现 |
| `3` | 提现驳回 |
| `4` | 提现完成 |

---

## 8. 店铺上下文（X-Shop-Id）

| 步骤 | 说明 |
|------|------|
| `created` | `GET /agri/seller/context` → `setSellerShopContext` |
| 全部 API | `sellerShopHeaders()` |
| Navbar 切店 | `location.reload()` 整页刷新 |

---

## 9. API 封装

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

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `getSellerFundOverviewSummary` | GET | `/summary` | query |
| `listSellerFundOverviewLogs` | GET | `/logs` | query |

---

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

| 场景 | 文案 |
|------|------|
| 流水无数据 | 「暂无收支记录」 |
| 概览余额为 0 | 仍展示 `¥0.00` |
| 无银行卡 | 银行卡数量 `0` |
| 用户名空 | `—` |

---

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

| 模块 | 关系 |
|------|------|
| **提现管理** | 写操作在提现模块；本页 **无** 提交入口 |
| **账户管理** | 银行卡维护在账户模块；本页 **只读** 数量 |
| **全部订单** | 订单收支由确认收货触发；本页 **只读** 流水 |
| **售后/退款** | 负向流水 **非本期** |

---

## 12. 联调检查清单

- [ ] 菜单挂载 `agri/seller/finance/overview/index`
- [ ] summary 四块指标与当前店铺一致
- [ ] 待结算随订单状态变化
- [ ] 确认收货后出现「订单收支」流水
- [ ] 提现 submit 后出现「余额提现」流水
- [ ] 变动列格式符合 §3.4
- [ ] 分页倒序（最新在前）
- [ ] Navbar 切店后概览与列表刷新

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：账户概览 + 收支流水分页 + 金额/变动格式化 + API 封装 |

---

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