permission-system-design

name	permission-system-design
description	设计权限系统架构，角色作为预设而非独立权限，支持细分权限与角色预设的灵活组合。用于：权限系统数据模型设计、API 设计、架构方案评审、设计检查清单生成。Use when: permission, RBAC, role, access control, authorization, 权限, 角色, 授权.
argument-hint	[项目描述或现有权限系统描述]
user-invocable	false

权限系统架构设计

核心设计理念

角色是预设，不是权限本身。

传统 RBAC 将权限绑定到角色，用户只能通过角色获得权限。本设计理念将角色降级为"权限预设包"，用户可以直接拥有细分权限，角色只是批量分配的快捷方式。

数据模型关系

用户 ──┬── 直接权限（细分权限，可单独授予/撤销）
       └── 角色预设 ── 预设包含的权限（模板，非绑定）

关键区别：

• 用户的最终权限 = 直接权限 ∪ 角色预设包含的权限
• 修改角色预设不影响已单独授予用户的直接权限
• 管理员可以：分配角色、撤销角色、单独授予/撤销任意细分权限

设计检查清单

1. 数据模型层

• 权限表（permissions）：每个权限是独立原子项，包含 id、code（如 user:create）、resource、action、description
• 角色预设表（role_presets）：仅作为权限集合的模板，包含 id、name、description、is_system（系统预设不可删除）
• 角色预设-权限关联表（role_preset_permissions）：角色预设包含哪些权限，多对多
• 用户-角色关联表（user_roles）：用户被分配了哪些角色预设，多对多，支持有效期
• 用户直接权限表（user_permissions）：用户单独拥有的细分权限，多对多，支持有效期、来源标记（管理员授予/自助申请等）
• 权限继承/覆盖机制：明确当角色预设权限与直接权限冲突时的优先级规则（建议：直接权限优先，deny 覆盖 allow）

2. 权限粒度设计

• 采用 resource:action 命名规范（如 order:read、order:export、user:role:assign）
• 权限支持层级关系（如 user:* 覆盖 user:read、user:write）
• 区分数据权限（行级）和功能权限（菜单/按钮/API 级）
• 权限分组/分类，便于管理界面展示

3. API 设计层

• 权限管理 API：CRUD 细分权限
• 角色预设管理 API：CRUD 角色预设、管理预设包含的权限
• 用户权限管理 API：
  • 分配/撤销角色预设
  • 授予/撤销直接权限
  • 查询用户最终权限（合并视图）
  • 查询用户权限来源（追溯：来自哪个角色或直接授予）
• 权限校验 API：给定用户 + 权限码，返回是否允许
• 批量操作 API：批量分配权限、批量切换角色

4. 管理员能力

• 管理员可以自由修改任意用户的角色预设
• 管理员可以自由授予/撤销任意用户的任意细分权限（不受角色限制）
• 管理员可以创建/修改/删除自定义角色预设
• 系统预设角色不可删除，但可以复制为自定义版本
• 提供权限审计日志：谁在什么时间给谁授予/撤销了什么权限

5. 安全与边界

• 超级管理员权限不可被其他管理员撤销
• 权限提升需要二次确认
• 角色预设修改后，已分配该角色的用户权限实时生效（或有明确的生效策略）
• 支持权限有效期，过期自动撤销
• 防止权限循环依赖

架构方案文档模板

当需要输出完整架构方案时，按以下结构组织：

1. 概述

• 设计目标与核心理念
• 与传统 RBAC 的对比说明

2. 数据模型

• ER 图（实体关系）
• 各表字段定义与索引设计
• 权限合并算法（用户最终权限的计算逻辑）

3. API 设计

• RESTful 或 GraphQL 接口定义
• 请求/响应示例
• 错误码定义

4. 权限校验流程

• 请求 → 中间件/拦截器 → 权限查询 → 决策 → 缓存策略
• 实时校验 vs 缓存校验的权衡

5. 管理界面设计建议

• 用户权限管理视图（合并视图 + 来源追溯）
• 角色预设管理视图
• 权限矩阵视图（用户 × 权限 的交叉表）

6. 迁移方案（如改造现有系统）

• 从传统 RBAC 迁移的步骤
• 数据迁移脚本
• 灰度切换策略

实施步骤

1. 收集需求：了解项目的技术栈、用户规模、权限复杂度
2. 设计数据模型：根据检查清单第 1-2 项输出 ER 图和字段定义
3. 设计 API：根据检查清单第 3 项输出接口文档
4. 评审方案：使用检查清单逐项验证
5. 输出文档：按架构方案文档模板组织最终交付物

参考资源

• ./references/data-model-examples.md — 各技术栈的数据模型示例
• ./references/api-examples.md — API 设计示例