# 运维手册（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 通常不建议覆盖已发布版本（避免破坏依赖缓存）。