4.7 KiB
首页公共活动日程接入
客户端登录后请求 POST activityConfig/list，传当前 uid，由 Utils 附带登录 token 并选择测试服/正式服。百人赛返回当前玩家的个人活动期，黄金矿工仍返回公共日程。需先部署后端对应接口；客户端修改不会自动发布云函数。
刷新与缓存
- 登录成功后获取一次；进入首页和切回前台时重新获取。并发请求合并。
- 首页每秒按服务器校准时间检查已缓存的开始/结束边界，两次实际请求之间可按本地时间更新入口。
- 按
refreshAt查询最新发布的活动，最长间隔 30 秒。登录后临时发布且未在缓存中的活动，在网络正常时约 30 秒内被发现。 - 离开首页或进入后台停止公共日程轮询，回到首页/前台立即刷新；其他原有玩法入口独立显示，不等待日程响应。
- 缓存键为
activitySchedule:v2:<API服务器地址>:<uid>，隔离环境和账号，只保存入口所需日程及接收时间，不保存对手、奖励或完整挑战存档。 - 账号、环境或登录 token 变化时清空内存状态，丢弃旧在途请求的响应；新登录不恢复磁盘中的旧日程，等待新请求，避免显示上次登录的个人期。
- 每次实际发起请求前先清空内存日程、删除当前环境的本地日程缓存，并通知首页更新入口。请求成功后写入新缓存；请求失败或格式错误保持无日程状态，约 30 秒后重试。合并中的请求或未到刷新时间的检查不会重复清缓存。
- 清理只针对当前账号日程，不删除其他环境缓存、玩家挑战存档或结算记录。超出查询窗口
windowEndsAt后不再将旧日程作为展示依据。缓存中的phase不用于时间判断。
百人赛入口
后端登录时创建个人活动期并开始倒计时，玩家仍需手动点击「开始」才匹配。已有未结束个人期时登录不重置；失败、完成三阶段或到期后，下次登录开新期。列表和首页刷新均不会开期，匹配也不会重新开始倒计时。后台需要已生效的百人赛配置模板，使用其中的时长、门槛和奖池。
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。