zyt/TUICallKit-Vue3/tongji/endless-game/PLATFORM_INTEGRATION.md

控糖消消乐平台接入说明

已接入能力

• 复用主小程序 token 与微信小程序登录，不创建第二套游戏账号。
• 按周一日期、性别自动分配最多 7 人的同行组。
• 以真实平台昵称、头像、认糖数和本周最高分排序。
• 每局用 session_key 上报绝对进度，断网重试不会重复加分。
• 待同步成绩最多本地保留 8 局，重新联网后自动补传。
• 微信好友与朋友圈分享使用随机分享码，不在链接中暴露用户 ID。
• 受邀进入只记录一次轻量分享访问，不自动建立家庭或好友绑定。

接口

• GET /api/tcm/gameWeeklyLeaderboard：获取或创建当前周同行榜。
• POST /api/tcm/gameSubmitProgress：上报 session_key、learned_count、score、ended。
• POST /api/tcm/gameRecordShare：记录分享动作并获取本周分享码。
• POST /api/tcm/gameAcceptShare：受邀用户登录后提交 invite_code。

四个接口都使用现有 LoginMiddleware 校验主小程序 token。

部署顺序

1. 执行 server/sql/1.9.20260717/add_tcm_endless_game_platform.sql。
2. 发布 server/app/api/logic/tcm/GamePlatformLogic.php 和 TcmController.php。
3. 重新构建并上传小程序前端。

如果后端或数据表尚未发布，游戏仍可离线游玩，榜单会显示“离线记录中”；联网且接口可用后自动补传。

上线前检查

• 用男女各两个测试账号进入，确认被分入对应性别组。
• 同一局重复提交相同 session_key，确认周认糖数不重复增加。
• 断网完成几次消除，再联网打开榜单，确认成绩补传。
• 分享给另一个微信账号，确认能直接进入游戏且链接中没有用户 ID。
• 周一验证新周重新分组，旧周成绩不带入新周。