Skip to content

存量数据同步流程 ​

1. 业务场景&任务目标 ​

1.1 背景说明 ​

游戏厂商(CP) 在 平台应用(APP) 原有游戏运营平台沉淀了大量厂商资质、游戏信息、合规资质等存量数据。为了让游戏厂商在 SUD OpenPaaS 平台开展平台应用(APP)游戏业务时更便捷,无需重新录入所有历史游戏信息,我们通过标准化的接口授权与数据拉取机制,实现存量数据的自动化、安全化同步,既降低厂商人工操作成本,也保障数据同步的准确性与合规性。

1.2 业务场景 ​

平台应用(APP)游戏存量业务迁移至 SUD OpenPaaS 平台 过程中,核心场景为:

  • 游戏厂商首次入驻 SUD OpenPaaS 平台时,需通过 OAuth 2.0 与平台应用(APP)发起账号关联申请,并收到厂商的授权许可;
  • 授权通过后,SUD OpenPaaS 平台自动拉取平台应用(APP)侧该厂商的全量存量数据,完成从「平台应用(APP)原有平台」到「SUD OpenPaaS 平台」的无感知数据迁移;
  • 迁移完成后,厂商可在 SUD OpenPaaS 平台统一管理游戏的厂商信息、游戏信息及合规资质,无需重复维护。

1.3 任务目标 ​

  1. 接口层面:平台应用(APP)开放基于 OAuth 2.0 授权码模式 的标准授权接口,及厂商/游戏数据拉取接口,供 SUD OpenPaaS 平台合规调用;
  2. 数据层面:SUD 通过 OAuth 2.0 授权流程获得厂商许可后,安全拉取平台应用(APP)侧对应开发者的全量存量数据,包含:
    • 游戏厂商(开发者)基础信息、KYC 资质信息;
    • 游戏列表(含游戏唯一标识、名称、图标等基础信息);
    • 单游戏详情(含图标集、描述、宣传视频/图片等运营信息);
    • 游戏 KYC 资质信息(含软著、版号、三方授权等合规信息);
    • 游戏 ICP 备案信息(主办方、负责人、前置审批及补充材料等);
  3. 业务层面:完成 SUD OpenPaaS 平台与平台应用(APP)平台的开发者账号映射,实现存量游戏数据的自动化同步,支撑厂商在 SUD OpenPaaS 平台的一站式运营。

若希望结合真实落地实现理解本流程,可参考示例章节:Hello OP 对接 SUD OpenPaaS 示例。


2. 参与角色 ​

text
┌────────────────┐     ┌───────────────────────┐     ┌────────────────────┐
│   用户浏览器    │     │  SUD OpenPaaS          │     │ 平台应用(APP)     │
│   (User Agent) │     │  OAuth2 Client         │     │ AS + RS             │
└────────────────┘     └───────────────────────┘     └────────────────────┘
角色身份说明
游戏厂商(用户)自然人 / 企业管理员同时拥有平台应用(APP)开发者账号与 SUD OpenPaaS 厂商账号
SUD OpenPaaSOAuth2 Client持有 client_id + client_secret,在获得厂商授权后代表该厂商调用 APP 侧数据接口
平台应用(APP)Authorization Server + Resource Server颁发 Token,并提供厂商/游戏存量数据拉取接口

关键原则:

  • 厂商密码只在 APP 侧登录页输入,不经过 SUD OpenPaaS;
  • SUD 仅拿到一次性授权码 code,再由服务端用 client_secret 换取 Token;
  • 后续数据拉取一律携带 Authorization: Bearer {access_token},且 Token 需能标识出被授权的厂商身份(如 cp_id / uid)。

3. 业务流程总览 ​

3.1 业务流程图 ​

3.2 分阶段说明 ​

阶段名称触发时机说明
阶段零Client 注册(一次性)APP / SUD 上线前在 APP 侧将 SUD 注册为 OAuth2 Client,获得并妥善保管 client_id / client_secret
阶段一用户授权(Authorization Code)每个厂商首次绑定浏览器跳转 APP 登录/授权页,用户确认后回调 code
阶段二换取令牌拿到 code 后SUD 服务端用 code + client_secret 换 access_token / refresh_token;厂商标识从 Token 声明或 cp.queryDetail 取得
阶段三存量数据拉取令牌有效期内按约定顺序调用厂商/游戏数据接口,完成入库与账号映射
阶段四Token 续签 / 解绑令牌过期或解绑时refresh_token 刷新;解绑时可吊销 Token 并清除映射

4. 业务流程说明 ​

4.1 阶段零:SUD 注册为 OAuth2 Client(一次性) ​

平台应用(APP)需支持将 SUD OpenPaaS 注册为可信第三方应用(OAuth2 Client),至少配置:

  • client_id / client_secret
  • 回调地址白名单 redirect_uri(须与后续授权请求完全一致)
  • 授权范围 scope(仅覆盖存量数据拉取所需权限)
  • 授权类型:至少支持 authorization_code、refresh_token

该步骤只做一次。后续所有厂商的绑定操作都复用同一对 Client 凭证。

4.2 阶段一:入驻与授权发起 ​

游戏厂商在 SUD OpenPaaS 平台完成基础入驻后,发起「同步存量游戏数据 / 绑定 APP 开发者账号」。SUD 拼接 OAuth 2.0 授权参数,通过浏览器 302 重定向 至 APP 授权入口(对应 oauth.authorize):

text
GET {authorize_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={sud_callback}
  &scope={scopes}
  &state={random_state}

若用户尚未登录 APP,则 APP 应先引导至自有登录页完成身份核验(账号密码、短信等,由 APP 自有逻辑实现),再进入授权确认。

注意: 授权页必须在 APP 域名下展示。厂商密码、会话 Cookie 对 SUD 不可见;SUD 只应在最终回调中收到 code 与 state。

4.3 阶段二:授权码回调与令牌换取 ​

用户确认授权后,APP 将浏览器重定向回 SUD 回调地址:

json
{redirect_uri}?code={AUTHORIZATION_CODE}&state={state}

SUD 必须:

  1. 校验 state 与发起授权时一致,防止 CSRF;
  2. 由服务端调用 oauth.accessToken,使用 authorization_code 换取令牌;
  3. 保存 access_token、refresh_token;从 Token 身份声明(如 uid)或随后调用的 cp.queryDetail 取得主体 id,与当前 SUD 厂商账号建立映射。

换码必须在服务端完成,client_secret 不得下发到浏览器。

4.4 阶段三:存量数据自动化拉取 ​

SUD 凭借有效且未过期的 access_token,建议按以下顺序拉取:

  1. cp.queryDetail — 厂商基础信息
  2. cp.queryKYC — 厂商 KYC
  3. game.queryList — 游戏列表(分页)
  4. 对列表中每个游戏依次调用:

拉取结果经清洗后写入 SUD OpenPaaS,并向厂商展示迁移结果。

4.5 阶段四:账号映射落地与 Token 续签 ​

  • 账号映射: cp_id(APP 侧厂商标识)与 SUD 侧厂商账号一一绑定,作为后续增量同步与计费关联依据。
  • Token 续签: access_token 过期后,调用 oauth.refreshToken 刷新;若 refresh_token 亦过期,引导厂商重新授权。
  • 解绑: 建议支持吊销 Token,并清除账号映射与缓存的令牌。

4.6 异常场景处理 ​

场景处理建议
授权失败 / 用户拒绝提示「授权失败」,引导重新发起授权
state 不一致终止流程,提示可能存在安全风险,要求重新授权
access_token 过期自动使用 refresh_token 刷新后重试业务请求
refresh_token 过期提示「授权已过期」,引导重新完成 APP 授权
部分游戏/资质缺失标注缺失项,引导厂商核对 APP 原平台数据或联系 APP 运营

5. 接口调用时序图 ​


6. 关键安全设计 ​

安全点机制说明
密码不经过 SUDAuthorization Code 流程用户仅在 APP 页面输入密码,SUD 只拿到 code
redirect_uri 白名单Client 注册时固化回调地址必须与注册值完全一致,防止码被发到恶意地址
授权码一次性且短时有效OAuth 标准机制code 使用后即失效,建议有效期不超过数分钟
client_secret 保护仅服务端换码换 Token 在 SUD 后端完成,不暴露给浏览器
state 防 CSRFSUD 生成并回校验确保回调对应本次用户发起的授权
Token 身份隔离Token 绑定厂商身份仅允许访问被授权厂商自身的数据,禁止用应用级凭证越权拉取
按应用吊销revoke(如支持)解绑时可单独吊销该 Client 下 Token,不影响厂商在 APP 的其他登录态

7. 涉及接口清单 ​

在上述同步流程中,需平台应用(APP)实现并提供以下 Webhook 接口(详见 开放接口):

7.1 授权与鉴权类(OAuth 2.0) ​

步骤接口说明
1oauth.authorize发起授权,浏览器侧获取授权码
2oauth.accessToken用授权码换取 access_token / refresh_token
3oauth.refreshToken刷新 access_token

7.2 存量业务数据拉取类 ​

步骤接口说明
4cp.queryDetail查询开发者/厂商详情
5cp.queryKYC查询开发者 KYC
6game.queryList查询游戏列表
7game.queryDetail查询单游戏详情
8game.queryKYC查询单游戏 KYC
9game.queryICP查询单游戏 ICP 备案