学页｜RBAC权限与审计组件
概述
学页 RBAC 权限与审计组件是一款面向 K12 教培机构研发团队的权限基础设施生成技能。团队只需描述业务系统与角色构成，即可一次性获得完整的权限与审计落地包：权限模型设计文档（.md）、数据库初始化脚本（.sql，含教培预置角色）、可直接集成到 Spring Boot 项目的权限校验与操作审计组件（Java），将权限系统搭建周期从 1-2 周缩短至半天。
本技能解决权限开发中"模型设计随意""权限矩阵漏洞多""审计不合规""组件重复造轮子"四大痛点：以 RBAC1（角色继承）+ 权限分层（功能权限/数据权限/字段权限）为标准模型，以矩阵校验工具兜底设计质量，以等保 2.0 /《个人信息保护法》为审计基线，以模板化 Java 组件保证工程落地质量。
技术栈：Java 17 + Spring Boot 3.x + MyBatis-Plus + JWT（jjwt）+ MySQL 8。模板采用"拦截器 + 注解 + AOP"轻量方案，不引入 Spring Security，降低教培中小团队的集成与维护成本。
触发场景
- 直接关键词：RBAC、权限组件、权限设计、权限系统、角色权限、权限矩阵、数据权限、菜单权限、按钮权限、操作审计、审计日志、操作日志、登录日志
- 语境触发：用户描述业务系统的权限需求（如"给我们的教务系统加权限""不同角色看到不同的学生数据""谁来都能改数据，想管控"）
- 材料触发：用户上传已有的权限设计文档/表结构/角色清单，要求评审或重构
- 复合需求：权限设计 + 审计合规 + 代码落地一起要
不触发的场景：仅做通用后端开发（不走本技能流程）、仅询问权限概念（直接口头解答）、前端权限框架选型（可附带说明，但主交付物是后端）。
工作流程
遵循七步标准化工作流，按序执行，每步输出作为下步输入。
Step 1: 需求采集
从用户输入提取权限需求关键要素，信息不完整时提问补充。
需采集的要素：
| 要素 | 必填 | 默认值 | 示例 |
|---|---|---|---|
| 业务系统 | 是 | — | 教务管理系统/学管系统/网课平台 |
| 角色清单 | 否（推荐） | 教培标准六角色 | 校长/教务/学管师/班主任/授课教师/助教 |
| 权限范围 | 否 | 功能权限+数据权限 | 是否需要字段级权限 |
| 审计要求 | 否 | 基线（登录+敏感操作） | 等保2.0/个保法/内部风控 |
| 包名/工程信息 | 否 | com.xueye.rbac | 已有工程则用户提供 |
采集规则：
1. 最多提问 3 个问题，一轮问完，禁止多轮追问
2. 用户上传已有设计文档时先提取信息，减少提问
3. 非必填项未提供时用默认值，不提问
4. 信息齐全直接进入 Step 2，无需确认
Step 2: 权限模型设计
加载 references/rbac-model-design.md 获取模型规范，加载 references/education-role-templates.md 获取教培角色模板。
生成内容：
- 角色体系：确定角色清单与层级关系（是否用角色继承）。教培机构默认使用六角色模板，多校区机构追加"校区管理员"
- 权限三分层：
- 功能权限：菜单 + 按钮 + 接口（形如student:view/student:export）
- 数据权限：全部/本校区/本班级/本人（scope 枚举 + 数据规则）
- 字段权限：敏感字段（身份证/银行账号/联系电话）按角色脱敏 - 角色-权限矩阵：以表格呈现"角色 × 权限点"，每个单元格标注 ✓/✗/部分
- 异常与边界：角色互斥、离职调岗、越权访问处理策略
输出物：权限模型设计文档.md（结构见 references/rbac-model-design.md 的文档模板节）
Step 3: 矩阵校验
执行 scripts/permission_matrix_validator.py 对 Step 2 产出的权限矩阵做质量校验。
做法： 将矩阵整理为标准 JSON（格式见脚本头部说明），执行：
python scripts/permission_matrix_validator.py matrix.json
python scripts/permission_matrix_validator.py matrix.json --fix # 自动修复建议
校验项： 权限编码规范、角色覆盖完整性、最小权限原则、互斥角色冲突、孤儿权限、数据范围与功能权限一致性。校验不通过的项修复后重新校验，直至 PASS。
Step 4: 数据库落地
加载 references/sql-schema.md 获取表设计规范，基于 assets/spring-boot-template/sql/rbac_audit_init.sql 定制生成。
定制要点：
1. 按业务改库名、按需增删权限点数据（INSERT 部分与 Step 2 矩阵严格一致）
2. 教培预置六角色及其权限绑定默认保留，用户特有角色追加
3. 多校区机构启用 campus_id 相关列与数据规则
4. 交付前用脚本对 SQL 与矩阵做一致性核对
输出物：rbac_init.sql（建表 + 索引 + 角色权限预置数据 + 审计表初始化）
Step 5: 后端组件集成
将 assets/spring-boot-template/ 复制到用户工程（或独立交付），按 assets/spring-boot-template/README.md 的集成说明适配。
模板组件清单：
| 组件 | 位置 | 职责 |
|---|---|---|
@RequirePermission / @RequireRole |
annotation/ | 接口级权限声明 |
PermissionInterceptor |
interceptor/ | JWT 解析 → 加载角色权限 → 校验注解 |
@AuditLog + AuditAspect |
annotation/ aspect/ | 敏感操作自动落审计表（异步） |
DataScopeInterceptor |
interceptor/ | MyBatis-Plus 数据权限 SQL 注入 |
SensitiveFieldSerializer |
util/ | 字段权限脱敏（Jackson） |
JwtUtil / CurrentUser |
util/ | 令牌签发校验 / 登录态上下文 |
| Service/Controller 示例 | service/ controller/ | 学生管理示例，演示三类权限用法 |
适配规则： 包名按用户工程调整；权限编码与 Step 2 矩阵一致；已有登录体系的替换 JwtUtil 对接部分，其余组件不动。
Step 6: 审计配置与合规检查
加载 references/audit-compliance.md，确定审计范围与保留策略，然后用 scripts/audit_log_validator.py 校验审计实现：
python scripts/audit_log_validator.py audit_config.json
python scripts/audit_log_validator.py logs/sample_log.jsonl --schema
基线要求： 登录/登出、权限变更、敏感数据导出、学生个人信息 CRUD 必须审计；日志含 who/when/what/where/result 五要素；不可篡改（仅追加）；保留 ≥ 180 天（等保 2.0 三级要求 6 个月）。含学生个人信息的操作按《个人信息保护法》要求记录处理目的与依据字段。
Step 7: 成果整合交付
调用 present_files 统一交付。
交付物：
| 交付物 | 格式 | 内容 |
|---|---|---|
| 权限模型设计文档 | .md | 角色/权限模型 + 完整矩阵 + 边界策略 |
| 数据库脚本 | .sql | 7 张核心表 + 索引 + 预置数据 |
| 后端组件包 | Java 源码目录 | 权限校验 + 审计 + 数据权限 + 示例 |
| 校验报告 | 终端输出/文本 | 矩阵校验 + 审计校验结果 |
交付后提示： 提示按 README 集成到工程；提示预置账号密码需首次登录强制修改；提示生产环境务必开启审计异步落库与定期归档。
参考文档索引
按需加载，不必一次性全部读取：
| 文档 | 路径 | 加载时机 |
|---|---|---|
| RBAC 模型设计规范 | references/rbac-model-design.md |
Step 2 |
| K12 教培角色权限模板 | references/education-role-templates.md |
Step 2 |
| 数据库表设计规范 | references/sql-schema.md |
Step 4 |
| 审计合规要求 | references/audit-compliance.md |
Step 6 |
工具脚本
| 脚本 | 路径 | 用途 | 调用时机 |
|---|---|---|---|
| 权限矩阵校验器 | scripts/permission_matrix_validator.py |
校验角色-权限矩阵质量，输出问题清单与修复建议 | Step 3 |
| 审计日志校验器 | scripts/audit_log_validator.py |
校验审计配置完整性、日志记录五要素合规性 | Step 6 |
依赖的 WorkBuddy 内置能力
| 能力 | 用途 | 调用步骤 |
|---|---|---|
present_files |
统一交付成果 | Step 7 |
| Bash/文件读写 | 执行校验脚本、复制模板 | Step 3/5/6 |
重要约束
- 矩阵一致性：设计文档、SQL 预置数据、Java 权限编码三者必须同源一致，任何一处变更需同步另两处。
- 最小权限原则：默认拒绝（deny by default），逐角色显式授权；校验器报 WARN 以上必须处理。
- 审计不可绕过：审计切面在鉴权之后、业务之前执行，禁止业务代码里"先删注解再调试"式的旁路。
- 默认拒绝而非默认放行：未标注权限注解的写操作接口，集成说明中必须提示补注解或加白名单评审。
- 教培默认角色可裁剪：六角色模板按需裁剪，但"校长/授课教师"两个锚点角色的权限边界不得合并混淆。
- 数据权限下沉 SQL：数据范围过滤必须在 SQL 层注入，禁止仅在内存过滤后返回。
- 敏感字段脱敏前置：学生身份证/银行卡/联系电话在序列化层脱敏，禁止依赖前端。
