# 角色管理 — 功能需求说明

> 本文档在《角色管理功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》**、**《员工管理功能需求》** v1.1、**《管理员列表功能需求》**、**《账号管理功能需求》**（平台）及商家侧 **商品分类 / 商品管理** 做边界对齐。  
> 范围：**店铺经营管理端 · 账号管理** 对 **当前店铺下员工角色** 的列表、检索、创建、维护与删除，以及 **商家端功能权限** 配置。  
> **说明：** 本文档 **仅描述功能需求与业务规则**；不涉及数据库结构、接口定义及技术实现细节。  
> **v1.1：** 对齐草稿 §5～§6：列表按 **当前店铺**（`X-Shop-Id`）；角色名称 **店铺内** 唯一；补店铺上下文协作规则。  
> **v1.0：** 首版定稿；对齐草稿 §1～§7；补全与平台侧角色体系、员工管理的协作链。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **店铺经营管理端（Web）· 账号管理** 提供 **商户端角色（员工角色）** 管理能力，使 **商户经营账号** 能够：

- 浏览、检索 **当前店铺** 已创建的 **员工角色**；
- **创建** 角色，配置 **角色名称、角色描述、状态** 及 **商家端功能权限**；
- **编辑**、**删除** 角色；
- 为 **员工管理** 提供可绑定的 **当前店铺角色** 来源。

**不包含（本期或与它模块分工）：**

| 能力 | 说明 |
|------|------|
| **平台管理员角色 / 菜单** | 见 **平台 · 系统管理 · 角色管理**（RuoYi 平台端菜单树） |
| **平台管理员账号维护** | 见 **平台 · 管理员列表** |
| **商户经营账号 `merchant` 平台角色** | 由 **平台 · 商户入驻 / 管理员列表** 分配；**非** 本模块创建 |
| **员工账号 CRUD** | 见 **店铺后台 · 员工管理**；本模块 **只定义角色**，员工模块 **选用绑定** |
| **经营账号自助资料/改密** | 见 **店铺后台 · 账号设置**（待建设） |
| **C 端会员** | **无关** |

### 1.2 与草稿的对应关系

| 草稿条目 | 定稿规则 |
|----------|----------|
| §1 创建角色 | 角色名称、角色描述、功能权限；支持编辑、删除；定稿补 **状态**（与列表 §2 一致） |
| §2 列表字段 | 角色名称、角色描述、状态、操作 |
| §3 高级检索 | **仅** 按角色名称模糊检索 |
| §4 操作 | （1）修改角色：名称、描述、功能权限；（2）删除角色 |
| §5 数据范围 | 当前登录账号 **所属店铺 ID**（`X-Shop-Id`）下该店铺的 **全部有效角色** |
| §6 店铺上下文 | 登录时解析所属店铺 ID 写入 header；商户管理员默认最早店铺；切换店铺后更新 header |
| §7 异常返回 | 统一 `code`、`msg`、`data` |
| §8 技术栈 | **不纳入** 本文档 |

### 1.3 在权限链中的位置

```text
【平台侧 · 与本模块无交叉维护】
    RuoYi 系统管理 · 角色管理 ── 平台端菜单（admin / merchant 等）
    管理员列表 ── 为平台用户分配平台角色

【商家侧 · 本模块】
    角色管理（本模块）── 定义 **当前店铺**「员工角色」+ 商家端功能权限
            ↓
    员工管理 ── 创建/编辑员工时绑定 **当前店铺角色**
            ↓
    员工登录商家端 ── 按绑定角色访问菜单（商品分类、商品管理等）
```

| 角色类型 | 定义入口 | 绑定对象 | 登录端 |
|----------|----------|----------|--------|
| **平台角色**（admin、merchant 等） | 平台 · 角色管理 | 平台管理员、经营账号 | 平台端 / 商家端（经营账号） |
| **商户员工角色**（本模块） | **本模块** | **员工（子管理员）** | **商家端** |

### 1.4 使用端与角色

| 端 | 可操作角色 | 能力 |
|----|------------|------|
| **店铺经营管理端** | **商户经营账号** | 本模块全部能力 |
| **店铺经营管理端** | 员工（子管理员） | **默认不可** 管理角色；是否在商家端开放本模块由 **功能权限** 配置决定 |
| **平台管理端** | 平台管理员 | **不** 使用本模块 |
| **C 端** | — | **不可** 访问 |

---

## 2. 关联需求分析

### 2.1 与《关联需求分析》— 账号体系 §9.2

| 关联点 | 定稿 |
|--------|------|
| **历史表述** | §9.2 曾写子管理员「增删、权限分配非本期」 |
| **本期落地** | **员工管理** 负责人员 CRUD；**本模块** 负责 **权限分配（角色定义）** |
| **人数上限** | 仍在 **平台 · 店铺设置**；本模块 **不** 控制员工人数 |
| **协作** | 先有 **本商户角色**，再在员工管理中绑定 |

### 2.2 与《员工管理功能需求》— 消费方

| 项 | 定稿 |
|----|------|
| 分工 | **本模块** 维护角色；**员工管理** 在创建/编辑时 **选用** 角色 |
| 范围 | 员工 **仅可绑定当前店铺已有角色**（员工需求 EM4） |
| 数量 | 员工至少绑定 **一个** 有效角色 |
| 角色变更 | 编辑角色权限后，**已绑定该角色的员工** 权限 **即时生效**（下次请求/刷新菜单） |
| 删除协作 | 角色 **已被员工绑定** 时 **不可删除**（见 §11） |
| 停用协作 | 角色 **停用** 后 **不可** 再绑定新员工；已绑定员工见 §12 |

### 2.3 与平台《管理员列表》— 边界

| 项 | 定稿 |
|----|------|
| 平台角色 | `admin`、`merchant` 等由 **平台** 维护；**不出现在** 本模块列表 |
| 本模块角色 | **仅** 供 **商家端员工** 使用；**不可** 分配 `admin` / `merchant` 平台权限包 |
| 列表互斥 | 平台管理员列表 **不含** 商户员工角色；本模块 **不含** 平台角色 |

### 2.4 与平台《账号管理》— 边界

| 项 | 定稿 |
|----|------|
| 数据主体 | 平台统览 **sys_user**；本模块统览 **本商户员工角色** |
| 交叉 | 员工作为用户可在平台账号管理检索；**角色定义** 不在平台侧完成 |

### 2.5 与商家侧《商品分类 / 商品管理》— 权限消费

| 项 | 定稿 |
|----|------|
| 操作主体 | 「店铺管理员」含经营账号与 **已授权子管理员** |
| 本模块作用 | 通过 **功能权限** 控制员工能否进入 **商品分类、商品管理** 等商家端菜单 |
| 数据范围 | 员工仅能操作 **当前店铺** 数据（须 **切换当前店铺**）；权限只控制 **能否进入菜单**，**不** 改变店铺数据隔离规则 |
| 平台菜单 | **平台商品分类** 等 **平台端** 菜单 **不可** 授予商户员工角色 |

### 2.6 与《店铺设置》— 子管理员上限

| 项 | 定稿 |
|----|------|
| 关系 | **间接**；上限限制 **员工人数**，**不限制** 本商户可创建的角色 **个数** |
| 说明 | 商户可预先创建多个角色模板，再分配给不超过上限的员工 |

---

## 3. 业务概念

| 概念 | 说明 |
|------|------|
| **商户** | 入驻主体；当前登录 **商户经营账号** 所属商户 |
| **当前店铺** | 登录后 `X-Shop-Id` 标识的店铺；列表、创建、名称唯一均以此为准 |
| **店铺员工角色** | 本模块创建、**归属当前店铺** 的角色，用于分配给员工 |
| **角色名称** | 展示用名称；**同一店铺内** 不可重复 |
| **角色描述** | 说明该角色职责；选填 |
| **状态** | **正常** / **停用** |
| **功能权限** | 该角色在 **商家端** 可访问的 **菜单与按钮** 集合（权限树勾选） |
| **商家端菜单范围** | 仅 **店铺经营管理端** 相关菜单（如商品分类、商品管理、员工管理等）；**不含** 平台管理端菜单 |
| **已绑定员工** | 在 **员工管理** 中已关联该角色的员工账号 |

---

## 4. 功能结构

```text
角色管理（店铺 · 账号管理）
├── 角色列表（含检索）
├── 创建角色（名称、描述、状态、功能权限）
├── 编辑角色（名称、描述、状态、功能权限）
└── 删除角色
```

---

## 5. 角色列表

### 5.1 列表范围

- **纳入：** 当前 **所属店铺**（`X-Shop-Id`）下 **全部有效** 员工角色；
- **排除：** 已删除角色；**其他店铺** 角色；**平台角色**；
- **排序：** 默认按 **创建时间倒序**；
- **上下文：** 展示 **当前店铺名称**（只读）。

### 5.2 列表字段

| 字段 | 说明 |
|------|------|
| 角色名称 | 主展示列 |
| 角色描述 | 无则展示「—」 |
| 状态 | **正常** / **停用** |
| 操作 | 修改角色、删除（见 §5.3） |

> **可选扩展（非草稿强制）：** 展示 **已绑定员工数**，便于删除前判断。

### 5.3 列表操作

| 操作 | 说明 |
|------|------|
| **修改角色** | 见 §9 |
| **删除** | 见 §11 |

---

## 6. 高级检索

| 检索项 | 规则 |
|--------|------|
| 角色名称 | **仅此一项**；模糊匹配 |

- 清空条件后恢复默认列表。

---

## 7. 创建角色

### 7.1 表单字段（对齐草稿 §1）

| 字段 | 必填 | 规则 |
|------|:----:|------|
| 角色名称 | 是 | 非空；**同一店铺内** 不可与已有角色重复 |
| 角色描述 | 否 | 长度合理 |
| 状态 | 是 | 默认 **正常** |
| 功能权限 | 是 | 至少勾选 **一项** 商家端菜单或按钮权限 |

### 7.2 功能权限范围

| 规则 | 说明 |
|------|------|
| 菜单树范围 | **仅商家端** 菜单（店铺经营管理端）；树形展示，支持 **菜单 + 按钮** 级勾选 |
| 不可授予 | **平台管理端** 任意菜单；**admin / merchant** 等平台级预置权限包 |
| 典型可选项 | 商品分类、商品管理、店铺资料、员工管理、角色管理等（以实际上线商家端菜单为准） |
| 父子联动 | 勾选子菜单时 **须** 含必要上级菜单；取消上级时 **同步** 取消下级（与 RuoYi 权限树交互一致） |

### 7.3 创建流程

```text
商户经营账号进入「角色管理」
    → 点击「创建角色」
    → 填写名称、描述、状态，勾选功能权限
    → 校验（名称店铺内唯一、至少一项权限）
    → 保存成功 → 列表刷新
    → 该角色可在「员工管理 · 绑定角色」中被选用（**当前店铺**）
```

---

## 8. 编辑角色

### 8.1 可编辑字段

| 字段 | 规则 |
|------|------|
| 角色名称 | 必填；**店铺内** 唯一（排除自身） |
| 角色描述 | 选填 |
| 状态 | 正常 ↔ 停用 |
| 功能权限 | 至少保留 **一项**；不可改为空 |

### 8.2 编辑约束

- **仅当前店铺** 角色可编辑；
- 权限变更 **立即** 作用于 **已绑定该角色的员工**（RM7）；
- 将角色 **停用** 后：见 §12。

---

## 9. 修改角色（草稿 §4(1)）

与 **§8 编辑** 字段一致；列表操作 **「修改角色」** 打开编辑表单，至少包含：

| 字段 | 规则 |
|------|------|
| 角色名称 | 必填 |
| 角色描述 | 选填 |
| 功能权限 | 至少一项 |

若产品 **合并** 编辑入口，**修改角色** 与 **编辑** 为同一弹窗即可。

---

## 10. 功能权限与员工登录协作

```text
角色管理 ── 定义角色 A（仅商品分类）、角色 B（商品+分类）
      ↓
员工管理 ── 员工张三绑定角色 A
      ↓
张三登录商家端 → 选择当前店铺 → 仅见「商品分类」菜单
```

| 规则 | 说明 |
|------|------|
| 多角色 | 若员工绑定 **多个** 角色，权限为 **并集**（以员工管理定稿为准） |
| 经营账号 | **商户经营账号** 权限来自 **平台 merchant 角色**，**不在** 本模块配置 |
| 无权限 | 员工若被解绑全部角色或角色权限为空，**不可** 正常访问商家端业务菜单 |

---

## 11. 删除角色（草稿 §4(2)）

### 11.1 规则

| 项 | 规则 |
|----|------|
| 可删对象 | **当前店铺** 员工角色 |
| 不可删 | **已被员工绑定** 的角色；**平台预置** 角色（若存在归属本商户的预置项，亦不可删） |
| 删除方式 | **逻辑删除**；删除后 **不再出现在列表**，**不可** 再被员工绑定 |
| 确认 | **二次确认** |

### 11.2 删除前校验

| 场景 | 处理 |
|------|------|
| 存在已绑定员工 | 失败；提示「该角色已分配给员工，请先解除绑定或调整员工角色」 |
| 无绑定 | 允许删除 |

---

## 12. 停用与启用

| 状态 | 新员工绑定 | 已绑定员工 | 列表展示 |
|------|:----------:|:----------:|----------|
| **正常** | 可 | 按权限访问商家端 | 展示 |
| **停用** | **不可** | 见下表 | 展示 |

**已绑定员工 + 角色停用：**

| 定稿策略 | 说明 |
|----------|------|
| **推荐（RM8）** | 停用后 **已绑定员工立即失去** 该角色贡献的权限（若仅剩该角色且无其他有效角色，则 **无商家端业务菜单**） |
| 绑定入口 | **员工管理** 创建/编辑时 **不可再选** 停用角色 |

启用停用角色前 **无须** 额外配额校验（角色数不受店铺设置上限约束）。

---

## 13. 业务流程总览

### 13.1 端到端协作

```text
【平台】店铺设置 ── 子管理员人数上限
【商户端】角色管理 ── 创建「店员」「店长」等角色 + 功能权限
            ↓
【商户端】员工管理 ── 创建员工并绑定角色
            ↓
【员工】登录商家端 → 选当前店铺 → 按角色操作商品/分类等
```

### 13.2 与平台权限链并行

```text
平台角色管理 ── admin / merchant（平台端）
                    ↓
              经营账号登录商家端（merchant 平台角色）

商户角色管理 ── 本商户员工角色（商家端菜单）
                    ↓
              员工登录商家端（本模块定义的角色）
```

---

## 14. 校验与提示

| 场景 | 提示要点 |
|------|----------|
| 非经营账号访问 | 仅商户经营账号可管理角色 |
| 角色名重复 | 该角色名称已存在 |
| 未选功能权限 | 请至少选择一项功能权限 |
| 删除已绑定角色 | 该角色已分配给员工，请先解除绑定 |
| 未选店铺 | 请先选择当前店铺 |
| 跨店铺操作 | 只能管理当前店铺的角色 |
| 响应格式 | 统一 **code、msg、data**（草稿 §6） |

---

## 15. 业务规则汇总

| 编号 | 规则 |
|------|------|
| RM1 | 列表 = **当前店铺**（`X-Shop-Id`）下 **全部有效** 员工角色 |
| RM2 | **仅商户经营账号** 可创建、编辑、删除角色 |
| RM3 | 检索 **仅角色名称** |
| RM4 | 创建/编辑须 **至少一项** 商家端功能权限 |
| RM5 | 功能权限 **仅商家端菜单**；**不可** 含平台管理端权限 |
| RM6 | 角色名称 **同一店铺内** 不可重复 |
| RM7 | 编辑权限后 **已绑定员工即时生效** |
| RM8 | 角色 **停用** 后不可新绑；已绑定员工 **失去该角色权限贡献** |
| RM9 | **已绑定员工** 的角色 **不可删除** |
| RM10 | 本模块角色 **供员工管理选用**；**不可** 替代平台 admin/merchant 角色 |
| RM11 | 角色个数 **不受** 子管理员人数上限约束 |
| RM12 | 须携带 **`X-Shop-Id`**；切换店铺后列表范围随之变化 |
| RM13 | 响应格式：**code、msg、data** |

---

## 16. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.1** | 对齐草稿 §5～§6：列表按当前店铺、名称店铺内唯一、`X-Shop-Id` 店铺上下文 |
| **v1.0** | 首版定稿：对齐草稿 §1～§7；关联员工管理、平台管理员列表、商品模块及 §9.2 协作链 |

---

*文档版本：v1.1 · 关联《角色管理功能需求-草稿》· 商家侧见《员工管理功能需求.md》v1.2*
