56 lines
6.2 KiB
Markdown
56 lines
6.2 KiB
Markdown
# 首页公共活动日程接入
|
|
|
|
客户端登录后请求 `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 分包清单](activity-bundles.md)。加载资源不额外请求活动列表；同次首页/前台周期共享清单，仅为当前需要的活动下载 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`。
|