6.2 KiB
首页公共活动日程接入
客户端登录后请求 POST activityConfig/list，传当前 uid，由 Utils 附带登录 token 并选择测试服/正式服。百人赛返回当前玩家的个人活动期，黄金矿工仍返回公共日程。需先部署后端对应接口；客户端修改不会自动发布云函数。
刷新与缓存
- 登录成功后获取一次；登录后的首次首页复用该请求或结果。之后返回首页、切回前台各刷新一次（关卡内切前台也刷新），全局和首页监听合并请求。
- 首页每秒按服务器校准时间检查已缓存的开始/结束边界，两次实际请求之间可按本地时间更新入口。
- 不再按
refreshAt定时请求；首页每秒只按serverNow校准后的时间及startsAt <= now < endsAt在本地更新入口。 afterLogin()、enterHome()、onForeground()统一驱动日程和公共资源检查周期。打开金字塔及抽奖、领奖、支付确认后的状态刷新仅请求pyramid/api action:info。后台临时发布的活动或未返回的下一期，在下次日程刷新时获取。- 缓存键为
activitySchedule:v2:<API服务器地址>:<uid>，隔离环境和账号，只保存入口所需日程及接收时间，不保存对手、奖励或完整挑战存档。 - 账号、环境或登录 token 变化时清空内存状态，丢弃旧在途请求的响应；新登录不恢复磁盘中的旧日程，等待新请求，避免显示上次登录的个人期。
- 请求期间及请求失败时保留当前账号的有效日程，避免入口闪烁；成功响应整体替换日程，空列表正常隐藏入口。时间到期仍在本地隐藏，账号或环境切换立即隔离旧数据，冷启动不恢复磁盘日程。金字塔首页不再每 30 秒同步，进入或切回前台时检查一次恢复任务。
- 清理只针对当前账号日程，不删除其他环境缓存、玩家挑战存档或结算记录。超出查询窗口
windowEndsAt后不再将旧日程作为展示依据。缓存中的phase不用于时间判断。
金字塔详情与日程分离（2026-10-10）
金字塔资源已接入公共 ZIP 分包清单。加载资源不额外请求活动列表；同次首页/前台周期共享清单，仅为当前需要的活动下载 ZIP。
activityConfig/list 的顶层及活动条目均不返回 pyramid、pyramidError、pyramidErrorMessage。金字塔条目仅包含期号、版本、开始/结束时间、关卡门槛和阶段；查询不会创建参与进度、冻结档位或执行结算。
PyramidService 使用 Utils.POST 的 JSON 模式请求 pyramid/api，传 {action:"info",uid,token,periodId?}，其中 uid 使用 users._id，公共列表仍使用 users.onlyId。成功的 data 是完整个人状态（没有可查询期次时为 null），失败使用标准 errorCode 和中文 msg。首次有效详情查询仍按原规则创建进度和冻结档位。
打开页面、首页恢复，以及抽奖、领奖发放、支付确认后仅刷新个人详情；不订阅或读取日程中的个人状态。每次详情响应校准服务器时间，账号切换丢弃旧响应。入口依据日程时间和关卡门槛展示，已查询到本期 completed:true 时隐藏，但不打断最后一次领奖动画；旧期完成状态不隐藏新期入口。
百人赛入口
后端登录时创建个人活动期并开始倒计时，玩家仍需手动点击「开始」才匹配。已有未结束个人期时登录不重置；失败、完成三阶段或到期后，下次登录开新期。列表和首页刷新均不会开期，匹配也不会重新开始倒计时。后台需要已生效的百人赛配置模板，使用其中的时长、门槛和奖池。
CloudRiseView 同时订阅公共日程和百人赛个人状态。活动进入/离开开放窗口或切换期次时，只更新首页图标；满足等级门槛时预加载活动页面资源，不请求百人赛个人状态，也不报名。
cloudRise/index?action=status 的调用时机：
-
登录时保留个人状态恢复流程，即使本地没有存档也能发现其他设备开始的挑战。
-
点击百人赛入口时同步详情和参与资格；打开活动页面后保留详情刷新。
-
已有 playing/waiting 挑战、待提交操作、未保存奖励或待展示结算时保留定时及切回前台同步。个人任务处理完毕后停止后台轮询。
-
无参与记录、没有打开活动页面时，首页初始化、公共日程变化和每隔 30 秒不再额外请求百人赛个人接口。首页公共日程仍由独立接口刷新。
-
个人挑战 playing/waiting 且未到个人截止时间：即使公共报名结束，入口仍保留。
-
本期已失败/过期/完成：不展示本期报名入口；下次登录开新一期后显示新入口。
-
未参与：按个人期起止时间展示；尚未达到解锁等级时仍沿用点击后的等级提示。
-
暂无可用公共日程时不使用个人接口中的报名时间兜底公共入口；已有未结束的个人挑战仍可展示入口。公共列表请求期间及请求失败后，保留尚在有效期内的现有日程；从未获得有效日程时等待成功响应。
-
点击入口必须先成功同步个人状态，再判断解锁/加载页面。公共日程不代替报名、结算、奖励或个人挑战存档。
既有常驻图标的控制和布局保持原样，百人赛入口沿用当前左侧排列逻辑，不会因公共接口失败隐藏其他入口。
黄金矿工与后续玩法接入
当前仓库仅实现百人赛页面。公共服务不限制活动名称，黄金矿工及未来活动的信息会一并缓存，但不会创建没有页面的入口。
后续玩法使用 ActivityScheduleService.active(activityId) 获取当前期，periods(activityId) 获取缓存中的各期次，通过 subscribe(callback) 监听更新并在组件销毁时取消订阅。首页的 HomeActivitySchedule 统一驱动刷新，不要为新玩法另建公共查询定时器。
结合各玩法自己的个人状态计算入口可见性，再接入图标和点击处理；不要把黄金矿工的 purchaseEnabled:false 当成整个活动关闭。未知活动不影响已有入口。
验证命令：node --test tools/test-activity-schedule.cjs tools/test-cloud-rise-availability.cjs。