6.6 KiB
新手礼包逻辑接入
沿用用户搭建的 assets/action_bundle/prefab/newbieGift.prefab，本次代码不创建、删除或重新布局 UI 节点。
NewbieGift 使用 timeContainer/time 显示 HH:MM:SS，使用 btnContainer/btn 处理购买；保留 closeStarter_pack、buyProduct、againGet 按钮绑定。脚本不依赖旧宝箱/气泡 Spine 和 propBg 节点，兼容在编辑器中删除这些旧节点。Loading、ConfirmBox 沿用现有节点，确认框标题为“幸运礼包充值”。到期后显示“已结束”，禁用购买按钮并隐藏首页入口。
当前职责划分
按最新确认方案，后端仅管理 48 小时活动期限及旧期限迁移，支付、查单、领取确认恢复原有接口行为。后端实现只位于同级独立 ../server 仓库；MatchMaster 内的 server 目录未修改。
前端按 3 元购买，统一发放 8000 金币、锤子/冻结/魔法棒各 8 个。奖励配置位于 assets/Script/module/Config/StarterPack.ts。正常购买和登录补单共用该配置，不读取订单奖励版本或快照；改版前创建但尚未发放的订单，由新版客户端补发时也采用新版奖励。已经发过的订单不会因此自动补差额。
首页开启门槛不变：通关第 15 关后（内部 level 为 15），满足原支付入口条件。首次触发立即弹出并记入当前账号当天记录，以后每天首次进入首页提醒一次，关闭后保留入口。加载失败不消耗提醒次数。
与原支付接口衔接
- 购买前读取活动截止时间和购买状态，在前端检查是否仍可购买；不要求活动接口或订单接口返回奖励版本。
- 直购订单查询返回
pay_state=2表示已支付待领取，随后调用原getOrderReward；收到code=1, data="ok"即按前端配置发奖。 - 直购领取确认失败时，本次会话保存已经确认支付的订单号，重试领取确认，避免重新查单被当成已完成。
- 旧 iOS 客服查单成功时，接口已完成订单；前端直接发奖，不再调用一次领取确认。
- 直购查询返回已领取，或旧 iOS 接口返回“已经获取到奖励”时，清除过期的待支付界面状态，不再次发奖。
- 正常购买与补单都显式传递原始订单号，在本地按账号和订单号去重；原领取接口不返回订单元数据。补发不修改月卡倍率或体力。
真机支付排查
“获得新手礼包数据”来自 limitedTimeEvent 活动查询，不是发奖日志。微信支付成功回调和回到前台可能各触发一次查询；查单进行中不会再次开启并发查询链。
新手礼包直购每轮查单最长 30 秒，超时显示重新领取确认框，保留原订单，不新建订单、不把微信客户端成功回调当作服务端已支付。晚到的查询响应不会继续触发已经超时的一轮处理。领取确认失败后继续使用已经确认支付的订单重试。
日志前缀为 [新手礼包支付]，依次包含微信回调成功、查单目标服务器、每次查单返回、领取确认和前端发奖。日志只输出订单号末 6 位，不输出 token 或微信支付凭证。
体验版和开发版当前连接测试服 sor779u2w8.sealoshzh.site，正式版连接 q6rvwvtnga.sealoshzh.site。直购签名的支付环境仍为 env=0。真机支付成功但查单超时时，需要按同一订单核对微信支付发货回调的实际地址、目标云函数日志和订单库：state=0 尚未记录支付，state=1 已支付待领取，state=2 已确认领取。当前代码无法证明微信后台实际配置了哪个回调地址，不应仅凭前端成功日志手动发奖。
有效期与限制
首次触发从服务器当前时间起计 48 小时。未购买且仍有效的旧 24 小时礼包在读取时增加 24 小时，并标记已迁移；已购买或已过期不重新开放。用户上的 starterPackVersion 仅作为期限迁移标记，客户端发奖不使用它。
到期前已创建的有效订单可继续走原支付流程。因后端下单接口恢复原逻辑，到期禁购由前端入口和购买前检查控制，不再保证请求到达服务端时仍未过期，也无法阻止旧客户端或直接请求在到期后下单。前端发奖保留原有跨设备去重及中断恢复方面的限制；旧 iOS 查单将订单置为完成后若客户端未收到成功结果，不能仅靠重试保证补发。
本地验证与发布
恢复真实支付（2026-09-09）
前端发奖经体验版验证后，已撤销非正式版跳过支付的临时逻辑。开发版、体验版、正式版均恢复原有下单、支付、查单、领取确认和前端发奖流程。此前的本地测试领取标记不再参与礼包资格判断，已发放的测试资源不会回滚。
独立 server 仓库的订单分流提交 0030b5a 保留，尚未部署。部署环境变量、三个函数和发布顺序见该仓库的 laf-cloud/paymentRouting.README.md；其中描述客户端测试旁路的段落是撤销前状态，以本文为准。生产分流上线前，测试服真实支付仍可能遇到回调落在生产服、测试订单保持 state=0 的问题。
node --test tools/test-starter-pack.cjs tools/test-first-game-entry.cjs tools/test-career-loading.cjs
测试读取实际预制体，覆盖节点绑定、首次/次日提醒、到期按钮、原接口返回格式、旧 iOS 直接发奖、领取确认重试、登录补单、统一奖励和本地去重。客户端测试不再依赖同级 server 仓库。
上次有效期简化验证：客户端 104 项、后端 14 项测试通过。客户端 134 个 TypeScript 文件在补充运行时 cc.fx 声明后与 HEAD 对比，均有 17 条既有类型诊断，没有新增类型诊断；这不等于项目全量编译通过。
本次真机查单问题回归：客户端 108 项测试通过，新增支付回调成功但服务端未确认、30 秒后保留原单重试、超时后晚到响应、异常查询数据和缺失订单号场景。后端未修改。
随后根据云端 function starterPackConfig not found 日志，已将时间规则合并到独立 server 仓库的 limitedTimeEvent.ts。活动接口修复只需替换并发布该完整文件，不再依赖额外的 starterPackConfig 云函数。该错误属于活动接口，不能代替 wx/payCallBack 的调用记录来判断支付是否确认。
后端测试和部署范围见独立仓库的 laf-cloud/starterPack.README.md。若之前已发布带订单版本校验的后端，需要配套恢复原支付函数，否则不带版本的新请求会被旧校验拒绝。未进行真实设备支付验收，也未推送或部署云函数。