WebCAD

分类代号：C.6 本章共 6 个接口

---

没有"启用开关"可探

• 下面 6 个 cmd 在图形服务里始终注册，不存在服务端 feature flag
• GET /api/v1/service/webcad 不是启用探针，而是 WebCAD 前端的 license 握手：要求 query 带前端加密的 stamp，解不开就回 HTTP 403 {code:7, msg:"error parameter!"}；成功时回 {status, version, time, stamp}，从不返回 enabled 字段。二次开发不要调它（旧版 SDK 的 webcadEnabled() / webcad_enabled() 据此恒判"未启用"，已移除）
• webcad 数据类接口只对"经 convertWebcad 转过"或有 vcad 数据的 mapid 有意义；listWebcadDraws 总能返回 {imports, designs} 列表

---

快速索引

后端实际还有 3 个分支管理命令（createWebcadBranch / deleteWebcadBranch / mergeWebcadBranch，同走 cmd/... 路由），SDK 未封装，需要时可裸 POST 调用。

---

42 · 列出 WebCAD 图 listWebcadDraws

URL：GET /api/v1/map/cmd/listWebcadDraws/_/v1
可选参数（query）：mapid / version（过滤 imports 列表）、designPath（过滤 designs 列表）。后端不读 type（那是 getWebcadData 的参数）。

响应——返回 imports 与 designs 两个数组：

{
  "status": true,
  "imports": [ ... ],
  "designs": [ ... ]
}

Python / Node

svc.list_webcad_draws()

await svc.listWebcadDraws();

---

43 · 读取 WebCAD 数据 getWebcadData

URL：POST /api/v1/map/cmd/getWebcadData/{mapid}/{version}

请求参数

响应

成功返回 vcad 数据本体——但形态是 gzip 压缩的原始字节，SDK 不解压也不解析：Python get_webcad_data 返回 bytes（\x1f\x8b 魔数开头，签名却声明 Dict），须自行 gzip.decompress 后得到 JSON（含 dbBlocks 实体树）。

缺 patchId 时走错误通道：HTTP 500 + {"error":"patchId is required"}，SDK 抛 VjmapError(status=500)（错误体在 e.body）。

⚠️ 普通图也能取到 base：未经 convertWebcad 的普通 mapid 调 patchId="base" 并不报 500，照样返回 gzip 字节（基底就是整图 vcad 数据）。HTTP 500 对应缺 patchId / 取不存在的 pN 补丁等非法路径。

Python

import gzip, json
raw = svc.get_webcad_data("proj_wc", "v1", patchId="base", branch="main")
data = json.loads(gzip.decompress(raw))  # raw 是 gzip bytes，不是 dict

---

44 · 保存 WebCAD 补丁 saveWebcadPatch

URL：POST /api/v1/map/cmd/saveWebcadPatch/{mapid}/{version}

请求参数

响应

{ "status": true, "patchId": "p13", "branch": "main" }

冲突时返回 { "status": false, "error": "conflict", "conflict": {...} }。

Python

svc.save_webcad_patch(
    "proj_wc", "v1",
    patch='[{"op":"add","entity":{...}}]',
    branch="main",
    author="alice",
    remark="add hatch",
    parentId="p12",
)

---

45 · 删除 WebCAD 图 deleteWebcadDraw

URL：POST /api/v1/map/cmd/deleteWebcadDraw/{mapid}/{version}

请求参数

参数全不给时 SDK 走 GET（空 JSON body 的 POST 会被 cmd 路由回 500 param error）。

响应

{ "status": true }

---

46 · 转为 WebCAD convertWebCAD

把一张已上传的 DWG 转成 WebCAD 可用的结构（初始化分支、预计算可编辑实体）。

URL：POST /api/v1/map/cmd/convertWebCAD/{mapid}/{version}

请求参数（均可选）

全不传时注意：cmd 路由对空 JSON body 的 POST 回 HTTP 500 param error（cmd 路由通用行为，与本命令无关）。SDK 的 convertWebcad / deleteWebcadDraw 在无参数时改走 GET 规避；手写 REST 用 GET 或至少带一个字段。

响应

{ "status": true, "path": ".../data/mapdraws/imports/<mapid>/<version>/" }

转换后的 vcad 数据落在 path 目录（前端 SDK 自动接管）。

对普通非 webcad 图：save_webcad_patch 对普通图也返回 {status:true, patchId:"p1", branch:"main"}——不校验图是否为 webcad 结构；delete_webcad_draw 对不存在的 drawingName 也返回 {status:true}（静默成功）；convert_webcad 对普通图正常返回 {status:true, path}。早先记录的"convert_webcad 对普通图 HTTP 500"其实是空 JSON body 的 POST 被 cmd 路由拒（param error），不是转换失败。

---

47 · 导出 WebCAD 为 DWG exportWebCAD

URL：POST /api/v1/map/cmd/exportWebCAD/_null/v1

请求参数

响应

{ "status": true, "path": "...", "filename": "xxx.dwg", "cached": true }

⚠️ 错误形态：mapid 不存在时不抛 HTTP 异常，返回 body 级 {"error": "Failed to read base.vcad", "status": false}——与 updateMetadata 的 HTTP 404 抛错、renameMap 的 body 级 error:true 构成三种不同错误形态，调用后务必判 status。