登录注册接入

更新日期:2026-11-19。当前唯一正式部署环境处于上线前阶段,实际运行配置为dev;按用户要求使用固定验证码123456,手机号和邮箱共用,暂不发送短信或邮件。公网HTTPS已验收,真实短信、邮箱及三方应用接入仍须分别完成;Flutter页面使用本页列出的服务端接口。没有独立测试服,上线前清库与正式配置准备见接入入口。

当前固定验证码联调

  • 服务地址:https://api.budyoo.cn。先获取登录方式与协议版本,申请手机号或邮箱挑战,再以返回的challengeId和123456调用验证码登录。
  • 获取方式和申请挑战响应中的verificationMode为development-fixed;关闭固定模式后为delivery。不要将开发成功提示解读为真实短信/邮件已经发出。
  • challenge仍5分钟有效、60秒重发冷却、5次失败上限,绑定安装UUID,成功消费一次。固定值不是跳过验证流程的万能入口。
  • 验证成功或退出注册不取消原发送冷却。重新申请返回429时,新提示区分“请在N秒后重新获取验证码”和“本小时次数已达上限,请在N分钟后重试”,并通过Retry-After返回剩余秒数;阈值和AUTH_RATE_LIMITED错误码保持不变,实际发布状态见验证码申请。
  • 开发账号使用独立dev_phone/dev_email身份;与相同手机号/邮箱的真实账号不互通。关闭固定模式或启用任何prod组合后,开发挑战和会话均失效,未来切换真实模式需真实验证并创建/登录真实身份。

页面与调用顺序

  1. 共用闪屏先读取IP布局配置,成功后显示地区相关协议与布局。协议选择结束后并发检查升级和登录方式与协议版本,任一失败使用不可取消重试,两项成功后才继续分流;登录页复用配置并要求用户明确同意。新协议目录传layoutPolicy=ip-v1,与本轮布局一致,不自动跨范围同意。
  2. 手机号/邮箱使用发送验证码及验证码登录。两种类型均在获取验证码时预检封禁,403 ACCOUNT_BANNED直接提示受限,不发送验证码或进入输入验证码页;验证与会话签发时仍复查封禁,刷新和受保护业务API不因提前提示放宽。三方登录使用申请挑战,调用原生SDK后再验证三方凭据。
  3. 将服务端返回的accessToken和refreshToken写入系统安全存储。根据registrationStatus、registrationStep和nextStep决定进入首页还是继续注册;registrationStep保存在服务端用户记录中,不根据本地页面缓存猜测账号状态。
  4. 国家选择读取支持国家与地区,我会的语言/学习语言读取支持资料语言,兴趣继续读取注册字典。新语言目录返回完整四语名称,旧字典的语言字段仍兼容;各独立接口说明实际部署与接入状态。每步使用保存注册草稿,等待成功响应后按返回步骤进入下一页;选头像先申请OSS直传,PUT成功后确认上传,再将确认回执中的avatarId保存到草稿。
  5. 国家、昵称、性别、生日、母语/学习语言、介绍及兴趣填写完成后调用完成注册。头像为选填。成功后registrationStep保持4、registrationStatus变为COMPLETE;再判断vipRequired,true进入VIP页、false进入首页。注册完成不授予VIP权益,规则见注册资料与VIP准入。
  6. 登录响应已足够决定跳转;需要回填表单内容时再调用既有当前用户读取资料。延续会话使用刷新凭证,退出使用当前设备或全部设备。

注册步骤与中断恢复

登录成功的data直接新增一个整数字段registrationStep,只返回1、2、3、4,前端据此跳转;不新增独立进度接口,不需要为取得步骤额外请求。当前正式UI的注册资料共4步,语言和生日弹窗属于第3步,头像属于第2步;登录验证码及VIP均不计入。

registrationStep 页面/状态 原有nextStep 推进条件
1 国家/地区 COUNTRY 国家保存成功后进入2
2 头像、昵称、性别 PROFILE 昵称和性别保存完整后进入3,头像选填
3 会的语言、学习语言、生日、个人介绍 INTRO 四项资料保存完整后进入4
4 兴趣标签 INTERESTS或COMPLETE_REGISTRATION 至少1个兴趣保存后仍为4;再调用完成注册

资料已完成用户也返回4,同时registrationStatus=COMPLETE、nextStep=HOME。前端先判断资料状态,INCOMPLETE按1–4跳转注册;COMPLETE再判断vipRequired,true进VIP页、false才进首页。VIP是独立第二层,registrationStep不会返回0或5。

registrationStep为服务端已经持久化的恢复位置,含义是“第一个尚未完成的资料页面”,不是客户端最后一次点开的页面。每次草稿保存会在同一事务中校验资料、保存内容并更新步骤。只保存部分昵称/性别时仍停在2;校验失败和事务回滚不推进;只有第4步资料已齐全也不会自动变成完成,仍须调用完成注册接口。

例如:保存国家后接口返回registrationStep:2;用户在第2页退出或被系统结束进程,再用手机号、邮箱或已接入的三方登录后,登录响应仍返回2。前端跳转第2页,并调用当前用户恢复已保存内容。刷新Token及读取本人资料也返回同样的步骤字段。用户返回已完成页面查看资料,不会仅因页面导航改写恢复位置;用户未提交成功的输入只存在本地,后端无法恢复。

登录、三方登录直接返回步骤与VIP第二层结果;现有刷新、当前用户、保存草稿和完成注册也返回同一组字段保持一致,原registrationStatus与nextStep保留。开关关闭时的示例:

{
  "registrationStatus": "INCOMPLETE",
  "nextStep": "PROFILE",
  "registrationStep": 2,
  "vipGateEnabled": false,
  "vipActive": false,
  "vipRequired": false
}

nextStep=COMPLETE_REGISTRATION表示已保存全部资料但尚未提交完成,仍属于第4页。客户端不要提交或缓存覆盖registrationStep及registrationStatus;它们是只读的服务端结果,不用于授予权限。直接伪造页码不能完成注册,服务端继续校验全部必填资料。已有账号按当前资料回填步骤,无需重新注册。

已在服务器隔离PostgreSQL验证第1–4步退出重登/刷新恢复、部分保存与失败不推进、伪造步骤不生效、完成幂等、资料与步骤共同回滚、并发更新,以及旧账号回填和1–4数据库约束。三方登录使用临时签名测试验证返回字段,未代表真实供应商已接通;Flutter页面跳转仍需在其登录成功处理内按上述字段接入。

会话约定

用户协议/隐私政策现在保存即生效。登录选项termsVersion/privacyVersion与目录requiredVersion共用数据库中的当前同意版本,记录该版本对应的全部地区/语言正文UUID;单条正文contentVersion独立,不能要求字符串相等。验证码申请、验证码验证、三方挑战和三方验证都重新校验当前同意版本,旧值返回409 CONSENT_VERSION_CHANGED。客户端保留账号输入,刷新配置并重新获得明确同意,再申请新的挑战;后台保存不会替用户勾选,也不覆盖旧auth_consent记录。

公开JS封装支持getAccessToken: () => 当前访问凭证;对验证码、三方验证和刷新调用设置useSession:false。固定码HTTP联调需同时显式配置allowInsecureDevelopment:true和allowInsecureDevelopmentSessions:true,默认仍拒绝明文Bearer。封装不自动刷新、不重试写操作;当前正式域名已使用HTTPS,无需开启这两个开发开关。Flutter复用统一网络层实现相同会话流程。

  • 本站使用随机不透明Bearer凭证,不是JWT;客户端不可解析其中内容。访问凭证最长15分钟,刷新凭证以创建会话时起30天为绝对期限。
  • 每次刷新必须串行,成功后同时替换两枚凭证。旧访问凭证立即失效,旧刷新凭证再次使用会撤销整个会话。刷新请求不携带Authorization,不能自动重复提交结果不明的旧refreshToken。
  • X-Device-Id表示持久安装实例,登录和后续请求必须一致;该标识不是硬件认证。清除安装数据后应重新登录。
  • 每账号只保留一个有效HTTP会话。新设备登录会撤销旧设备的访问与刷新凭证,旧设备下一次请求返回401,客户端清理凭证并引导重新登录。退出与账号封禁对HTTP请求立即生效。实时连接的即时撤销传播另行联动,不能据此宣称已实现即时踢线。
  • 未完成资料的凭证只能访问本人资料、头像和会话端点;完成资料后若VIP门槛开启且没有有效权益,仍不能访问普通业务或申请正式连接票据。服务端每次请求重算,不依赖客户端隐藏页面;App身份不能获得ADMIN权限。
  • 不以三方返回邮箱相同自动合并不同身份;显式账号绑定、换绑、删除账号属于后续独立业务,本批未新增这些接口。

发送和三方服务边界

开发固定模式不调用供应商,且三方入口关闭。关闭固定模式后,SMTP适配使用强制STARTTLS或隐式TLS;短信使用服务端配置的HTTPS网关并要求accepted=true;Google/Apple验证官方JWKS及claims,微信兑换官方授权码。真实模式未配置必要参数时返回AUTH_PROVIDER_UNAVAILABLE,不回退固定码。

开发验证码固定123456,真实模式随机六位;两种模式均5分钟有效、60秒重发、单挑战最多5次校验,同账号/安装/IP分别限流。验证码只保存绑定挑战的HMAC,Token只保存摘要,成功响应返回原始Token一次;请求与响应不得写入日志。

传输与验证范围

当前公网API使用https://api.budyoo.cn,证书与HTTPS入口已验收;dev固定模式仍使用隔离开发身份联调。真实模式默认要求HTTPS,prod始终要求且忽略开发例外。X-Forwarded-Proto默认不可信,只有受控代理链可传递可信协议信息。

服务端已通过真实PostgreSQL迁移、MockMvc和真实Servlet网络请求验证,包含随机验证码、注册恢复、重放与并发、Token用途、设备绑定、退出、头像越权以及临时RSA密钥的Google/Apple验签。测试用发送替身只在src/test存在,不发真实短信/邮件;这些历史认证测试不代表真实供应商登录或Flutter真机认证已验收;后续公网HTTPS检查结果见安全状态。

相关协议:公共请求头、统一响应、安全状态。供应商校验依据:Google后端身份验证、Apple验证用户、Spring Security JWT校验。