# 控糖消消乐平台接入说明

## 已接入能力

- 复用主小程序 `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。
- 周一验证新周重新分组，旧周成绩不带入新周。