权限系统设计

<title>权限系统设计</title>

> 本文档抓取自官方文档中心（2026-10-10 快照），具体功能以实际产品为准。

# 权限系统设计方案

## 概述

基于现有系统的用户模型和权限代码清单，设计一个分阶段的权限系统，支持初版和加强版两种模式。

## 初版权限系统（用户-权限组-权限模型）

### 核心概念

- **用户（User）**：系统使用者，通过手机号注册
- **权限组（PermissionGroup）**：权限的集合，可分配给用户
- **权限（Permission）**：具体的功能权限，如 `video_workflow:view`

### 数据模型

#### 1. 权限表（permissions）

```sql
CREATE TABLE permissions (
    id INT PRIMARY KEY AUTO_INCREMENT,
    permission_code VARCHAR(100) NOT NULL UNIQUE COMMENT '权限代码，如 video_workflow:view',
    permission_name VARCHAR(200) NOT NULL COMMENT '权限名称，如 视频工作流查看',
    module VARCHAR(50) NOT NULL COMMENT '所属模块，如 video_workflow',
    description TEXT COMMENT '权限描述',
    status TINYINT DEFAULT 1 COMMENT '状态：1-启用，0-禁用',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_module (module),
    INDEX idx_status (status)
);
```

#### 2. 权限组表（permission_groups）

```sql
CREATE TABLE permission_groups (
    id INT PRIMARY KEY AUTO_INCREMENT,
    group_name VARCHAR(100) NOT NULL COMMENT '权限组名称',
    group_code VARCHAR(100) NOT NULL UNIQUE COMMENT '权限组代码',
    description TEXT COMMENT '权限组描述',
    status TINYINT DEFAULT 1 COMMENT '状态：1-启用，0-禁用',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_group_code (group_code),
    INDEX idx_status (status)
);
```

#### 3. 权限组-权限关联表（permission_group_permissions）

```sql
CREATE TABLE permission_group_permissions (
    id INT PRIMARY KEY AUTO_INCREMENT,
    group_id INT NOT NULL COMMENT '权限组ID',
    permission_id INT NOT NULL COMMENT '权限ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_group_permission (group_id, permission_id),
    FOREIGN KEY (group_id) REFERENCES permission_groups(id) ON DELETE CASCADE,
    FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
);
```

#### 4. 用户-权限组关联表（user_permission_groups）

```sql
CREATE TABLE user_permission_groups (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL COMMENT '用户ID',
    group_id INT NOT NULL COMMENT '权限组ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_user_group (user_id, group_id),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    FOREIGN KEY (group_id) REFERENCES permission_groups(id) ON DELETE CASCADE
);
```

### 核心功能

#### 权限验证流程

1. 用户登录后获取用户信息
2. 查询用户所属的所有权限组
3. 获取权限组对应的所有权限代码
4. 将权限代码列表缓存到用户会话中
5. API请求时通过中间件验证权限

#### 权限验证中间件

```python
class PermissionMiddleware:
    def __init__(self, required_permission):
        self.required_permission = required_permission

    def __call__(self, func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            # 获取当前用户
            user = get_current_user()
            if not user:
                return jsonify({"error": "用户未登录"}), 401

            # 检查用户权限
            if not self.has_permission(user.id, self.required_permission):
                return jsonify({"error": "权限不足"}), 403

            return func(*args, **kwargs)
        return wrapper

    def has_permission(self, user_id, permission):
        # 查询用户权限
        user_permissions = self.get_user_permissions(user_id)
        return permission in user_permissions

    def get_user_permissions(self, user_id):
        # 从缓存或数据库获取用户权限列表
        # 优先从Redis缓存获取
        cache_key = f"user_permissions:{user_id}"
        permissions = redis_client.get(cache_key)

        if not permissions:
            # 从数据库查询
            permissions = self.query_user_permissions(user_id)
            # 缓存1小时
            redis_client.setex(cache_key, 3600, json.dumps(permissions))
        else:
            permissions = json.loads(permissions)

        return permissions
```

#### API接口设计

```python
# 权限管理API
@app.route('/api/permissions', methods=['GET'])
@admin_required
def list_permissions():
    """获取权限列表"""
    pass

@app.route('/api/permission-groups', methods=['GET'])
@login_required
def list_permission_groups():
    """获取权限组列表"""
    pass

@app.route('/api/permission-groups', methods=['POST'])
@admin_required
def create_permission_group():
    """创建权限组"""
    pass

@app.route('/api/users/<int:user_id>/permission-groups', methods=['GET'])
@admin_required
def get_user_permission_groups(user_id):
    """获取用户的权限组"""
    pass

@app.route('/api/users/<int:user_id>/permission-groups', methods=['PUT'])
@admin_required
def update_user_permission_groups(user_id):
    """更新用户的权限组"""
    pass
```

## 加强版权限系统（增加用户组概念）

### 新增概念

- **用户组（UserGroup）**：用户的集合，可分配权限组
- **用户-用户组关联**：用户可属于多个用户组

### 新增数据模型

#### 1. 用户组表（user_groups）

```sql
CREATE TABLE user_groups (
    id INT PRIMARY KEY AUTO_INCREMENT,
    group_name VARCHAR(100) NOT NULL COMMENT '用户组名称',
    group_code VARCHAR(100) NOT NULL UNIQUE COMMENT '用户组代码',
    description TEXT COMMENT '用户组描述',
    parent_id INT DEFAULT NULL COMMENT '父用户组ID，支持层级结构',
    status TINYINT DEFAULT 1 COMMENT '状态：1-启用，0-禁用',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_group_code (group_code),
    INDEX idx_parent_id (parent_id),
    INDEX idx_status (status),
    FOREIGN KEY (parent_id) REFERENCES user_groups(id) ON DELETE SET NULL
);
```

#### 2. 用户-用户组关联表（user_group_members）

```sql
CREATE TABLE user_group_members (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL COMMENT '用户ID',
    group_id INT NOT NULL COMMENT '用户组ID',
    role_in_group VARCHAR(50) COMMENT '用户在组内的角色，如 member, admin',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_user_group (user_id, group_id),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    FOREIGN KEY (group_id) REFERENCES user_groups(id) ON DELETE CASCADE
);
```

#### 3. 用户组-权限组关联表（user_group_permission_groups）

```sql
CREATE TABLE user_group_permission_groups (
    id INT PRIMARY KEY AUTO_INCREMENT,
    group_id INT NOT NULL COMMENT '用户组ID',
    permission_group_id INT NOT NULL COMMENT '权限组ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_group_permission_group (group_id, permission_group_id),
    FOREIGN KEY (group_id) REFERENCES user_groups(id) ON DELETE CASCADE,
    FOREIGN KEY (permission_group_id) REFERENCES permission_groups(id) ON DELETE CASCADE
);
```

### 权限验证逻辑升级

#### 权限获取流程（加强版）

1. 获取用户直接绑定的权限组权限
2. 获取用户所属用户组的权限组权限
3. 合并所有权限（去重）
4. 按优先级处理权限冲突

#### 权限优先级规则

- 用户直接权限 > 用户组权限
- 如果多个用户组有冲突权限，取并集
- 支持权限的显式拒绝（黑名单模式）

#### 升级后的权限验证

```python
def get_user_effective_permissions(user_id):
    """获取用户的有效权限列表"""
    permissions = set()

    # 1. 获取用户直接绑定的权限组权限
    direct_permissions = get_user_direct_permissions(user_id)
    permissions.update(direct_permissions)

    # 2. 获取用户所属用户组的权限
    user_group_permissions = get_user_group_permissions(user_id)
    permissions.update(user_group_permissions)

    # 3. 应用权限规则（黑名单、优先级等）
    final_permissions = apply_permission_rules(user_id, permissions)

    return final_permissions

def get_user_group_permissions(user_id):
    """获取用户所属用户组的权限"""
    permissions = set()

    # 查询用户所属的用户组
    user_groups = get_user_groups(user_id)

    for group in user_groups:
        # 获取用户组的权限组
        group_permission_groups = get_group_permission_groups(group.id)

        for pg in group_permission_groups:
            # 获取权限组的权限
            pg_permissions = get_permission_group_permissions(pg.id)
            permissions.update(pg_permissions)

    return permissions
```

### 加强版API接口

#### 用户组管理API

```python
@app.route('/api/user-groups', methods=['GET'])
@admin_required
def list_user_groups():
    """获取用户组列表"""
    pass

@app.route('/api/user-groups', methods=['POST'])
@admin_required
def create_user_group():
    """创建用户组"""
    pass

@app.route('/api/user-groups/<int:group_id>', methods=['PUT'])
@admin_required
def update_user_group(group_id):
    """更新用户组"""
    pass

@app.route('/api/user-groups/<int:group_id>/members', methods=['GET'])
@admin_required
def get_user_group_members(group_id):
    """获取用户组成员"""
    pass

@app.route('/api/user-groups/<int:group_id>/members', methods=['POST'])
@admin_required
def add_user_group_member(group_id):
    """添加用户组成员"""
    pass

@app.route('/api/user-groups/<int:group_id>/permission-groups', methods=['GET'])
@admin_required
def get_user_group_permission_groups(group_id):
    """获取用户组的权限组"""
    pass

@app.route('/api/user-groups/<int:group_id>/permission-groups', methods=['PUT'])
@admin_required
def update_user_group_permission_groups(group_id):
    """更新用户组的权限组"""
    pass
```

## 实施计划

### 第一阶段：初版实现（2-3周）

1. 创建权限相关数据库表
2. 实现权限管理模型类
3. 开发权限验证中间件
4. 实现基础API接口
5. 集成到现有系统

### 第二阶段：加强版升级（2-3周）

1. 创建用户组相关表
2. 升级权限验证逻辑
3. 开发用户组管理功能
4. 更新API接口
5. 测试和优化

### 第三阶段：权限管理界面（2周）

1. 开发权限管理后台界面
2. 实现权限分配可视化
3. 添加权限审计功能
4. 用户友好的权限配置

## 技术要点

### 性能优化

- Redis缓存用户权限，减少数据库查询
- 批量权限验证，支持一次验证多个权限
- 权限变更时主动更新缓存

### 安全性考虑

- 权限验证必须在服务端进行
- 防止权限提升攻击
- 记录权限变更审计日志
- 敏感操作需要二次验证

### 扩展性设计

- 支持自定义权限类型
- 支持数据权限（按资源过滤）
- 支持动态权限配置
- 支持权限继承和组合

## 与现有系统集成

### 用户模型兼容性

- 复用现有的 `users` 表结构
- 保留 `role` 字段作为默认权限组
- 新增权限系统作为增强功能

### 权限代码复用

- 使用现有的功能权限代码清单
- 支持动态添加新的权限代码
- 保持权限命名规范一致性

### API兼容性

- 现有API逐步迁移到新权限系统
- 提供向后兼容的权限验证方式
- 平滑过渡，不影响现有功能