insert / 插入资源总览

文档：vjcad/doc/insert/index.md 示例：vjcad/example/insert/svg/、vjcad/example/insert/symbol/、vjcad/example/insert/vectorize/

insert 模块用于把 外部资源 转成 vjcad 实体并插入到当前文档，三大子领域：

三种插入路径对比

flowchart LR
    A[本地 / 服务端符号<br/>vcadData] --> M[parseSymbolVcadData<br/>→ symbolDoc] --> P[mergeSymbolToDocument]
    B[SVG 字符串] --> S[getWebCadCoreService<br/>.parseSvgToWebcad] --> N[CadDocument.fromDb] --> P
    C[PNG / JPG / 拖拽 / 粘贴] --> V[VectroizeService<br/>convertToSvg] --> S
    P --> E[Engine.pcanvas.addEntity<br/>不记 undo]

三条路径在最后都走 临时 CadDocument → 把 *Model 块里的实体 clone 后 move 到插入点 → Engine.pcanvas.addEntity（mergeSymbolToDocument 内部逐个 pcanvas.addEntity，不是 Engine.addEntities，不记录 undo）。需要可撤销时自己包一层：

Engine.startUndoMark('插入符号');
const ents = mergeSymbolToDocument(symbolDoc, insertPoint, basePoint, 1, 0, false);
if (ents.length) Engine.undoManager.added_undoMark(ents);
Engine.endUndoMark();
Engine.regen();

子文档

• 符号创建（本地 / 服务端）→ symbol-create
• 符号插入（基础 / 交互式 / 修改属性）→ symbol-insert
• 符号管理（分类 / CRUD）→ symbol-manage
• SVG 导入 → svg-import
• 图片转矢量 → vectorize

通用红旗

• parseSvgToWebcad 等 async WASM 方法内部会自动 await this.initWasm()，无需手动先调；失败时返回 null 而非抛错，JSON.parse 前必须判空
• 服务端符号 / 服务端图纸依赖 serviceUrl + accessToken：未配置 serviceUrl 时访问 Engine.service 会直接抛错（SERVICE_URL is not configured），不会返回空值——if (!Engine.service) 判断无效，要用 try/catch
• 用 mergeSymbolToDocument(symbolDoc, insertPoint, basePoint, scale, rotation, clearSourceInfo)，参数顺序是 doc → 插入点 → 基点 → 缩放 → 旋转，不要反过来
• 旋转角度单位是 度（mergeSymbolToDocument / SymbolInteractiveInserter 都按度），但实体级 entity.rotate(center, ang) 是 弧度。两套不要混

参考（官方文档 MCP）

• 文档：vjcad/doc/insert/index.md
• 示例：vjcad/example/insert/svg/、vjcad/example/insert/symbol/、vjcad/example/insert/vectorize/