7.5 KiB
7.5 KiB
权限管理 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.mdDATA_MODEL/DATA_MODEL_PERMISSION.mdPRD/权限管理/首页.mdPRD/权限管理/客源.mdPRD/权限管理/房源-二手租赁.md竞品截图参考：screenshots/权限管理/权限管理-人员列表.pngscreenshots/权限管理/权限管理-批量设置角色.pngscreenshots/权限管理/权限管理-人员编辑特定权限.pngscreenshots/权限管理/权限管理-修改个人权限-客源.pngscreenshots/权限管理/角色管理-角色列表.pngscreenshots/权限管理/角色管理-添加角色1.pngscreenshots/权限管理/角色管理-修改角色.png
1. 目标与范围
1.1 页面目标
本页用于完成权限管理模块 MVP 主链路：
- 角色配置（US-PERMISSION-001）
- 角色列表（预设 + 自定义）
- 新增自定义角色
- 预设角色不可删
- 可进入角色权限配置抽屉
- 人员权限列表管理（US-PERMISSION-002）
- 按姓名/工号、部门、角色、职务检索
- 列表展示角色、管理范围、不一致标记
- 批量设置角色（US-PERMISSION-003）
- 勾选员工后批量赋角色
- 覆盖个人权限提醒
- 功能权限控制（US-PERMISSION-004）
- 人员权限编辑页支持模块级开关 + 权限项配置
- 模块关闭时视为菜单隐藏
- 数据权限控制（US-PERMISSION-005）
- 范围型权限（本人/本组/本门店/本区域/本大区/全公司）
- 管理范围详情弹窗
1.2 任务边界
- ✅ 包含：权限管理 Tab、角色管理 Tab、批量角色弹窗、个人权限抽屉、权限项详情抽屉、角色新增弹窗、角色配置抽屉、范围详情弹窗、分页/空态/Toast
- ✅ 包含：必填校验、角色唯一性校验、预设角色删除限制、批量按钮禁用态
- ⛔ 不包含：真实权限后端、真实 Redis 失效、真实 403 路由拦截、真实日志系统
2. 信息架构
2.1 页面骨架
- Top Bar：系统一级导航（人事主入口高亮）
- Sidebar：组织人事二级菜单（权限管理高亮）
- Main Content：
- 面包屑：
人事OA / 组织人事 / 权限管理 - 主 Tab：
权限管理（人员维度）/角色管理（角色维度）
- 面包屑：
2.2 权限管理 Tab（人员维度）
- 筛选区
- 姓名/工号
- 员工部门
- 角色
- 职务名称
- 权限与角色权限不一致（快捷筛选）
- 操作区
- 批量设置角色
- 导出
- 人员表格
- 复选框、员工姓名、工号、部门、职务、角色、管理范围（详情）、操作
- 行操作
- 修改权限
- 复制角色
- 扩充范围
- 范围
- 分页区
2.3 角色管理 Tab（角色维度）
- 筛选区
- 角色名称
- 角色类别
- 修改时间范围
- 操作区
- 新增角色
- 批量删除角色
- 角色表格
- 复选框、角色名称、角色类别、应用人数（查看）、引用角色、创建时间、修改时间、操作
- 行操作
- 编辑（进入角色权限配置）
- 删除（预设角色禁删）
- 修改日志
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）
- 覆盖 US-PERMISSION-001：角色列表 + 新增角色 + 预设角色不可删
- 覆盖 US-PERMISSION-002：人员权限列表筛选、分页、操作入口
- 覆盖 US-PERMISSION-003：批量设置角色弹窗 + 覆盖提醒
- 覆盖 US-PERMISSION-004：模块级开关 + 权限项编辑 + 保存
- 覆盖 US-PERMISSION-005：范围型权限 + 管理范围详情
- 控制台 0 报错（待本地预览验证）
8. 后续衔接
- 任务08评审后进入任务09（系统配置）
- 权限管理结果将与组织人事（员工/部门）及后续业务模块菜单展示联动