Etusivu Tutki Apua
Rekisteröidy Kirjaudu sisään
186-template-175
/
mini-starter
haarautettu lähteestä 155-template-138/mini-starter
2
0
Haarauta 0
Tiedostot
Puu: 3eeaefc94a
Haarat Tunnisteet
mini-starter
/
docs
/
prd
/
epic-008-permission-role-management.md

epic-008-permission-role-management.md 16 KB
Historia Raaka

史诗008：权限角色管理系统

概述

完善系统权限角色管理功能，实现基于角色的权限控制，特别针对广告管理功能添加细粒度权限控制，确保超级管理员可见可操作，普通管理员不可见，提升系统安全性和管理灵活性。

业务背景

当前系统已具备基础的角色和权限实体框架，但实际应用有限：

  1. 角色实体存在：系统已有Role实体和permissions字段（simple-array类型）
  2. 权限中间件存在：已有permissionMiddleware和checkPermission函数，但未广泛使用
  3. 菜单权限配置存在：广告管理等菜单已有permission: 'advertisement:manage'配置，但未实现实际检查
  4. 广告管理无权限控制：广告模块路由只使用authMiddleware，所有登录管理员都可访问
  5. 角色定义不清晰：缺乏明确的超级管理员和普通管理员角色定义和权限分配

为提升系统安全性和管理精细化，需要完善权限角色管理系统，实现真正的基于角色的权限控制。

目标

  1. 完善角色权限系统：定义清晰的超级管理员和普通管理员角色，分配相应权限
  2. 实现广告管理权限控制：广告管理功能仅对超级管理员可见可操作
  3. 集成现有权限框架：充分利用已有的权限中间件和角色实体
  4. 前后端权限统一：实现前端菜单权限控制和后端API权限检查的一致性
  5. 数据库默认数据：添加默认角色和权限数据迁移
  6. 专注广告管理：本次仅实现广告管理权限控制，其他模块权限保持现有状态

范围

包含的功能

  1. 角色权限定义完善 (user-module增强)

    • 明确超级管理员（super-admin）和普通管理员（admin）角色定义
    • 定义标准权限命名规范（entity:action格式）
    • 添加广告管理相关权限：advertisement:view, advertisement:create, advertisement:edit, advertisement:delete, advertisement:manage
    • 本次仅定义广告管理相关权限，其他模块权限保持不变

  2. 后端API权限检查增强 (server和advertisements-module)

    • 广告模块路由集成permissionMiddleware权限检查
    • 更新广告管理API，要求advertisement:manage权限
    • 扩展权限中间件支持基于权限字符串数组检查
    • 确保多租户上下文下的权限验证正确性

  3. 前端权限控制实现 (web管理后台)

    • 实现菜单项权限过滤：基于用户角色权限隐藏/显示菜单
    • 实现路由守卫：无权限用户无法访问受保护页面
    • 实现UI组件权限检查：按钮、操作等细粒度控制
    • 集成用户权限查询和缓存机制

  4. 数据库默认数据 (user-module-mt迁移)

    • 创建默认角色数据：超级管理员、普通管理员
    • 分配默认权限集给各角色
    • 确保多租户环境下的默认数据一致性
    • 提供角色权限管理API供后台使用

  5. 测试和数据迁移

    • 编写权限检查单元测试和集成测试
    • 创建数据库迁移脚本添加默认角色数据
    • 验证广告管理权限控制功能

不包含的功能

  1. 动态权限管理系统UI（未来可扩展）
  2. 角色组和权限继承功能
  3. 数据行级权限控制
  4. 权限审计日志系统

用户故事

故事1：完善角色权限定义和默认数据

作为 系统架构师 我希望 明确定义超级管理员和普通管理员角色及其权限 以便 为系统提供清晰的权限基础

验收标准：

  • 在user-module中定义标准权限常量：PERMISSION_ADVERTISEMENT_MANAGE = 'advertisement:manage'等
  • 创建超级管理员角色：super-admin，包含广告管理权限
  • 创建普通管理员角色：admin，不包含广告管理权限
  • 权限定义仅针对广告管理，其他模块权限保持现有状态
  • 创建数据库迁移脚本添加默认角色数据到role表
  • 提供角色权限管理API：角色列表、权限分配、用户角色分配
  • 编写单元测试验证角色权限逻辑

优先级：高 技术依赖：user-module, server

故事2：实现后端API权限检查

作为 安全工程师 我希望 广告管理API进行权限检查 以便 防止未授权用户访问广告管理功能

验收标准：

  • 更新广告模块路由，集成permissionMiddleware权限检查
  • 广告列表API：要求advertisement:view或advertisement:manage权限
  • 广告创建API：要求advertisement:create或advertisement:manage权限
  • 广告编辑API：要求advertisement:edit或advertisement:manage权限
  • 广告删除API：要求advertisement:delete或advertisement:manage权限
  • 广告类型管理API：同样添加权限检查
  • 扩展权限中间件支持权限字符串数组检查（如checkPermission(['advertisement:manage'])）
  • 确保权限检查在租户上下文中正常工作
  • 编写集成测试验证API权限控制

优先级：高 技术依赖：advertisements-module, server, user-module-mt

故事3：实现前端权限控制

作为 后台管理员 我希望 菜单和页面根据我的权限动态显示 以便 我只看到和访问我有权限的功能

验收标准：

  • 实现菜单权限过滤：useMenu根据用户权限过滤菜单项
  • 广告管理菜单项：仅对拥有advertisement:manage权限的用户显示
  • 实现路由守卫：无权限用户访问受保护页面时重定向到404或无权限页面
  • 实现权限检查Hook：useHasPermission(permission)返回布尔值
  • 实现UI组件权限包装器：<RequirePermission permission="advertisement:manage">
  • 集成用户权限查询：用户登录时或定期获取权限列表
  • 权限缓存和状态管理：避免重复查询
  • 编写前端权限控制测试
  • 确保权限变更时UI及时更新

优先级：高 技术依赖：web, user-module-mt, server

故事4：广告管理权限集成测试

作为 测试工程师 我希望 验证广告管理权限控制功能 以便 确保权限系统正确工作

验收标准：

  • 创建超级管理员测试账号：拥有advertisement:manage权限
  • 创建普通管理员测试账号：无advertisement:manage权限
  • 后端API测试：验证不同角色访问广告API的结果
  • 前端E2E测试：验证菜单显示和页面访问控制
  • 权限变更测试：验证权限变更后UI及时更新
  • 多租户权限测试：验证租户间的权限隔离
  • 性能测试：验证权限检查对系统性能的影响
  • 安全测试：验证权限绕过漏洞

优先级：中 技术依赖：所有相关模块

技术设计

数据库设计

-- 现有role表结构保持不变，用于存储角色和权限
-- 默认角色数据迁移脚本（仅关注广告管理权限）
-- 如果角色已存在，则更新权限；如果不存在，则插入
INSERT INTO role (name, description, permissions)
VALUES
('super-admin', '超级管理员', ARRAY['advertisement:manage']),
('admin', '普通管理员', ARRAY[]::text[])
ON CONFLICT (name) DO UPDATE
SET permissions =
  CASE
    WHEN EXCLUDED.name = 'super-admin' THEN
      -- 超级管理员：确保有 advertisement:manage 权限，保留其他现有权限
      array_append(role.permissions, 'advertisement:manage')
    WHEN EXCLUDED.name = 'admin' THEN
      -- 普通管理员：确保没有 advertisement:manage 权限，保留其他现有权限
      array_remove(role.permissions, 'advertisement:manage')
  END,
description = EXCLUDED.description;

-- 用户角色关联表（已存在多对多关系）

权限命名规范

采用entity:action格式：

  • advertisement:view - 查看广告
  • advertisement:create - 创建广告
  • advertisement:edit - 编辑广告
  • advertisement:delete - 删除广告
  • advertisement:manage - 广告管理（包含所有操作）

模块结构

packages/
├── user-module/                          # 用户模块（增强）
│   ├── src/
│   │   ├── constants/                    # 新增：权限常量定义
│   │   │   └── permissions.constants.ts
│   │   ├── entities/                     # 现有：角色实体
│   │   │   └── role.entity.ts
│   │   ├── services/                     # 现有：角色服务
│   │   │   └── role.service.ts
│   │   └── migrations/                   # 新增：默认角色数据迁移
│   │       └── 1234567890-add-default-roles.ts
│   └── package.json
├── advertisements-module/                # 广告模块（增强）
│   ├── src/
│   │   └── routes/                       # 更新：集成权限中间件
│   │       └── index.ts
│   └── package.json
└── server/                               # 服务器（增强）
    ├── src/
    │   └── middleware/                   # 现有：权限中间件
    │       └── permission.middleware.ts
    └── package.json

web/                                      # 前端管理后台
└── src/
    └── client/
        └── admin/
            ├── hooks/                    # 新增：权限相关hooks
            │   ├── usePermissions.ts
            │   └── useHasPermission.ts
            ├── components/               # 新增：权限组件
            │   └── RequirePermission.tsx
            ├── menu.tsx                  # 更新：菜单权限过滤
            └── routes.tsx                # 更新：路由守卫

API设计

权限相关API（新增/增强）

  1. GET /api/user/permissions - 获取当前用户权限列表
  2. GET /api/roles - 获取角色列表（带权限）
  3. PUT /api/roles/{id}/permissions - 更新角色权限
  4. GET /api/users/{id}/roles - 获取用户角色
  5. PUT /api/users/{id}/roles - 更新用户角色

广告管理API（权限保护）

所有广告管理API需要相应权限：

  • GET /api/advertisements - 需要advertisement:view或advertisement:manage
  • POST /api/advertisements - 需要advertisement:create或advertisement:manage
  • PUT /api/advertisements/{id} - 需要advertisement:edit或advertisement:manage
  • DELETE /api/advertisements/{id} - 需要advertisement:delete或advertisement:manage
  • 广告类型管理API同理

前端权限控制流程

  1. 用户登录 → 获取用户信息和权限列表
  2. 权限缓存 → 将权限列表存储在状态管理（Context/Store）
  3. 菜单渲染 → useMenu根据权限过滤菜单项
  4. 路由访问 → 路由守卫检查权限，无权限则重定向
  5. 组件渲染 → RequirePermission包装器控制组件显示
  6. 权限检查 → useHasPermissionhook用于逻辑判断

集成点

与现有系统集成

  1. 用户模块集成：扩展user-module的RoleService，添加权限管理方法
  2. 广告模块集成：在advertisements-module路由中添加permissionMiddleware
  3. 服务器集成：使用现有的permission.middleware.ts中间件
  4. 前端集成：扩展web管理后台的菜单和路由系统
  5. 多租户集成：确保权限检查在租户上下文中工作

数据流

权限检查流程

  1. 用户请求受保护API → authMiddleware验证身份
  2. → permissionMiddleware检查权限
  3. → 调用checkPermission函数验证用户角色权限
  4. → 通过RoleService.hasPermission()检查具体权限
  5. → 权限通过 → 继续处理请求
  6. → 权限拒绝 → 返回403 Forbidden

前端权限流程

  1. 用户登录成功 → 获取用户权限列表
  2. 渲染菜单 → useMenu过滤无权限菜单项
  3. 页面访问 → 路由守卫检查页面权限
  4. 组件渲染 → RequirePermission控制组件显示
  5. 权限变更 → 重新获取权限，更新UI

兼容性要求

  1. API兼容性：新增权限API，现有API添加权限检查但不改变接口签名
  2. 数据库兼容性：只添加数据不修改表结构，完全向后兼容
  3. UI兼容性：权限控制透明，不影响现有UI功能
  4. 多租户兼容性：权限系统支持多租户隔离
  5. 性能兼容性：权限检查对系统性能影响最小化

风险与缓解

风险1：权限系统影响现有功能

  • 缓解措施：先在小范围（广告管理）试点，逐步推广
  • 验证机制：充分测试现有功能不受影响
  • 回滚方案：可临时禁用权限检查中间件

风险2：前端权限缓存不一致

  • 缓解措施：实现权限缓存失效机制，定时刷新
  • 同步机制：权限变更时通知前端更新
  • 降级方案：缓存失败时重新获取权限

风险3：多租户权限隔离问题

  • 缓解措施：确保权限检查在租户上下文中进行
  • 测试策略：编写多租户权限隔离测试
  • 监控机制：监控跨租户权限访问尝试

风险4：性能瓶颈

  • 缓解措施：权限列表缓存，避免重复数据库查询
  • 优化策略：批量检查权限，减少数据库访问
  • 性能监控：监控权限检查耗时

测试策略

单元测试

  • 角色权限逻辑测试：RoleService.hasPermission()
  • 权限中间件测试：permissionMiddleware和checkPermission
  • 前端权限Hook测试：useHasPermission和usePermissions
  • 菜单过滤逻辑测试：useMenu权限过滤

集成测试

  • API权限检查测试：不同角色访问广告API
  • 数据库迁移测试：默认角色数据正确性
  • 多租户权限测试：租户间权限隔离
  • 前后端集成测试：权限信息同步

E2E测试

  • 超级管理员流程：广告管理完整操作
  • 普通管理员流程：验证广告管理不可访问
  • 权限变更测试：角色权限变更后UI更新
  • 错误场景测试：无权限访问尝试处理

部署计划

阶段1：开发环境部署

  1. 更新user-module添加权限常量定义
  2. 创建数据库迁移脚本添加默认角色
  3. 部署权限系统基础框架

阶段2：测试环境验证

  1. 广告模块集成权限检查
  2. 前端权限控制实现
  3. 完整功能测试和集成测试
  4. 性能测试和安全测试

阶段3：生产环境部署

  1. 执行数据库迁移添加默认角色
  2. 部署更新后的各模块
  3. 监控权限系统运行状态
  4. 监控广告管理权限控制效果

成功指标

  1. 功能指标：

    • 超级管理员可正常访问和操作广告管理
    • 普通管理员无法看到和访问广告管理
    • API权限检查正确返回403 Forbidden
    • 前端菜单和路由权限控制正确

  2. 性能指标：

    • 权限检查响应时间 < 50ms
    • 权限缓存命中率 > 90%
    • 系统整体性能影响 < 5%

  3. 安全指标：

    • 无权限绕过漏洞
    • 权限变更及时生效
    • 多租户权限隔离完整

  4. 用户体验指标：

    • 权限控制对授权用户透明
    • 无权限用户获得清晰提示
    • 权限变更后UI及时更新

后续优化建议

  1. 动态权限管理UI：提供后台界面管理角色和权限
  2. 权限审计日志：记录权限相关操作便于审计
  3. 角色组和继承：支持角色组和权限继承
  4. 数据行级权限：实现更细粒度的数据权限控制
  5. 权限分析报表：提供权限使用情况分析

创建时间：2025-12-19 负责人：产品经理 状态：待开始 优先级：高

开发进度

待完成

  1. ⏳ 故事1：完善角色权限定义和默认数据
  2. ⏳ 故事2：实现后端API权限检查
  3. ⏳ 故事3：实现前端权限控制
  4. ⏳ 故事4：广告管理权限集成测试

技术实现考虑

  1. 多租户支持：权限系统需完全支持多租户架构
  2. 缓存策略：用户权限信息需要合理缓存
  3. 错误处理：权限检查失败提供清晰错误信息
  4. 专注广告管理：设计仅针对广告管理权限控制，保持简单性
  5. 测试覆盖：确保权限相关逻辑充分测试