1

docs/design/PLATFORM_WORK_DETAIL_AND_REMIX_DESIGN_2026-04-28.md

@@ -29,6 +29,7 @@
    - 四项统计需要使用浅色图标底强化识别，但不得追加规则说明类文案。
 6. 简介区：展示玩法标签和作品简介；不追加说明类文案。
 7. 底部动作：左侧按钮为“作品改造”，右侧主按钮为“启动”；两个按钮必须位于同一行，点击“启动”后进入对应玩法运行态并记录游玩次数。
+   - 未登录用户可进入并浏览作品详情页，但点击“作品改造”和“启动”都必须先弹出登录入口面板；登录成功后自动继续刚才点击的动作，不直接发起 Remix、启动 run 或本地运行态。
 8. 页面配色必须跟随平台明暗主题变量；亮色主题使用平台浅色底、深色文字和主按钮渐变，暗色主题使用平台暗色底、亮色文字和对应主按钮渐变，不在详情页写死独立黑色皮肤。
 9. 字号规范跟随平台页面既有节奏：标题/主按钮使用 `1rem` 级别，作品名使用卡片标题同级 `1rem`，辅助信息与简介使用 `0.8125rem` / `0.875rem`，标签与统计标签使用 `0.75rem`，避免在详情页使用随视口放大的独立大字号。
 
@@ -100,5 +101,6 @@
 4. Remix 后原作品改造次数增加，新草稿归当前用户所有，且不会继承源作品统计。
 5. 点赞公开作品会走对应后端记录入口，首次点赞后刷新仍能看到递增后的点赞次数，重复点赞不会继续增加。
 6. 启动公开作品会走对应后端记录入口，刷新后仍能看到递增后的游玩次数。
-7. 移动端首页“推荐”和“今日游戏”列表滚动时，仅中心卡片自动轮播多封面；旧中心卡离开后回到首张封面，新的中心卡接续轮播。
-8. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。
+7. 未登录进入作品详情页后，点击“作品改造”和“启动”只打开登录入口面板；登录成功后恢复对应动作，未登录期间不会创建 Remix 草稿、开始拼图 run、记录 RPG 游玩或启动大鱼本地运行态。
+8. 移动端首页“推荐”和“今日游戏”列表滚动时，仅中心卡片自动轮播多封面；旧中心卡离开后回到首张封面，新的中心卡接续轮播。
+9. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。

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 个道具按钮，不写规则说明文案。