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 邀请码预填与提交。

docs/technical/PUZZLE_RUNTIME_TIMER_AND_PROPS_2026-04-29.md

@@ -91,6 +91,7 @@ remainingMs = max(0, timeLimitMs - effectiveElapsedMs)
 1. 播放冻结视觉特效。
 2. 显示冻结剩余时长。
 3. 第一版冻结 `10000ms`。
+4. 若玩家打开冻结确认弹窗前视觉上仍是 `playing`，但确认扣费期间正式 run 已被服务端计时结算为 `failed`，服务端不得返回“操作不合法”。本次调用视为一次边界同步，已预扣费用必须退款，只返回失败态快照并刷新存档；前端关闭道具确认窗，展示失败面板，不播放冻结特效。
 
 ## 计费规则
 
@@ -106,6 +107,8 @@ remainingMs = max(0, timeLimitMs - effectiveElapsedMs)
 
 若扣费或道具过程失败，确认弹窗保持打开并继续暂停倒计时，在弹窗内展示失败原因；只有成功确认后才关闭弹窗并播放对应反馈。
 
+补充规则：冻结时间的边界同步不属于道具使用成功。服务端若发现 run 已超时失败，应退回本次预扣、把失败态落库并返回最新快照，避免玩家在确认窗内看到“操作不合法”。
+
 ## UI 规则
 
 1. 底部只放 3 个道具按钮，不写规则说明文案。