auth 认证与授权

这是什么

@01mvp/auth 是项目的登录认证系统，基于 Better Auth 构建。它的核心工作只有两件事：

1. 认证（Authentication，验证身份）：确认"你是谁"。比如输入手机号 + 验证码、微信扫码、邮箱密码等方式登录
2. 授权（Authorization，控制权限）：确认"你能做什么"。比如管理员能删除用户，普通用户不能

能做什么

登录方式

• 手机号登录：发送短信验证码，输入验证码即登录
• 微信登录：PC 端扫码登录，手机端跳转微信授权
• 邮箱密码登录：传统的邮箱 + 密码方式
• 第三方登录：支持 GitHub、Google 等 OAuth 登录（OAuth = 用第三方账号登录，不用注册新账号）
• 邀请码注册：通过邀请码注册，可暂时不填邮箱（后续再绑定）

权限管理

系统有一个权限枚举 AdminPermission，里面定义了所有可管理的权限项，比如：

• VIEW_USERS -- 查看用户列表
• MANAGE_USERS -- 管理用户（编辑、删除）
• BAN_USERS -- 封禁用户
• REVIEW_CONTRIBUTIONS -- 审核贡献
• MANAGE_BADGES -- 管理勋章
• 等等...

检查权限用 hasPermission(user, AdminPermission.XXX)，返回 true 或 false。

有两个预设管理员角色：

• 超级管理员（SUPER_ADMIN）：拥有所有权限
• 运营管理员（OPERATION_ADMIN）：拥有运营相关权限

权限枚举速查

下面列出了 AdminPermission 中所有可用的权限项：

组织管理

支持组织和成员角色管理。组织内有三种角色层级：全局管理员 > 组织所有者 > 组织管理员。

怎么配置

# 微信登录
WECHAT_APP_ID=your-app-id
WECHAT_APP_SECRET=your-app-secret

# 移动端微信登录（如果需要）
WECHAT_MOBILE_APP_ID=your-mobile-app-id
WECHAT_MOBILE_APP_SECRET=your-mobile-app-secret

# GitHub OAuth（如果需要）
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Google OAuth（如果需要）
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

微信登录需要先在微信开放平台注册应用并配置回调域名。

大概原理

登录流程

用户点击"登录"
  -> 选择登录方式（手机/微信/邮箱/第三方）
    -> Better Auth 处理认证流程（验证码校验 / OAuth 跳转 / 密码比对）
      -> 认证成功 -> 生成 Session（会话），用户保持登录状态
      -> 认证失败 -> 返回错误提示

权限检查流程

页面加载 / API 调用
  -> hasPermission(user, AdminPermission.XXX)
    -> 检查用户角色（super_admin / operation_admin / 普通用户）
      -> 有权限 -> 正常显示 / 继续操作
      -> 无权限 -> 隐藏按钮 / 返回 403

权限检查实践

重要：权限检查要做两次：

1. 客户端检查（控制 UI 显示）：没权限就不显示按钮
2. 服务端检查（真正的安全防线）：API 层也要检查，防止直接调用接口绕过前端

路由保护配置

RouteConfig 用来定义路由的访问控制规则，配合 matchRoute 和 checkRouteAccess 使用：

相关链接

• 认证系统指南 -- 完整配置和使用指南
• Better Auth 文档 -- 底层认证框架
• 微信开放平台 -- 注册微信应用