iflow-engine-base

BIM Engine SDK for Vue2, Vue3, React and HTML

Installation

npm install iflow-engine-base

Usage

Import the SDK

import { createEngine } from 'iflow-engine-base';
// CSS文件会自动引入，无需手动导入

Create Engine Instance

const engine = createEngine({
  container: document.getElementById('app'),
  sdkAuth: {
    endpoint: 'https://api.example.com/openapi',
    token: 'sdk_token_xxx'
  },
  // ... other options
});

sdkAuth 现在是必填项。不传时，SDK 会直接拒绝初始化。

推荐生产环境由你自己的后端先使用 AppId/AppKey/AppSecret 调用 POST /openapi/oauth/sdk-token，再把短期 sdkToken 下发给浏览器。开发联调时也可以直接给 sdkAuth.appId/appKey/appSecret，但不建议在公网前端长期暴露 AppSecret。

sdkAuth.appId/appKey/appSecret 认证方式说明

当你这样传参时：

const engine = await createEngine({
  containerId: 'viewer',
  sdkAuth: {
    endpoint: 'https://api.example.com/openapi',
    appId: 'app_xxx',
    appKey: 'key_xxx',
    appSecret: 'sk_xxx'
  }
});

SDK 内部会自动执行两步：

1. 调用 POST /openapi/oauth/sdk-token/secure SDK 先使用 appSecret 计算密钥材料，再结合当前 UTC 年月日、时间戳、nonce 派生当日密钥，对 appKey/appSecret 做 AES-GCM 加密后发给服务端
2. 调用 POST /openapi/oauth/sdk-verify 使用上一步返回的 sdkToken 做二次校验，校验通过后才继续初始化引擎

服务端收到后，会：

1. 按明文 appId 找到应用
2. 读取平台保存的安全密钥材料
3. 按同一天的日期重新派生密钥并解密
4. 解密出 appKey/appSecret 后，再走原有的应用凭证校验
5. 校验通过才签发短期 sdkToken

也就是说，sdkAuth.appId/appKey/appSecret 本质上仍然是“SDK 代替你的服务端去换票”，但传输时不再直接明文发送 appKey/appSecret。

补充说明：

• appId 仍然会明文发送，因为服务端必须先知道是哪个应用，才能取出对应的安全材料解密
• 当前年月日已经参与密钥派生
• 同时还加入了时间戳和 nonce，避免“只有日期、整天可重放”的问题
• 老应用如果是在这套安全方案上线前创建的，需要先在控制台重置一次 AppSecret，让平台补齐安全密钥材料后才能使用该模式

适用场景：

• 本地开发
• 内网环境联调
• 受控测试环境

不建议用于公网生产前端，原因是：

• AppSecret 会下发到浏览器
• 用户可以在 DevTools、抓包工具或源码中拿到密钥
• 一旦泄露，第三方可以伪造你的应用去申请新的 sdkToken

生产环境推荐方式：

1. 你的业务后端安全保存 AppId/AppKey/AppSecret
2. 业务后端调用 POST /openapi/oauth/sdk-token
3. 业务后端把短期 sdkToken 返回给前端
4. 前端 SDK 只传 sdkAuth.token

这样浏览器侧永远不会接触 AppSecret，安全边界才是正确的。

权限与校验结果

• 运营后台现在只给团队成员配置引擎权限，如 3d、2d、720、gis、gaussian
• OpenAPI 在签发 sdkToken，以及后续执行 sdk-verify 时，都会重新计算当前有效权限：
  • effectiveScopes = 应用 scopes
  • effectiveEnginePermissions = 成员引擎权限
• 这意味着：
  • 去掉成员的某个引擎权限后，即使 appKey/appSecret 正确，也不能再初始化对应引擎
• POST /openapi/oauth/sdk-verify 的返回会带上 enginePermissions，可作为当前 SDK 会话最终生效引擎权限的结果。

使用 viewToken 加载

除了原有的 URL 加载方式，现在还支持通过 viewToken 让 SDK 自行去 OpenAPI 解析真实加载地址：

const engine = await createEngine({
  containerId: 'viewer',
  sdkAuth: {
    endpoint: 'https://api.example.com/openapi',
    token: 'sdk_token_xxx'
  }
});

await engine.loadModelByViewToken('vt_xxx');

目前支持的方法：

• createEngine(...).loadModelByViewToken(viewToken, options?)
• createEngine2d(...).loadModelByViewToken(viewToken, options?)
• createEngineGIS(...).loadModelByViewToken(viewToken, options?)
• createEngineGaussian(...).loadModelByViewToken(viewToken, options?)
• createEngine720(...).loadPanoramaByViewToken(viewToken)

SDK 会自动请求 POST /openapi/models/view-token/resolve，并带上：

• sdkToken
• viewToken
• engineType

服务端会同时校验：

• sdkToken 是否有效
• 当前应用是否仍具备 sdk:use
• 当前成员是否仍具备对应引擎权限
• viewToken 所属模型是否与当前 sdkToken 对应的是同一个应用

最后这一条是强制限制：A 应用的 sdkToken 不能去解析 B 应用下的 viewToken。

Important Notes

• CSS样式已自动包含，无需手动导入
• 该SDK依赖 three 和 vue，确保项目中已安装这些依赖