# 账户管理 — 前端技术方案

> **依据：** 《账户管理功能需求.md》v1.0、《账户管理技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** 当前店铺 **提现收款账户** 列表、**添加 / 编辑 / 删除**；**不含** 提现提交、平台审核、余额/流水。  
> **实现状态：** `index.vue`、`api/agri/seller/finance/payAccount.js` **已按 v1.0 落地**；待菜单配置及 `/agri/seller/finance/payAccount` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/employee/index.vue`（CRUD 弹窗）、`agri/seller/finance/overview/index.vue`（财务模块上下文） |
| 布局 | 列表 `el-card` + `border` 表格 + 分页 |
| 表单 | `el-dialog` width=520px（`append-to-body`） |
| 店铺切换 | **仅 Navbar**；业务页禁止展示店铺选择器 |

---

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

| 项 | 说明 |
|----|------|
| 账户类型 | `1` 银行卡 / `2` 支付宝 / `3` 微信 |
| 类型锁定 | **添加时选定**；**编辑不可改类型**（PA-A3） |
| 列表账号 | 展示后端 **脱敏** 字段 `accountNoMask`，**不展示明文** |
| 编辑账号 | 列表无明文；编辑须 **重新输入完整账号** |
| 删除 | 二次确认；逻辑删除；**不影响** 已提交提现快照 |
| 检索 | **非本期**；仅分页列表 |
| 与资金概览 | 银行卡类型计入概览「银行卡数量」 |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/seller/finance/payAccount/index.vue` | 列表 + 添加/编辑弹窗 |
| API | `ruoyi-ui/src/api/agri/seller/finance/payAccount.js` | list、options、add、edit、remove |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

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

**不提供：** 关键词检索、批量删除、默认账户、导出、详情页、页内实名认证。

---

## 4. 菜单与路由

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

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

| 按钮权限 | 标识 | 页面落点 |
|----------|------|----------|
| 列表 | `agri:seller:finance:payAccount:list` | 进入页面 |
| 添加 | `agri:seller:finance:payAccount:add` | 「添加账户」、POST |
| 编辑 | `agri:seller:finance:payAccount:edit` | 「编辑」、PUT |
| 删除 | `agri:seller:finance:payAccount:remove` | 「删除」、DELETE |

> `GET /options` 权限为 `agri:seller:finance:withdraw:list`，供 **提现管理** 调用，非本页使用。

---

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

```text
账户管理 index.vue
├── 列表区 table-card
│   ├── 添加账户（权限 add）
│   ├── right-toolbar（刷新）
│   ├── el-table border
│   │   ├── 收款方式 accountTypeText
│   │   ├── 真实姓名 realName
│   │   ├── 账号 accountNoMask
│   │   ├── 添加时间 createTime
│   │   └── 操作：编辑 | 删除
│   └── pagination
└── 添加/编辑弹窗 el-dialog
    ├── 收款方式 accountType（编辑 disabled）
    ├── 真实姓名 realName
    └── 账号 accountNo（标签随类型变化；编辑展示当前脱敏提示）
```

---

## 6. 表单与校验

### 6.1 字段映射（PayAccountSaveDTO）

| 字段 | 添加 | 编辑 |
|------|------|------|
| accountType | 必选 | 只读展示，随 payload 原样提交 |
| realName | 必填，≤64 | 可改 |
| accountNo | 必填明文 | 必填明文（重新输入） |
| accountId | — | 必填 |

### 6.2 前端校验

| 规则 | 说明 |
|------|------|
| 收款方式未选 | 「请选择收款方式」 |
| 姓名为空 | 「请填写真实姓名」 |
| 账号为空 | 按类型提示（银行卡号/支付宝号/微信号） |
| 银行卡号 | **纯数字**（`/^\d+$/`） |
| 支付宝/微信 | 非空即可 |

成功提示：添加「添加成功」、编辑「保存成功」、删除「删除成功」。

---

## 7. 删除确认

**文案：** 确认删除该{类型}账户「{脱敏账号}」吗？删除后不可在提现时选择，已提交的提现单不受影响。

---

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

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

---

## 9. API 封装

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

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `listSellerPayAccounts` | GET | `/list` | payAccount:list |
| `listSellerPayAccountOptions` | GET | `/options` | withdraw:list |
| `addSellerPayAccount` | POST | `/` | payAccount:add |
| `updateSellerPayAccount` | PUT | `/` | payAccount:edit |
| `delSellerPayAccount` | DELETE | `/{accountId}` | payAccount:remove |

---

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

| 场景 | 文案 |
|------|------|
| 列表无数据 | 「暂无收款账户，请先添加」 |
| 后端类型无效 | 「收款方式无效」 |
| 账户不存在 | 「收款账户不存在」 |

---

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

| 模块 | 关系 |
|------|------|
| **提现管理** | 提交前须本模块有账户；下拉调 `GET /options` |
| **资金概览** | 只读银行卡数量；本页维护后概览刷新可见 |
| **平台提现审核** | 读提现快照；**不读**本模块实时数据 |

---

## 12. 联调检查清单

- [ ] 菜单挂载 `agri/seller/finance/payAccount/index`
- [ ] 添加三类账户成功并列表可见
- [ ] 列表账号为脱敏展示
- [ ] 编辑时类型不可改、须填完整账号
- [ ] 删除后列表移除、options 不可选
- [ ] 权限：无 add/edit/remove 时按钮隐藏
- [ ] Navbar 切店后列表刷新

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：列表/添加/编辑/删除/API 封装；对齐需求 v1.0 |

---

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