8.9 KiB
新排行榜与周竞赛交接说明
更新日期：2026-10-28。依据当前 newRanks 工作区代码整理。文档迁移已提交；本轮虚拟列表优化与相应文档更新尚未提交。本文与同目录 DOCX 说明当前实现，不替代后端发布的正式接口协议。
当前功能
旧 ranking.ts 的 init 在 RankingEntry.enabled 为 true 时隐藏旧面板，通过常驻 ranking_v2_entry/RankingEntry.ts 打开新版。首页旧逻辑保留，入口关闭开关可回退。新版包含玩家榜和周竞赛，微信好友榜及授权流程未迁移，头像底框统一使用新版美术。
RankingV2.prefab 保存两页主体和固定 Header；PlayerRow.prefab、WeeklyRow.prefab 保存列表行布局。Slot0 至 Slot6 是行位置参考。支持左右滑动、标签点击、选中条跟随和边界回弹。玩家榜隐藏玩法问号。不要运行旧的全量预制体生成工具覆盖编辑器布局。
首次打开通过公用小猫加载动画等待资源及首屏数据或可展示错误态准备好，再显示面板；不设置固定最低播放时长。远程头像仍异步加载。已有缓存时先展示缓存，后台刷新不显示加载动画。
玩家榜虚拟列表
玩家榜已改为可视区域加缓冲行的虚拟列表。服务端返回的完整玩家数据仍保留在内存中，前三名使用领奖台；其余玩家不再一次性创建全部节点。滚动时复用已有行，更新位置和玩家信息，底部本人栏保持独立。周竞赛列表保持原实现。
RankingPanel.ts 的 updatePlayerRows 根据视口位置筛选需要展示的行，监听 scrolling 和 Content 的位置变化，兼容手势滚动与程序跳转。前七行沿用 Slot0 至 Slot6 的编辑器位置、尺寸、缩放、锚点和角度，其后沿用原行距；行内布局仍由 PlayerRow.prefab 控制。预制体文件未因本次优化改写。
回收行时隐藏节点，释放该行持有的头像引用，并更新异步请求版本，阻止旧玩家头像回调覆盖复用后的行。仍在可视范围的行不会因每次滚动重复绑定数据。节点池保留面板打开期间达到的容量，关闭面板时随界面销毁；这不是跨面板的全局对象池。
200 名玩家的浏览器测试中，原本需要197个普通列表行；当前在540×1170测试视口下首次创建10个，滚动到中间最多12个，反复滚动不再增长。实际节点数随视口和预制体布局变化，此数值不是所有设备的固定上限。该优化减少行节点及头像绑定工作，不减少接口返回的数据量。
check-virtual-list.cjs 已验证顶部、中间、底部及反复滚动、旧头像回调、人数减少和空榜；check-prefab-layout.cjs 已验证编辑器布局、标签切换与缩放；check-data.cjs 类型与数据检查通过。尚未重新构建并完成微信端性能验证，不能把浏览器节点数量验证等同于真机帧率结论。
接口与服务器
玩家榜通过 Utils.getRank 调用 POST getRank，保留服务端顺序，使用 levelAmount 显示过关数，奖杯沿用旧映射。首页入职及地区榜使用 getSRank，二者均由 Utils.POST 跟随当前环境，不再固定走旧排行榜专用域名。
正式服配置为 https://q6rvwvtnga.sealoshzh.site/，测试服为 https://sor779u2w8.sealoshzh.site/，定义于 assets/Script/module/Pay/Utils.ts。浏览器默认测试服，允许手动切换；微信正式版固定正式服，开发版及体验版允许切换。接口是否部署及数据量由对应服务器决定。
周榜查询使用 POST getWeeklyCompetitionRank，由 WeeklyCompetition.ts 经 Utils.POSTJSON 调用，携带当前 uid 与登录 token。消费 status、serverTime、cacheTtlSeconds、currentWeek、board、canClaim 和 pendingReward。board.rank 提供成员及名次，board.reward 提供前三奖励；当前前端不自行分组或结算。
serverTime、startAt、endAt 是毫秒时间戳；cacheTtlSeconds 是秒数，3600 表示一小时。board 与 currentWeek 可能属于不同周期：有待领奖励时可展示历史榜。当前适配器要求 canClaim 为布尔值，并验证领取凭证格式。
领奖使用 POST claimWeeklyCompetitionReward，发送 uid、token 和 claimId。返回值需包含可重新解析的周榜数据及 receipt；前端校验 receipt.claimId 与请求一致，从 receipt.rewards 读取 type 和 count。不能只返回一个领取成功标记。
POST settleWeeklyCompetitionTest 是测试结算接口，参数为 uid、token、weekId。它由测试工具显式调用，正常排行榜不会调用。当前已取消测试白字入口，测试面板和 Mock 代码保留，重启后 Mock 默认关闭。
缓存与结算按钮
WeeklyCache 按服务器和账号持久化请求结果。有效期从本地请求开始时间计算，取 cacheTtlSeconds × 1000 与本周期剩余时间的较小值。缓存命中不延长有效期；时钟回拨、通关保存成功及领奖等操作可使缓存失效。
打开榜单、切换标签或返回前台时检查缓存；有效期内复用，过期后后台请求，有旧显示快照则继续显示，失败保留旧数据。当前没有在页面持续停留时按 TTL 定时轮询的功能；周期结束边界有一次刷新。TTL 为零表示下次访问重新查询，不表示循环请求。
玩家榜在同一服务实例中缓存，接口给出数值 cacheTtlSeconds 时按其过期；未给出则默认复用至面板关闭。周榜显示快照与请求缓存分开保存，过期不等于立即清空画面。
未结算时不显示底部继续按钮。待领奖时显示领取，校验回执并完成金币保存后播放独立复制的战令领奖效果，随后展示新的榜单。没有奖励且收到新周期数据时，若有上期快照，保留上期画面并标注上次记录，显示继续；继续刷新并确认新周期，不返回首页。没有旧快照时不会虚构历史排名，旧快照也不是后端最终结算名次。
奖励保存与限制
当前真实领奖仅支持 coin 金币。前端收到有效回执后，复用公用 Utils.withCoinSave 串行队列，再调用 userCoin 保存余额；不加载或依赖黄金矿工活动分包。其他奖励类型会阻止成功发放并提示处理，不能据此宣称道具已经接入。
以 claimId 记录 pending、saving、saved 状态，已保存回执不重复增加金币。保存结果不确定时保留记录并提示核对，避免重复加钱。日志按账号和环境隔离；清除本地数据或跨设备的去重无法仅靠本地日志保证，需要后端进一步提供可靠的到账确认或同步机制。
宝箱奖励浮层复制自喵运登高，领取表现复制自战令；代码、预制体、图片和字体均有本包副本。动画仅负责展示，不再次发放奖励。旧 RewardCelebration 模板已移除，reward-coin.png 暂保留但当前不使用。
远程资源与发布
ranking_v2 使用与黄金矿工相同的 activity-bundles 机制。资源生成到 build/wechatgame-activities/remote/ranking_v2 的带哈希 ZIP，公共 manifest.json 包含该条目。业务脚本仍在本地 src/scripts/ranking_v2，常驻入口位于 ranking_v2_entry；远程 ZIP 不下载执行脚本。
重新构建后，先上传对应 ZIP，再更新完整公共 manifest.json，保留其他活动条目。既有 CDN 地址为 https://cdn.pay.nika4games.com/remote/；提交前核对实际构建配置，不能把本机调试地址当成正式地址。
用户已确认通过 http://127.0.0.1:8785/remote/ 的本地资源服务器成功打开排行榜。此地址只对本机有效。该验证不能替代 CDN 发布、微信真机首次下载、缓存重开及真实领奖到账验证；本轮文档更新不代表已完成这些验证。
素材与历史资料
素材使用清单.html 与 art-manifest.json 包含原美术来源和当前 img、reward 资源盘点。静态引用扫描可辅助核对，但动态选择的素材不能仅凭未命中静态引用判定未使用。已知不使用的原稿包含效果 JPG、字号颜色标注和系统隐藏文件。
旧入口接线待批准.patch 是历史审阅存档，已应用且其中入口路径已被后续迁移替代，不能再次执行。当前真实入口应查看 assets/Script/ranking.ts 和 assets/ranking_v2_entry/RankingEntry.ts。本目录位于公共 docs 下，不进入排行榜 Asset Bundle。
排行榜说明、DOCX、素材清单及历史资料统一存放于 docs/ranking_v2。assets/ranking_v2 和 assets/ranking_v2_entry 不保留 README 或其他说明文档。运行 docs/ranking_v2/update_documents.py 可从本 README 生成 DOCX 并更新素材报告，不会重新在代码包内生成 README。
交付前待验证
核对正式环境接口及资源域名、真实账号查询与领奖保存、跨周无奖继续与有奖领取、断网重试和多设备记录。微信好友榜尚未迁移；非金币奖励、页面停留期间 TTL 定时轮询均未实现。素材清单中的静态未确认项需结合动态使用复核，不能直接删除。