# 统一应用自动入驻与接入 API v3

每个独立后端配置火花地址，自动读取自身已有主体、应用资料、发行渠道和能力，发送申请；火花后台审核，后端自动查询结果，通过后按返回地址继续联调。无需人工填入驻表、邀请码、提前建档或复制密钥。

## 类别、渠道与能力

- `applicationCategoryCode` 是可配置的应用类别代码。初始配置包含两个类别，可在火花后台“接入设置 → 应用类别设置”增加或改名。新增类别选择已有接入能力，不修改接口枚举。
- `applicationChannelCode` 是后端提供的发行渠道代码，接受小写字母开头、后续小写字母/数字/下划线/短横线的1至64位字符串；`applicationChannelName` 是对应显示名称。它们不限定为已知平台，微信、TapTap、抖音或后续渠道使用同一套协议。
- `submission.capabilities` 描述当前后端真实采集能力；不因渠道名称自行推断登录、存档或奖励能力。支持新渠道的入驻不代表已实现该渠道登录SDK。
- 类别、发行渠道和操作系统不能靠同一个固定选项表推断。后端负责为当前应用提供真实值；火花后台按收到的数据展示渠道及生成筛选项。

## 独立后端自动运行

App在自身 `apps` 配置项中增加以下接入配置；游戏服务在自己的顶层配置中使用相同字段。`category` 的值来自火花类别配置，本例仅展示初始数据之一。

```json
{
  "enrollment": {
    "url": "https://platform.example.com/api/sdk/enrollments/applications",
    "category": "app",
    "profilePath": "data/application-profile.json"
  }
}
```

本地配置项enrollment.category只指定同步器的类别配置，HTTP正文和结果统一使用applicationCategoryCode；资料文件中的渠道使用applicationChannelCode/applicationChannelName。

`profilePath` 由业务后端从自身数据库或配置导出，不是让运营重新填写申请表。公共用户服务没有公司名称、应用介绍等业务资料，不能伪造这些内容。资料文件相对路径以服务配置文件所在目录解析。

后端启动即同步，此后每分钟查询；待审核或已通过时不重复申请，也不依赖资料文件持续可读。首次申请或驳回后的重提读取当前真实资料；同一份被驳回资料不会在火花生成新版本，修改后才重新待审。暂时失败保留申请身份并在下轮重试，错误不会被当成通过。

申请UUID及32字节随机凭据由后端生成并持久化。App保存到配置文件旁的 `data/huohua-app-enrollment-应用ID.json`；游戏保存到数据库目录的 `huohua-enrollment.json`。审核结果在同名 `.status.json` 文件中，包含真实 `sdkPath` 及完整 `sdkUrl`；SDK凭据从私有身份文件读取。状态文件须放在服务端私有目录并备份，不对前端或公网提供。该SDK凭据不等于现有玩家事件上报或广告回调签名密钥。

Node业务后端可调用游戏服务目录中的 `scripts/enrollment-client.mjs`：`syncEnrollment({platformUrl,statePath,applicationCategoryCode,applicationData})`，applicationData直接传入已有资料对象；不传applicationData则只查询。返回connection只供服务端使用。

## 唯一对外协议

请求使用HTTPS，申请凭据通过 `Authorization: Bearer <64位小写hex>` 发送；客户端禁止带凭据跟随跳转。本机回环测试地址可用HTTP。申请及联调正文限制64KiB。

| 操作 | 路径 |
| --- | --- |
| 自动提交申请 | POST /api/sdk/enrollments/applications |
| 查询申请结果 | GET /api/sdk/enrollments/applications/{applicationCategoryCode}/{externalApplicationId} |
| 查询接入状态 | GET /api/sdk/applications/{applicationCategoryCode}/{integratedApplicationId} |
| 更新应用与任务建议 | PUT 上一路径/submission |
| 读取任务清单 | GET 上一路径/manifest |
| 发送隔离联调事件 | POST 上一路径/trials |
| 查询联调事件 | GET 上一路径/trials/{eventId} |
| 重置未通过审核的联调 | DELETE 上一路径/trials |
| 查询正式处理回执 | GET 上一路径/receipts/{eventId} |
| 获取/分配用户ID前缀 | GET/PUT 上一路径/user-id-prefix |

自动申请的资料结构如下。externalApplicationId和applicationCategoryCode由后端同步器注入，其余内容来自业务数据：

```json
{
  "externalApplicationId": "后端自动生成的UUID",
  "applicationCategoryCode": "当前应用的类别代码",
  "subject": {"name": "已有合作主体", "contact": "已有联系方式"},
  "applicationChannelCode": "future_channel",
  "applicationChannelName": "当前发行渠道名称",
  "submission": {
    "name": "已有应用名称",
    "description": "已有应用介绍",
    "iconUrl": "https://assets.example.com/icon.png",
    "entryUrl": "https://app.example.com/entry",
    "serviceVersion": "1.0.0",
    "capabilities": [{"name":"finished","label":"业务完成","type":"boolean","unit":"","meaning":"真实服务端业务结果","trigger":"业务事务提交后"}],
    "tasks": [{"key":"finish","name":"完成业务","conditionType":"finished","conditionValue":1,"bountyRewardAmountFen":100,"maxParticipants":20}]
  }
}
```

联调事件统一使用 `userId`、`eventId`、`manifestVersion`、`data`。任务奖励以分为单位；接收资料不自动启用奖励。

## 火花后台审核与边界

申请直接显示在“自建游戏库”或“自建App库”；类别配置决定归库，后端上报发行渠道。两个库只保留“待审核、启用中、已下线”，默认待审核，无“全部”和手工新增。申请、资料审核、任务审核及联调在同一记录详情中完成；“接入设置”仅管理类别，不另设申请审核列表。微信拉取游戏库独立管理。

- 待审核：首次申请、驳回待后端补正、初审通过后的任务审核/联调和待最终审核。初审通过不代表已启用。
- 启用中：当前资料、任务及联调完成最终审核，档案已启用。
- 已下线：曾完成接入审核的档案被管理员下线。后端重复上报不自动恢复；重新启用需验证当前审核版本并由管理员操作。

主体及来源资料由后端发送，管理员只读核对；运营海报、二维码、推广链接可单独维护。旧档案没有可信申请关联时只读展示“历史来源待核对”，不按名称或AppID猜测归并，不伪造申请。列表和详情不返回后端凭据。

火花后台显示资料、渠道、能力和历史审核，选择通过或填写原因驳回。通过自动创建禁用档案并关联原申请凭据，随后审核任务建议、校验真实的达标/未达标联调案例，最终审核启用。重复提交、通知丢失后的查询、重复或并发审核不会重复建档或发奖。类别与UUID组成独立命名空间，凭据不能跨应用或类别使用；有申请的类别不能删除或改绑处理方式。

发行渠道筛选使用当前申请资料，不会错误匹配审核历史里的旧渠道。每类别每小时最多100个首次申请；同申请重试不新增记录。

这次直接切换到v3。旧的游戏/App申请及SDK公共路由、旧字段别名均已移除；原后端持久身份和凭据继续保留；字段切换不得重建身份。历史账务及奖励不删除。相关后端需要一同构建部署，不能把未更新的旧下载包当作已支持v3。

数据库除类别迁移外，还需应用20261027000100、20261027000200两项来源关联迁移；既有已审核任务合同按部署说明执行只读核查及受控元数据转换。接入方案、身份及数据源均可在本机验证，本次未向生产平台申请或部署。

HTTP申请结果使用enrollmentStatus、enrollmentRevision和externalApplicationId；火花档案使用integratedApplicationId（UUID）。任务清单使用bountyTaskId、bountyTaskStatus、bountyRewardAmountFen；联调结果使用bountyTaskId。正式事件、签名和历史财务幂等键的既有业务含义保留。

测评只引用微信拉取游戏的wechatCatalogGameId及reviewTaskId。上述自动入驻、赏金任务、事件和礼包码接口只服务接入应用；不做两库关联、查重或转换。