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