# 游戏后端与火花完整接入

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

登录交互规则：微信小游戏（含桌面图标）、TapTap内H5、TapTap桌面发行端与桌面快捷入口优先校验/复用有效登录态并自动登录；无有效登录态或平台要求授权时，允许走对应平台官方流程。TapTap可按实际运行环境跳转TapTap客户端或官方登录页，完成后回到游戏；微信小游戏使用其实际微信运行环境允许的官方登录/授权，不擅自改成网站扫码OAuth。需要官方授权不等于登录失败，不禁止必要的官方登录按钮/页面，也不强制每次重复授权。取消、认证失败或读档失败时仅提供实际状态及重新登录/重试，不提供密码、游客、试玩或离线兜底。TapTap桌面发行端仍是taptap/taptap，微信桌面图标仍是wechat/wechat；操作系统和快捷方式不决定登录方式。TapTap小游戏保留平台登录，独立App仍为app/password及登录名密码。后端必须验证真实凭据、会话和进度归属，不信任客户端自报成功；给出前端配合契约，不擅自修改未授权业务工程。

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

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

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

## 1. 固定各层身份

| 配置 | 含义 |
| --- | --- |
| game.id | 公共服务与中转使用的游戏内部标识，如game-ab |
| game.prefix | 统一分配的2至3位小写字母玩家前缀 |
| game.wechatAppId / 微信密钥 | 当前游戏自己的微信应用身份 |
| relay games[].machineId | 火花后台分配的机器标识，进入X-Game-Id |
| relay games[].applicationType / applicationId | 火花目录类型及数字ID；礼包下发game_id使用这个数字ID |
| 游戏调用令牌 | 游戏后端调用自己的公共服务 |
| 中转调用令牌 | 单个游戏公共服务调用中转；各游戏独立 |
| 平台密钥 | 中转与火花双向签名，不是微信AppSecret |

游戏自己的game.id、火花数字applicationId、机器machineId是三个不同标识，不能互换。

## 2. 中转服务与平台配置

复制relay.example.json为本地配置，设定SQLite绝对路径和腾讯云实际HTTPS API域名。监听明确的京东云内网IP，例如10.0.0.8:8090；游戏调用此IP，访问范围通过安全组限制。平台密钥和每游戏中转令牌从环境变量读取，配置文件不保存明文。

公开HTTPS反向代理只开放签名礼包码POST路径，参考deploy/relay-nginx.example.conf。HTTP事件、查询、导入与管理路径留在内网，不在公网直接暴露。提供模板但不自动申请证书。

在火花后台选中应用，打开“礼包码中转接入配置”，填写：

```text
https://relay.example.com/v1/relay/games/game-ab/gift-codes
```

新推广员领码后，平台按应用级配置排队，现有后台推送任务负责投递；旧任务回调保留兼容兜底。历史已有码通过“同步历史礼包码”每批100个排队。重复同步对仍待发送记录不重复排队，已发送码重新下发也不会重复登记领取。

平台推送新增X-Game-Id、X-Game-Type、X-Game-Timestamp、X-Event-Id、X-Game-Signature；签名为HMAC-SHA256(secret, machineId+timestamp+原始JSON正文)。接收端校验时间±300秒、应用身份与game_id。旧接收端可以忽略新增请求头；新中转不接受无签名回调。

平台收到200表示中转已持久登记，不表示每个游戏实例已经拉取；游戏端用gift-codes查询确认可用。首次联调必须检查平台推送任务正在运行以及日志结果，不能只保存回调地址就认为已下发。

## 3. 游戏独立实例

复制config.example.json，配置自己的game、微信环境密钥、独立SQLite文件和本机端口。sync.relayUrl指向京东云内网，sync.tokenEnv与中转对应游戏一致。内网HTTP必须显式allowPrivateHttp=true，且目标必须是私网或回环IP；如需加密内网传输使用HTTPS。

开发者接口调试与用户游戏入口分开：无sync.relayUrl时可验证用户、存档与事件持久化接口，但不会同步；这不授权用户在认证或在线进度失败时本机试玩/离线进入。capabilities.transportEnabled=false，不能视为联调完成。

## 4. 游戏业务调用

所有游戏接口由游戏后端携带自身Bearer令牌调用，客户端不拿公共服务令牌。真实玩家ID由微信登录返回，游戏后端必须把自己的客户端登录态绑定到该玩家，不能任由客户端指定其他playerId。

```text
POST /v1/games/game-ab/users/wechat-login
{"code":"新微信code"}
```

成功得到player及sessionToken；会话校验、退出沿用接口契约。

礼包输入完成后：

```text
GET /v1/games/game-ab/gift-codes/PROMO-SXXXXXX
POST /v1/games/game-ab/gifts/reservations
{"playerId":"ab61021004827","cdkey":"PROMO-SXXXXXX","idempotencyKey":"gift-player-request-001"}
```

返回claimId和reserved/confirmed状态。每玩家默认只有一次新手推广礼包资格，同一玩家换码返回409；同一幂等键换玩家或换码也返回409。

游戏用claimId作为自己发道具事务的唯一键，将“已发放记录”和“增加道具”放在同一游戏业务事务。真正发放成功后调用：

```text
POST /v1/games/game-ab/gifts/reservations/{claimId}/confirm
GET /v1/games/game-ab/gifts/reservations/{claimId}
```

确认可重复。确认超时后查同一claimId或重试；不能换key重新发放。预留不自动超时取消，避免在游戏已发道具但确认丢失时再次领取。

预留时记录公共服务收到有效填写的时间filledAt，并产生独立填写事件；确认时记录confirmedAt并生成确认同步事件。火花现有redeemedAt仍使用filledAt，不能替换为confirmedAt。确认事件适配现有火花接口时重复提交同一填写事实，平台去重，不新增有效用户；完整确认时间保留在两级事件的occurredAt与本机领取记录中。

## 5. 存档和进度

```text
PUT /v1/games/game-ab/archives/ab61021004827/main
{"expectedVersion":0,"data":{"level":1,"items":[]}}
```

创建用0，返回version=1。更新携带当前版本；并发只有一个成功，另一个409。409后读取最新存档合并业务，再提交新版本，不盲目重试覆盖。

```text
POST /v1/games/game-ab/events
{
 "eventId":"player-level-0001",
 "playerId":"ab61021004827",
 "occurredAt":"2026-10-21T10:30:00+08:00",
 "data":{"level":10},
 "fieldLabels":{"level":"游戏等级"}
}
```

只接受已确认礼包玩家的服务端进度，自动取绑定礼包码，不允许换码。必须提供稳定eventId、真实发生时间、字段中文说明；累计值按快照提交，不把增量重复累加。当前进度类型对应火花原接口的有限数值、布尔、字符串。

202表示本机已持久化，不表示奖励已发放。游戏后台计算进度，不能把客户端随意提交的数值直接用于奖励。

## 6. 两级回执与补传

游戏每3秒执行同步，拉取最多100条礼包登记变更，每轮最多处理10条事件；中转最多8个投递worker，按全局到期事件调度，避免逐一扫描全部游戏。超时10秒，事件租约60秒，崩溃后租约到期可继续。

事件状态：pending→sending→accepted（中转已接收）→delivered（火花返回合法处理回执）；失败退避，连续发送失败12次进入failed。等待中转处理本身不消耗网络失败预算。failed不会静默删除。

```text
GET /v1/games/game-ab/events/{eventId}
GET /v1/games/game-ab/sync-status
POST /v1/games/game-ab/events/{eventId}/retry
```

重试失败事件保留相同内容和ID。delivered不允许重置。回执中的matched/skipped/invalid/redemptions表示现有平台处理口径，不是实发金额；真实收入以火花钱包明细为准。

导出每批最多100条未最终投递事件，包包含version、events、sha256、nextAfterId及hasMore。hasMore为true时，将nextAfterId经URL编码放入下一次/export?afterId=参数，直到结束，避免总是导出同一批。导出期间新增的较早字典序ID可在下一轮从头扫描补齐，不宣称跨批是一个数据库快照：

```text
GET /v1/games/game-ab/export
POST /v1/relay/games/game-ab/import
```

从游戏导出后，可以直接上传文件到中转，或先上传私有对象存储再由受控任务下载并导入。服务不接受任意远程文件URL，不需要内置云厂商账户。将完整JSON包作为import正文，不能删改时间或ID。中转也提供/export，游戏提供/import，支持恢复；摘要不匹配、跨游戏或同ID不同内容整包回滚。重复导入已成功事件不会重复投递。

每游戏未最终投递事件上限100000，满额返回429并保留原数据；不要在满额时绕过公共服务声称填写已记录。历史成功事件保留用于幂等，不自动清理；需监控磁盘空间，未压测前不承诺2核4G或4核8G的最大吞吐。

## 7. 联调验收清单

1. 有效微信code登录、重复登录复用、退出和过期拒绝。
2. 推广员领码→平台推送日志成功→中转有登记→游戏查询可用。
3. 并发同一礼包领取不重复；换码、重复key不同内容被拒绝。
4. 游戏真实发道具；模拟确认超时后恢复，不能再次增加道具。
5. 存档读写、并发409、服务重启及备份恢复。
6. 未达标和达标进度回传；用户端有效用户与实际收益分别核对。
7. 暂停网络、重启两级服务、恢复网络；同一事件不重复入账。
8. 文件重复导入、坏摘要、跨游戏令牌、错误签名都按约定处理。

自动测试已覆盖可模拟部分；真实云网络、微信凭据及生产火花域名由部署联调确认。

礼包停用命令disable_cdkey可通过相同签名入口登记。停用为终态，不复用同一礼包码，迟到的旧register_cdkey不会重新激活；平台当前自动下发为register_cdkey。