# 提现管理 — 前端技术方案

> **依据：** 《提现管理功能需求.md》v1.0、《提现管理技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** **提交提现**、**提现记录列表与检索**、提交区 **可用余额** 辅助展示；**不含** 平台审核、账户 CRUD、资金概览页。  
> **实现状态：** `index.vue`、`api/agri/seller/finance/withdraw.js` **已按 v1.0 落地**；待菜单配置及 `/agri/seller/finance/withdraw` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/stock/inbound/index.vue`（日期检索）、`agri/seller/finance/payAccount/index.vue`（财务模块） |
| 布局 | 提交 `el-card` + `<br/>` + 检索 `el-card` + `<br/>` + 列表 `el-card` + `border` 表格 |
| 账户下拉 | 复用 `@/api/agri/seller/finance/payAccount.js` → `listSellerPayAccountOptions` |
| 店铺切换 | **仅 Navbar**；业务页禁止展示店铺选择器 |

---

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

| 项 | 说明 |
|----|------|
| 唯一提交入口 | 本页 **POST submit**；无撤销/改待审单 |
| 账户来源 | **账户管理** `GET /payAccount/options`；无账户时提示先添加 |
| 可用余额 | `GET /balance`；提交前校验 **≤ availableBalance** |
| 提现状态 | `1` 待审核 / `2` 审核不通过 / `3` 提现完成 |
| 处理说明 | 待审核展示 **—**；终态只读展示 `processRemark` |
| 账户摘要 | 列表优先 `accountSummary`；兜底拼接类型+脱敏+姓名 |
| 检索 | 申请时间区间 + 提现状态下拉 |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/seller/finance/withdraw/index.vue` | 提交区 + 检索 + 记录列表 |
| API | `ruoyi-ui/src/api/agri/seller/finance/withdraw.js` | list、balance、submit |
| 协作 API | `api/agri/seller/finance/payAccount.js` | options 下拉 |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

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

**不提供：** 撤销待审核、修改待审单、页内添加账户、导出、按编号检索。

---

## 4. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 提现管理 | `agri/seller/finance/withdraw/index` | `seller/finance/withdraw` | `agri:seller:finance:withdraw:list` |

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

| 按钮权限 | 标识 | 页面落点 |
|----------|------|----------|
| 列表 + 余额 | `agri:seller:finance:withdraw:list` | 记录列表、可用余额 |
| 提交提现 | `agri:seller:finance:withdraw:submit` | 「提交提现」 |

---

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

```text
提现管理 index.vue
├── 提交提现 submit-card
│   ├── 可用店铺余额（GET /balance）
│   ├── 无账户 warning 提示
│   ├── 提现账户 accountId（options 下拉）
│   ├── 提现金额 withdrawAmount（>0，两位小数）
│   ├── 备注 remark（选填，≤200 字）
│   └── 提交 / 重置
├── <br/>
├── 检索区 search-card
│   ├── 申请时间 daterange → beginApplyTime / endApplyTime
│   ├── 提现状态 withdrawStatus
│   └── 搜索 / 重置
├── <br/>
└── 提现记录 table-card
    ├── el-table border
    │   ├── 提现编号 withdrawNo
    │   ├── 申请时间 applyTime
    │   ├── 提现账户 accountSummary
    │   ├── 提现金额 withdrawAmount
    │   ├── 备注 remark
    │   ├── 提现状态 withdrawStatusText（tag）
    │   └── 提现处理说明 processRemark
    └── pagination
```

---

## 6. 提交提现

### 6.1 接口

**GET** `/balance` → `{ availableBalance }`

**POST** `/submit`

```json
{
  "accountId": 1,
  "withdrawAmount": 100.00,
  "remark": "选填"
}
```

**成功：** `msgSuccess('提交成功')` → 刷新余额与列表、重置表单。

### 6.2 前端校验

| 规则 | 说明 |
|------|------|
| 未选账户 | 「请选择提现账户」 |
| 金额空或 ≤0 | 「请输入有效的提现金额」 |
| 超过余额 | 「提现金额不能超过可用余额」 |
| 备注 | maxlength 200 |

后端另校验账户有效性、余额并发（FOR UPDATE）。

---

## 7. 提现记录列表

### 7.1 接口

**GET** `/list?pageNum=&pageSize=&withdrawStatus=&beginApplyTime=&endApplyTime=`

| 参数 | 说明 |
|------|------|
| beginApplyTime | `yyyy-MM-dd` 开始（含 00:00:00） |
| endApplyTime | `yyyy-MM-dd` 结束（含 23:59:59） |
| withdrawStatus | 空=全部；`1`/`2`/`3` |

> **联调说明：** 后端 `SellerWithdrawQuery` 须包含 `beginApplyTime`、`endApplyTime` 字段，与 Mapper XML 一致；前端已按平铺 Query 传参。

### 7.2 状态展示

| withdrawStatus | 文案 | Tag |
|----------------|------|-----|
| `1` | 待审核 | warning |
| `2` | 审核不通过 | danger |
| `3` | 提现完成 | success |

---

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

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

---

## 9. API 封装

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

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `listSellerWithdraws` | GET | `/list` | withdraw:list |
| `getSellerWithdrawBalance` | GET | `/balance` | withdraw:list |
| `submitSellerWithdraw` | POST | `/submit` | withdraw:submit |

---

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

| 场景 | 文案 |
|------|------|
| 无收款账户 | warning：请先至账户管理添加 |
| 记录无数据 | 「暂无提现记录」 |
| 检索无结果 | 「未找到符合条件的提现记录」 |
| 提交成功 | 「提交成功」 |
| 后端账户无效 | 「提现账户不存在或已删除」 |

---

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

| 模块 | 关系 |
|------|------|
| **账户管理** | options 下拉；无 inline 添加 |
| **资金概览** | 提交后写「余额提现」流水；本页只读余额 |
| **平台提现审核** | 审核结果回写状态与处理说明 |

---

## 12. 联调检查清单

- [ ] 菜单挂载 `agri/seller/finance/withdraw/index`
- [ ] 无账户时不可提交并提示
- [ ] 提交成功生成待审核记录
- [ ] 超余额提交被后端拒绝
- [ ] 日期区间、状态筛选生效
- [ ] 平台审核后列表状态与处理说明更新
- [ ] Navbar 切店后数据刷新

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：提交区 + 记录检索 + API 封装；对齐需求 v1.0 |

---

*文档版本：v1.0 · 依据《提现管理功能需求.md》v1.0、《提现管理技术方案.md》v1.0*
