7.0 KiB
HomeScene 自动弹窗管理器
本版仅调整弹窗调度；弹入、关闭、金币和奖励领取动画沿用现有实现。动画管理器及黄金矿工、每日任务的动画统一留给后续版本。
职责与批次
assets/home_popup_queue/HomePopupPolicy.ts：纯规则，负责频次、排序、实际展示数、购买限额、新手流程和每日记录。HomePopupQueue.ts：首页队列，等待初始检查完成、执行任务、检查可见窗口和奖励链、取消离开首页的批次。- 活动 Host/View：检查业务状态、加载资源、真正显示后通知管理器；保留手动入口、发奖和活动协议。
成功启动登录调用 beginLogin，接下来第一次首页消耗该登录标记；同一次登录和首页进入合为一批。之后每次重新进入首页是返回批次。回前台、网络恢复、停留首页时到期仅刷新状态，不追加自动展示批次。
首页先收集七日、月卡领取/购买、礼包、战令、小鱼干、每日任务、金字塔、黄金矿工和百人赛的初始候选，再按固定顺序执行。异常检查最多等待 20 秒，随后关闭本批收集；迟到候选等待下次符合频次的批次。初始化查询完成后调用 completePreparation，二段查询可在收集阶段调用 holdPreparation。
频次与顺序
类型 0 不自动展示，手动入口可用；类型 1 每个北京时间自然日成功展示一次；类型 2 每次成功启动登录展示；类型 3 每次进入/返回首页展示。
| 顺序 | 意图 key | 默认类型 |
|---|---|---|
| 10 | sevenDayGift 新手七天签到 | 1 |
| 20 | monthlyReward 月卡每日领取通知 | 1 |
| 30 / 31 / 32 / 33 | pyramidSettlement / jungleSettlement / coinMadnessSettlement / battlePassSettlement | 3 |
| 34 / 35 | cloudRiseElimination / cloudRiseResult 百人赛未处理结果兜底 | 3 |
| 40 / 41 / 42 | pyramidDailyReminder / jungleTreasure / goldMinerDailyReminder 普通活动 | 2 |
| 50 | starterPack 新手礼包 | 2 |
| 70 | dailyQuests 每日任务 | 2 或 3 |
| 80 | cloudRiseDailyReminder 百人赛普通入口 | 3 |
| 90（停用） | winStreak 连胜介绍 | 0，仅手动打开 |
| 100 / 101 | passCheckIntro / monthlyCard 战令、月卡购买 | 1，满足本批数量限制 |
原来带 DailyReminder 名称的活动 key 为兼容接入保留；活动服务的旧日标记不再参与展示资格判断，频次由管理器统一控制。
- 登录批次包含符合条件的 1、2、3；同日后续登录包含未展示的 1、新的 2、3。返回首页仅 3，未完成的新手强制展示除外。
- 战令购买、月卡购买（含续费提示）每天最多自动展示一次，仅在登录批次检查，普通返回首页不自动展示。保留解锁与购买资格判断，月卡仍需剩余有效期不足 5 天。连胜介绍仍仅手动打开；战令结算、月卡每日奖励领取通知及连胜活动本身不受影响。
- 每日任务保留解锁门槛；存在每日或每周可领红点时为 3，领完恢复 2，并在出队前复查。
- 礼包存在有效可购买期即可按登录展示，不再要求低资源或连续失败；原有礼包重新激活规则保留。
- 百人赛正常结果仍在对局内处理，首页只兜底尚未处理的结果，不重新启动已完成流程。
成功、失败和计数
只在节点实际激活或 Host 确认展示成功后计数、写入当天已展示记录。入队、开始加载、加载失败、透明发货遮罩不计数。
同一个弹窗及其领取奖励后的详情是一条展示链，算一次，并等该链结束后推进。金字塔结算弹窗与金字塔普通活动弹窗是不同意图，可以先后展示，各算一次。手动打开不计入自动批次数。
战令购买、月卡购买排在本批其他弹窗之后，先战令再月卡。独立的 otherPopupCount 只统计本批除这两个购买弹窗以外实际展示成功的弹窗，月卡每日奖励和战令结算仍计入；两个购买弹窗不互相消耗额度。
| 本批其他弹窗数 N | 战令购买 | 月卡购买 |
|---|---|---|
| 0～2 | 允许 | 允许 |
| 3 | 允许 | 跳过 |
| ≥4 | 跳过 | 跳过 |
超限只跳过本批，不写当天禁止展示记录；旧版持久化的两个购买弹窗 blocked 标记在创建规则时清理，已成功展示的当天记录保留。加载失败不记展示，下次登录可重试。新批次计数从零开始，手动入口不受额度限制。
战令结算准备失败释放当前队列，但不把业务结算标记为已完成。小鱼干普通弹窗排队期间转为到期结算时，释放普通意图，本批已关闭收集则等待下次返回首页；手动打开仍可直接处理结算。月卡奖励发放与通知分离，已发放但没展示的通知持久化为 pending，下次登录展示不重复发奖。
每日记录按服务端校准时间取北京时间日期；存储 key 为 homePopup:v1:<apiBaseUrl>:<uid>，保存 shown、blocked、新手步骤和月卡待通知标记。退出首页、进关准备、账号/令牌切换取消剩余任务，异步展示回调检查当前任务是否仍有效。
新手回首页
GM_INFO.level 表示已经完成的关卡；当前 B 组通过第 15 关（待玩第 16 关），其他组通过第 23 关时达到门槛，统一通过 GameConfig.getNewPlayerHomeLevel() 取得。
点击下一关时，先完成本局结算和百人赛结果，再返回首页。强制七日签到、礼包排在本批最前（-20、-10），计入实际展示数，且不在本批重复入队。已领、已展示、已购买或已失效的对应步骤视为完成，加载失败保留。完成后恢复七日类型 1、礼包类型 2。
首次升级到本版时，已超过门槛的存量用户不补触发；恰好达到门槛或本次新跨越门槛的用户执行并持久化未完成步骤。
验证
针对新规则的主要命令：
node --test tools/test-home-popup-policy.cjs tools/test-monthly-card-lifecycle.cjs tools/test-pyramid-home-reminder.cjs tools/test-activity-schedule.cjs tools/coin-madness/check-daily-reminder.cjs tools/test-seven-day-loading.cjs tools/test-win-streak-popup.cjs tools/test-battle-pass-settlement-check.cjs
node tools/coin-madness/check-popup-queue.cjs
node tools/coin-madness/check-home-entry-ready.cjs
本次购买弹窗调整的主命令共 115 项通过，覆盖数量边界、购买弹窗末尾排序、失败不计数、每日频次、旧阻止记录清理和月卡奖励生命周期。
此前对战令结算、百人赛可用性、金字塔结算和商城奖励四组测试做了修改前后对比：共 119 项，前后均 91 通过、28 既有失败，失败用例集合一致。
上述是 Node 引擎桩与规则验证。发布前仍需在 Cocos/微信开发版验证：冷启动与二次登录、其他弹窗数为 2/3/4 时的购买弹窗、连胜介绍仅手动打开、同批结算加普通活动、领取后奖励详情占用、新手门槛、跨北京时间零点、资源失败后重登，以及加载中进关/切号。此轮没有运行真机视觉与点击验收。