# V1本机接口契约

微信小游戏（含桌面图标）与TapTap内H5、桌面发行端、快捷入口均遵守[在线入口门禁](在线登录与进度门禁.md)：优先自动登录，需要时官方授权；认证与在线读档成功后进入，失败不能试玩或离线降级。

当前产品接入先遵守[应用类型与登录规则](应用类型与登录规则.md)：TapTap H5/小游戏为taptap（tap.login→code2Session）、微信小游戏为wechat、App为password，不按底层接口可选范围任意混搭。

当前平台与登录方式已分开，仅支持账号密码、微信、TapTap三种；新接入以[三种登录方式](平台与三种登录方式.md)为认证及身份结构的权威说明。

当前0.7.0按全新部署使用，账号返回platform，支持微信和TapTap小游戏登录；具体配置与身份隔离见[TapTap与平台账号接入](TapTap与平台账号接入.md)。不新增旧账号回填、旧库升级或旧SDK适配。

一个服务实例只绑定一个游戏。所有游戏接口需要`Authorization: Bearer <本游戏调用令牌>`，路径gameID必须与配置一致；其他游戏即使拿到本实例令牌也不能访问对应路径。客户端不直接调用这些接口。

| 方法与路径 | 状态与用途 |
| --- | --- |
| GET /healthz | 进程存活200，不检查微信远端 |
| GET /readyz | 本机持久数据库可用200，不可用503；不代表跨云网络已连通 |
| GET /v1/games/{gameID}/capabilities | users/gifts/archives/sync=true；transportEnabled单独表示中转是否配置 |
| POST /v1/games/{gameID}/users/taptap-login | 已实现，使用TapTap小游戏code创建平台独立账号会话 |
| POST /v1/games/{gameID}/users/wechat-login | 已实现，使用新微信code创建会话 |
| POST /v1/games/{gameID}/users/sessions/validate | 已实现，校验会话并返回玩家与到期时间 |
| POST /v1/games/{gameID}/users/sessions/logout | 已实现，撤销当前会话，可重复调用 |
| POST /v1/games/{gameID}/gifts/reservations | 已实现，预留领取并记录填写事件 |
| POST /v1/games/{gameID}/gifts/reservations/{claimID}/confirm | 已实现，幂等确认 |
| GET/PUT /v1/games/{gameID}/archives/{playerID}/{slot} | 已实现，JSON存档及版本控制 |
| POST /v1/games/{gameID}/events | 已实现，持久化后202 |

## 微信登录和会话

请求为application/json，最多4096字节，拒绝未知字段及多个JSON值：

```json
{"code":"微信登录code"}
```

服务端调用微信jscode2session，获取本游戏OpenID；不接受客户端自报OpenID，不跨游戏合并身份。微信换码请求超时为5秒，不跟随重定向，不返回或记录AppSecret、session_key和OpenID。

成功响应示例：

```json
{
  "player":{"playerId":"ab61021004827","gameId":"game-ab","platform":"wechat"},
  "loginMethod":"wechat",
  "sessionToken":"64位随机十六进制会话凭证",
  "expiresAt":"2026-10-22T02:00:00Z"
}
```

同游戏、同平台、同OpenID通过数据库唯一约束复用玩家，首登并发不会创建多个用户。每次成功微信换码产生独立会话，退出只撤销指定会话，不影响其他设备。默认24小时有效，可配置1至720小时；数据库只保存会话摘要。当前未实现刷新凭证，过期后通过新code登录。

校验或退出请求：

```json
{"sessionToken":"登录返回的会话凭证"}
```

校验成功返回player、expiresAt，不回显sessionToken。退出返回`{"loggedOut":true}`。不存在或已撤销的合法长度凭证退出同样返回成功，不暴露其存在性。

登录每实例默认120次/分钟，最大同时4个换码请求；超过限制返回429与Retry-After。游戏后端仍须在面向玩家的登录入口限制请求，避免某一玩家耗尽全游戏额度。

错误：401 UNAUTHORIZED为游戏调用鉴权失败；400 INVALID_WECHAT_CODE为微信code无效或已使用；502 WECHAT_UNAVAILABLE为微信失败或限频；401 INVALID_SESSION为会话无效、已撤销或过期；503 STORAGE_UNAVAILABLE为本地用户存储故障；415为非JSON，413为超大正文。

不要直接重试已使用的微信code并假定会成功；微信换码成功但本地响应失败时，客户端应重新取得code登录，数据库继续复用原玩家。

## 玩家ID与存储

格式：2至3位小写字母游戏前缀+年份末位+北京时间MMDD+六位随机数字。使用密码学随机源，数字保留前导零。数据库保证player_id唯一、(game_id,platform,login_method,issuer,subject_hash)身份唯一；碰撞最多尝试32次，失败不建立半成品会话。完整注册时间独立保存。

每个数据库文件记录固定gameID。其他gameID误用该数据文件时启动失败。前缀、微信应用均固定分配，不提供历史换绑限制或复用流程；全局前缀唯一仍由平台分配保证。

## 礼包、存档与中转接口

上述模块已实现，具体请求、查询、失败恢复及文件补传见[完整接入与联调](完整接入与联调.md)。

- GET /v1/games/{gameID}/gift-codes/{code}：已同步的礼包码状态。
- GET /v1/games/{gameID}/gifts/reservations/{claimID}：领取状态和填写/确认时间。
- GET /v1/games/{gameID}/events/{eventID}：事件状态和最终平台处理回执。
- POST /v1/games/{gameID}/events/{eventID}/retry：仅失败事件可重试。
- GET /v1/games/{gameID}/sync-status：各状态数量及中转是否配置。
- GET /v1/games/{gameID}/export、POST /v1/games/{gameID}/import：带摘要的事件文件补传，正文最多4MiB，每包最多100条。

业务错误：400 INVALID_REQUEST、404 NOT_FOUND、409 CONFLICT、429 BACKLOG_FULL、503 STORAGE_UNAVAILABLE。存档最大1MiB；事件最多64个字段、每条编码后最多32KiB。礼包领取请求最多4KiB。

单玩家一次新手推广礼包，游戏根据claimId幂等发道具后确认。客户端不应持有公共服务令牌。存档成功不构成进度真实证明。投递状态delivered表示火花返回处理回执，不等于已奖励。