简述

说明

1. client_id / client_secret：由 SView 实施人员提供，OAuth 鉴权凭证。
2. tenant‑id 租户 ID：由 SView 实施人员提供，区分企业租户。
3. integrationId：集成开发方业务系统内用户、部门的唯一编码，同步到 SView 系统后，后续绝大多数业务都依靠该字段做数据关联。

1. 两种 Token 获取模式
   • 客户端模式 (client_credentials)：用于集成开发方同步组织架构、部门、员工账号；无具体用户上下文，不能操作文件、项目。
   • 个人身份模式 (mobile 模式)：拼接格式INTEGRATION@{integrationId}获取 Token；代表某一个具体 SView 用户执行操作，适用于文件上传、预览、项目操作、读取站内信等业务。
2. Token 生命周期管理
   • access_token：业务访问凭证，有效期为返回的 expires_in 秒；建议提前 10% 有效期时长使用 refresh_token 刷新令牌，避免运行中令牌突然失效。
   • refresh_token：刷新 access_token 凭证，有效期远长于 access_token；refresh_token 过期后，必须重新执行个人身份登录获取全新令牌。
   • 调试 / 运行期可调用/auth/token/check_token接口校验 access_token 有效性，获取签发、过期时间。
3. 公共 Header 注意事项
   • deviceModel 字段必须进行 UrlEncode 编码，直接传原始值会引发接口异常；
   • 除获取上传链接接口，全部接口必须携带这套请求头。集成开发方通用最佳实践

Token 处理逻辑

1. 客户端 Token（组织同步）：全局缓存，定时提前刷新；
2. 用户个人 Token：每个用户维度缓存 access_token、refresh_token、expires_in；
3. 不要等待 access_token 完全过期再刷新；提前expires_in * 0.1时间调用grant_type=refresh_token接口刷新令牌；
4. 业务接口收到 HTTP401，优先执行刷新令牌；刷新失败，重新走 mobile 模式登录；
5. 调试环境可频繁调用 check_token 接口校验令牌；生产环境减少调用频率。

业务接口成功判定标准（所有接口统一）

1. HTTP 响应状态码为 2xx；
2. 返回 JSON 中 code == 0 && ok == true；

⚠️即使 HTTP200，只要 code 不等于 0，全部视为业务失败，读取 msg 字段排查错误原因。

WebSocket 通用规范

1. http 网关用 ws://，https 网关必须切换 wss://；
2. 任何 command 消息只要 status=failed，直接终止任务，关闭 socket；
3. 业务拿到最终结果之后，代码主动关闭 WebSocket 连接，避免连接泄漏。

关键字段区分对照表（集成开发方高频混淆）