真实支付与生产接入边界

本页是商用接入计划，不是已可调用的接口清单。当前 NODE_ENV=production 会在启动时抛出 PRODUCTION_NOT_READY 并阻止服务运行。直接删除该保护不能补齐支付、实名、外部发货及运维能力。

已实现与仍需接通

领域	本版已有	商用前需完成
登录	授权码、PKCE、服务端兑换、会话失效与应用审批	实际游戏服账号映射、正式域名与可靠部署
短信与实名	本地流程演示	合约供应商、正式身份核验与相应业务规则
支付	本地演示确认、订单快照、事务与幂等	合法商户通道、签名回调、主动查单、渠道对账
发货	本地模拟钻石、月卡与钱包变更	外部游戏服订单投递、幂等发货及失败补偿
退款	本地资产回退与余额回退	渠道退款、异步结果、真实资产回收与差错流程
平台币	单运营主体共享钱包与两类余额流水	资金与赠币规则、真实收款对账；独立商户结算另行设计

推荐落地顺序

1. 确认主体、渠道与商品规则

先明确运营主体、收款主体、游戏归属及 Android 分发渠道。渠道包应按渠道支付与账号接入要求实现适配，不能假定所有 Android 包都能使用同一外部支付方式。确定平台币适用游戏、付费币与赠币扣减顺序、有效期、退款和客服规则，展示在用户购买流程中。

若计划支持独立游戏商户或用户间转账、提现，不应直接沿用当前共享钱包模型，需要先完成商户与资金责任设计。本版没有这些接口。

2. 接入一个正式支付通道

新增服务端支付适配层，输出渠道下单参数；客户端只负责拉起支付和展示查询结果。渠道密钥与证书保存在服务端受控配置。创建订单时固定商户、币种、金额、商品、App ID 与目标角色，回调时逐一比对。

支付结果须通过渠道官方要求验签、检查通知标识、防重放并持久化后处理。客户端“支付成功”回调不能直接把订单改为已付款。渠道请求超时应主动查单；收到重复、乱序或延迟通知必须能收敛到同一个订单状态。

3. 接入实际游戏服发货

将支付确认与外部履约解耦。推荐支付事务内写入待发货事件，再由可重试任务投递；外部游戏服以平台订单号建立唯一发货记录，并校验签名、游戏、角色、区服与商品映射。只有游戏服明确确认成功后才标记履约完成。

重试需要指数退避、次数上限、人工补单队列与可追踪记录。补单复用原订单号，不能新造订单绕过幂等。发货接口、事件协议与回执状态在本版尚未定义为公开契约，联调前需双方确认并版本化。

4. 补齐退款与日常对账

引入退款申请、处理中、成功和失败等独立状态，保留原订单及渠道退款号。先核实游戏资产是否可回收，再协调退款；渠道受理不等于资金已退回。跨系统失败应进入可见的人工处理队列。

每日核对渠道收款、平台订单、游戏服发货与钱包流水，覆盖已付未发、已发未记账、渠道成功平台未知、退款结果不一致等差错。对账差异应留存原因、处理人和补偿记录。

5. 灰度发布

以一个逻辑游戏、一个渠道、小范围用户完成联调。正式域名使用 HTTPS，限制跨域来源，验证密钥轮换、会话吊销、日志脱敏、备份恢复、告警与容量。评估数据库并发与部署方式后再扩大游戏数量；不能把当前本地 SQLite 部署直接承诺为大规模多副本服务。

商用验收证据

上线评审应能出示以下实际记录，而不是仅有演示截图：

1. 支付沙箱与正式小额交易的下单、渠道凭证、验签和查单记录。
2. 重复回调、错误金额、错误商户、超时和乱序回调不会重复入账的测试结果。
3. 游戏服停机后恢复可自动补发；重复投递不重复发货的联调结果。
4. 可退款、资产已消费、部分系统失败等场景的退款与差错处理记录。
5. 渠道账单与平台流水对齐、数据库恢复演练、生产密钥和告警责任人的确认。

本页不提供虚构支付回调 URL 或可直接启用生产的配置。完成上述适配后，应扩展公开 API 契约及自动化回归，再调整生产启动保护。

实现依据

• packages/server/src/platform.ts：演示支付与本地履约路径。
• packages/server/src/app.ts：启动阶段生产保护；当前路由尚无真实支付回调及外部发货回执。
• examples/game-server.mjs：仅演示身份兑换，未实现实际游戏资产发货。