存量数据同步流程
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 任务目标
- 接口层面:平台应用(APP)开放基于 OAuth 2.0 授权码模式 的标准授权接口,及厂商/游戏数据拉取接口,供 SUD OpenPaaS 平台合规调用;
- 数据层面:SUD 通过 OAuth 2.0 授权流程获得厂商许可后,安全拉取平台应用(APP)侧对应开发者的全量存量数据,包含:
- 游戏厂商(开发者)基础信息、KYC 资质信息;
- 游戏列表(含游戏唯一标识、名称、图标等基础信息);
- 单游戏详情(含图标集、描述、宣传视频/图片等运营信息);
- 游戏 KYC 资质信息(含软著、版号、三方授权等合规信息);
- 游戏 ICP 备案信息(主办方、负责人、前置审批及补充材料等);
- 业务层面:完成 SUD OpenPaaS 平台与平台应用(APP)平台的开发者账号映射,实现存量游戏数据的自动化同步,支撑厂商在 SUD OpenPaaS 平台的一站式运营。
若希望结合真实落地实现理解本流程,可参考示例章节:Hello OP 对接 SUD OpenPaaS 示例。
2. 参与角色
┌────────────────┐ ┌───────────────────────┐ ┌────────────────────┐
│ 用户浏览器 │ │ SUD OpenPaaS │ │ 平台应用(APP) │
│ (User Agent) │ │ OAuth2 Client │ │ AS + RS │
└────────────────┘ └───────────────────────┘ └────────────────────┘| 角色 | 身份 | 说明 |
|---|---|---|
| 游戏厂商(用户) | 自然人 / 企业管理员 | 同时拥有平台应用(APP)开发者账号与 SUD OpenPaaS 厂商账号 |
| SUD OpenPaaS | OAuth2 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):
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 回调地址:
{redirect_uri}?code={AUTHORIZATION_CODE}&state={state}SUD 必须:
- 校验
state与发起授权时一致,防止 CSRF; - 由服务端调用 oauth.accessToken,使用
authorization_code换取令牌; - 保存
access_token、refresh_token;从 Token 身份声明(如uid)或随后调用的 cp.queryDetail 取得主体id,与当前 SUD 厂商账号建立映射。
换码必须在服务端完成,client_secret 不得下发到浏览器。
4.4 阶段三:存量数据自动化拉取
SUD 凭借有效且未过期的 access_token,建议按以下顺序拉取:
- cp.queryDetail — 厂商基础信息
- cp.queryKYC — 厂商 KYC
- game.queryList — 游戏列表(分页)
- 对列表中每个游戏依次调用:
拉取结果经清洗后写入 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. 关键安全设计
| 安全点 | 机制 | 说明 |
|---|---|---|
| 密码不经过 SUD | Authorization Code 流程 | 用户仅在 APP 页面输入密码,SUD 只拿到 code |
redirect_uri 白名单 | Client 注册时固化 | 回调地址必须与注册值完全一致,防止码被发到恶意地址 |
| 授权码一次性且短时有效 | OAuth 标准机制 | code 使用后即失效,建议有效期不超过数分钟 |
client_secret 保护 | 仅服务端换码 | 换 Token 在 SUD 后端完成,不暴露给浏览器 |
state 防 CSRF | SUD 生成并回校验 | 确保回调对应本次用户发起的授权 |
| Token 身份隔离 | Token 绑定厂商身份 | 仅允许访问被授权厂商自身的数据,禁止用应用级凭证越权拉取 |
| 按应用吊销 | revoke(如支持) | 解绑时可单独吊销该 Client 下 Token,不影响厂商在 APP 的其他登录态 |
7. 涉及接口清单
在上述同步流程中,需平台应用(APP)实现并提供以下 Webhook 接口(详见 开放接口):
7.1 授权与鉴权类(OAuth 2.0)
| 步骤 | 接口 | 说明 |
|---|---|---|
| 1 | oauth.authorize | 发起授权,浏览器侧获取授权码 |
| 2 | oauth.accessToken | 用授权码换取 access_token / refresh_token |
| 3 | oauth.refreshToken | 刷新 access_token |
7.2 存量业务数据拉取类
| 步骤 | 接口 | 说明 |
|---|---|---|
| 4 | cp.queryDetail | 查询开发者/厂商详情 |
| 5 | cp.queryKYC | 查询开发者 KYC |
| 6 | game.queryList | 查询游戏列表 |
| 7 | game.queryDetail | 查询单游戏详情 |
| 8 | game.queryKYC | 查询单游戏 KYC |
| 9 | game.queryICP | 查询单游戏 ICP 备案 |
