阅读主题
区服角色与可靠履约
游戏自己的区服、角色和资产由可信游戏服务器管理。平台提供绑定及持久化履约事件，客户端不能自行声明角色归属或以支付成功回调直接发货。
绑定区服和角色
- 游戏服务器用 X-API-Key 调用 POST /api/server/realms，提交 appId、serverId、name、enabled、version 和 requestId。新建 version 为 0，更新使用上次返回的版本。
- 用 X-API-Key 与目标玩家 Bearer 一起调用 POST /api/server/roles/bind。提交 appId、serverId、externalRoleId、name、level、enabled、version、requestId。
- 游戏密钥和玩家会话必须属于同一逻辑游戏。同一区服的外部角色不能绑定给两个账号。
- 玩家 GET /api/realms 和 GET /api/roles 读取可信绑定。创建订单的 roleId 传 bindingId；平台将区服、外部角色写入订单快照。
开启外部履约
开发者在“接入配置 → 游戏服履约”切换为 external；保存时检查版本。已有订单沿用创建时的模式和角色快照，切换不改写旧订单。仅 game_item 走外部游戏资产；平台月卡与平台币仍由平台账本管理。
| 阶段 | 平台订单 | 游戏服务器工作 |
|---|---|---|
| 下单 | pending | 保留订单对应的角色目标 |
| 演示支付 / 钱包支付确认 | paid | 平台事务内写入 grant 事件，尚未发货 |
| 领取并发货 | paid | claim → 本地持久化幂等执行 → ack |
| 发货回执完成 | fulfilled | 平台核验有效租约及唯一回执 |
| 申请退款 | refund_pending | 领取 revoke 事件并回收原角色资产 |
| 回收回执完成 | refunded | 平台按原钱包分桶规则退回金额 |
拉取与回执
所有下列游戏服请求都需要 X-API-Key，密钥不放客户端。claim 返回的 leaseToken 是短期回执凭证，不写日志。
| 接口 | 请求体 |
|---|---|
| POST /api/server/deliveries/claim | appId、limit（1～50，默认 10） |
| POST /api/server/deliveries/{id}/ack | appId、leaseToken、receiptId、requestId |
| POST /api/server/deliveries/{id}/fail | appId、leaseToken、reason、requestId |
租约有效 30 秒；失败按指数退避，最多 5 次后进入 dead。过期租约不能确认。一次处理可被多次投递，游戏服务器必须按事件 ID 持久化去重，在同一数据库事务内记录回执并增减资产。网络断开后复用回执，不重复增减资产。发货和回收分别有独立事件 ID。
开发者可查看自己游戏的事件并人工重试 dead 事件。管理员可按游戏查看和重试，重试保留原事件及订单 ID。必须先核对游戏服执行记录，再点击重试，不能直接把订单改成完成。
验收
覆盖多消费者竞争、重复回执、过期租约、处理完成后回执断网、退款资产不足、原目标角色停用、服务重启和跨游戏访问。外部事件确认只说明接入方提交了可信回执；平台无法凭空验证未接入的外部游戏资产。参考仓库 examples 中的消费者示例，以自己的游戏资产事务替换样例逻辑。