ok

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

@@ -0,0 +1,64 @@
+<!-- bc83d927-425a-451f-a178-e2ee0317eb13 -->
+---
+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 发放仍属父活动（钱包）。