---
name: auth-permission
when: '权限认证, 权限校验, 认证, 登录, 鉴权, 授权, Token, JWT, RBAC, 角色, @PreAuthorize, 登录验证, 访问控制'
scope:
  - backend
products:
  - '*'
id: ka-pattern-auth-permission
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 权限认证
  - 权限校验
  - 认证
  - 登录
  - 鉴权
  - 授权
  - Token
  - JWT
  - RBAC
  - 角色
  - '@PreAuthorize'
  - 登录验证
  - 访问控制
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 所有写接口必须有权限注解或 URL 级别鉴权
- 禁止在 Controller 中硬编码角色判断（if role == "ADMIN"）
- JWT Token 必须设置过期时间（建议 2-8 小时）
- 密码必须使用 BCrypt 哈希存储，禁止明文或可逆加密
- 前端隐藏按钮不能替代后端权限校验
- 任何新增或修改菜单必须同步声明角色、权限标识、默认可见性和数据范围
- 页面可见不等于可操作，按钮权限、接口权限和数据权限必须分别定义
- 接口鉴权要求必须能回链到角色与权限模型，不能只写 auth=token
- 禁止菜单可见性与接口可调用性解耦（菜单隐藏但接口暴露）
- 登录失败不得提示具体原因（不区分"用户名不存在"和"密码错误"）
- 登录接口必须有暴力破解防护（连续失败 N 次锁定或验证码）
- Session ID 必须在登录成功后重新生成，防止会话固定攻击
- 前端敏感操作（修改密码、删除）必须重新验证身份（re-authentication）
- API 接口必须实现限流（Rate Limiting），防止暴力枚举和 CC 攻击

## 验收项
- [AC-01] 写接口有权限注解或鉴权
- [AC-02] Token 有过期时间
- [AC-03] 密码 BCrypt 哈希存储
- [AC-04] 无硬编码角色判断
- [AC-05] 菜单/按钮/接口/数据范围三层权限同步定义
- [AC-06] 接口鉴权可回链到角色权限模型
- [AC-07] 登录失败不暴露具体原因
- [AC-08] 有暴力破解防护机制
- [AC-09] 敏感操作重新验证身份
- [AC-10] API 接口有限流策略
