junhong_cmp_fiber/openspec/changes/archive/2026-01-15-implement-b-end-auth-system/specs/b-end-auth/spec.md

B 端认证系统规范

ADDED Requirements

Requirement: B 端用户登录

系统 SHALL 支持后台管理员、代理商和企业用户通过用户名/手机号和密码进行登录认证。

Scenario: 后台管理员登录成功

• WHEN 用户访问 POST /api/admin/login 并提供有效的用户名和密码
• THEN 系统验证凭据，生成 access token 和 refresh token，返回 token 和用户信息

Scenario: H5 端代理商登录成功

• WHEN 用户访问 POST /api/h5/login 并提供有效的用户名和密码
• THEN 系统验证凭据，生成 access token 和 refresh token，返回 token 和用户信息

Scenario: 登录失败 - 凭据无效

• WHEN 用户提供错误的用户名或密码
• THEN 系统返回 401 错误，错误码 1040，消息"用户名或密码错误"

Scenario: 登录失败 - 账号已禁用

• WHEN 用户账号状态为禁用
• THEN 系统返回 403 错误，错误码 1041，消息"账号已被锁定或禁用"

Requirement: Token 管理

系统 SHALL 使用 Redis 存储的双令牌机制管理用户会话，包括 access token（24小时有效）和 refresh token（7天有效）。

Scenario: 生成 Token 对

• WHEN 用户登录成功
• THEN 系统生成随机 UUID 作为 access token 和 refresh token，将用户信息（UserID、UserType、ShopID、EnterpriseID、Username、Device、IP、LoginTime）存储到 Redis，设置相应的 TTL

Scenario: 验证 Access Token

• WHEN 请求受保护的 API 端点时，在 Authorization 头中提供 Bearer token
• THEN 系统从 Redis 查询 token 对应的用户信息，验证 token 有效性，将用户信息注入到请求上下文

Scenario: Token 过期

• WHEN access token 超过 24 小时未使用
• THEN Redis 自动删除 token，后续验证返回 401 错误，错误码 1002，消息"令牌无效或已过期"

Scenario: Token 不存在

• WHEN 提供的 token 在 Redis 中不存在
• THEN 系统返回 401 错误，错误码 1002，消息"令牌无效或已过期"

Requirement: 用户登出

系统 SHALL 支持用户主动登出，撤销当前使用的 access token 和 refresh token。

Scenario: 成功登出

• WHEN 用户访问 POST /api/admin/logout 或 POST /api/h5/logout 并提供有效的 token
• THEN 系统从 Redis 删除对应的 access token 和 refresh token，并从用户 token 列表中移除，返回成功响应

Scenario: 已登出的 Token 无法再使用

• WHEN 用户登出后，使用相同的 token 访问受保护端点
• THEN 系统返回 401 错误，消息"令牌无效或已过期"

Requirement: Token 刷新

系统 SHALL 支持使用 refresh token 刷新 access token，延长会话有效期而无需重新登录。

Scenario: 成功刷新 Access Token

• WHEN 用户访问 POST /api/admin/refresh-token 或 POST /api/h5/refresh-token 并提供有效的 refresh token
• THEN 系统验证 refresh token，生成新的 access token（保持 refresh token 不变），返回新的 access token

Scenario: Refresh Token 无效

• WHEN 提供的 refresh token 不存在或已过期
• THEN 系统返回 401 错误，错误码 1002，消息"刷新令牌无效或已过期"

Requirement: 获取当前用户信息

系统 SHALL 支持已认证用户查询当前用户的详细信息和权限列表。

Scenario: 成功获取用户信息

• WHEN 用户访问 GET /api/admin/me 或 GET /api/h5/me 并提供有效的 access token
• THEN 系统从 token 解析用户 ID，查询数据库获取用户信息（ID、用户名、手机号、用户类型、店铺 ID、企业 ID）和权限列表，返回完整的用户信息

Scenario: Token 无效时无法获取用户信息

• WHEN 提供无效或过期的 token
• THEN 系统在中间件层拦截，返回 401 错误

Requirement: 修改密码

系统 SHALL 支持已认证用户修改自己的密码，并在密码修改后撤销所有旧 token。

Scenario: 成功修改密码

• WHEN 用户访问 PUT /api/admin/password 或 PUT /api/h5/password，提供旧密码和新密码
• THEN 系统验证旧密码，使用 bcrypt 哈希新密码并更新数据库，撤销用户所有 token（包括当前使用的 token），返回成功响应

Scenario: 旧密码错误

• WHEN 提供的旧密码不正确
• THEN 系统返回 400 错误，错误码 1043，消息"旧密码不正确"

Scenario: 密码修改后旧 Token 失效

• WHEN 用户修改密码后，使用旧的 token 访问任何端点
• THEN 系统返回 401 错误，消息"令牌无效或已过期"

Requirement: 多端认证隔离

系统 SHALL 通过认证中间件实现后台和 H5 端的用户类型隔离，确保不同端点只能被对应用户类型访问。

Scenario: 后台端点用户类型验证

• WHEN 用户访问 /api/admin/* 端点
• THEN 认证中间件验证用户类型必须为 SuperAdmin(1)、Platform(2) 或 Agent(3)，否则返回 403 错误

Scenario: H5 端点用户类型验证

• WHEN 用户访问 /api/h5/* 端点
• THEN 认证中间件验证用户类型必须为 Agent(3) 或 Enterprise(4)，否则返回 403 错误

Scenario: 公开端点无需认证

• WHEN 用户访问 /api/admin/login、/api/admin/refresh-token、/api/h5/login 或 /api/h5/refresh-token
• THEN 中间件跳过认证检查，允许匿名访问

Requirement: Token 批量撤销

系统 SHALL 支持撤销指定用户的所有 token，用于密码修改或账号禁用场景。

Scenario: 撤销用户所有 Token

• WHEN 调用 RevokeAllUserTokens(userID) 方法（内部使用，密码修改时触发）
• THEN 系统从 Redis 查询用户 token 列表（auth:user:{userID}:tokens），删除所有 access token 和 refresh token 及其对应的用户信息，清空 token 列表

Scenario: 撤销不存在用户的 Token

• WHEN 调用 RevokeAllUserTokens 但用户没有任何活跃 token
• THEN 系统不报错，直接返回成功

Requirement: 并发安全

系统 SHALL 保证 Token 管理器在高并发场景下的线程安全和数据一致性。

Scenario: 并发生成 Token

• WHEN 同一用户在不同设备上同时登录（多个并发请求）
• THEN 每个请求生成独立的 token 对，所有 token 都有效，互不干扰

Scenario: 并发撤销 Token

• WHEN 多个请求同时撤销同一 token
• THEN Redis 操作原子性保证只有一个请求成功删除，其他请求不报错

Requirement: 性能要求

系统 SHALL 满足以下性能指标。

Scenario: 登录响应时间

• WHEN 用户发起登录请求
• THEN API P95 响应时间 < 200ms，P99 响应时间 < 500ms

Scenario: Token 验证响应时间

• WHEN 请求受保护端点触发 token 验证
• THEN Redis 查询时间 < 50ms

Scenario: Token 生成唯一性

• WHEN 系统生成 token
• THEN 使用 UUID v4 保证全局唯一性，碰撞概率 < 10^-15