# 管理员列表 — 功能需求说明

> 本文档在《管理员列表功能需求-草稿》基础上整理，并关联《农资商城web》目录下 **会员管理》v1.0.1**、**店铺管理》v1.3.5**、**商户管理》v1.5**、**店铺设置》v1.1**、《关联需求分析.md》v1.5 及同目录 **《账号管理功能需求-草稿》** 做边界与流程对齐。  
> 范围：**平台管理端** 对 **平台后台管理员账号** 的列表、检索、新增、编辑、删除；不涉及数据库结构、接口定义及技术实现细节。  
> **说明：** 本模块管理的是 **登录 ruoyi-ui 平台管理端** 的运营/管理人员；**不是** C 端买家会员，**不是** 商家端店铺经营账号。  
> **v1.1：** 草稿 §5 修订：列表/表单角色范围为 **`admin` + `merchant`**（原 v1.0 的 `shop_admin` 已废止）。  
> **v1.0：** 对齐草稿列表/添加/检索/编辑/删除能力；明确与账号管理、会员管理、商户绑定的边界。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **平台管理端（Web）** 提供 **平台管理员账号** 的统一维护能力：

- 浏览、检索已授权进入平台后台的管理员；
- 新增管理员并分配 **平台侧角色**；
- 编辑管理员资料与角色；
- 单独或批量删除不再需要的管理员账号（受安全规则约束）。

**不包含（本期）：** 商家端店铺经营账号维护（见 **账号管理** / **店铺管理 · 账号管理**）；C 端会员维护（见 **会员管理**）；菜单与按钮权限的细粒度配置界面（沿用 RuoYi **角色/菜单** 体系，本模块仅 **选用已有角色** 分配给管理员）。

### 1.2 在业务链中的位置

```text
【权限链 · 平台侧】
    管理员列表（本模块）── 维护平台后台登录用户 + 平台角色
            ↓
    平台各业务模块（组织/商品/内容/会员/订单…）── 按角色授权访问

【供给链 · 商家侧 · 与本模块无直接维护关系】
    商户管理 / 店铺管理 ── 维护 biz 层「商户经营账号」（商家端登录）
            ↑
    可选：从已有「平台用户」中选取带 merchant 角色的账号绑定商户（见商户管理 §6.7）

【用户链 · C 端 · 与本模块无关】
    会员管理 ── C 端买家（member 角色）
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **账号管理**（草稿） | **并列、不重叠** | 草稿侧重 **经营账号**（账号名称、**店铺数**）；本模块侧重 **平台管理员**（角色名称、**添加时间**） |
| **会员管理** v1.0.1 | **无交叉维护** | 会员为 C 端买家；**不出现在** 本列表 |
| **店铺管理** v1.3.5 | **间接** | 店铺 **经营账号** 在店铺模块维护；**不** 在本模块开户 |
| **商户管理** v1.5 | **间接** | 新增商户时可 **选用** 已具备 **merchant** 经营角色的平台用户绑定；绑定动作在 **商户管理**，不在本模块 |
| **店铺设置** v1.1 | **间接** | 子管理员 **人数上限** 为全局数字；子管理员 **人员维护非本期**；与本模块「平台管理员」不同层 |
| **关联需求分析** v1.5 | **账号体系** | §9 区分 **商户经营账号** 与 **子管理员**；本模块属于 **平台管理端账号**，第四类补充见 §1.3 |

### 1.3 与《关联需求分析》账号体系的关系（定稿）

| 账号类型 | 登录端 | 维护入口 | 是否在本模块 |
|----------|--------|----------|:------------:|
| **平台管理员**（本模块） | 平台管理端 Web | **管理员列表** | ✓ |
| **商户经营账号** | 商家端 | 店铺管理 · 账号管理 | ✗ |
| **C 端会员** | 用户商城 | 会员管理 | ✗ |
| **子管理员**（预留） | 商家端 | 待建设 | ✗ |

### 1.4 使用端与角色

| 端 | 角色 | 能力 |
|----|------|------|
| **平台管理端** | 已授权的超级管理员 / 商户经营角色用户等 | 本模块 **全部** 能力（以菜单权限为准） |
| **商家端 / C 端** | — | **不可** 访问 |

---

## 2. 业务概念

| 概念 | 说明 |
|------|------|
| **管理员** | 可登录 **平台管理端** 的后台用户 |
| **管理员名称** | 对外展示用名称；**优先** 用户昵称，无昵称时用登录名（与 RuoYi 用户管理习惯一致） |
| **登录名** | 平台登录账号（用户名称）；新增时必填；**全平台唯一** |
| **手机号 / 邮箱** | 联系方式；手机号 **建议必填**；格式校验 |
| **头像** | 可选；用于平台端展示 |
| **角色名称** | 管理员已分配的 **列表范围内角色** 展示名；一人可多角色，列表 **聚合展示**（如「超级管理员、商户经营」） |
| **添加时间** | 该管理员账号 **首次创建** 时间 |
| **列表范围角色（草稿 §5）** | 列表仅展示已分配 **权限字符为 `admin`（超级管理员）** 或 **`merchant`（商户经营）** 的用户；**不含** 仅具 **member**（买家）角色的用户 |
| **merchant 经营角色** | 商户入驻绑定与平台侧经营用；**仅 merchant** 的用户 **纳入** 本列表；可与 `admin` 并存 |

---

## 3. 功能结构

```text
管理员列表（平台 · 权限管理）
├── 管理员列表（含检索）
├── 添加管理员
├── 编辑管理员
└── 删除管理员（单独 / 批量）
```

---

## 4. 管理员列表

### 4.1 列表字段（定稿 · 对齐草稿）

| 字段 | 说明 |
|------|------|
| 管理员名称 | 见 §2；列表主展示列 |
| 手机号 | 完整或按平台脱敏规则展示 |
| 邮箱 | 无则显示「—」 |
| 角色名称 | 已分配 **admin/merchant** 角色名称；多角色 **顿号或逗号** 连接 |
| 添加时间 | 创建时间，日期时间格式 |
| 操作 | **编辑**、**删除**（见 §7） |

### 4.2 列表行为

| 项 | 规则 |
|----|------|
| 默认排序 | **添加时间** 倒序（最新在前） |
| 分页 | 支持分页 |
| 数据范围 | 仅 §2 列表范围（`admin`、`merchant`）；**不含** 已逻辑删除用户、**不含** 纯 member |
| 空态 | 无数据时友好提示 |

### 4.3 高级检索（定稿 · 对齐草稿）

| 检索项 | 规则 |
|--------|------|
| 管理员名称 | **模糊** 匹配管理员名称（昵称/登录名，以实现为准） |

可选扩展（非草稿强制，产品可二期）：按角色、手机号检索。

---

## 5. 添加管理员

### 5.1 表单字段（定稿 · 对齐草稿）

| 字段 | 必填 | 说明 |
|------|:----:|------|
| 管理员名称 | ✓ | 对应用户 **昵称**；用于列表与详情展示 |
| 登录名 | ✓ | 平台登录账号；**唯一**；创建后 **不可改**（与 RuoYi 惯例一致，若产品允许改登录名须单独立项） |
| 手机号 | ✓ | 格式校验；**未删除用户内唯一** |
| 邮箱 | — | 格式校验 |
| 头像 | — | 图片上传 |
| 角色 | ✓ | **至少选一个**；选项为 **`admin`、`merchant`**（草稿 §5）；**不可** 选 member |
| 初始密码 | ✓ | 新增时设置登录密码；强度规则与平台统一 |

### 5.2 提交与反馈

| 场景 | 行为 |
|------|------|
| 校验失败 | 字段级提示；不创建 |
| 登录名/手机号重复 | 阻断；提示已存在 |
| 成功 | 提示成功；返回列表；新记录 **添加时间** = 当前时间 |

### 5.3 与商户绑定的关系

- 本模块 **新增** 管理员时可直接分配 **merchant** 角色；创建后可在 **商户管理** 绑定为经营账号来源（见商户管理 §6.7）。
- **商户管理 · adminUserOptions** 检索范围与本列表 **merchant 用户子集一致**（均须具 `role_key=merchant`）。

---

## 6. 编辑管理员

### 6.1 可编辑内容

| 字段 | 可改 | 说明 |
|------|:----:|------|
| 管理员名称（昵称） | ✓ | |
| 登录名 | ✗ | 建议定稿 **不可改** |
| 手机号 | ✓ | 唯一性校验（排除自身） |
| 邮箱 | ✓ | |
| 头像 | ✓ | |
| 角色 | ✓ | 至少保留一个 **列表范围角色**（`admin` 或 `merchant`）；变更后立即影响菜单/商户绑定能力 |
| 登录密码 | — | **不在** 编辑表单改密；若需改密走独立「重置密码」能力（可二期，草稿未列则非本期） |

### 6.2 不可编辑 / 限制

| 项 | 规则 |
|----|------|
| 当前登录用户 **编辑自身** | 允许改昵称、手机、邮箱、头像；**不可** 通过本页移除自己的 **全部** 列表范围角色（防锁死） |
| 最后一个超级管理员 | **不可** 删除或 **降权** 至无任何 `admin` 类角色（防平台无管理员） |

---

## 7. 删除管理员

### 7.1 方式（定稿 · 对齐草稿）

| 方式 | 说明 |
|------|------|
| 单独删除 | 行操作「删除」 |
| 批量删除 | 列表勾选多条后批量删除 |

### 7.2 前置条件与阻断

| 条件 | 处理 |
|------|------|
| 删除 **当前登录用户自身** | **禁止**；提示不可删除自己 |
| 删除 **最后一个** 具备超级管理员（`admin`）权限的账号 | **禁止** |
| 该用户仍被 **商户经营账号** 引用（`biz_merchant_account.account_id=user_id`） | **建议禁止** 或提示须先在商户/店铺侧解绑 |
| 二次确认 | 单独/批量删除均须确认；批量可提示「删除后不可恢复」 |

### 7.3 删除效果

- 账号 **逻辑删除** 或 **停用**（与 RuoYi 用户管理策略一致）；删除后 **不再出现在** 本列表；
- **不自动** 删除商户、店铺、商品等业务数据；
- **不自动** 删除 C 端会员档案。

---

## 8. 与关联模块的协作

### 8.1 管理员列表 vs 账号管理（草稿）

| 维度 | 管理员列表（本模块） | 账号管理（草稿） |
|------|---------------------|------------------|
| 对象 | 平台后台 **管理员** | 商家 **经营账号** |
| 列表核心字段 | 角色名称、添加时间 | **店铺数** |
| 登录端 | 平台 Web | 商家端 |
| 新增字段 | 头像、**角色** | 改密、**店铺数** 统计 |

两模块 **菜单并列**，数据 **不混列表**。

### 8.2 与商户管理 · 绑定经营账号

```text
【路径 A · 本模块新建】
    管理员列表 → 添加用户（分配 admin 和/或 merchant）
        ↓
    商户管理 → 新增商户 → 绑定类型「平台管理员」→ 远程搜索该用户（须具 merchant）
        ↓
    创建 biz_merchant_account 关联行（account_id=user_id，shop_id=NULL）

【路径 B · 仅 merchant 用户】
    管理员列表 → 添加/维护仅 merchant 角色用户
        ↓
    出现在本列表；可被商户管理 adminUserOptions 检索并绑定
```

### 8.3 与会员管理

- **member** 角色用户 **仅** 出现在会员管理列表；
- 本模块 **不提供** 会员新增/禁用；**禁止** 在添加管理员时选择 member 角色。

---

## 9. 业务规则汇总

| 编号 | 规则 |
|------|------|
| A1 | 列表范围：**`admin`、`merchant`**（草稿 §5）；**不含** 纯 member |
| A2 | 新增须 **登录名 + 手机号 + 至少一个列表范围角色 + 初始密码** |
| A3 | 登录名、手机号在有效用户内 **唯一** |
| A4 | 列表默认按 **添加时间倒序** |
| A5 | 检索：**管理员名称** 模糊匹配 |
| A6 | **不可** 删除自己；**不可** 删除最后一个超级管理员 |
| A7 | 编辑角色变更 **立即** 生效于平台菜单权限 |
| A8 | 本模块 **不维护** 商家经营账号、**不维护** C 端会员 |
| A9 | 角色选项为 **`admin`、`merchant`**；本模块 **不创建** 新角色定义 |

---

## 10. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 列表页 | 检索区 + 表格 + 分页；工具栏 **添加管理员**、**批量删除** |
| 添加/编辑 | 弹窗或抽屉；角色 **多选**；头像上传可选 |
| 删除 | 二次确认；批量删除展示条数 |
| 角色展示 | 多角色聚合；过长 **省略号 + tooltip** |
| 权限 | 菜单 **权限管理 → 管理员列表**；按钮级权限与 RuoYi 惯例一致（list/add/edit/remove） |

---

## 11. 非本期

| 项 | 说明 |
|----|------|
| 角色/菜单权限树配置 | 沿用 RuoYi **系统管理 · 角色管理** |
| 商家端子管理员 CRUD | 见店铺设置上限；人员管理待建设 |
| 经营账号列表 | 见 **账号管理** 专册 |
| 管理员操作审计专册 | 可依赖 RuoYi 操作日志 |
| 导入/导出 Excel | 不做 |
| 部门/岗位（dept/post） | 若 RuoYi 自带则可选填，**非** 草稿强制字段 |

---

## 12. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.1** | 草稿 §5：`admin` + `merchant` 列表/表单范围；废止 `shop_admin` |
| **v1.0** | 首版：对齐草稿列表/添加/检索/编辑/删除；明确与账号管理/会员/商户边界 |

---

*文档版本：v1.1 · 关联《关联需求分析.md》v1.5、《会员管理功能需求.md》v1.0.1、《店铺管理功能需求.md》v1.3.5、《商户管理功能需求.md》v1.5*
