classDiagram
    class Employee {
        +str employee_id
        +str corp_id
        +str name
        +str department
        +str position
        +str avatar
    }
    class Agent {
        +str user_id
        +str name
        +str role
        +str status
        +str mfa_secret
        +bool mfa_enabled
        +datetime mfa_bound_at
        +datetime mfa_last_verified_at
        +str password_hash
        +int current_load
        +int max_load
    }
    class OtpSecret {
        <<值对象，内嵌于 Agent>>
        +str secret
        +bool enabled
        +datetime bound_at
        +datetime last_verified_at
    }
    class Token {
        <<Redis 存储>>
        +str token
        +str employee_id
        +list roles
        +str current_role
        +str login_source
        +int ttl_seconds
    }
    class MFAService {
        <<static 封装 pyotp>>
        +generate_secret() str
        +build_provisioning_uri(secret, id) str
        +render_qrcode_base64(uri) str
        +verify_code(secret, code) bool
        +mark_verified(redis, id, ttl)
        +is_verified(redis, id) bool
    }
    class TokenService {
        +create_token(employee_id, name, roles, ...) str
        +get_user_info(token) dict
        +refresh(token) bool
        +switch_role(token, role) bool
    }
    class OtpRouter {
        <<FastAPI 前缀 /api/auth>>
        +GET otp-status
        +POST otp-bind
        +POST otp-verify
        +POST otp-unbind
        +POST otp-admin-reset/{id}
        +GET otp-admin-users
    }
    class LoginRouter {
        <<agents/login + auth_qrcode>>
        +POST agents/login
        +POST auth_qrcode/create
        +GET auth_qrcode/poll/{ticket}
        +POST auth_qrcode/scan
        +POST auth_qrcode/confirm
    }
    class H5OAuthRouter {
        <<h5 OAuth>>
        +GET h5/oauth/authorize
        +GET h5/oauth/sns-callback
        +POST h5/oauth/callback
    }
    class AdminIPWhitelistMiddleware {
        +is_production 门控
        +ip_in_whitelist(ip) bool
    }
    Agent "1" *-- "1" OtpSecret : 内嵌 mfa_*
    OtpRouter ..> MFAService : 复用
    OtpRouter ..> Agent : 读写 mfa_*
    OtpRouter ..> Token : 依赖 Bearer 鉴权
    LoginRouter ..> TokenService : 签发 token
    LoginRouter ..> MFAService : agents/login 内联校验
    H5OAuthRouter ..> TokenService : 签发 employee token
    TokenService ..> Token : 存 Redis(user/employee/agent)
    AdminIPWhitelistMiddleware ..> LoginRouter : 守卫 /api/admin/*