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. 新账号泥点初始化

当短信登录、开发密码入口或微信激活流程创建新账号时，后端注册链路必须调用 grant_new_user_registration_wallet_reward，为该用户写入 10 个初始泥点。

该赠送落在 profile_dashboard_state.wallet_balance 与 profile_wallet_ledger 中，流水来源为 new_user_registration_reward，流水 ID 固定为 new-user-registration:{user_id}，用于保证重复调用不重复发放。已有账号登录不得再次发放。

6. 完成定义

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