万圣节战令改版验收说明（2026-10-08）

预制体编辑入口
assets/passCheck/prefab/PassSettlement.prefab：
  panel/offer = 图1；panel/empty = 图2；panel/claim = 图3；
  panel/confirmation = 图4。编辑时可切换各分支的active预览，运行时由代码选择分支。
  title、copy、background、closeButton、buyButton、claimButton可直接调位置/大小/图片。
  图4的thinkAgainButton和abandonButton分别对应再想想和放弃。
  offer/claim 的 rewards/topRow、bottomRow 用Layout排列固定奖励槽；可调整行位置和
  Layout间距。若需逐个手动拖动槽位，请禁用对应行的Layout组件。
  每个slot/item/icon包含各类型图标，slot/item/amount是动态数字的定位节点。
  数字子节点在运行时生成，不要在amount下面添加需要保留的固定装饰。
assets/passCheck/prefab/PassUnlock.prefab：
  content/vip = 图6的18元表现；content/svip = 图6的30元/升档表现。
  badge、copy和cardAnimation/card可直接调整。入场动画只缩放cardAnimation外层，
  不覆盖card图片本身的位置、尺寸或缩放；点击shade关闭。
assets/shop/prefab/buyActivate.prefab：图5原有购买选择界面。
两个新预制体均为原生Cocos节点/组件，固定图片通过Sprite引用，无需挂新增脚本。
请保留上述代码使用的节点名称及父子关系；位置、尺寸、颜色、透明度、Sprite引用可改。
根节点1080×1920是适配基准；运行时只对panel/content外层做屏幕适配，不重新排布UI。
tools/create-battle-pass-prefabs.cjs仅用于首次结构生成，已有文件会跳过，不能覆盖编辑器调整。

实现入口
BattlePassSettlement：旧赛季结算队列、图1/2/3/4交互和上期18元购买。
BattlePassArt：图片文案、万圣节数字/南瓜/时钟、图6购买成功展示。
BattlePassSettlementModel：使用当前最新 PASS_CHECK 表计算奖励并合并同类项。
HomePopupQueue：结算优先级-100，完整结算/奖励动画结束后才继续原有弹窗。
触发入口沿用黄金矿工：首页 start、cc.game.EVENT_SHOW；不新增 onShow。
每次登录首次进入首页读取结算；成功完成整条弹窗/奖励动画流程后缓存结果。
缓存仅保留在本次登录内，跨 HomeScene/GameScene 保留，账号/token变化或重新登录重置。
首页每秒仅检查本地时间和缓存，不轮询接口；周期依据 passCheck/read.time（idcount 周期起点）+30天，使用结算返回的 serverTime 校准本地时间。
到期时请求一次；在战斗/后台跨过到期点则回首页/前台补查。其他接口先推进到新周期也不会漏掉旧周期检查。
缺少周期信息时补读一次 passCheck/read，读取失败不写成功缓存。
待恢复战令订单、支付完成/失败使缓存失效；网络失败按5/10/20/40/60秒重试，最多间隔60秒，成功后停止。
410人工处理订单在本次登录内不反复重试，保留订单记录；重新登录可再次检查。
销毁首页移除监听和本地计时；未完成弹窗流程不缓存，结算优先级仍为-100。
登录支付恢复先补齐战令权益再读取快照，其他订单和奖励弹窗延后。

规则
图2无可领项，该期仅提示一次；图3有奖励，X和领取都提交同一幂等请求。
图3实际入账成功才播放既有奖励动画，失败保留弹窗；之后再展示符合条件的图1。
图1仅最新结束的一期、未买战令玩家可见；只售18元，展示即消耗唯一机会。
图1预制体准备好后保持隐藏，offer_shown 服务端确认成功才显示；410 静默跳过，避免每次返回首页时先闪出无资格的购买窗口。网络异常沿用同一 token 自动重试，切场景后不再显示迟到的响应。
图4“再想想”仅关闭确认层；“放弃”永久退出。遮罩不关闭；返回键与X一致。
上期支付只播付费奖励补发动画。期内18元显示VIP卡，30元/18升30显示豪华卡；
实际权益沿用原逻辑，升级仅新增权益。图5仅改美术引用。
界面固定文案使用图片，不新增Label。现有奖励数量/时长用数字图片。
离线不入账；服务端冻结进度，客户端按最新奖励表计算，提交后原子入账。

资源
已导入用户指定两套美术目录并复用 lose/texture 的确认弹窗素材。
目前无缺失素材。原用户已修改的 passCheckWindow/tongpiaozi 保留。
tools/import-battle-pass-art.cjs 可重建新增资源/meta及预制体图片引用；
主界面背景有hash保护，避免覆盖后续美术调整。

测试命令（客户端目录）
node --test tools/test-battle-pass-settlement-check.cjs
node --test tools/test-battle-pass-settlement.cjs tools/test-battle-pass.cjs
node --test tools/test-battle-pass-ui.cjs
新增模块使用 creator.d.ts 的定向TypeScript检查通过。
现有UI套件31项中30项通过：tools/test-battle-pass-ui.cjs:328 的数字节点
x预期25、实际0是本次修改前已有断言差异，未调整无关位置代码。

本地视觉预览
node tools/preview-battle-pass-settlement.cjs
浏览器 http://127.0.0.1:8776/，按钮可切换图1/2/3/4、18元/30元成功表现。
使用本机已安装的 Cocos Creator 2.4.15 预览引擎，实际组件和图片资源；
网络/支付为模拟数据，数字渲染预览适配不等于完整游戏构建。已逐项视觉检查。

发布和真机测试
后端变更在同级 workspace/server，不在本客户端仓库的旧 server 快照目录。
参见 ../server/laf-cloud/docs/pass-check-settlement.txt 的发布列表与验收清单。
本次未自动发布云函数/定时器，也未发起真实支付；必须先部署后端再发布配套客户端。
现有用户其他未提交修改均保留。后端按其AGENTS约定进行本地提交，不push。
