79 lines
6.0 KiB
Plaintext
79 lines
6.0 KiB
Plaintext
战令结束结算接入说明（2026-10-09）
|
||
|
||
时间契约
|
||
沿用现有 passCheck/read 返回的 time：毫秒级周期起点，结束点为 time + 30 天。
|
||
不把该值改成秒，也不改变已存档 stage.time（毫秒结束点）。周期保留运营配置的
|
||
北京时间起点，不再按云函数宿主本地时区 setHours，也不再由不同接口分别推进30/60天。
|
||
|
||
发布清单（本次只本地实现和测试，尚未部署）
|
||
1. 先发布 passCheckSettlement、passCheckJobs、passCheckUpgrade、passCheck、
|
||
passCheckTime、wx/checkIos。passCheckUpgrade 补齐了 POST YAML。
|
||
2. 按 functions/pass-check.trigger.json 创建/更新每分钟触发器，目标 passCheckJobs。
|
||
passCheckJobs 不开放 HTTP 方法；需要现有 PASSCHECKTIME_ID 环境配置。
|
||
每分钟仅用于检查周期和继续未完成的批次；本期扫描完成后不再读取用户表。
|
||
3. 再发布配套客户端。旧客户端的过期进度写入将被拒绝，不能继续按旧方式领上期奖励。
|
||
4. 不清空用户历史。快照存入 users/usersAd 的 passSettlements，
|
||
passSettlementRevision 用于 CAS。后台每期每个用户集合只完成一轮分页扫描，
|
||
每次触发各处理最多100条；进度保存在 passCheckJobCursors。
|
||
请按用户规模评估扫描延迟；玩家请求时同样惰性补建快照，不必等待后台扫到自己。
|
||
|
||
按期扫描与旧任务升级
|
||
- 当前全局周期起点同时是上一期结束点，以该毫秒时间戳标识扫描期。
|
||
即使在线接口先推进了全局周期，后台仍会对比自己的 periodEnd，启动新一期扫描。
|
||
- 新进度键为 season:users、season:usersAd；保存 periodEnd、after、completed、
|
||
completedAt、revision、leaseUntil。仅使用已有集合的 _id 索引，无需手动初始化。
|
||
保留旧 users/usersAd 游标，但不再读取它们；升级后的首次运行从头补扫一次历史存档。
|
||
此后只有全局周期推进才开启新一轮；配置的起点还在未来时不扫描。
|
||
- 每批成功后推进游标，不足100条时标记完成；恰好整批时下一次空页确认完成。
|
||
两个集合分别完成。全部完成后每次触发仅读取周期配置和两个进度文档，不扫描用户，
|
||
不反复更新游标；云函数每分钟的触发次数本身未减少。
|
||
- 每批取得5分钟租约，并用 revision 比较更新防止重叠执行或旧执行覆盖新进度。
|
||
批次失败保留起始游标、释放租约，下次重试；进程直接退出时租约到期后恢复。
|
||
失败重试或租约超时接管可能重复读取该批，但已有快照不重复生成，也不自动发奖。
|
||
- 跨期仍未扫完时先续完旧扫描，再开启最新一期。停机错过多期时无需为每个中间期
|
||
重扫全服：freezeUser 一次补齐该玩家存档中所有可验证的到期记录。
|
||
扫描完成后新增或导入的历史玩家记录，由其在线请求补建，或在下一期扫描时补齐。
|
||
- 已部署旧版时，本次只需重新发布 passCheckJobs 并更新触发器描述；cron 仍为
|
||
* * * * *。不需要改客户端、奖励领取接口，不删除用户快照或旧游标。
|
||
|
||
协议
|
||
POST passCheckSettlement，使用现有 uid/token/gameName 鉴权。
|
||
read：返回 rows（按结束时间升序）、resources、serverTime。
|
||
empty_seen + end：图2实际展示后标记该期已提示。
|
||
offer_shown + end + offerToken：图1实际展示后消耗唯一展示机会；仅原令牌/登录会话
|
||
可重试确认。令牌不在 read 中返回；进程关闭后不可恢复该购买窗口。
|
||
decline + end：永久放弃该期机会，不影响已支付订单的补发。
|
||
claim + end + rewards + claimFlags：领取客户端按最新配置计算的已解锁未领奖励。
|
||
purchase_claim 另加 outTradeNo：上期18元订单补发已解锁付费奖励。
|
||
rewards 为合并后的 coin/freeze/hammer/magic/infinite_health，体力数量单位为秒。
|
||
claimFlags 仅更新实际领取的 free/passCheck 索引为0，不修改冻结经验或等级。
|
||
|
||
服务端不保存奖励配置或版本、不计算应发奖励数量。按已确认的客户端可信方案，
|
||
只检查类型/正整数、归属、支付状态和收据。此方案防重复领取，但不能防篡改客户端
|
||
伪造奖励数量；这不是服务端权威发奖方案。
|
||
|
||
一致性
|
||
到期只冻结进度、购买档位、领取标志，不给离线玩家入账。
|
||
普通进度更新用数据库 $$NOW 截止条件；冻结同时 CAS 所有进度输入。
|
||
领取资源增量与收据在同一用户文档原子写入，订单状态更新可幂等补齐。
|
||
已支付的期内订单延迟恢复时，仅接受冻结进度及订单对应权益，不接受客户端替换
|
||
过期进度。领取掩码保留，30元的20点经验/3000金币仍沿用已有权益逻辑。
|
||
同一期第二笔补购支付不二次发奖，订单标记 passReview=duplicate_post_season_payment，
|
||
需人工退款处理，不自动退款。
|
||
|
||
验证
|
||
Node 24：node --test laf-cloud/tests/pass-check-settlement.test.mjs（15项通过）。
|
||
覆盖完成后零用户扫描/零写入、分页、新周期、空集合/整批边界、失败重试、旧游标升级、
|
||
跨期续跑、租约超时接管与旧执行防回退、在线补建、未来周期配置；保留原发奖幂等测试。
|
||
配套客户端 tools/test-battle-pass-settlement.cjs 覆盖奖励表、UI关闭=领取、
|
||
失败重试、确认弹窗、优先队列、多期顺序和支付幂等。
|
||
现有 rookie-gift.test.mjs 在导入阶段失败：goldMiner/config 缺少 paymentProductId
|
||
导出，与本次战令改动无关，未修改该模块。
|
||
|
||
上线前真机验收
|
||
Android、原生iOS支付、客服iOS支付分别验证成功/取消/延迟回调/杀进程恢复。
|
||
跨截止时刻验证已解锁未领范围、点击X领取、奖励动画后补购、永久放弃。
|
||
断网/重复点击/跨设备重试验证资源只入账一次。停留在图1时可重试失败支付，
|
||
重新登录不恢复该期图1；已支付订单仍可从原有登录订单补发入口恢复。
|
||
本地模拟数据库和Cocos视觉预览不替代上述真实支付及云端验收。
|