Genarrative/docs/technical/AUTH_NEW_ACCOUNT_INVITE_MODAL_2026-05-01.md

新账号短信登录后置邀请码弹窗设计

日期：2026-05-01

1. 目标

账号入口不再展示独立注册入口。用户统一从短信登录进入，后端通过 POST /api/auth/phone/login 返回的 created 字段判断本次是否创建了新账号。

当 created=true 时，前端在登录成功后额外弹出独立邀请码面板：

1. 标题固定为 请填写邀请码。
2. 标题下方展示邀请码输入框。
3. 输入为空时主按钮显示 跳过，点击后关闭面板。
4. 输入非空时主按钮显示 提交，点击后提交邀请码。
5. 面板右上角提供取消按钮，点击后关闭面板。

2. 入口调整

登录弹窗只保留可用登录方式：

1. 短信登录。
2. 密码登录。
3. 微信登录。

不得再展示 注册 页签、注册按钮或注册表单。邀请码不再出现在短信验证码表单中，避免用户把登录和注册理解成两套入口。

3. 邀请码提交

后置弹窗提交邀请码时调用已登录接口：

POST /api/profile/referrals/redeem-code

请求体：

{
  "inviteCode": "SPRING2026"
}

后端继续使用 SpacetimeDB 的 redeem_profile_referral_invite_code procedure 作为唯一真相源。该 procedure 已负责校验：

1. 每个用户最多只能填写一个邀请码。
2. 邀请码必须存在。
3. 用户不能填写自己的邀请码。
4. 双方奖励与钱包流水在同一事务内落地。

4. URL 邀请码

若地址中存在 inviteCode 或 invite_code，前端只将其作为新账号后置弹窗的默认输入值。它不会触发注册页签，也不会在短信登录请求中提前提交。

若用户登录的是已有账号，则不会弹出新账号邀请码面板。

5. 完成定义

1. 登录弹窗内不可见注册入口。
2. 短信登录创建新账号后弹出邀请码面板。
3. 邀请码为空时按钮为 跳过，非空时按钮为 提交。
4. 取消按钮可关闭面板。
5. 已登录邀请码接口允许提交，并继续由 SpacetimeDB procedure 兜底业务校验。
6. 前端测试覆盖注册入口删除、新账号弹窗、URL 邀请码预填与提交。