# App后端自动接入协议

先读[统一应用自动入驻](统一应用自动入驻.md)。每个独立后端自动发送自身已有资料，由火花后台审核；类别和渠道不使用固定枚举。新接口统一到 /api/sdk/applications/{category}/{applicationId}，不保留旧公共入口或字段别名。

## 自动执行顺序

1. 配置统一申请地址、当前应用类别和后端资料源。同步器自动生成并保存申请UUID及凭据，发送申请并查询反馈。不能要求用户手填入驻表、领邀请码、提前建档或复制令牌。
2. 审核通过后读取本机私有审核结果及sdkPath。通过统一user-id-prefix接口取得平台分配前缀，再写入受控运行配置；台账未初始化时报告平台配置问题，不能猜测前缀或调用管理员接口。
3. 使用entryUrl、serviceVersion、capabilities和tasks提交真实资料，读取批准后的manifest，按真实字段及业务口径实现采集。
4. 用userId提交每项任务有效的达标与未达标案例，错误类型不能代替未达标覆盖。按60秒查询审核，等待不是批准。
5. 验证真实运行链路及正式处理回执。sandbox不证明第三方认证、权益发放或奖励支付。最终审核通过才启用应用和已批准任务。

运行接口和入驻/联调接口的凭据独立，前端只调用自己的业务后端。登录、会话和权益规则仍按对应模块文档执行；发行渠道可扩展不代表自动增加新的登录实现。

## App 业务接入

- 默认由公共服务封装登录名与密码注册登录，生成统一公式 appUserId；App后端代理 /auth/register、/auth/login、/auth/change-password。字段、限流及前缀分配见《登录名密码与统一用户ID.md》。
- 不增加用户名、昵称、邮箱、手机号。不同App账号独立；以当前App登录名密码认证方式创建/绑定公共ID，不能直传外部主体或任意appUserId创建会话。
- 前端只请求 App 自己的业务后端，运行凭据不能下发前端。运行会话不等于付费会员权益。
- App 后端向 promotion-claims 提交 code/appUserId/idempotencyKey。服务端记录 firstValidAt，并立即持久排队首次有效事实；这与任务是否完成独立。
- App 若有附带权益，在自己的数据库以 claimId 唯一约束，和实际权益变更同一事务提交，然后 confirm。无附带权益也 confirm，之后才接收可信业务进度。确认超时先查询，不能创建新发放单绕过幂等。
- 每次真实业务事务完成后，用稳定 eventId 提交 schemaVersion=1、occurredAt、data、fieldLabels。公共服务自行关联推广码；不允许 App 进度接口伪造 redeemedAt。App 自己也需要持久 outbox，以覆盖公共服务不可用期间。
- 同ID同内容重试幂等；同ID不同正文409。401停止检查凭据；403停用；409查询当前记录；429退避；5xx和超时保留原业务ID重试。不要自动重试未知结果的非幂等业务发放。

## 当前能力与边界

当前包括登录名密码注册登录、改密、统一用户ID、当前password认证及底层登录身份管理、会话、推广关系、权益确认状态和可信事件；云同步、会员钱包、支付、订阅、排行榜未实现，不能把它们写进已支持能力。当前App不启用第三方登录，底层小游戏换码适配不属于App接入方案。

App 工程不引用游戏 internal 包，不安装游戏 SDK；App 公开路径、运行配置和数据均独立。底层平台兼容适配里仍使用历史 players/playerId 等字段，由 App 程序内部转换；游戏接口不是 App 新接入入口。

## 0.3.0账号状态与权益广告

接入前读取[账号状态与公共权益广告](账号状态与公共权益广告.md)。账号注销、禁用/恢复和全部会话撤销已提供；广告与礼包按受控配置直接发入公共权益字段，App通过预留/确认/取消消费。管理及广告回调使用独立managementTokenEnv；普通运行令牌不具备该权限。穿山甲与腾讯优量汇直连均已适配；优量汇须配置独立密钥、networkAppId与adUnitId，真实渠道仍需逐App验收。

## 0.4.0广告流程

广告按SDK完成通知先发奖，后台异步验真；正常和异常数据均发送火花，由广告数据核查页面人工处理。接入必读[广告先发奖异步验真与火花核查](广告先发奖异步验真与火花核查.md)。不自动追回、不自动封禁，广告上报不自动触发赏金结算。


当前认证权威说明为[平台与登录方式](平台与登录方式.md)。users/resolve和任意appUserId创建会话的入口已移除，不能用自报外部主体代替认证。当前App只使用password，完整固定矩阵见[应用类型与登录规则](应用类型与登录规则.md)。