生成三维预览链接

使用身份：用户个人 Token； 
业务背景：文件上传解压完成后，集成开发方需要获取预览 URL，嵌入业务系统页面或者直接给到用户打开三维看图；分为普通单件文件、zip 解压后的装配包两种场景。 
前置条件：

• 单件模型：已经完成上传元信息同步，拿到 fileId；
• 装配 zip 包：完成上传、sync‑file‑meta、完成解压任务。

详细调用流程

1. 调用生成预览链接接口 接口：POST /login‑register/open‑api/documents/preview‑url
   • Header：Bearer 用户 access_token + 公共 Header，json；
   • Body 参数：
     • fileId：SView 内部文件 ID；
     • fileScope：personal/project；
     • projectCode：fileScope=project必须传入外部项目编码；
     • urlType：preview标准预览页面；headless无头预览（只保留三维画布，适合业务系统内嵌）；
     • mainFileName【装配包才传】：压缩包内部主装配完整文件名，带后缀，例如总装.SLDASM；单件模型不要传该字段；
2. 处理接口返回，两种分支
   • 分支 A：data 直接返回 previewUrl → 直接使用该链接进行三维预览；
   • 分支 B：previewUrl 为空，返回 taskId → 文件需要后台执行转码，建立 WebSocket 监听 taskId。
3. WebSocket 监听转码任务
   • ws/wss 地址：ws(s)://baseURL/emh/ws/info?socketId={taskId}；
   • 消息 command=CONVERT_TASK，代表文件转码任务；
   • status=success：data 字段取出 previewUrl，预览就绪；
   • status=failed：转码失败，终止流程。

关键规则：UNCOMPRESS_FILE的 success 只是解压成功；只有 CONVERT_TASK 的 success，才代表三维预览真正就绪。

集成开发方留存关键数据

previewUrl，给到前端页面打开三维模型。

高频踩坑说明

1. zip 装配包场景忘记传 mainFileName，预览无法识别主装配；
2. 收到 UNCOMPRESS_FILE 成功就直接拿链接，转码还未完成预览打不开。