# 5.7 角色管理

本文档从《基础平台产品设计》第 5 章拆分而来，用于独立描述基础平台功能模块的业务需求、规则和验收标准。

上级文档：[基础平台产品设计](../基础平台产品设计.md)

## 5.7.1 功能说明

角色管理用于将应用、菜单、菜单操作权限和数据范围组合成可分配给用户的权限集合。

角色不是用户基础信息。用户基础信息只维护自然人档案、所属组织和默认组织；用户能访问什么应用、菜单、操作和数据，由用户被分配的角色决定。

应用管理负责定义应用、菜单和菜单下的操作权限；角色管理负责引用这些已定义能力进行授权；用户与账号管理负责把角色分配给具体用户。

## 5.7.2 功能范围

- 查询角色列表
- 查看角色详情
- 新增角色
- 编辑角色
- 复制角色
- 启用 / 停用角色
- 配置角色菜单权限
- 配置角色操作权限
- 配置角色数据范围
- 查看已分配用户
- 查看角色操作记录

## 5.7.3 字段要求

角色基础信息至少包括：

| 字段 | 说明 | 是否必填 |
| --- | --- | --- |
| 所属客户 | 角色归属客户；平台角色可为空或归属平台 | 条件必填 |
| 角色名称 | 角色展示名称 | 是 |
| 角色编码 | 角色唯一编码 | 是 |
| 角色类型 | 平台角色、客户角色、应用角色 | 是 |
| 所属应用 | 应用角色归属应用 | 条件必填 |
| 角色来源 | 系统预置、自定义 | 是 |
| 是否角色模板 | 是否可作为应用开通后的默认角色模板 | 是 |
| 角色说明 | 角色用途说明 | 否 |
| 启用状态 | 启用、停用 | 是 |
| 创建时间 | 角色创建时间 | 是 |
| 更新时间 | 角色最近更新时间 | 是 |

### 5.7.3.1 角色编码规则

角色编码用于系统识别、权限计算、日志追踪和接口返回，不作为页面主要展示名称。

编码规则：

- 平台角色编码在基础平台全局唯一。
- 客户角色编码在同一客户下唯一。
- 应用角色编码在同一应用下唯一。
- 编码建议采用大写英文字母、数字和下划线组合。
- 系统预置角色编码创建后原则上不允许修改。
- 自定义角色编码创建后原则上不允许修改，避免影响权限引用和日志追踪。

编码示例：

| 角色类型 | 编码示例 | 说明 |
| --- | --- | --- |
| 平台角色 | PLATFORM_ADMIN | 平台超级管理员 |
| 客户角色 | CUSTOMER_ADMIN | 客户管理员 |
| 应用角色 | RECON_FINANCE | 连锁业务对账系统财务角色 |

## 5.7.4 角色类型

基础平台 1.0 支持以下角色类型：

| 角色类型 | 定义 | 维护主体 | 适用范围 |
| --- | --- | --- | --- |
| 平台角色 | 平台内部管理角色 | 平台超级管理员 | 平台管理、客户管理、应用管理、运维管理等平台级功能 |
| 客户角色 | 客户内部通用角色 | 客户管理员 / 实施人员 | 客户下多应用、多组织用户 |
| 应用角色 | 面向某个应用的角色 | 产品管理员 / 客户管理员 | 指定应用下的菜单、操作和数据范围 |

业务说明：

- 平台角色主要用于公司内部平台管理人员，不直接面向客户普通业务用户。
- 客户角色用于客户内部通用管理场景，例如客户管理员、总部财务、区域运营等。
- 应用角色用于某个业务系统内的权限组合，例如对账财务、分账运营、客服主管等。
- 督导不是组织类型，也不是用户基础字段；督导可以作为客户角色或应用角色维护，并通过数据范围配置其负责门店。

## 5.7.5 权限配置

### 5.7.5.1 菜单权限

菜单权限用于控制用户能否在基础平台门户中看到对应菜单，并进入对应业务页面。

业务规则：

- 菜单来源于应用管理中已启用的应用菜单。
- 客户未开通的应用，不可为客户角色授权该应用菜单。
- 停用应用下的菜单不可授权。
- 停用菜单不可授权。
- 授权子菜单时，系统应自动包含其上级菜单的展示权限，保证菜单路径完整。
- 取消上级菜单权限时，应提示是否同步取消下级菜单和操作权限。

### 5.7.5.2 操作权限

操作权限用于控制用户在某个菜单或页面下可执行的具体动作。

业务规则：

- 操作权限来源于应用管理中菜单下配置的操作权限。
- 操作权限必须依附于具体菜单或页面。
- 不允许脱离菜单单独授权操作权限。
- 用户未获得菜单权限时，不可单独获得该菜单下操作权限。
- 菜单下操作权限停用后，不可继续用于新增角色授权。
- 已被角色引用的操作权限停用时，需要在角色权限配置中展示停用状态，并提示管理员处理。

### 5.7.5.3 数据范围

数据范围用于控制用户可查看或操作的数据边界。

基础平台 1.0 支持以下数据范围：

| 数据范围 | 说明 | 选择要求 |
| --- | --- | --- |
| 全部数据 | 当前客户下全部授权数据 | 仅平台角色、客户高权限角色可选 |
| 本组织及下级组织 | 用户默认组织及下级组织数据 | 无需手工选择组织 |
| 本组织 | 用户默认组织数据 | 无需手工选择组织 |
| 指定组织 | 指定组织及可选下级范围 | 需要选择组织 |
| 指定门店 | 指定门店数据 | 需要选择门店 |
| 本人数据 | 用户本人创建、负责或被分配的数据 | 无需手工选择组织 |

业务规则：

- 数据范围必须按客户隔离。
- 指定组织来源于组织管理中的启用组织。
- 指定门店来源于组织管理中组织类型为门店的启用组织，左侧管理组织树默认不展示门店，但数据范围选择器需要支持门店检索和选择。
- 督导负责区域下部分门店时，数据范围应配置为指定门店，或配置为指定组织并明确是否包含下级门店。
- 角色未配置数据范围时，不应默认授予全部数据。
- 多角色用户的数据范围按授权范围合并，但不得突破客户隔离边界。

## 5.7.6 业务规则

- 角色必须归属于平台或某个客户。
- 客户角色只能在所属客户内使用。
- 应用角色必须归属于一个应用。
- 客户未开通某应用时，不可给该客户角色授权该应用菜单和操作权限。
- 系统预置角色可复制为自定义角色。
- 系统预置角色是否允许编辑由平台配置控制；1.0 建议只允许复制，不直接编辑核心预置角色。
- 自定义角色可编辑角色名称、说明、菜单权限、操作权限和数据范围。
- 已分配给用户的角色停用后，该角色权限对用户失效。
- 角色停用后不可继续分配给新用户。
- 停用角色不删除历史分配记录和操作日志。
- 删除角色不作为 1.0 必备能力；如需取消使用，通过停用处理。
- 用户拥有多个角色时，菜单权限和操作权限取并集。
- 用户拥有多个角色时，数据范围按角色授权范围合并。
- 权限变更后，用户下次刷新菜单、获取当前用户信息或 Token 重新鉴权时应获得最新权限结果。

## 5.7.7 界面设计

### 5.7.7.1 功能入口与访问权限

角色管理作为基础平台的客户内管理功能，建议放置在基础平台左侧菜单：

```text
基础平台
└── 角色管理
```

页面访问规则：

- 平台超级管理员、实施人员、具备角色管理权限的平台用户可维护平台角色和客户角色。
- 客户管理员只能维护本客户下客户角色和应用角色。
- 产品管理员可维护其负责应用的应用角色模板。
- 普通业务用户不可访问角色管理页面。
- 无角色管理权限的用户不展示角色管理菜单。

### 5.7.7.2 角色列表页

点击基础平台 > 角色管理后，进入角色列表页。

展示方式：

- 平台用户进入页面后，顶部展示客户选择器和角色查询条件。
- 客户管理员或归属于某个客户的用户进入页面后，系统默认当前客户，不展示客户查询条件。
- 角色列表采用查询区域 + 数据表格展示。
- 查询条件较多时支持展开 / 收起。
- 查询按钮作为查询区域最后一个表单元素。

简化版原型图：

```text
┌──────────────────────────────────────────────────────────────────────────────┐
│ 基础平台 > 角色管理                                          [新增角色]     │
├──────────────────────────────────────────────────────────────────────────────┤
│ 客户：[客户选择器/当前客户只读]  角色名称：[      ]  角色编码：[      ]      │
│ 角色类型：[全部 v]  所属应用：[全部 v]  启用状态：[全部 v]  [查询] [重置]   │
├──────────────────────────────────────────────────────────────────────────────┤
│ 角色列表                                                                     │
│ ┌────────────┬────────────┬────────┬────────────┬────────┬────────┐        │
│ │ 角色名称   │ 角色编码   │ 类型   │ 所属应用   │ 状态   │ 操作   │        │
│ ├────────────┼────────────┼────────┼────────────┼────────┼────────┤        │
│ │ 客户管理员 │ CUSTOMER...│ 客户   │ -          │ 启用   │ 查看   │        │
│ │ 对账财务   │ RECON_FIN  │ 应用   │ 对账系统   │ 启用   │ 编辑   │        │
│ └────────────┴────────────┴────────┴────────────┴────────┴────────┘        │
│                                                            < 1 / 20 >        │
└──────────────────────────────────────────────────────────────────────────────┘
```

查询条件：

| 查询项 | 控件类型 | 值来源 / 录入方式 | 说明 |
| --- | --- | --- | --- |
| 所属客户 | 客户选择器 / 只读文本 | 客户管理中已启用客户 | 平台用户选择；客户管理员只读当前客户 |
| 角色名称 | 文本输入框 | 人工录入 | 支持模糊查询 |
| 角色编码 | 文本输入框 | 人工录入 | 支持精确或模糊查询 |
| 角色类型 | 下拉框 | 平台角色、客户角色、应用角色 | 可为空 |
| 所属应用 | 下拉框 | 当前客户已开通应用 / 平台全部应用 | 可为空 |
| 启用状态 | 下拉框 | 全部、启用、停用 | 默认全部 |
| 查询 | 按钮 | 用户点击 | 作为查询区域最后一个表单元素 |

列表字段：

| 字段 | 说明 |
| --- | --- |
| 角色名称 | 角色展示名称 |
| 角色编码 | 角色编码 |
| 所属客户 | 平台用户查看时展示 |
| 角色类型 | 平台角色、客户角色、应用角色 |
| 所属应用 | 应用角色展示所属应用 |
| 角色来源 | 系统预置、自定义 |
| 是否角色模板 | 是、否 |
| 启用状态 | 启用、停用 |
| 已分配用户数 | 当前角色已分配用户数量 |
| 更新时间 | 最近更新时间 |
| 操作 | 查看、编辑、复制、配置权限、启用、停用 |

### 5.7.7.3 角色新增 / 编辑页

角色新增 / 编辑页用于创建或维护角色基础信息。新增和编辑使用同一个页面或弹窗，根据操作模式控制默认值、只读字段和保存规则。

展示方式：

- 采用表单方式展示。
- 只维护角色基础信息。
- 不在新增 / 编辑页直接配置菜单权限、操作权限和数据范围。
- 角色保存后，在角色详情页下方页签中配置权限和数据范围。

表单字段：

| 字段 | 控件类型 | 值来源 / 录入方式 | 说明 |
| --- | --- | --- | --- |
| 所属客户 | 客户选择器 / 只读文本 | 客户管理中已启用客户 | 平台角色可为空；客户管理员只读当前客户 |
| 角色名称 | 文本输入框 | 人工录入 | 必填 |
| 角色编码 | 文本输入框 | 人工录入 / 系统生成 | 必填，按角色类型校验唯一性 |
| 角色类型 | 下拉框 | 平台角色、客户角色、应用角色 | 必填 |
| 所属应用 | 下拉框 | 应用管理中已启用应用 | 应用角色必填 |
| 角色来源 | 只读文本 | 新增默认为自定义 | 系统预置角色由系统生成 |
| 是否角色模板 | Switch | 人工选择 | 默认否 |
| 启用状态 | Switch | 人工选择 | 默认启用 |
| 角色说明 | 多行文本框 | 人工录入 | 选填 |

新增模式规则：

- 角色名称、角色编码、角色类型、启用状态为必填。
- 客户角色必须选择所属客户。
- 应用角色必须选择所属应用。
- 客户管理员新增角色时，所属客户默认为当前客户且不可修改。
- 新增角色时不直接分配用户。
- 新增角色时不直接配置权限，保存后进入角色详情页配置。

编辑模式规则：

- 角色编码、角色类型、角色来源原则上只读。
- 系统预置角色是否允许编辑，由平台配置控制。
- 已分配用户数大于 0 的角色，编辑权限或数据范围时需要提示影响范围。
- 停用角色时需要提示该角色已分配用户数量和权限失效影响。

### 5.7.7.4 角色详情页

角色详情页用于查看角色基础信息、配置权限、配置数据范围、查看已分配用户和操作记录。

展示方式：

- 上方为角色基础信息只读区。
- 下方为 Tab 页签。
- Tab 页签包括：菜单权限、数据范围、已分配用户、操作记录。

详情页区域：

| 区域 | 展示方式 | 主要内容 |
| --- | --- | --- |
| 上方基础信息区 | 只读信息区 | 角色名称、角色编码、角色类型、所属客户、所属应用、启用状态、已分配用户数 |
| 下方页签区 | Tab 页签 | 菜单权限、数据范围、已分配用户、操作记录 |

详情页主操作按钮：

- 编辑角色
- 复制角色
- 配置权限
- 配置数据范围
- 启用角色
- 停用角色

### 5.7.7.5 菜单权限配置页签

菜单权限配置页签用于维护角色可访问的应用菜单和菜单下操作权限。

展示方式：

- 采用应用选择器 + 菜单树形表格展示。
- 菜单树按应用分组展示。
- 菜单节点支持勾选菜单权限。
- 菜单节点下展示该菜单可授权的操作权限复选框。

字段与控件：

| 字段 | 控件类型 | 值来源 / 录入方式 | 说明 |
| --- | --- | --- | --- |
| 应用 | 下拉框 / 应用分组 | 当前客户已开通且启用的应用 | 客户角色可多应用；应用角色限定所属应用 |
| 菜单树 | 树形表格 + 复选框 | 应用管理中已启用菜单 | 勾选菜单访问权限 |
| 操作权限 | 复选框组 | 菜单下已启用操作权限 | 勾选查看、新增、编辑、审核、导出等操作 |

页面规则：

- 客户未开通应用时，不展示该应用菜单。
- 应用角色只展示所属应用菜单。
- 勾选操作权限时，系统自动勾选对应菜单权限。
- 取消菜单权限时，系统提示是否同步取消该菜单下操作权限。
- 保存后，已分配该角色的用户权限在重新获取权限时生效。
- 权限配置变更需要记录操作日志。

### 5.7.7.6 数据范围配置页签

数据范围配置页签用于维护角色对应的数据访问边界。

展示方式：

- 采用表单 + 组织 / 门店选择器展示。
- 数据范围类型使用单选框。
- 指定组织、指定门店根据所选数据范围展示对应选择器。

字段与控件：

| 字段 | 控件类型 | 值来源 / 录入方式 | 说明 |
| --- | --- | --- | --- |
| 数据范围类型 | 单选框 | 全部数据、本组织及下级组织、本组织、指定组织、指定门店、本人数据 | 必填 |
| 指定组织 | 树形多选器 | 当前客户启用组织树 | 选择指定组织时展示 |
| 是否包含下级组织 | Switch | 人工选择 | 指定组织时可配置 |
| 指定门店 | 门店选择器 / 表格多选 | 当前客户启用门店 | 选择指定门店时展示 |
| 数据范围说明 | 多行文本框 | 人工录入 | 选填 |

页面规则：

- 数据范围类型必填。
- 指定组织时，至少选择一个组织。
- 指定门店时，至少选择一个门店。
- 指定门店选择器需要支持按门店名称、门店编码、所属区域查询。
- 普通客户角色默认不允许选择全部数据，除非具备高权限授权。
- 保存后，已分配该角色的用户数据范围在重新获取权限时生效。
- 数据范围变更需要记录操作日志。

### 5.7.7.7 已分配用户页签

已分配用户页签用于查看当前角色已被哪些用户使用。

展示方式：

- 采用查询区域 + 数据表格展示。

查询条件：

| 查询项 | 控件类型 | 值来源 / 录入方式 | 说明 |
| --- | --- | --- | --- |
| 用户姓名 | 文本输入框 | 人工录入 | 支持模糊查询 |
| 手机号 | 文本输入框 | 人工录入 | 支持模糊查询 |
| 所属组织 | 树形选择器 | 当前客户组织树和门店选择器 | 可为空 |
| 用户状态 | 下拉框 | 全部、启用、停用 | 默认全部 |

列表字段：

| 字段 | 说明 |
| --- | --- |
| 用户姓名 | 用户显示姓名 |
| 手机号 | 用户手机号 |
| 默认组织 | 用户默认组织 |
| 用户状态 | 启用、停用 |
| 分配人 | 执行角色分配的用户 |
| 分配时间 | 角色分配时间 |

页面规则：

- 已分配用户页签只做查看，不在此处直接分配或移除用户角色。
- 用户角色分配和移除在用户与账号管理中完成。

### 5.7.7.8 操作记录页签

操作记录页签用于查看角色相关关键操作。

展示方式：

- 采用数据表格展示。

列表字段：

| 字段 | 说明 |
| --- | --- |
| 操作时间 | 操作发生时间 |
| 操作人 | 执行操作的用户 |
| 操作类型 | 新增、编辑、复制、启用、停用、配置菜单权限、配置操作权限、配置数据范围 |
| 操作内容 | 操作摘要 |
| 操作说明 | 操作原因或备注 |

## 5.7.8 使用导航

### 5.7.8.1 查询角色

操作路径：

```text
基础平台 > 角色管理
```

操作步骤：

1. 进入角色列表页。
2. 平台用户选择客户；客户管理员和客户内用户默认当前客户，不展示客户查询条件。
3. 按角色名称、角色编码、角色类型、所属应用或启用状态查询。
4. 在角色列表中查看角色。

### 5.7.8.2 新增角色

操作路径：

```text
基础平台 > 角色管理 > 角色新增 / 编辑页
```

操作步骤：

1. 进入角色列表页。
2. 点击新增角色。
3. 系统打开角色新增 / 编辑页，并进入新增模式。
4. 填写角色名称、角色编码。
5. 选择角色类型。
6. 如为客户角色，选择所属客户。
7. 如为应用角色，选择所属应用。
8. 设置是否角色模板、启用状态和角色说明。
9. 保存角色。
10. 系统创建角色并记录操作日志。
11. 进入角色详情页配置菜单权限和数据范围。

### 5.7.8.3 编辑角色

操作路径：

```text
基础平台 > 角色管理 > 角色新增 / 编辑页
```

操作步骤：

1. 进入角色列表页。
2. 查询并选择目标角色。
3. 点击编辑角色。
4. 系统打开角色新增 / 编辑页，并进入编辑模式。
5. 修改角色名称、是否角色模板、启用状态或角色说明。
6. 保存修改。
7. 系统刷新角色详情并记录操作日志。

### 5.7.8.4 配置菜单权限和操作权限

操作路径：

```text
基础平台 > 角色管理 > 角色详情 > 菜单权限
```

操作步骤：

1. 进入角色详情页。
2. 打开菜单权限页签。
3. 选择应用或查看应用分组。
4. 在菜单树中勾选角色可访问菜单。
5. 在菜单节点下勾选可授权操作权限。
6. 保存权限配置。
7. 系统刷新菜单权限页签并记录操作日志。

### 5.7.8.5 配置数据范围

操作路径：

```text
基础平台 > 角色管理 > 角色详情 > 数据范围
```

操作步骤：

1. 进入角色详情页。
2. 打开数据范围页签。
3. 选择数据范围类型。
4. 如选择指定组织，选择组织并设置是否包含下级组织。
5. 如选择指定门店，按门店名称、门店编码或所属区域查询并选择门店。
6. 保存数据范围。
7. 系统刷新数据范围页签并记录操作日志。

### 5.7.8.6 复制角色

操作路径：

```text
基础平台 > 角色管理 > 角色列表 / 角色详情 > 复制角色
```

操作步骤：

1. 查询并选择目标角色。
2. 点击复制角色。
3. 系统打开角色新增 / 编辑页，并带入原角色基础信息、菜单权限、操作权限和数据范围。
4. 修改角色名称和角色编码。
5. 保存角色。
6. 系统创建新角色并记录操作日志。

### 5.7.8.7 启用 / 停用角色

操作路径：

```text
基础平台 > 角色管理 > 角色列表 / 角色详情 > 启用 / 停用
```

操作步骤：

1. 查询并选择目标角色。
2. 点击启用或停用。
3. 停用角色时，系统提示已分配用户数量和权限失效影响。
4. 确认操作。
5. 系统更新角色状态并记录操作日志。

停用影响：

- 角色不可继续分配给新用户。
- 已分配该角色的用户不再获得该角色对应菜单、操作和数据范围。
- 历史角色分配记录和操作日志不删除。

## 5.7.9 验收标准

- 可按客户查询角色列表。
- 平台用户可选择客户查看角色；客户管理员只能查看和维护本客户角色。
- 客户管理员和客户内用户进入角色列表页时，默认当前客户，不展示客户查询条件。
- 可新增、编辑、复制、启用、停用角色。
- 用户基础信息中不维护角色，角色通过用户详情页分配。
- 角色编码按角色类型和归属范围校验唯一性。
- 平台角色、客户角色、应用角色的适用范围正确。
- 应用角色必须归属于一个应用。
- 客户未开通应用时，不可为该客户角色授权该应用菜单和操作权限。
- 菜单权限来源于应用管理中的启用菜单。
- 操作权限来源于应用管理中菜单下的启用操作权限。
- 不允许脱离菜单单独授权操作权限。
- 勾选操作权限时，系统自动具备对应菜单权限。
- 可配置数据范围：全部数据、本组织及下级组织、本组织、指定组织、指定门店、本人数据。
- 指定组织和指定门店的数据范围选择器可正常选择和保存。
- 督导负责部分门店时，可通过指定门店或指定组织数据范围授权。
- 角色停用后不可继续分配给新用户。
- 角色停用后，已分配用户不再获得该角色权限。
- 多角色用户菜单权限和操作权限按并集生效。
- 多角色用户数据范围按授权范围合并，且不突破客户隔离。
- 角色新增、编辑、复制、启用、停用、菜单权限配置、操作权限配置、数据范围配置均生成操作日志。