cursor/plans/lobby welcome popup prd-bc83d927.plan.md

---

todos:

• id: "create-04" content: "新增 docs/requirements/register_popup_game_entry/04_lobby_welcome_popup.md，覆盖 10 点需求、uid 起始值 1257832、launch_url 预取、接口/字段/异常/测试/代码对照" status: pending
• id: "update-parent" content: "更新父文档 register_popup_game_entry.md：game 增加 launch_url 字段、点击行为补充、uid 起始值说明、索引与版本号" status: pending
• id: "update-readme" content: "更新 register_popup_game_entry/README.md：新增 04 子需求行与代码对照表条目" status: pending isProject: false

---

新用户大厅欢迎弹窗 — 需求文档（子需求 04）

背景与现状对照

需求 10 点中，多数已在现有代码落地，仅 2 点为新增能力。文档需如实标注「已落地 / 待做」。

• 已落地（前端 [lobby/src/components/OnboardingGamePopup.vue](lobby/src/components/OnboardingGamePopup.vue) + 后端 [slot-console/app/api/logic/OnboardingRecommendLogic.php](slot-console/app/api/logic/OnboardingRecommendLogic.php)）：
  • 注册成功进入大厅弹欢迎窗（点 1）、欢迎信息（点 2）、平台第几位玩家 player_number（点 3）、player_number = uid（点 4）、推荐游戏图片 cover_url（点 6）、3 秒倒计时自动进入 countdown_seconds（点 7）、点击 LET'S PLAY 立即进入（点 8）、关闭按钮关闭且停倒计时 closePopup() 调 stopCountdown()（点 9）。
• 待做（本需求核心）：
  • 点 5：真实注册 uid 发号起始值 = 1257832（slot-user）。
  • 点 10：recommend-game 接口提前返回 launch_url，前端进入时直接使用（slot-console + lobby）。

交付物（仅 Markdown 文档）

1. 新增 docs/requirements/register_popup_game_entry/04_lobby_welcome_popup.md

子需求 04，结构对齐既有 01/02/03（表头元信息 + 目标/范围 + 链路 + 接口 + 规则 + 异常 + 测试 + 代码对照）。核心章节：

• 元信息表：版本 V1.0、序号 04、涉及仓库 lobby、slot-console、slot-user、slot-pwa（launch）。
• 需求点 → 实现映射表：把 10 点逐条映射到「位置 / 状态（已落地/待做）」。
• 弹窗交互规格（点 1-4、6-9）：触发时机（注册响应 is_new_user === true）、文案、player_number_display 千分位、倒计时、确认/关闭/遮罩点击行为；引用现有 OnboardingGamePopup.vue。
• 点 5 uid 起始值 = 1257832：
  • 现状：[slot-user/.../AbstractRegisterService.php](slot-user/app/service/register/AbstractRegisterService.php) generateUid() = USER_UUID_POOL(来自 config/txt/uuid.txt 洗牌) + (repeat+1)*1000000；池由 [slot-user/app/command/Uuid.php](slot-user/app/command/Uuid.php) 载入。
  • 需求：首个发放 uid = 1257832，后续按发号规则递增、保持唯一。
  • 实现方案（文档给出建议，标注需研发确认）：将发号改为以 1257832 为基准的顺序自增计数（如新增 USER_UUID_BASE 常量 + incr 计数 key），或重建 uuid.txt/池基准使首个映射值落在 1257832；二选一，避免与现有洗牌池产生小于基准的 uid。
  • 影响与校验：player_number = uid 自动满足点 3/4；新环境从 1257832 起，已上线环境只对增量生效（写明灰度/存量说明）。
• 点 10 launch_url 提前返回：
  • 接口 GET /slot-console/api/onboarding/recommend-game 的 game 节点新增字段 launch_url。
  • 后端：OnboardingRecommendLogic::buildRecommendPayload() 选中游戏后，复用现有 launch 链路（[slot-console/app/api/logic/GameLogic.php](slot-console/app/api/logic/GameLogic.php) → SlotPlatformService::launch($uid,$game_code,$ip) → pwa）预取 url 填入 game.launch_url；失败降级为 launch_url="" 不阻断弹窗。
  • 前端：OnboardingGamePopup.vue 进入游戏时，若 game.launch_url 非空则直接写 game store 跳转（跳过再次 /api/game/launch），为空时回退现有 launchByCode(game_code)。
  • 注意点：launch 走 pwa Session 链路（[slot-pwa/.../GameLaunchSessionLogic.php](slot-pwa/app/api/logic/GameLaunchSessionLogic.php) 有短窗口 dedup），预取与点击进入复用同一 session，文档说明幂等/有效期与不阻断注册首页的降级。
• 返回示例（含 launch_url）、字段说明表、异常与降级表、测试用例、与已实现代码对照表。

2. 更新父文档 docs/requirements/register_popup_game_entry.md

• §6.1 console 返回示例与字段说明：game 增加 launch_url 字段。
• §8.2 点击行为：补充「优先使用预取 launch_url」。
• 新增小节或在 §1.3 In Scope 标注：uid 发号起始值 = 1257832（指向 04）。
• 文首子需求索引行追加 04 链接，版本号自增（如 V1.5，附变更说明）。

3. 更新 docs/requirements/register_popup_game_entry/README.md

• 子需求列表新增 04 行（lobby 大厅欢迎弹窗 + uid 起始值 + launch_url 预取）。
• 「与已实现代码对照」表追加：弹窗组件已落地、uid 起始值待做、launch_url 预取待做。

不在本次范围

• 不实际改 PHP/Vue 代码（本次只交付需求文档）。
• 不改 center 渠道配置与 admin 后台（见 01/02）。
• Trial Balance 发放仍属父活动（钱包）。