By name: yweb-auth description: YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
YWeb 认证授权与权限管理规范
核心要点
YWeb 提供完整的认证授权体系：
- 双 Token 机制：Access Token（短期）+ Refresh Token（长期）
- 认证服务基类：继承
BaseAuthService实现自定义认证 - 一站式认证设置：
setup_auth()快速启用 - Token 黑名单：
setup_auth(token_blacklist=True)自动集成黑名单检查，登出/踢出时撤销 Token - RBAC 权限框架：基于角色的访问控制，支持树形角色继承
- 缓存优化：
@cached(orm_model=User)缓存用户信息，自动 merge 回 Session 解决 detached 问题 - M2M 关系缓存失效：
cache_invalidator.register()默认监听 ManyToMany 集合变更（如 roles 增删），自动失效缓存 - 组织架构管理：
setup_organization()快速启用组织管理功能
关键编码规范
- 认证依赖注入：使用
auth.get_current_user作为 FastAPI 依赖（setup_auth()返回的AuthSetup对象） - 权限检查：使用权限装饰器或依赖注入，不在 API 层手动检查
- Token 处理：后端使用
jwt_manager，前端实现自动刷新机制 - 用户模型：认证相关模型遵循框架约定（RoleMixin 等）
- 缓存 ORM 对象：使用
@cached(orm_model=User)而非裸@cached()，确保缓存命中时自动 merge 回 Session - 缓存失效：
cache_invalidator.register(Model, func)默认watch_relationships=True，自动监听 M2M 集合变更；显式传False可关闭
详细规范文档
| 主题 | 文档路径 |
|---|---|
| 认证模块完整指南 | yweb-core/docs/06_auth_guide.md |
| 认证流程详解（含缓存优化） | yweb-core/docs/webapi_development_standards/auth_flow_guide.md |
| JWT Token 前后端规范 | yweb-core/docs/webapi_development_standards/jwt_auth_guide.md |
| 权限管理模块（RBAC） | yweb-core/docs/08_permission_guide.md |
| 组织架构管理 | yweb-core/docs/07_organization_guide.md |
工作流程
- 初次接入认证功能，阅读
06_auth_guide.md了解支持的认证方式 - 实现 JWT 相关逻辑前，阅读
jwt_auth_guide.md了解双 Token 机制 - 理解认证流程和缓存策略，阅读
auth_flow_guide.md - 实现权限控制前，阅读
08_permission_guide.md - 涉及组织架构管理时，阅读
07_organization_guide.md