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