Appearance
05 · 账户与认证系统
0. 文档说明
| 项 | 内容 |
|---|---|
| 版本 | V1.0 |
身份底座。用户、凭证、KYC、会话全部按租户强隔离(→ 00 §4.9);注册发
UserRegistered(→ 09 新人活动 / 11 绑定上级)。
一、定位与职责
- 定义用户账号模型(多标识:用户名/邮箱/手机)与登录注册合一流程;
- 定义游客态与门禁规则(可浏览、动作即弹登录);
- 定义 KYC(实名认证)等级与状态机、触发时机;
- 定义会话/设备管理与安全中心(改密、绑定、登录日志);
- 定义推广关系的注册时绑定(与 11 协作)。
边界:后台管理账号是独立体系(→ 15,不混用);风控名单与封禁策略归 14;本系统执行封禁动作。
二、核心概念与数据模型
2.1 用户 User
| 字段 | 说明 |
|---|---|
userId / tenantId | 用户标识、归属租户(同一手机号在两个租户 = 两个独立用户) |
nick / avatar | 昵称、头像(默认生成,可改) |
status | ACTIVE / FROZEN(冻结:可登录可看不可交易)/ BANNED(封禁:不可登录) |
inviterId | 上级(注册时绑定,不可改,→ 11) |
registerChannel / registerAt | 注册来源、时间 |
2.2 登录标识 UserIdentifier(一账号多标识)
type ∈ USERNAME / EMAIL / PHONE,同租户内 (type, value) 唯一。认证方式:
| 方式 | 凭证 | 备注 |
|---|---|---|
| 用户名 | 密码 | 注册即设密码 |
| 邮箱 | 仅验证码(OTP) | 无密码路径,60s 重发倒计时 |
| 手机号 | 仅验证码(OTP) | 同上 |
登录注册合一:同一入口页;标识不存在 → 视为注册并创建账号;存在 → 登录。无独立注册页、无邀请码输入框——推广关系由落地链接 ?ref=<code> 静默携带绑定(§3.4)。
2.3 游客态 Guest
未登录可浏览全站(首页/大厅/优惠列表);门禁动作(进游戏、收藏⭐、收藏/最近 tab、领取、充值、赚钱、爆奖卡、活动参与)一律弹出登录注册页,不做空状态页。
2.4 KYC(状态机)
NONE(未认证) ──提交──► PENDING(审核中) ──通过──► APPROVED(已认证)
│
└──驳回(可重提)──► REJECTED ──重提──► PENDING等级:BASIC(证件)→ ADVANCED(人脸/地址证明,可选启用)。触发时机由 auth.kycRequired 配置:never / onWithdraw / onRegister;默认 never,后台可对单个账户下发要求(风控/合规触发,→ 14/15)。
BASIC 级提交信息(生产口径):
| 字段 | 校验 |
|---|---|
| 证件类型 | 身份证 / 护照(枚举,决定后续字段与照片数) |
| 真实姓名 | 2–20 位中文(含少数民族分隔号「·」);认证通过后锁定,收款账户须实名一致(→ 04) |
| 证件号码 | 身份证:18 位 GB11643 校验位算法 + 出生段基本合理性;护照:8–9 位字母数字 |
| 证件有效期 | 日期 或 勾选「长期有效」 |
| 证件照片 | 身份证:人像面 + 国徽面 + 手持证件照(三张);护照:资料页 + 手持证件照(两张)。要求边框完整/清晰无反光、手持照面部与证件同框,单张 ≤ 5MB |
| 授权勾选 | 同意仅用于合规核验、加密存储(→ §八 payload_cipher) |
审核:提交即 PENDING(预计 1–3 分钟,OCR + 人工兜底);驳回必附原因(证件模糊/信息不符/证件过期…),REJECTED 保留已填信息一键重提;通过后展示脱敏摘要(张** / 1101**********09),不可自行修改(变更走客服工单)。
2.5 会话 Session 与设备
登录签发 token(TTL 可配);设备指纹登记(→ 14);多端策略可配(共存/互踢);安全中心可查登录日志、踢除其他设备。
三、业务规则
- 注册即全链路就绪:创建用户 → 初始化本站本位币钱包(02,按
wallet.baseCurrency;单币种站一人一钱包)→ 绑定上级(若有 ref)→ 发UserRegistered→ 09 新人活动实例化、16 欢迎通知。 - OTP 安全:验证码 6 位、TTL 5 分钟、60s 重发限制、错误 5 次锁定 15 分钟;发送走 16 的短信/邮件通道。
- 密码策略:最小强度可配;连续失败锁定;修改密码踢除其他会话。
- 推广绑定:
?ref=在注册完成时绑定inviterId,一次绑定终身不可改;自邀/环路由 14 校验拒绝。 - 冻结与封禁:FROZEN 禁交易类动作(充提/投注/领取),BANNED 禁登录;触发方 = 14 风控或后台人工(留审计)。
- 实名一致性:KYC 通过后姓名锁定,法币银行卡绑定须 name-match(→ 04)。
- 资金密码触发清单:资金密码为 6 位数字、默认关闭、用户在安全中心主动开启(→ §七)。开启状态下,以下敏感动作在执行前必须先弹资金密码校验(校验通过方继续,连续错误按 OTP 同策 5 次锁定 15 分钟):
- 提现:点「确认提现」→ 通过金额/KYC 校验后、
WITHDRAW_LOCK建单前(→ 04 §3.1、§七#wd-go); - 提现撤销:处理中提现单原路退回前(→ 04 §七
#sub-wtxn详情撤销); - 收款账户增/删/改:新增账户、编辑账号、删除账户、设为默认(→ 04 §2.2 账户管理);
- 安全中心敏感变更:修改登录密码、换绑手机、换绑/改邮箱前(与各自 OTP 叠加,资金密码在前)。 未开启资金密码时,上述动作按各自原校验链执行(不额外拦截)。资金密码真实值加密存储(校验比对而非仅存布尔),忘记走绑定手机 OTP 重置(→ §七)。
- 提现:点「确认提现」→ 通过金额/KYC 校验后、
四、★ 租户可配置项(auth 命名空间)
jsonc
"auth": {
"methods": ["username", "email", "phone"], // 开放哪些注册/登录方式(⊆ 三种)
"kycRequired": "never", // never(默认)| onWithdraw | onRegister;后台可按账户下发覆盖(→ 14/15)
"kycLevels": ["BASIC"], // 启用的认证等级
"password": { "minLen": 8, "requireMix": true },
"otp": { "ttlSec": 300, "resendSec": 60, "maxRetry": 5 },
"session": { "ttlMin": 43200, "multiDevice": true },
"guestBrowse": true // 游客可浏览(false=强制先登录)
}五、与其他系统的关系 / 接口
| 接口 | 调用方 | 幂等键 | 说明 |
|---|---|---|---|
authOrRegister(type, value, credential, ref?) | 展示层 | OTP 一次性 | 合一入口:不存在即注册,存在即登录 |
sendOtp(type, value) | 展示层 | 频控 | 走 16 通道 |
me() | 展示层 | — | 01 §5.2 用户快照(聚合 02/06/09 红点) |
submitKyc / kycReview | 展示层 / 15 | 提交批次 | KYC 提交与审核 |
freeze / ban / unfreeze(userId, reason) | 14 / 15 | 工单号 | 状态变更,留审计 |
事件:产 UserRegistered;消费 RiskFlagged(执行冻结/封禁)。
六、运营后台能力(→ 15)
| 侧 | 能力 |
|---|---|
| 平台控制台 | 跨租户风险账号检索(配合 14 全局名单) |
| 商户控制台 | 用户查询(标识/ID/注册时间)、冻结/解冻/封禁(留痕)、KYC 审核队列(证件比对、通过/驳回+原因)、登录日志查看、敏感字段脱敏展示(按角色) |
七、展示契约(→ 原型映射)
| UI 元素 | 数据 | 原型载体 | 系统契约 |
|---|---|---|---|
| 登录注册合一页 | auth.methods | #sub-login:seg 三方式(用户名密码/邮箱验证码/手机验证码),60s 倒计时,提交跳 ?state=user | 方式列表由配置驱动;提交调 authOrRegister;?ref= 静默传递 |
| 游客门禁 | guestBrowse + 登录态 | body.auth-guest(?state=guest),requireReg()=openPage('sub-login');.auth-guest-only/.auth-user-only 显隐 | 登录态 = /me 有值;门禁点清单不变(游戏/⭐/收藏最近/充值/赚钱/爆奖卡/领取) |
| 我的·游客卡 | 登录态 | .me-guest 登录卡,隐藏余额/VIP/交易(.auth-user-only) | 不变 |
| 账号头部 | nick / avatar / userId 复制 / VIP | .me-head(头像/名/VIP18/ID复制/齿轮) | 数据来自 /me |
| 安全中心 | 账号安全四项 + 设备 + 安全记录 | 「我的 → 安全中心」#sub-security | 账号安全:登录密码(改密=旧密+新密≥8位字母数字+二次一致,成功踢出其他设备)/ 资金密码(6 位数字,默认关闭·用户主动开启;设置/修改/忘记重置三种模式,忘记走绑定手机 OTP 验证重置、无需旧密码;开启后按 §三.7 资金密码触发清单在提现/账户增删改/撤销/敏感变更前二次校验,真实值加密存储、校验比对)/ 绑定手机(双步换绑:先验当前手机 OTP,再绑新号,新号不得与当前相同)/ 绑定邮箱(首绑单步;更换双步同手机);登录设备(本机 + 可踢除);安全记录(登录/改密/绑定/拦截流水,时间·IP·设备)。不设安全评分、谷歌验证器、提现二次验证、注销账号(→ §九) |
| 登录注册提交校验 | auth.methods + 协议 + OTP | #sub-login 提交按钮 | 提交前校验链(按序,任一失败内联错误不跳转):① 当前方式必填项非空(用户名/邮箱/手机)→ ② 协议已勾选(未勾禁用或提示)→ ③ 凭证校验:用户名方式=密码非空;邮箱/手机方式=验证码 6 位且未过期 → ④ 提交 authOrRegister;失败态含账号锁定(错误 5 次锁定 15 分钟,§三.2)、验证码错误/过期、方式未开放等内联文案;OTP 按钮 60s 倒计时 + 频控(§三.2) |
| 找回登录密码向导 | 绑定手机/邮箱 OTP | #sub-forgot:两步向导(step-dots 真实推进) | 适用范围:仅用户名+密码账号需找回密码(邮箱/手机为纯 OTP 无密码路径,§2.2,不进本流程);步骤:①验身份(输入用户名 → 向其已绑手机/邮箱发 OTP,60s 倒计时 + 频控,校验通过进下一步)→ ②设新密码(新密 ≥8 位字母数字 + 二次一致,提交重置);重置成功踢出其他会话(§三.3),回登录页;身份验证失败/无绑定可联系客服 |
实名认证页 #sub-kyc | KYC 状态机四态 | 「我的 → 身份认证」入口(状态徽标)+ 提现门触发(→ 04) | NONE=说明卡+表单(类型/姓名/号码/有效期/照片上传/协议,校验见 §2.4);PENDING=审核中态(脱敏摘要);APPROVED=已认证态(绿盾+脱敏);REJECTED=原因+保留数据一键重提;从提现进入的认证,通过后自动继续原提现;调试 ?kyc=1(后台要求该账户)`&kycst=pending |
八、数据库设计(全表含 tenant_id)
| 表 | 关键字段 | 约束/索引 |
|---|---|---|
users | user_id PK, tenant_id, nick, avatar, status, inviter_id, register_channel, register_at | IDX(tenant_id,register_at);IDX(tenant_id,inviter_id) |
user_identifiers | id PK, tenant_id, user_id, type, value, verified | UK(tenant_id,type,value) |
user_credentials | user_id, password_hash, updated_at | UK(tenant_id,user_id) |
user_sessions | token_id PK, tenant_id, user_id, device_id, ip, expires_at, revoked | IDX(tenant_id,user_id) |
kyc_submissions | id PK, tenant_id, user_id, level, payload_cipher, state, reviewer_id, reason, created_at, decided_at | IDX(tenant_id,state) |
login_logs | id PK, tenant_id, user_id, ip, device_id, result, created_at | IDX(tenant_id,user_id,created_at) |
证件照等敏感载荷加密存储(payload_cipher),访问按 15 权限脱敏。
九、扩展点
- 三方登录(Google/Telegram):预留
methods扩展枚举。 - 用户侧两步验证:V1 不做(TOTP/提现二次验证均不引入);敏感操作二次确认由资金密码承担(§安全中心)。
- 同人多租户识别:默认互不相通;14 的跨租户设备关联仅用于风控,不用于账号打通。
- 注销账号:V1 不提供用户自助注销入口(与 §七 安全中心一致);确需处置的账户走后台冻结/封禁(§三.5)+ 客服工单,不做自助注销与数据物理删除。合规保留期与「被遗忘权」类区域差异诉求,按 compliance 专章展开(数据加密留存、脱敏访问,→ §八),不在本篇 V1 落地为自助功能。
十、验收要点
- [ ] 三种方式均可完成「不存在即注册、存在即登录」;关闭某方式后入口与 API 同时不可用;
- [ ] 游客点任一门禁动作弹登录页,登录成功后回到原动作上下文;
- [ ]
?ref=注册绑定上级且不可再改;无 ref 正常注册; - [ ] 同一手机号在两个租户注册互不干扰(独立 userId/钱包/等级);
- [ ] KYC 默认关闭;后台对账户下发
onWithdraw后,确认提现打开实名页,通过自动继续原提现;二次不弹; - [ ] FROZEN 用户投注/充提/领取全被拒且提示;BANNED 无法登录;
- [ ] OTP 频控与错误锁定生效;改密后其他设备会话失效;
- [ ] 登录注册提交校验链:必填空/协议未勾/验证码错或过期/账号锁定各出内联错误且不跳转;全过方
authOrRegister; - [ ] 资金密码开启后,§三.7 清单动作(提现/撤销/账户增删改/敏感变更)执行前弹校验,错误 5 次锁定;未开启不额外拦截;
- [ ] 找回登录密码仅对用户名账号可用,两步向导(验身份 OTP → 设新密)推进正确,重置后其他会话失效;
- [ ] 无用户自助注销入口。