金字塔开发与联调说明

日期：2026-09-28。前后端代码已落地本地，未部署、未发布活动、未发生真实支付。

已实现

2026-10-10：金字塔接入公共 remote/manifest.json 与 SHA-256 ZIP 缓存，构建及上传步骤见活动分包说明。本地需完整重新构建并上传资源后联调。
assets/pyramid/prefab/Pyramid.prefab：独立 Cocos 2.4 活动包，按效果图组合标题、阶梯、奖励格子、箭头、道具数量、倒计时和购买/抽奖/免费领取按钮。
PyramidPanel.ts 与 PyramidDigits.ts：配置驱动奖励布局、宝箱气泡详情、抽奖高亮、领取勾选、过期及支付未决状态。仅宝箱点击后展示其内部奖励，普通奖励和顶部大奖不弹出道具详情。气泡按效果图使用圆角底图和向下尖角，锚定对应宝箱上方；点击外部关闭。所有数值均以图片数字拼接；缺少字符会报告并停止显示，不回退到 Label。
assets/Script/PyramidView.ts：首页入口直接复用 JiaZai.startUI2 的 pyramid.png，不叠加文字；活动弹窗与既有首页队列接入，登录及在线补发恢复；活动不存在或完成后隐藏入口。
assets/Script/module/Config/PyramidService.ts：接口、持久化请求 ID、支付轮询、账号切换隔离、跨期授权恢复、库存保存收据与发奖确认。

2026-10-12 补发查询与黄金矿工对齐：进入/返回首页、切回前台，以及本地检测到活动开始/结束边界时，查询 /pyramid/api action:settlement_read。并发查询共享任务，已返回但尚未展示的清单按 noticeId 合并保留。接口返回 status: settling 表示定时任务尚未准备完清单；请求失败或仍在结算时，仅重试补发查询，间隔为 2、3、5、7、10、15、25、30、50 秒。返回 ready 后停止重试，包括没有奖励的情况；持续停留首页不做常规接口轮询。下一次首页/前台触发会重新检查。查询和自动补发在首页弹窗队列及输入遮挡中执行；当前流程见下文。

2026-11-03：金字塔结算改为自动补发后的到账通知。settlement_read 本身仍只返回清单；前端查询后串行调用现有 settlement_claim（periodId、noticeId），成功后同步服务端绝对库存，再展示该批奖励。失败或仍在结算时沿用有界重试。无限体力按服务端返回的到期时间同步，入账即生效，不在关闭弹窗时再次延长。

自动请求前在现有 pyramid:v1:<服务器>:<账号> 日志的 settlements 中保存 pending 记录；确认入账后保存 ready 通知，关闭后保留 dismissed 去重标记。重启时恢复 ready 通知和 pending 请求，即使发奖响应丢失、服务端已不再返回该通知，也按原 noticeId 重试幂等接口。此恢复面向同设备本地数据保留的场景，不保证清缓存或换设备后补看通知。

PyramidSettlement 删除领取按钮和原 copy 文本，使用分包内独立复制的 art/settlement/ended_copy.png；保留五类奖励与逐批展示。关闭只确认本地通知，不发奖，也不再播放 RewardWindow。弹窗加载失败或离开首页不确认通知，下次可继续展示。本次无需变更后端接口，客户端和 pyramid 远程分包需配套更新。

独立后端 C:/Users/NK/Desktop/workspace/server/laf-cloud/functions/pyramid：期次配置、单笔未决支付、不放回加权抽奖、六层领取、到期结算、幂等发奖和测试。下单在既有两个微信签名接口中路由；共享 pay_test 通过 activityType:pyramid 区分。

测试配置与待补内容

测试排期为北京时间 2026-09-28 00:00 至 2026-09-29 00:00。前五层均 pay_test，草稿暂按 100 分/次。用户“价格1元1”的原文在实际发布前需要最终核对。后端草稿文件为 config/2026-09-28-test.draft.json。

各层正式奖励、数量、目标格子和权重未提供；草稿留空且不能通过发布校验。浏览器隔离预览和单元测试的奖励仅是样例，不写入活动数据库。第六层是否有固定奖也须由配置确定。

素材	当前处理
普通数字零至九、价格数字零至九	原目录两套共二十张全部齐全，原样导入；哈希测试核对原图
背景、阶梯、标题、按钮、箭头、四种宝箱	原样导入到 `assets/pyramid/art`
效果图顶部独立蛋糕大奖	原目录未找到，暂用提供的第四种宝箱占位，需补独立透明图
关闭、金币、锤子、冻结、魔法棒、无限体力、已领取勾、分钟单位	复用项目现有 `seven_day_gift` / `jungle_treasure` 图片，来源见素材清单
小数点数字字形	原目录未找到；当前整数元使用图片数字加原有“元”图。未来非整元价格显示图片数字组成的分值加文字单位“分”，不以 Label 显示数字；若要求元小数样式需补小数点

完整源图映射：tools/pyramid-art-manifest.json。tools/generate-pyramid-assets.cjs 可从原素材目录重建元数据和预制体，会覆盖预制体编辑结果；日常调 UI 直接在 Creator 中编辑预制体。

验证结果

检查	结果与范围
新增后端测试	24 项通过：并发下单/抽奖、权重及多目标、签名校验、幂等、支付截止、到期补发、保存收据、关单恢复
新增客户端测试	8 项通过：丢失响应恢复、支付取消保持锁、切换账号、图片数字及预制体引用
既有黄金矿工及支付路由回归	111 项通过；使用测试桩，需提供既有回调转发 URL 环境变量
前端 TypeScript 对比	HEAD 基线 18 个既有错误，当前同样 18 个，无新增；完整根目录检查另受旧 `server/drawHead.ts` 语法错误影响
实际 Cocos 引擎隔离预览	已加载实际预制体、源码组件及原图；验证购买转抽奖、终点全部领取及过期显示。服务层为本地模拟，不等于真实支付联调
Creator 完整构建	本机命令行构建长时间停在资源库初始化，已停止本次启动的构建进程；未取得完整构建成功结果

运行：node --test tools/test-pyramid-client.cjs；node tools/check-pyramid-types.cjs；node tools/preview-pyramid.cjs。预览仅监听 127.0.0.1:8766，依赖本机 Creator 2.4.15 引擎及项目已有 build/wechatgame/assets/internal。预览不连接业务服务器、不真实付款。

尚需环境验收

真实 Mongo/Laf 与微信真机支付尚未联调。当前轮询依靠服务端已验签回调和持久化状态恢复；仓库无已验证的该渠道主动查单/关单能力，因此无回调会保持未决，不会因客户端取消或超时放行。管理员只能在渠道已明确不可逆关单后记录关单凭据。详见后端 README。

发奖已经通过同一次用户文档更新保存库存和收据，并接入首页串行队列；旧游戏库存接口仍可能发送绝对值覆盖，真机验收需要检查其他自动保存流程，不应只以隔离预览作为上线依据。

发布前补齐运营配置、顶部蛋糕图（或确认宝箱占位）、价格确认，并完成 Creator 构建、Mongo/Laf、支付成功/取消/延迟/断网恢复验收。活动默认保持未发布。

云函数名额优化

金字塔从十三个云函数合并为两个：pyramid/api（唯一 HTTP 入口）与 pyramid/jobs（内部定时任务）。客户端通过 POST pyramid/api 的 action 指定 info、query、draw、claim、delivery_list、delivery_save、delivery_confirm；保存步骤改用 phase，避免占用 action。管理员 action:admin 单独验证 adminToken。现有支付签名和回调通过 api 的导出函数复用同一实现。2026-10-10 起，公共 activityConfig/list 仅提供入口日程，移除 pyramid、pyramidError、pyramidErrorMessage；完整个人状态由 action:info 返回，错误使用标准 errorCode 和中文 msg。前后端须配套更新。

本次验证：后端二十四项、客户端八项、既有回归一百一十一项通过。尚未更新或删除测试环境的云函数；按后端 README 的迁移顺序更新 api、支付函数、jobs 和客户端，再移除旧的十一个云函数，才能释放远端名额。数据集合和历史记录无需变更。

2026-09-29：v3 奖励与分档

独立后端已补入两份 v3 文档的四档 80 格目录、自动分档及反馈、免费首抽、登顶自动建立补齐授权；配置草稿默认关闭，尚未上线。完整接入合同见独立后端 laf-cloud/functions/pyramid/V3-OFFERS.md。付费用户必须提供可信净支付/退款/SKU 版本事实，旧 RFM 不直接作为报价证据。

本客户端新增全部楼层价格展示、实际渲染后的价格曝光事件及画像暂不可用提示。tools/preview-pyramid.cjs 在相邻后端有 v3 目录时自动读取，也可用 PYRAMID_CATALOG_PATH 指定；URL 的 ?tier=1 至 ?tier=4 仅控制本地隔离预览，不写服务端或提供生产切档。既有真机支付/库存验收边界不变。

临时免费抽奖测试（上线前删除）

PyramidPanel.ts 的 PYRAMID_ANIMATION_DEBUG 当前设为 false，预览、开发版、体验版和网页版均走正式服务端流程。需要单独验证动画时才临时启用；正式抽奖结果始终由后端决定。

测试状态集中在 PyramidAnimationDebug.ts，深拷贝进入面板时的活动快照，在本次面板会话中保留进度，关闭重开、切换账号或期次后重新开始复制。每次免费按剩余格子权重抽取，标记已获得并排除，命中 up 后上楼；概率弹窗读取同一份本地状态。第六层手动领取剩余奖励及终点奖励，完成后不可重复领取。测试不创建订单、不调用抽奖/发奖接口、不修改真实库存，展示仍复用战令领奖效果。

上线前必须删除测试代码，而非仅把标识改为 false：

删除 PYRAMID_ANIMATION_DEBUG、animationDebug()、actionDebug()、debugSession 字段以及 PyramidAnimationDebug 导入和 .ts/.meta 文件。
action() 直接调用 actionLive()，state() 直接返回 Service.data()；恢复初始化的价格曝光和待发奖励处理、恢复 recoverDelivery() 正式处理，移除渲染中的测试有效期分支。
删除 tools/test-pyramid-animation-debug.cjs 及隔离预览中的调试模块和会话引用；检查 rg "PYRAMID_ANIMATION_DEBUG|PyramidAnimationDebug|actionDebug|animationDebug|debugSession" assets 无匹配。
重新执行类型检查、tools/test-pyramid-client.cjs，并完成真机支付成功、取消、恢复、抽奖上楼及领奖验收。

SummitGlow 是预制体内位于 SummitPrize 后方的独立光效节点，由面板以每秒 60 度持续旋转；它属于正式表现，不随测试代码一起删除。

11 KiB Raw Permalink Blame History Unescape Escape