1

docs/technical/AUTH_NEW_ACCOUNT_INVITE_MODAL_2026-05-01.md

@@ -0,0 +1,63 @@
+# 新账号短信登录后置邀请码弹窗设计
+
+日期：`2026-05-01`
+
+## 1. 目标
+
+账号入口不再展示独立注册入口。用户统一从短信登录进入，后端通过 `POST /api/auth/phone/login` 返回的 `created` 字段判断本次是否创建了新账号。
+
+当 `created=true` 时，前端在登录成功后额外弹出独立邀请码面板：
+
+1. 标题固定为 `请填写邀请码`。
+2. 标题下方展示邀请码输入框。
+3. 输入为空时主按钮显示 `跳过`，点击后关闭面板。
+4. 输入非空时主按钮显示 `提交`，点击后提交邀请码。
+5. 面板右上角提供取消按钮，点击后关闭面板。
+
+## 2. 入口调整
+
+登录弹窗只保留可用登录方式：
+
+1. 短信登录。
+2. 密码登录。
+3. 微信登录。
+
+不得再展示 `注册` 页签、注册按钮或注册表单。邀请码不再出现在短信验证码表单中，避免用户把登录和注册理解成两套入口。
+
+## 3. 邀请码提交
+
+后置弹窗提交邀请码时调用已登录接口：
+
+```text
+POST /api/profile/referrals/redeem-code
+```
+
+请求体：
+
+```json
+{
+  "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 邀请码预填与提交。