# 管理员列表 — 前端技术方案

> **依据：** 《管理员列表功能需求.md》v1.1、《管理员列表技术方案.md》v1.1  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台管理端** 管理员列表、添加、编辑、删除；商家端经营账号、C 端会员 **不在本页实现**。  
> **实现状态：** 页面与 API 封装已落地，待后端 `/agri/platformAdmin` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI（与 RuoYi-Vue 一致） |
| 请求 | `@/utils/request` 封装的 axios |
| 参考页面 | `ruoyi-ui/src/views/agri/member/index.vue`（双 el-card + 弹窗 CRUD） |
| 布局 | 检索区 `el-card` + `<br/>` + 列表区 `el-card` + 表格 `border` |
| 密码规则 | `@/utils/passwordRule` 混入（6～20 位，与平台统一） |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/platformAdmin/index.vue` | 列表、检索、添加/编辑弹窗、批量删除 |
| API | `ruoyi-ui/src/api/agri/platformAdmin.js` | 列表、详情、增删改、角色选项 |

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

---

## 3. 菜单与路由

若依路由由 **后端菜单** 动态加载，前端需配置：

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 管理员列表 | `agri/platformAdmin/index` | `platformAdmin` | `agri:platformAdmin:list` |

**上级菜单：** 农资管理 → **权限管理**

| 按钮权限 | 标识 |
|----------|------|
| 查看详情（编辑回显） | `agri:platformAdmin:query` |
| 添加管理员 | `agri:platformAdmin:add` |
| 编辑管理员 | `agri:platformAdmin:edit` |
| 删除管理员 | `agri:platformAdmin:remove` |

---

## 4. 页面结构

```text
管理员列表
├── 检索区（el-card）
│   └── 管理员名称 keyword（模糊：昵称/登录名）
├── 列表区（el-card + border 表格）
│   ├── 工具栏：添加管理员、批量删除
│   ├── 列：管理员名称、手机号、邮箱、角色名称、添加时间
│   ├── 多选列（内置超管 userId=1 不可选）
│   └── 操作：编辑、删除（超管无删除按钮）
└── 添加/编辑弹窗（600px）
    ├── 管理员名称 adminName（必填）
    ├── 登录名 userName（新增必填；编辑 disabled）
    ├── 初始密码 password（仅新增；pwdValidator）
    ├── 手机号 phonenumber（必填）
    ├── 邮箱 email（选填）
    ├── 头像 avatar（ImageUpload，选填）
    └── 角色 roleIds（多选；至少 1 个 admin/merchant）
```

---

## 5. 复用组件

| 组件 | 路径 | 用途 |
|------|------|------|
| `Pagination` | 全局注册 | 分页 |
| `RightToolbar` | 全局注册 | 检索区显隐 |
| `ImageUpload` | `@/components/ImageUpload` | 头像上传 |

**头像上传参数：**

| 属性 | 值 |
|------|-----|
| `limit` | `1` |
| `file-size` | `5`（MB） |
| `file-type` | `['png','jpg','jpeg']` |

---

## 6. API 对接

**基路径：** `/agri/platformAdmin`（见 `src/api/agri/platformAdmin.js`）

| 前端方法 | HTTP | 路径 | 调用场景 |
|----------|------|------|----------|
| `listPlatformAdmin` | GET | `/list` | 列表、检索、分页 |
| `getPlatformAdmin` | GET | `/{userId}` | 编辑回显 |
| `addPlatformAdmin` | POST | `/` | 添加管理员 |
| `updatePlatformAdmin` | PUT | `/` | 编辑 |
| `delPlatformAdmin` | DELETE | `/{userIds}` | 单独/批量删除（逗号分隔） |
| `platformAdminRoleOptions` | GET | `/roleOptions` | 表单角色多选 |

### 6.1 列表请求参数

| 字段 | 说明 |
|------|------|
| pageNum, pageSize | 分页 |
| keyword | 管理员名称模糊（昵称/登录名） |

**排序：** 后端默认 `create_time DESC`（添加时间倒序）。

### 6.2 列表行字段

| 字段 | 展示规则 |
|------|----------|
| adminName | 后端已组装（昵称优先，否则登录名） |
| phonenumber | 完整展示 |
| email | 空显示「—」 |
| roleNames | 多角色聚合；`show-overflow-tooltip` |
| createTime | `parseTime` 格式化 |

### 6.3 新增请求体

| 字段 | 表单 | 说明 |
|------|:----:|------|
| adminName | 必填 | → nick_name |
| userName | 必填 | 登录名，唯一 |
| phonenumber | 必填 | 11 位手机号 |
| password | 必填 | pwdValidator |
| email | 选填 | 邮箱格式 |
| avatar | 选填 | ImageUpload |
| roleIds | 必填 | 至少 1 个；选项来自 roleOptions |

### 6.4 编辑请求体

| 字段 | 说明 |
|------|------|
| userId | 必填 |
| adminName, phonenumber | 必填 |
| email, avatar | 选填 |
| roleIds | 至少 1 个 admin/merchant |
| userName / password | **不传**（登录名 disabled；改密非本期） |

**后端安全规则（前端配合）：** 编辑自身不可清空全部列表范围角色；最后一个 admin 不可降权；删除自身/最后一个 admin/已绑定经营账号由后端阻断并 msg 提示。

### 6.5 角色选项

`GET /roleOptions` 返回 `[{ roleId, roleName, roleKey }]`，范围仅 **`admin`、`merchant`**；**不含** member。

页面 `created` 预加载；添加/编辑弹窗共用同一 `roleOptions`。

### 6.6 删除

| 场景 | 前端行为 |
|------|----------|
| 单独删除 | 行操作 → `$modal.confirm` → `delPlatformAdmin(userId)` |
| 批量删除 | 勾选多条 → 提示条数 +「删除后不可恢复」→ `delPlatformAdmin(ids.join(','))` |
| userId=1 | 无删除按钮；多选不可勾选 |
| 失败 | 后端 msg（不能删自己、须保留超管、已绑定经营账号等）由 request 拦截器弹出 |

---

## 7. 交互与校验

| 场景 | 前端行为 |
|------|----------|
| 检索 | keyword 回车或点搜索；重置清空并回到第 1 页 |
| 添加 | 弹窗 600px；提交成功关闭并刷新列表 |
| 编辑 | 登录名只读 disabled；无密码字段 |
| 角色多选 | `el-select multiple`；校验至少 1 项 |
| 空邮箱 | 列表显示「—」 |
| 权限 | 按钮 `v-hasPermi` 与 §3 一致 |

---

## 8. 权限指令

```html
v-hasPermi="['agri:platformAdmin:add']"
v-hasPermi="['agri:platformAdmin:edit']"
v-hasPermi="['agri:platformAdmin:remove']"
```

---

## 9. 与关联模块边界

| 模块 | 关系 |
|------|------|
| 会员管理 | member 用户 **不在** 本列表；表单 **不可选** member 角色 |
| 商户管理 | 本页可分配 merchant 角色；绑定动作在商户管理 adminUserOptions |
| 账号管理（草稿） | **并列菜单**；经营账号专册，列表字段不同（店铺数） |
| RuoYi 系统用户 | 全量用户维护；农资业务入口走 **本模块** |

---

## 10. 联调检查清单

- [ ] 菜单组件路径 `agri/platformAdmin/index` 可打开  
- [ ] 列表仅含 admin/merchant 用户；纯 member 不出现  
- [ ] keyword 模糊检索昵称/登录名  
- [ ] 列表默认添加时间倒序  
- [ ] 添加：必填校验、角色至少 1 个、登录名/手机号重复后端 msg  
- [ ] 角色下拉仅超级管理员、商户经营  
- [ ] 编辑：登录名 disabled；改资料成功  
- [ ] 编辑自身不可清空全部角色（后端 msg）  
- [ ] 单独/批量删除二次确认  
- [ ] 不可删自己、最后一个 admin、已绑定经营账号（后端 msg）  
- [ ] userId=1 无删除按钮  

---

## 11. 非本期（前端）

| 项 | 说明 |
|----|------|
| 详情抽屉 | 编辑弹窗已覆盖回显需求 |
| 重置密码 | 可二期或走 RuoYi 系统用户 |
| 导入/导出 | 不做 |
| 部门/岗位 | 后端固定 dept_id=100，表单不展示 |

---

## 12. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-06 | 首版：列表 CRUD、角色多选、批量删除、前端技术方案 |

---

*文档版本：v1.0 · ruoyi-ui · 关联《管理员列表功能需求.md》v1.1 / 《管理员列表技术方案.md》v1.1*
