Web 认证模块 — CUJ 关键用户旅程

Employee Auth, RBAC & Session Management | 更新时间: 2026-02-09

架构概览

双认证系统

JWT Token 生命周期

flowchart LR
    A["POST /auth/login\n邮箱+密码"] --> B["验证密码\nbcrypt compare"]
    B --> C["检查账户状态\nactive? locked?"]
    C --> D["生成 JWT\nRS256 签名"]
    D --> E["Access Token\n15 分钟有效"]
    D --> F["Refresh Token\n7 天有效"]
    E --> G["HttpOnly Cookie\n+ localStorage 备份"]
    F --> G
    G --> H["每 10 分钟\n自动刷新"]
    H --> I["POST /auth/refresh"]
    I --> D

    J["登出 / Token 过期"] --> K["Token Blacklist\nauth_token_blacklist"]
    K --> L["重定向 /login"]

Token 配置

JWT Payload 结构

角色层级与权限

三层权限优先级

Rate Limiting

目录

CUJ 总览与优先级矩阵

CUJ-A1: 员工邮箱登录

P0 系统入口 — 员工通过邮箱密码登录管理后台

用户流程

flowchart TD
    A["访问 /en/qqnails/login"] --> B["TenantContext 验证租户"]
    B --> C{租户有效?}
    C -->|"否"| D["显示 Tenant Error 页面"]
    C -->|"是"| E["显示登录表单\n含租户 Logo"]
    E --> F["输入邮箱 + 密码"]
    F --> G["POST /api/auth/employee/login\nbody 含 tenant_id"]
    G --> H{后端验证}
    H -->|"账户锁定"| I["错误: 账户已锁定\n30分钟后重试"]
    H -->|"密码错误"| J["错误: Invalid email or password\n失败次数+1"]
    H -->|"must_change_password"| K["重定向到改密页"]
    H -->|"成功"| L["JWT Token → Cookie + localStorage"]
    L --> M{角色判断}
    M -->|"admin"| N["跳转 /admin/dashboard"]
    M -->|"其他"| O["跳转 /appointments/board"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style N fill:#4CAF50,stroke:#2E7D32,color:#fff
    style O fill:#4CAF50,stroke:#2E7D32,color:#fff
    style I fill:#f44336,stroke:#c62828,color:#fff
    style J fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 A1.1: 正常登录 — 正确凭据

测试: login.spec.ts

场景 A1.2: 登录失败 — 错误密码

测试: login.spec.ts

场景 A1.3: 邮箱自动去除空格

测试: AuthContext.login.test.tsx (单元)

场景 A1.4: 支持 returnUrl 参数

场景 A1.5: 会话过期提示

CUJ-A2: 会话保持与自动刷新

P0 用户体验 — Access Token 15分钟有效，每10分钟自动刷新

用户流程

flowchart TD
    A["用户正在操作后台"] --> B["AuthContext setInterval\n每10分钟检查"]
    B --> C{Token 即将过期?}
    C -->|"否 (>5min)"| A
    C -->|"是 (<5min)"| D["POST /api/auth/refresh\n携带 refresh token"]
    D --> E{刷新成功?}
    E -->|"是"| F["新 access token\n更新 Cookie + localStorage"]
    F --> A
    E -->|"否 (refresh 也过期)"| G["清除所有 token"]
    G --> H["重定向 /login?sessionExpired=true"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style F fill:#4CAF50,stroke:#2E7D32,color:#fff
    style H fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 A2.1: Token 自动刷新 — 静默成功

测试: 缺失 — 需新增

场景 A2.2: Refresh Token 过期 — 强制重新登录

测试: full-flow/01-auth-verification.spec.ts (部分覆盖)

场景 A2.3: 网络断开恢复后自动重试

CUJ-A3: 未认证重定向与公开路由

P0 安全性 — 未登录用户只能访问公开路由，其余重定向到登录页

用户流程

flowchart TD
    A["访问任意页面"] --> B["AuthGuard 检查"]
    B --> C{已认证?}
    C -->|"是"| D["正常渲染"]
    C -->|"否"| E{是公开路由?}
    E -->|"是"| F["允许访问"]
    E -->|"否"| G["重定向 /login\n携带 returnUrl"]

    style D fill:#4CAF50,stroke:#2E7D32,color:#fff
    style F fill:#4CAF50,stroke:#2E7D32,color:#fff
    style G fill:#FF9800,stroke:#E65100,color:#fff

公开路由列表

BDD 场景

场景 A3.1: 未登录访问受保护页面

测试: url-redirects.spec.ts

场景 A3.2: 公开路由不拦截

测试: AuthGuard.test.tsx (单元 — 8 公开路由 + 7 受保护路由)

CUJ-A4: 账户锁定与安全防护

P0 防暴力破解 — 连续5次错误密码后锁定30分钟

BDD 场景

场景 A4.1: 连续5次错误 — 账户锁定

测试: 缺失 — 需新增

场景 A4.2: 锁定到期 — 自动解锁

场景 A4.3: 成功登录重置计数

CUJ-A5: RBAC 权限检查

P0 最小权限 — 页面级 ProtectedRoute + 组件级 PermissionGate

权限检查流程

flowchart TD
    A["用户访问页面"] --> B["ProtectedRoute 检查"]
    B --> C{已认证?}
    C -->|"否"| D["重定向 /login"]
    C -->|"是"| E["加载用户权限\nusePermissions()"]
    E --> F{有 requiredPermission?}
    F -->|"否"| G["渲染页面"]
    F -->|"是"| H{检查权限}
    H -->|"DENY 特殊权限"| I["Permission Denied 对话框"]
    H -->|"GRANT 特殊权限"| G
    H -->|"检查 Role 权限"| J{角色有此权限?}
    J -->|"是"| K{检查权限级别}
    J -->|"否"| I
    K -->|"view 够用"| G
    K -->|"需要 manage"| L{有 manage 级别?}
    L -->|"是"| G
    L -->|"否"| I

    style G fill:#4CAF50,stroke:#2E7D32,color:#fff
    style I fill:#f44336,stroke:#c62828,color:#fff
    style D fill:#FF9800,stroke:#E65100,color:#fff

BDD 场景

场景 A5.1: ProtectedRoute — 有权限

场景 A5.2: ProtectedRoute — 无权限

场景 A5.3: PermissionGate — 组件级隐藏

场景 A5.4: Superadmin 跳过权限检查

场景 A5.5: 门店范围权限

CUJ-A6: 多租户登录隔离

P1 数据安全 — 不同租户的登录凭据和会话完全隔离

用户流程

flowchart TD
    A["访问 /en/qqnails/login"] --> B["TenantContext 验证 qqnails"]
    B --> C{租户有效且激活?}
    C -->|"否"| D["Tenant Error 页面\nTENANT_NOT_FOUND"]
    C -->|"是"| E["渲染登录表单\n显示租户 Logo"]
    E --> F["POST /auth/login\n含 tenant_id"]
    F --> G["后端切换 Schema\ntenant_qqnails"]
    G --> H["在租户 Schema 中验证员工"]
    H --> I["JWT 写入 tenant_short_id"]

    style E fill:#4CAF50,stroke:#2E7D32,color:#fff
    style D fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 A6.1: 正确租户登录

测试: AuthContext.login.test.tsx (单元)

场景 A6.2: 无效租户 — 显示错误页

测试: 缺失 — 需新增

场景 A6.3: 跨租户 Token 拒绝

测试: 缺失 — 需新增

CUJ-A7: 密码变更

P1 安全合规 — 首次登录强制改密 + 主动密码变更

BDD 场景

场景 A7.1: 首次登录 — 强制改密

测试: 缺失 — 需新增

场景 A7.2: 主动改密

CUJ-A8: 门店切换

P1 多门店支持 — 员工在授权的多个门店间切换

BDD 场景

场景 A8.1: 切换到授权门店

场景 A8.2: 管理员 — 可查看所有门店

CUJ-A9: 登出

P2 安全性 — 用户主动登出，清除所有会话数据

BDD 场景

场景 A9.1: 正常登出

测试: login.spec.ts

跨模块链接

关键业务规则