gongxue-base/openspec/changes/rbac-refactor/proposal.md

Why

当前系统采用硬编码双角色鉴权（admin/operator），权限控制仅通过前端菜单可见性（allowedMenus JSON 字段）实现软限制，后端所有接口零权限校验。随着角色需求扩展到超管、机构负责人、老师、宿管老师等多种角色，并为后续数据级权限（机构→班级→学生）扩展预留基础，需要将鉴权体系重构为标准 RBAC（基于角色的访问控制）模型。

What Changes

• RBAC 实体层：新增 Role、Permission、RolePermission、UserRole 四张表，替代 users 表的单一 role 字段和 allowedMenus 字段
• 权限守卫：新增 @RequirePermission 装饰器和 PermissionGuard，在后端对所有 API 接口实施权限校验（BREAKING：现有接口仅依赖 JwtAuthGuard 无权限控制）
• 用户实体迁移：users 表移除 role 和 allowedMenus 字段，改为通过 UserRole 多对多关联角色；现有 admin 用户自动迁移获得超管角色
• 种子数据：应用启动时自动创建超管角色（含全部权限点）、四个预置角色（超管、机构负责人、老师、宿管老师）、约 40+ 权限点
• 前端权限管理界面：角色管理（CRUD + 权限勾选）、权限一览（按模块分组展示）、用户-角色关联编辑
• 前端权限适配：路由守卫按权限控制页面访问，按钮/操作按权限控制可见性，登录后 JWT 携带权限点列表
• 权限点定义：从现有 18 个 API endpoint + 前端按钮操作反推，覆盖学生/宿舍/入住/费用/账单/教室/押金/操作日志/账号管理全部模块

Capabilities

New Capabilities

• db-migration: TypeORM Migration 基础设施搭建（CLI 配置、迁移脚本生成与执行命令），用于 RBAC 建表、种子数据插入和 users 表结构变更
• rbac-core: RBAC 核心实体与数据库层（Role、Permission、RolePermission、UserRole 表，种子数据初始化，users 表迁移）
• permission-guard: 后端权限守卫（@RequirePermission 装饰器、PermissionGuard、JWT payload 扩展、403 响应）
• permission-admin-ui: 前端权限管理界面（角色 CRUD、权限一览、用户-角色分配）

Modified Capabilities

Impact

• 数据库：新增 4 张表（roles、permissions、role_permissions、user_roles）；users 表删除 role 和 allowedMenus 列
• 后端：所有 Controller 方法需添加 @RequirePermission 装饰器；auth module 重构为 rbac module；JWT payload 扩展携带权限列表
• 前端：MainLayout 菜单过滤逻辑从 allowedMenus 改为权限点匹配；App.tsx 路由增加权限守卫；Login 页登录成功处理调整；Users 管理页重构为用户-角色分配
• 破坏性变更：api.login() 返回的 user 对象结构变化（role + allowedMenus → roles 数组 + permissions 数组），所有依赖这些字段的前端代码需同步更新