核心概念与边界

账号、应用和角色

概念	用途
开发者账号	团队登录控制台，管理属于自己的应用与订单
逻辑游戏 gameId	一款游戏的归属与隔离范围；开发者应用记录的 id 即该标识
客户端 appId	区分同一游戏的 H5、Android、iOS、Windows 接入配置与授权目标
平台玩家账号	平台内部统一管理玩家身份，不作为第三方查询全平台玩家数据的入口
游戏用户标识 gameUserId	同一玩家在同一逻辑游戏中的稳定身份；同游戏各端相同，不同游戏不同
角色 roleId	礼包与订单的发放目标，必须属于当前玩家及游戏

当前演示每个玩家、每款逻辑游戏只有一个内置角色。新应用批准后可初始化隔离的演示角色，不代表平台已支持任意外部区服、多角色或角色转服。把客户端的 roleId 换成外部角色号会被拒绝；应先实现可信角色绑定与游戏服务端履约。

每款应用可申请 1～4 个不同平台；iOS 新增或扩端都需要批准，不会自动加入既有演示应用。账号身份互通也不自动带来存档互通。游戏后端负责角色、区服、存档与实时连接。

授权码、平台会话与游戏会话

登录生成短期一次性 code，绑定目标 App ID 和 PKCE S256 challenge。SDK 保留随机 codeVerifier 并校验 state；游戏服务器携带对应密钥调用 /api/server/auth/exchange 完成兑换。

• 授权码有效期为 60 秒，成功兑换后不可再次使用。
• X-API-Key 只由可信游戏服务器发送，不能由浏览器、APK 或 iOS App 保存。
• 平台玩家会话用于 SDK 业务访问；游戏服务器另外建立自己的业务会话。
• 平台的退出、封禁和撤销不会自动推送到任意外部游戏，游戏方须补会话验证或同步机制。
• 玩家、开发者、管理员令牌不互换，不能把控制台令牌传给玩家接口。

新开发者应用不能使用演示快捷兑换 /api/demo/game/session。它仅服务于内置演示标识。

会话过期/撤销与账号限制都可能结束 SDK 身份。当前客户端将指定会话失效 401，以及 403 ACCOUNT_RESTRICTED / APP_UNAVAILABLE 作为终止信号；普通业务权限拒绝不等于退出。终止只影响对应请求的旧身份，不允许迟到响应清除后来登录的新账号。各端的候选存储和生命周期处理不同，应使用对应接入指南。

幂等与版本

requestId 表示一次业务意图。同一次下单、领取或管理提交的网络重试保留原标识；改变商品、角色、名称等内容时使用新的标识。相同标识配不同内容会返回冲突。

幂等只能防止同一操作重复处理，不代替权限校验或订单状态检查。已退款订单不能通过新支付请求再付款。version 用于发现并发编辑：提交基于当前版本，服务端接受后增加版本，旧版本应刷新确认。

钱包与订单

金额均使用整数最小单位。当前演示规则是 100 钱包单位 = 1 平台币 = 1 元；现金价格字段以分计。例如 amountCents: 600 表示 6 元，不能当作 600 元。

付费余额与赠送余额分开记录，消费先用赠送余额，退款按原扣款来源退回。钱包与会员在当前同一运营主体内共享；它不是跨厂商商户结算系统。

订单状态通常为 pending → fulfilled → refunded，内部付款确认阶段也有 paid；未支付可转为 closed。当前付款确认与演示发货由同一服务事务完成，因此客户端常直接看到 fulfilled。外部异步支付与发货不能假设同样立即完成。

优惠券在创建订单时锁定，成功支付核销，未付关闭或符合条件的退款释放；到期券仍不可再次使用。支付排查见订单与充值排查。