bim_engine/docs/运维手册.md

运维手册（RUNBOOK）

本文档面向维护者，描述 SDK 的构建、发布与回滚流程。

发布（Deployment）

本项目是 SDK（library）形态，发布通常指 npm publish（或内部制品库发布）。

发布前检查：

1. 本地构建通过：npm run build
2. dist/ 目录产物完整：
   • dist/iflow-engine.es.js
   • dist/iflow-engine.umd.js
   • dist/index.d.ts
3. demo 自测（建议）：
   • npm run dev:demo 或 npm run dev:demo-vue

说明：prepublishOnly 已配置为 npm run build，因此 npm publish 前会自动触发构建。

监控与告警（Monitoring & Alerts）

SDK 仓库本身不包含线上服务，因此没有传统意义的运行时监控。

建议的“质量监控”方式：

• 发布后在一个最小集成项目中验证：
  • ESM/UMD 能否被正确加载
  • 类型定义是否可用（TypeScript 项目可正常编译）
• 对关键交互（目录树、右键菜单、构件详情、剖切/测量/漫游）做冒烟回归

常见问题与处理（Common Issues）

1) build 失败

现象：npm run build 报 TypeScript 或 Vite 打包错误。

处理：

• 优先修复类型错误/导入路径错误
• 确认 dist/ 未被误引用为源码依赖

2) demo 无法正常显示 3D 或缺少 draco

现象：HTML demo 中模型无法加载，控制台提示 draco 相关资源缺失。

处理：

• 运行 npm run copy:demo-draco
• 或直接运行 npm run dev:demo（会自动执行 build + copy）

3) 右键菜单/弹窗交互异常（事件被 3D 场景吞掉）

处理：

• 检查 UI 容器是否对 mouse 事件做了 stopPropagation
• 检查 RightKey/Menu 子菜单容器是否阻止 mousedown 冒泡

回滚（Rollback）

SDK 发布回滚常见方式：

1. 版本回退：在上游业务工程将依赖版本 pin 回稳定版本
2. 重发版本：发布一个修复版本（推荐）

注意：npm registry 通常不建议覆盖已发布版本（避免破坏依赖缓存）。