权限与角色管理

概述

在掌上意见箱智能意见收集管理平台中，权限与角色管理是保障系统安全、实现数据隔离和精细化操作控制的核心模块。本系统采用基于角色的访问控制（RBAC）模型，通过将权限赋予角色，再将角色分配给用户，来简化权限管理流程。

核心概念

1. 权限 (Permission)

权限是系统中最细粒度的操作许可，代表执行某个特定操作（如创建、读取、更新、删除）或访问特定资源的能力。

权限示例：

opinion:create：创建意见
opinion:read：读取意见
opinion:update：更新意见
opinion:delete：删除意见
dashboard:view：查看数据看板
user:manage：管理用户

2. 角色 (Role)

角色是权限的集合，代表用户在系统中的职责或身份。系统预定义了若干核心角色，也支持创建自定义角色。

3. 用户 (User)

系统的最终使用者。一个用户可以拥有一个或多个角色，继承这些角色所包含的所有权限。

预定义角色

掌上意见箱平台默认提供以下核心角色，开箱即用：

角色名称	角色标识	描述	典型权限
系统管理员	`admin`	拥有系统全部管理权限，最高权限角色。	所有权限
部门管理员	`dept_admin`	管理指定部门内的意见、用户及报表。	`opinion:*` (本部门), `report:view`, `user:read` (本部门)
意见收集员	`collector`	负责创建、发布和管理意见收集活动。	`opinion:create`, `opinion:read`, `opinion:update` (自己创建的)
普通用户	`user`	提交意见、查看自己提交的历史及公开结果。	`opinion:create`, `opinion:read` (自己提交的)
只读访客	`guest`	仅能查看已公开的意见汇总信息。	`opinion:read` (公开的)

自定义角色与权限配置

除了预定义角色，高级用户可以根据实际业务需求创建自定义角色，并为其分配精确的权限组合。

通过管理界面配置

以系统管理员身份登录管理后台。
导航至 系统设置 > 角色与权限。
点击“新建角色”，输入角色名称和标识符。
在权限列表中，勾选该角色需要的具体权限。
保存角色，并将其分配给相应用户。

通过API管理（示例）

掌上意见箱提供了完整的RESTful API用于权限与角色管理。

示例1：创建自定义角色

POST /api/v1/roles
Authorization: Bearer {your_access_token}
Content-Type: application/json

{
  "code": "project_lead",
  "name": "项目负责人",
  "description": "负责特定项目的意见审核与进度查看",
  "permissions": [
    "opinion:read",
    "opinion:update",
    "report:view",
    "project:manage"
  ]
}

示例2：为用户分配角色

POST /api/v1/users/{userId}/roles
Authorization: Bearer {your_access_token}
Content-Type: application/json

{
  "roleCodes": ["dept_admin", "project_lead"]
}

示例3：检查当前用户权限（前端集成示例）

// 假设已引入掌上意见箱的JS SDK
import { auth } from 'palm-feedback-sdk';

// 检查是否拥有某个具体权限
if (auth.hasPermission('opinion:delete')) {
    // 显示删除按钮
}

// 检查是否拥有某个角色
if (auth.hasRole('dept_admin')) {
    // 显示管理部门数据的界面
}

权限验证逻辑

系统在处理任何请求时，都会执行以下权限验证流程：

身份认证：验证访问令牌（JWT）的有效性。
角色提取：从令牌或会话中获取当前用户所属的所有角色。
权限合并：合并所有角色拥有的权限，得到用户最终权限集。
权限校验：判断请求对应的操作权限是否存在于用户的最终权限集中。
访问决策：通过则执行操作，拒绝则返回 403 Forbidden 错误。

最佳实践

最小权限原则：始终为用户分配完成工作所必需的最小权限集合。
角色继承：对于复杂的权限结构，可以设计角色继承关系（如“高级收集员”继承“收集员”的所有权限，并额外增加一些权限）。
定期审计：定期审查角色定义和用户角色分配，确保与当前组织结构和职责匹配。
日志记录：系统关键权限操作（如角色分配、权限修改）应记录详细审计日志。
API安全：调用管理类API时，务必使用高权限且受保护的访问令牌，并在后端服务间通信时使用服务账户。

故障排除

用户报告“无权访问”：检查用户是否被分配了正确的角色，以及该角色是否包含执行目标操作所需的权限。
权限更改未立即生效：用户权限通常在下次登录或令牌刷新后生效。对于即时性要求高的场景，可考虑调用令牌失效或用户会话更新接口。
API返回403错误：确认调用API的服务或账户持有执行该操作所需的权限。

通过合理利用掌上意见箱的权限与角色管理系统，您可以构建安全、合规且高效协同的意见收集与管理环境。