应用接入流程
本文介绍如何为产品接入 GoodVision 登录，再按需增加 API、事件和商业能力。仅接登录时，创建应用、填写回调并复制配置、验证登录三个步骤即可开始联调。
接入前准备
登录当前环境的开发者后台。首次没有企业的账号会自动准备个人空间，可在其中创建应用；创建者自动成为该应用所有者，无需先配置业务角色。协作已有企业的应用时，再加入该企业并取得对应应用权限。准备产品名称和应用实际实现的登录回调，例如 https://app.example.test/auth/callback。
一个独立产品、一个环境对应一个应用（Application）。同一产品的用户登录与后台调用使用同一应用中的两种身份；Sandbox 与 Production 分开。多个产品如何关联用户，请参见多应用、用户与事件接入。
仅接入用户登录（3 步）
第 1 步：创建应用
在应用中心填写应用名称并创建，默认使用 Sandbox，应用代码自动生成；需要自定义代码时再展开高级设置。保存后在凭证页核对环境和接入状态。自动配置成功时状态为 active；依赖失败时按提示恢复原请求，不重复创建。
第 2 步：填写回调并复制配置
进入“开发接入 → OAuth/OIDC 配置 → 用户身份”，确认用户身份已启用，填写精确的登录回调。平台生成并校验当前应用的登录配置，保存后复制非敏感配置。
| 配置 | 必填性 | 说明 |
|---|---|---|
| 登录回调（Callback URL） | 🔴 必填 | 精确填写应用已实现的授权码接收路由 |
| 退出地址（Logout URL） | 可选 | 核对自动建议值；不需要退出后跳转时可不配置 |
| 网站来源（Web Origin） | 可选 | 仅协议、主机和端口；需要浏览器跨来源请求时配置 |
| Issuer、Client ID | 平台提供 | 接入必需，从当前应用复制 |
| Client Secret | 用户身份不需要 | 后台应用身份调用时必需 |
例如，回调为 https://app.example.test/auth/callback 时，网站来源为 https://app.example.test，退出后可返回 https://app.example.test/。产品访问地址和登录回调用途不同。
第 3 步：实现回调并验证登录
应用服务端实现授权码 + PKCE、回调核验和自己的会话。确认精确回调成功、会话可刷新及退出，并验证错误 Token 和错应用被拒绝。具体操作见认证与授权。
登录后调用用户与客户空间，首次发送 {}。平台自动准备或复用个人空间，返回当前用户、空间与成员；开发者不用填写 Group 或固定客户企业 ID。暂不可用时保留登录并提供重新读取入口。
仅接登录不要求业务 API Subscription、Webhook 或订阅套餐。登录和成员关系不会授予付费权益或产品权限。
按需增加 API 能力（可选）
后台任务使用应用身份，用户登录后的操作使用用户身份。两种身份分别使用独立的 OAuth Client、Scope 和 API 调用授权，详见接入入口与权限。
- 进入当前应用的“API 与权限”，确认调用身份。
- 选择产品实际使用的 API 和最小权限（Scope）。不要手工拼接产品未公开的权限。
- 保存配置，平台自动校验归属、身份与权限；成功后直接启用，无需人工审核。
- 使用当前 API 产品提供的 Base URL 调用一个只读接口，验证 Token、Audience、Scope 和客户范围的正向及拒绝路径。
仅应用身份需要 Client Secret。应用 Owner 可按“凭证与基础信息”中的当前状态即时查看或轮换，也可能通过受控渠道交付。Secret 只保存在服务端，不进入普通配置导出、日志或缓存。源码、内部域名和示例占位路径不能作为调用地址。
接收业务事件（可选）
没有使用事件的应用无需配置接收方式。需要事件时，进入“开发接入 → 事件与 Webhook”，选择实际消费的事件并保存。
| 接收方式 | 所需配置 | 下一步 |
|---|---|---|
| 长连接（推荐） | 当前应用的应用身份、Client Secret 和事件集合；无需公网接收地址 | 运行Node.js 22 示例，处理后 ACK |
| HTTPS Webhook | 公网 HTTPS 地址、地址校验和接收端签名配置 | 按接收 Webhook验签、持久接收并返回 2xx |
| 同步回调（按需） | 独立回调集合、已验证 HTTPS 地址、结构化响应 | 按同步回调在 5 秒内返回结果；不自动重试 |
两种异步接收方式都要核对应用、环境与客户范围，按 event_id 去重并处理资源版本，验证断线、超时和重复投递。测试入队不表示接收成功；继续查看投递日志和接收端处理结果。
订阅用应用、环境、客户空间与 subscription ID 关联；成员事件按 membership_id 关联。完整说明见多应用、用户与事件接入。
接入订阅与支付（可选）
需要通过平台收费时，再配置接入能力、发布套餐和购买入口。登录配置、API 调用权限、商业可售状态及客户权益分别核验。具体步骤见第三方 SaaS 计费。
Sandbox 验收清单
| 检查项 | 预期结果 |
|---|---|
| 应用与环境 | 所选能力属于正确开发者、应用和环境；未选择能力不是登录前置 |
| 登录 | 精确回调、刷新和退出成功；用户身份不要求 Secret |
| 用户与空间 | 首次准备、并发与重登复用；失效选择不静默切换，503 可恢复 |
| 已选 API | Audience、Scope、客户范围和资源权限均有正向与负向测试 |
| 已选事件 | 验签、范围、去重、乱序、持久 ACK 和故障恢复通过 |
| 写命令与凭据 | 稳定的 Idempotency-Key；日志、工单和邮件没有 Token 或 Secret |
准备 Production 与上线
- 按需完成 Sandbox 开发和适用测试，明确记录测试结果；平台配置校验不替代实际应用联调。
- 在“开发接入 → Sandbox 与上线”创建独立的 Production 配置。无需等待 Sandbox 当前验收通过；创建不代表正式可用。凭据、用户同意、业务数据和审核结论不会跨环境复制。
- 配置 Production 所需的登录、API、事件、资料和可用范围。进入“应用管理 → 版本管理与发布”，保存版本草稿并填写本次测试证据引用。
- 显式提交上线审核。独立审核人员统一核对本版本，申请人不能自审；退回后修改配置并创建新版本。
- 审核通过后显式发布获批版本。发布重核验资源和当前权限，成功后统一更新正式入口；新草稿和审核过程保留旧正式版本。
仅开发测试的应用无需上架市场。正式上线适用于定向自用、定向客户和公开分发的实际范围。商业价格、付款和客户权益仍遵守各自授权规则。
结果未知时只恢复原操作；版本冲突时先回读当前版本和正式状态。登录恢复不会自动提交或发布。详见应用版本。