MatchMaster/docs/home-popup-queue.md

HomeScene 自动弹窗管理器

本版仅调整弹窗调度；弹入、关闭、金币和奖励领取动画沿用现有实现。动画管理器及黄金矿工、每日任务的动画统一留给后续版本。

职责与批次

• assets/home_popup_queue/HomePopupPolicy.ts：纯规则，负责频次、排序、实际展示数、购买限额、新手流程和每日记录。
• HomePopupQueue.ts：首页队列，等待初始检查完成、执行任务、检查可见窗口和奖励链、取消离开首页的批次。
• 活动 Host/View：检查业务状态、加载资源、真正显示后通知管理器；保留手动入口、发奖和活动协议。

成功启动登录调用 beginLogin，接下来第一次首页消耗该登录标记；同一次登录和首页进入合为一批。之后每次重新进入首页是返回批次。本次登录已展示记录跨场景保留，仅新登录重置；普通回前台不视为新登录。回前台、网络恢复、停留首页时到期不重新启动整批登录提醒。

首页先收集七日、月卡领取/购买、礼包、战令、小鱼干、每日任务、金字塔、黄金矿工和百人赛的初始候选，再按固定顺序执行。异常检查最多等待 20 秒，随后关闭普通候选收集；明确登记的类型 1/2 待展示请求允许晚到，按优先级插入尚未执行的队列，不打断当前弹窗或奖励链。初始化查询完成后调用 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、明确待补弹的 1/2，以及未完成的新手强制展示。类型 1 检查当天是否已展示，类型 2 检查本次登录是否已展示；没有待展示请求时不重放登录提醒。
• 战令购买、月卡购买（含续费提示）每天最多自动展示一次，普通返回首页无待展示请求时不自动展示。保留解锁与购买资格判断，月卡仍需剩余有效期不足 5 天。连胜介绍仍仅手动打开；战令结算、月卡每日奖励领取通知及连胜活动本身不受影响。
• 每日任务保留解锁门槛；存在每日或每周可领红点时为 3，领完恢复 2，并在出队前复查。
• 幸运礼包 starterPack 保持类型 2：存在有效可购买期即可按登录展示；游戏内触发自动提醒后，本次登录未展示则回首页补弹。资源/失败触发先保存原因，在安全界面完成激活请求后登记展示请求；商城、购买意向仍只恢复入口。待确认原因按服务器、账号持久化，场景切换或重启不丢失。
• 百人赛正常结果仍在对局内处理，首页只兜底尚未处理的结果，不重新启动已完成流程。

成功、失败和计数

只在节点实际激活或 Host 确认展示成功后计数、写入当天已展示记录。入队、开始加载、加载失败、透明发货遮罩不计数。

同一个弹窗及其领取奖励后的详情是一条展示链，算一次，并等该链结束后推进。金字塔结算弹窗与金字塔普通活动弹窗是不同意图，可以先后展示，各计一次总展示数，但只有普通活动弹窗参与购买限额计数。手动打开不计入自动批次数。

战令购买、月卡购买排在本批其他弹窗之后，先战令再月卡。独立的 otherPopupCount 只统计本批实际展示成功的普通弹窗，排除这两个购买弹窗以及所有标记为 settlement 的结算类窗口：金字塔、小鱼干、黄金矿工、战令结算和百人赛淘汰/结果。结算后的奖励详情也不另计；月卡每日奖励通知仍计入。两个购买弹窗不互相消耗额度。

战令结算中可能展示上期战令补购窗口（offer），该流程不自动打开本期战令界面。上期补购属于结算链，不占购买限额，也不会阻止本批后续的本期战令购买窗口 passCheckIntro；后者仍按普通弹窗不足 4 次、当天未展示及当前购买资格判断。

本批其他弹窗数 N	战令购买	月卡购买
0～2	允许	允许
3	允许	跳过
≥4	跳过	跳过

超限只跳过本批，不写当天禁止展示记录；旧版持久化的两个购买弹窗 blocked 标记在创建规则时清理，已成功展示的当天记录保留。已入队的类型 1/2 候选在实际显示前保留待展示状态；加载失败或离开首页不消耗次数，下次返回首页或登录时可重试，同一次首页停留不循环重试。新批次计数从零开始，手动入口不受额度限制。

战令结算准备失败释放当前队列，但不把业务结算标记为已完成。小鱼干普通弹窗排队期间转为到期结算时，释放普通意图，本批已关闭收集则等待下次返回首页；手动打开仍可直接处理结算。月卡奖励发放与通知分离，已发放但没展示的通知持久化为 pending，并登记为类型 1 补弹请求，下次返回首页或登录时展示不重复发奖。

每日记录按服务端校准时间取北京时间日期；存储 key 为 homePopup:v1:<apiBaseUrl>:<uid>，保存 shown、blocked、新手步骤和月卡待通知标记。类型 1/2 待展示请求保存在该 key 的 :pending 后缀下；本次登录已展示记录只保存在内存会话中。退出首页、进关准备、账号/令牌切换及重新登录取消旧任务的展示资格。

活动确认产生自动展示意图后可调用 HomePopupQueue.requestPresentation(key)（游戏内也可调用），首页适配器重新检查业务条件后沿用 enqueue。已有队列可调用实例的同名方法登记晚到请求。管理器仅保存展示意图，不代替活动接口确认资格；明确已购买、已过期等情况由适配器调用 unavailable(key) 清除请求，请求失败则保留。成功展示调用 markShown(key)，同时清除请求、写入每日/登录记录。普通读取活动可用性不等于新触发请求。

新手回首页

GM_INFO.level 表示已经完成的关卡；当前 B 组通过第 15 关（待玩第 16 关），其他组通过第 23 关时达到门槛，统一通过 GameConfig.getNewPlayerHomeLevel() 取得。

点击下一关时，先完成本局结算和百人赛结果，再返回首页。强制七日签到、礼包排在本批最前（-20、-10），计入实际展示数，且不在本批重复入队。已领、已展示、已购买或已失效的对应步骤视为完成，加载失败保留。完成后恢复七日类型 1、礼包类型 2。

首次升级到本版时，已超过门槛的存量用户不补触发；恰好达到门槛或本次新跨越门槛的用户执行并持久化未完成步骤。

验证

2026-10-27 频次与补弹调整：弹窗策略/队列与战令结算检查共 57 项通过，包含幸运礼包真实首页适配器、游戏触发延后、接口晚到、回包前离开首页、每日/每次登录去重、跨日、失败重试和账号隔离。扩展到礼包、月卡、七日与金字塔共 153 项，91 通过，62 项失败与修改前集合一致；TypeScript 与修改前均有 20 条既有诊断，没有新增诊断。未进行 Cocos/微信真机验收。

针对新规则的主要命令：

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 时的购买弹窗、连胜介绍仅手动打开、同批结算加普通活动、领取后奖励详情占用、新手门槛、跨北京时间零点、资源失败后重登，以及加载中进关/切号。此轮没有运行真机视觉与点击验收。