角色与权限
角色与权限
欣悦互通采用 RBAC（基于角色的访问控制）体系管理用户权限。通过将权限分配给角色、再将角色分配给用户的方式，实现灵活且可复用的权限管理。
本篇介绍如何创建角色、分配权限、管理菜单，以及通过版本体系控制功能可见性。
RBAC 概念
RBAC 的核心思想是「用户 → 角色 → 权限」三层关系：
- 用户：系统中的实际使用者，一个用户可拥有多个角色。
- 角色：权限的集合，如「管理员」「运营」「只读用户」。
- 权限：对系统资源的访问能力，如「查看 GEO 项目」「创建内容」「删除用户」。
通过角色作为中间层，可以批量管理用户权限。当业务变化时，只需调整角色对应的权限，所有拥有该角色的用户权限会自动更新。
!NOTE 欣悦互通的权限粒度细到按钮级别（如「删除」按钮的可见性），通过
v-access指令在前端控制。
角色管理
查看角色列表
- 进入「系统管理 → 角色管理」查看当前租户下的所有角色。
- 列表展示角色名称、描述、关联用户数、创建时间。
- 支持按角色名称搜索。
创建角色
- 在角色列表页点击「新增」按钮。
- 填写角色名称和描述。
- 在「权限分配」区域勾选该角色拥有的权限。
- 在「菜单分配」区域勾选该角色可见的菜单。
- 点击「确定」保存。
系统调用 POST /api/system/roles（或 POST /api/roles）创建角色，角色与权限、菜单的关联关系会一并保存。
编辑和删除角色
- 在角色列表中点击「编辑」修改角色信息、权限或菜单。
- 点击「删除」移除角色。
!WARNING 删除角色前，请确保该角色下没有关联的用户。如有用户仍使用该角色，需先将用户迁移到其他角色，否则删除操作将被拒绝。
权限列表与同步
查看权限列表
进入「系统管理 → 权限管理」可查看系统中所有已定义的权限项，包括：
- 权限编码（如
geo:project:create） - 权限名称
- 所属模块
- 权限类型（菜单/按钮/接口）
权限列表通过 GET /api/system/permissions 获取。
权限同步
当系统升级、新增功能模块后，权限项可能发生变化。点击「同步权限」按钮，系统将调用 POST /api/permissions/sync 扫描所有路由和按钮，自动注册新的权限项。
!TIP 建议每次系统升级后执行一次权限同步，确保新功能的权限项可用，然后再到角色管理中为相应角色分配新权限。
角色菜单分配
菜单分配决定角色用户在后台能看到哪些导航菜单。每个菜单项可单独勾选，支持按模块批量分配。
- 在角色编辑页切换到「菜单分配」标签。
- 通过树形勾选组件选择可见菜单。
- 父菜单选中后，子菜单默认全部选中。
- 点击「确定」保存。
菜单数据通过 GET /api/menus/tree 以树形结构返回，便于在前端展示层级关系。
版本体系管理
版本体系用于控制不同套餐或版本下的功能可见性。例如「基础版」看不到「AI 对话」功能，「专业版」则可使用全部功能。
创建版本
- 进入「系统管理 → 版本管理」。
- 点击「新增」填写版本名称、版本标识、排序。
- 在「功能列表」中为该版本配置可用的功能项。
- 点击「确定」保存。
版本管理通过 GET/POST /api/editions 创建，GET /api/editions/{id}/features 查询版本下的功能列表。
版本与角色配合
版本体系控制功能级可见性，角色权限控制操作级权限。两者配合实现：某功能在当前版本可见，但只有特定角色才能操作。
菜单管理
菜单管理用于维护后台的导航结构，包括菜单项的层级、排序、图标和关联路由。
- 进入「系统管理 → 菜单管理」查看菜单列表。
- 点击「菜单树」可查看层级结构视图。
- 点击「新增」创建菜单项，填写：菜单名称、上级菜单、路由路径、图标、排序、权限编码。
- 点击「编辑」或「删除」修改或移除菜单项。
菜单数据通过 GET/POST /api/menus、GET /api/menus/tree 管理接口操作。
!WARNING 删除菜单前请确保没有子菜单，且该菜单未被任何角色引用。删除父菜单会级联删除所有子菜单，请谨慎操作。
v-access 权限指令
前端通过 v-access:code 指令控制按钮级权限。例如：
<tiny-button v-access:code="'geo:project:create'">新增项目</tiny-button>
只有当前用户角色包含 geo:project:create 权限时，该按钮才会显示。指令由 vben5 框架原生支持，无需额外配置。
!TIP 开发自定义页面时，建议为所有敏感操作按钮添加
v-access:code，避免越权操作。