fix: resolve 3 review findings (permission codes, profile guard, JSDoc)

openspec/changes/rbac-refactor/proposal.md

@@ -0,0 +1,31 @@
+## 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
+<!-- 本次为纯新增基础设施，不修改现有 spec 级别的行为需求 -->
+
+## 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` 数组），所有依赖这些字段的前端代码需同步更新