认证模块

认证模块提供基于 JWT 的完整双端认证体系，支持 SM2 国密加密传输和 bcrypt 密码哈希存储。

功能说明

• B 端用户名密码登录（SM2 加密传输）
• B 端用户注册
• B 端用户登出（服务端 Token 失效）
• 图形验证码生成与校验
• Token 签发与校验（Redis 服务端缓存）

API 接口

B 端认证

方法	路径	权限	说明
POST	/api/v1/public/b/login	无	B 端用户名密码登录
POST	/api/v1/public/b/register	无	B 端用户注册
POST	/api/v1/b/logout	@HeiCheckLogin	B 端用户登出

验证码

方法	路径	权限	说明
GET	/api/v1/public/b/captcha	无	获取 B 端图形验证码

登录流程

1. 前端请求验证码 GET /api/v1/public/b/captcha
   ← 返回 captcha_base64（图片）和 captcha_id
2. 前端获取 SM2 公钥（内置在前端配置中）
3. 前端使用公钥加密密码（SM2 C1C3C2 模式）
4. 发送登录请求 POST /api/v1/public/b/login
   {
     "username": "admin",
     "password": "SM2加密后的密码",
     "captcha_id": "...",
     "captcha_code": "..."
   }
5. 后端验证：
   a. 验证码校验（如提供）
   b. 私钥解密密码
   c. bcrypt 比对密码哈希
   d. 签发 JWT Token（写入 Redis）
6. 后续请求携带 Authorization Header

认证配置

JWT 配置在 .env 文件中：

JWT__SECRET_KEY=your-secret-key     # JWT 密钥
JWT__ALGORITHM=HS256                # 加密算法
JWT__EXPIRE_SECONDS=2592000         # Token 有效期 30 天
JWT__TOKEN_NAME=Authorization       # Token Header 名称

认证工具类

HeiAuthTool（B端）

from core.auth.auth import HeiAuthTool

# 登录：签发 Token 并写入 Redis
token = await HeiAuthTool.login(user_id, request, extra)

# 检查是否登录
is_login = await HeiAuthTool.isLogin(request)

# 获取登录用户 ID
user_id = await HeiAuthTool.getLoginIdAsString(request)

# 获取登录用户信息
user_info = await HeiAuthTool.getLoginUser(request)

# 检查权限
has_perm = await HeiAuthTool.hasPermission("sys:banner:page", request)

# 获取角色列表
roles = await HeiAuthTool.getRoleList(request)

# 登出（清除 Redis 中的 Token）
await HeiAuthTool.logout(request)

HeiClientAuthTool（C端）

from core.auth.auth import HeiClientAuthTool

# 使用方式与 HeiAuthTool 相同
token = await HeiClientAuthTool.login(user_id, request, extra)

权限装饰器

B 端权限装饰器

from core.auth.decorator import HeiCheckLogin, HeiCheckPermission, HeiCheckRole

# 检查是否登录
@HeiCheckLogin

# 检查权限（权限标识格式：module:action）
@HeiCheckPermission("sys:banner:page")

# 检查角色
@HeiCheckRole("admin")

C 端权限装饰器

from core.auth.decorator import HeiClientCheckLogin, HeiClientCheckPermission

# 检查 C 端用户是否登录
@HeiClientCheckLogin

# 检查 C 端用户权限
@HeiClientCheckPermission("c:client-user:page")

SM2 国密加密

密码加密流程

1. 前端获取 SM2 公钥（内置在前端配置 VITE_SM2_PUBLIC_KEY）
2. 前端使用公钥加密密码
3. 后端使用私钥解密密码
4. 后端使用 BCrypt 验证密码（注册时使用 bcrypt 哈希存储）

SM2 工具类

from core.utils import sm2_crypto_util as sm2

# 初始化密钥
sm2.init(private_key, public_key)

# 加密（使用公钥）
ciphertext = sm2.encrypt(plaintext)

# 解密（使用私钥）
plaintext = sm2.decrypt(ciphertext)

# 生成密钥对
private_key, public_key = sm2.gen_keypair()

验证码服务

from modules.auth.captcha.core import CaptchaService

# 获取验证码（返回 base64 图片 + captcha_id）
result = await CaptchaService.get_captcha()

# 校验验证码
await CaptchaService.check_captcha(captcha_id, captcha_code)

验证码使用 Redis 存储，有效期内可校验一次后自动失效。

权限自动发现

应用启动时自动扫描所有路由的 @HeiCheckPermission 装饰器，将权限定义缓存到 Redis：

# core/auth/permission_scan.py 中的流程
1. 遍历 app.routes 所有路由
2. 提取 endpoint 的 _hei_permission 属性
3. 按模块分组（如 sys:banner → sys）
4. 缓存到 Redis key: hei:permissions

权限定义不会自动写入数据库，需要管理员通过权限管理页面手动创建权限记录。