# 权限管理 UI 设计文档

> **任务编号**：08（P0-C）  
> **覆盖范围**：`US-PERMISSION-001 ~ US-PERMISSION-005`  
> **输出文件**：`UI_DESIGN/权限管理_UI.html`  
> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（后台壳层、筛选区、表格、分页、Modal/Drawer）  
> **需求依据**：
> - `PRD/TASK.md`（US-PERMISSION-001~005）
> - `PRD/权限管理/权限管理模块PRD.md`
> - `DATA_MODEL/DATA_MODEL_PERMISSION.md`
> - `PRD/权限管理/首页.md`
> - `PRD/权限管理/客源.md`
> - `PRD/权限管理/房源-二手租赁.md`
> **竞品截图参考**：
> - `screenshots/权限管理/权限管理-人员列表.png`
> - `screenshots/权限管理/权限管理-批量设置角色.png`
> - `screenshots/权限管理/权限管理-人员编辑特定权限.png`
> - `screenshots/权限管理/权限管理-修改个人权限-客源.png`
> - `screenshots/权限管理/角色管理-角色列表.png`
> - `screenshots/权限管理/角色管理-添加角色1.png`
> - `screenshots/权限管理/角色管理-修改角色.png`

---

## 1. 目标与范围

### 1.1 页面目标

本页用于完成权限管理模块 MVP 主链路：

1. **角色配置（US-PERMISSION-001）**
   - 角色列表（预设 + 自定义）
   - 新增自定义角色
   - 预设角色不可删
   - 可进入角色权限配置抽屉
2. **人员权限列表管理（US-PERMISSION-002）**
   - 按姓名/工号、部门、角色、职务检索
   - 列表展示角色、管理范围、不一致标记
3. **批量设置角色（US-PERMISSION-003）**
   - 勾选员工后批量赋角色
   - 覆盖个人权限提醒
4. **功能权限控制（US-PERMISSION-004）**
   - 人员权限编辑页支持模块级开关 + 权限项配置
   - 模块关闭时视为菜单隐藏
5. **数据权限控制（US-PERMISSION-005）**
   - 范围型权限（本人/本组/本门店/本区域/本大区/全公司）
   - 管理范围详情弹窗

### 1.2 任务边界

- ✅ 包含：权限管理 Tab、角色管理 Tab、批量角色弹窗、个人权限抽屉、权限项详情抽屉、角色新增弹窗、角色配置抽屉、范围详情弹窗、分页/空态/Toast
- ✅ 包含：必填校验、角色唯一性校验、预设角色删除限制、批量按钮禁用态
- ⛔ 不包含：真实权限后端、真实 Redis 失效、真实 403 路由拦截、真实日志系统

---

## 2. 信息架构

### 2.1 页面骨架

- **Top Bar**：系统一级导航（人事主入口高亮）
- **Sidebar**：组织人事二级菜单（权限管理高亮）
- **Main Content**：
  1. 面包屑：`人事OA / 组织人事 / 权限管理`
  2. 主 Tab：`权限管理`（人员维度）/ `角色管理`（角色维度）

### 2.2 权限管理 Tab（人员维度）

1. 筛选区
   - 姓名/工号
   - 员工部门
   - 角色
   - 职务名称
   - 权限与角色权限不一致（快捷筛选）
2. 操作区
   - 批量设置角色
   - 导出
3. 人员表格
   - 复选框、员工姓名、工号、部门、职务、角色、管理范围（详情）、操作
4. 行操作
   - 修改权限
   - 复制角色
   - 扩充范围
   - 范围
5. 分页区

### 2.3 角色管理 Tab（角色维度）

1. 筛选区
   - 角色名称
   - 角色类别
   - 修改时间范围
2. 操作区
   - 新增角色
   - 批量删除角色
3. 角色表格
   - 复选框、角色名称、角色类别、应用人数（查看）、引用角色、创建时间、修改时间、操作
4. 行操作
   - 编辑（进入角色权限配置）
   - 删除（预设角色禁删）
   - 修改日志

### 2.4 关键弹层

- 批量设置角色 Modal
- 新增角色 Modal
- 人员权限编辑 Drawer
- 权限项详情 Drawer（显示角色应用人数及名单）
- 管理范围详情 Modal
- 角色权限配置 Drawer

---

## 3. 关键交互与校验

### 3.1 批量设置角色（US-PERMISSION-003）

- 未勾选员工时按钮禁用
- 打开弹窗后 `角色` 为必填
- 若选中员工存在个人覆盖权限，显示提示：
  - `该操作将覆盖所选员工的个人自定义权限，请确认`
- 提交成功：
  - 批量更新角色
  - 清除个人不一致标记
  - Toast 成功提示

### 3.2 新增角色（US-PERMISSION-001）

- 必填字段：
  - 角色名称
  - 角色类别
- 校验：
  - 角色名称同租户唯一
- 成功后：
  - 角色入列表
  - 默认可进入权限配置抽屉

### 3.3 删除角色（US-PERMISSION-001）

- 预设角色 (`isBuiltin=true`) 禁止删除
- 应用人数 > 0 时禁止删除
- 删除成功后刷新列表并 Toast

### 3.4 人员权限编辑（US-PERMISSION-004）

- 左侧模块树切换，右侧权限项按分组展示
- 模块总开关关闭后，该模块权限项置灰（模拟菜单隐藏）
- 权限项支持三类控件：
  - 开关型（BOOLEAN）
  - 范围型（SCOPE）
  - 数值型（INTEGER）
- 点击 `编辑` 打开单项详情抽屉
- 保存后：
  - 标记该员工为“权限与角色不一致”
  - 人员列表可被快捷筛出

### 3.5 数据范围与管理范围（US-PERMISSION-005）

- 人员列表 `管理范围` 列展示范围摘要
- 点击 `详情` 打开范围详情弹窗
- 范围项支持：`无 / 本人 / 本组 / 本门店 / 本区域 / 本大区 / 全公司`

---

## 4. 状态矩阵

| 状态 | 触发 | 页面反馈 |
|---|---|---|
| 默认态 | 页面初次进入 | 权限管理 Tab 默认选中 |
| 查询态 | 输入筛选后点击查询 | 列表按条件过滤 |
| 空结果 | 条件无匹配 | 表格空态文案“暂无匹配人员/角色” |
| 勾选态 | 勾选员工/角色 | 批量按钮启用 |
| 批量角色校验失败 | 角色未选 | 字段下错误文案 |
| 新增角色校验失败 | 名称/类别为空或重名 | 字段错误文案 |
| 删除受限 | 内置角色/有应用人数 | Toast 错误提示 |
| 权限保存成功 | 个人或角色权限保存 | 列表状态更新 + Toast |
| 主题策略 | 后台统一浅色体系 | 页面内不包含 Light/Dark/System 控件 |

---

## 5. 字段与数据模型映射（DATA_MODEL_PERMISSION）

| UI 字段 | 数据模型字段 |
|---|---|
| 角色名称 | `roles.name` |
| 角色类别 | `roles.category` |
| 角色来源模板 | `roles.template_role_id` |
| 是否内置角色 | `roles.is_system_builtin` |
| 员工角色关联 | `staff_roles.staff_id / role_id / is_primary` |
| 个人权限覆盖 | `staff_permission_overrides.*` |
| 权限定义 | `permission_defs.code / value_type / default_value` |
| 角色权限值 | `role_permissions.value` |
| 员工管理范围 | `staff_data_scopes.scope_type / org_unit_id` |
| 权限变更日志入口 | `permission_change_logs`（本页仅展示入口） |

---

## 6. 可访问性与实现规范

- 表格头部使用 `<th scope="col">`
- 弹窗可通过 `Esc` 关闭
- 必填错误使用明确文本，不仅依赖颜色
- 按钮禁用态提供 `disabled` + 视觉弱化
- 行内链接均保留可点击区域（>= 28px 高）
- 保持后台浅色设计，不加入主题切换组件

---

## 7. 验收清单（任务08）

- [x] 覆盖 US-PERMISSION-001：角色列表 + 新增角色 + 预设角色不可删
- [x] 覆盖 US-PERMISSION-002：人员权限列表筛选、分页、操作入口
- [x] 覆盖 US-PERMISSION-003：批量设置角色弹窗 + 覆盖提醒
- [x] 覆盖 US-PERMISSION-004：模块级开关 + 权限项编辑 + 保存
- [x] 覆盖 US-PERMISSION-005：范围型权限 + 管理范围详情
- [ ] 控制台 0 报错（待本地预览验证）

---

## 8. 后续衔接

- 任务08评审后进入任务09（系统配置）
- 权限管理结果将与组织人事（员工/部门）及后续业务模块菜单展示联动