bim_xg/bim_engine
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(tree,menu,docs): 对接目录树三类数据并中文化文档

Browse Source
This commit is contained in:
yuding
2026-01-28 17:19:36 +08:00
parent 3ab9d4b0ea
commit 0b8dcd36fa
32 changed files with 4060 additions and 3302 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1232
docs/API调用链.md Normal file
View File

File diff suppressed because it is too large Load Diff

0
docs/MODULES/services.md → docs/MODULES/服务模块.md
View File

2
docs/MODULES/core.md → docs/MODULES/核心模块.md
View File

@@ -122,7 +122,7 @@ class ManagerRegistry {
buttonGroup: ButtonGroupManager | null;
rightKey: RightKeyManager | null;
constructTree: ConstructTreeManagerBtn | null;
propertyPanel: PropertyPanelManager | null;
componentDetail: ComponentDetailManager | null;
measure: MeasureDialogManager | null;
walkControl: WalkControlManager | null;
map: MapDialogManager | null;

18
docs/MODULES/_INDEX.md → docs/MODULES/模块索引.md
View File

@@ -4,10 +4,10 @@
| 模块 | 路径 | 职责 | 文档 |
|------|------|------|------|
| **core** | `src/core/` | 核心基础设施：事件系统、管理器基类、注册表 | [core.md](core.md) |
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑和组件协调 | [managers.md](managers.md) |
| **components** | `src/components/` | 20+ 个 UI 组件 | [components.md](components.md) |
| **services** | `src/services/` | 全局服务：国际化、主题管理 | [services.md](services.md) |
| **core** | `src/core/` | 核心基础设施：事件系统、管理器基类、注册表 | [核心模块.md](核心模块.md) |
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑和组件协调 | [管理器模块.md](管理器模块.md) |
| **components** | `src/components/` | 20+ 个 UI 组件 | [组件模块.md](组件模块.md) |
| **services** | `src/services/` | 全局服务：国际化、主题管理 | [服务模块.md](服务模块.md) |
## Core 模块
@@ -20,7 +20,7 @@
| BaseManager | `base-manager.ts` | Manager 抽象基类 |
| BaseDialogManager | `base-dialog-manager.ts` | 对话框 Manager 基类 |
[查看详情 →](core.md)
[查看详情 →](核心模块.md)
## Managers 模块
@@ -40,7 +40,7 @@
| 管理器 | 职责 |
|--------|------|
| PropertyPanelManager | 属性面板管理 |
| ComponentDetailManager | 构件详情弹窗管理 |
| ConstructTreeManagerBtn | 构件树管理 |
| MeasureDialogManager | 测量对话框管理 |
| SectionPlaneDialogManager | 平面剖切管理 |
@@ -51,7 +51,7 @@
| WalkPlanViewDialogManager | 漫游平面图管理 |
| MapDialogManager | 地图管理 |
[查看详情 →](managers.md)
[查看详情 →](管理器模块.md)
## Components 模块
@@ -88,7 +88,7 @@
| BimTab | 标签页 |
| BimDescription | 描述列表 |
[查看详情 →](components.md)
[查看详情 →](组件模块.md)
## Services 模块
@@ -99,7 +99,7 @@
| LocaleManager | 国际化服务，多语言支持 |
| ThemeManager | 主题管理服务，明暗切换 |
[查看详情 →](services.md)
[查看详情 →](服务模块.md)
## 类型定义

14
docs/MODULES/managers.md → docs/MODULES/管理器模块.md
View File

@@ -18,7 +18,7 @@ src/managers/
├── dialog-manager.ts # 对话框管理器
├── button-group-manager.ts # 按钮组管理器
├── right-key-manager.ts # 右键菜单管理器
├── property-panel-manager.ts # 属性面板管理器
├── component-detail-manager.ts # 构件详情弹窗管理器
├── construct-tree-manager-btn.ts # 构件树管理器
├── walk-control-manager.ts # 漫游控制管理器
├── measure-dialog-manager.ts # 测量对话框管理器
@@ -41,7 +41,7 @@ BaseManager
├── DialogManager
├── ButtonGroupManager
├── RightKeyManager
├── PropertyPanelManager
├── ComponentDetailManager
├── ConstructTreeManagerBtn
└── WalkControlManager
@@ -61,7 +61,7 @@ BaseDialogManager (继承自 BaseManager)
|------|--------|------|
| **核心** | EngineManager | 3D 引擎管理 |
| **UI 容器** | ToolbarManager, DialogManager, ButtonGroupManager | 容器组件管理 |
| **交互** | RightKeyManager, PropertyPanelManager, ConstructTreeManagerBtn | 用户交互 |
| **交互** | RightKeyManager, ComponentDetailManager, ConstructTreeManagerBtn | 用户交互 |
| **3D 工具** | MeasureDialogManager, SectionPlaneDialogManager, SectionAxisDialogManager, SectionBoxDialogManager | 3D 操作工具 |
| **漫游** | WalkControlManager, WalkPathDialogManager, WalkPlanViewDialogManager, MapDialogManager | 漫游功能 |
@@ -350,20 +350,20 @@ class WalkControlManager extends BaseManager {
---
## PropertyPanelManager
## ComponentDetailManager
### 概述
管理构件属性面板的显示。
管理构件详情弹窗（属性展示）的显示。
### API
```typescript
class PropertyPanelManager extends BaseManager {
class ComponentDetailManager extends BaseManager {
init(): void;
show(): void;
hide(): void;
isOpen(): boolean;
hide(): void;
destroy(): void;
}
```

0
docs/MODULES/components.md → docs/MODULES/组件模块.md
View File

0
docs/ENGINE_API_INTEGRATION.md → docs/引擎API对接.md
View File

4
docs/GETTING_STARTED.md → docs/快速开始.md
View File

@@ -378,8 +378,8 @@ import type {
## 下一步
- 查看 [架构文档](ARCHITECTURE.md) 了解设计原理
- 查看 [模块文档](MODULES/_INDEX.md) 了解详细 API
- 查看 [架构文档](架构设计.md) 了解设计原理
- 查看 [模块文档](MODULES/模块索引.md) 了解详细 API
- 查看 [demo](../demo/) 获取更多示例
---

19
docs/INDEX.md → docs/文档索引.md
View File

@@ -18,9 +18,12 @@
| 文档 | 说明 | 适合人群 |
|------|------|---------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | 架构设计、设计模式、模块依赖 | 架构师、核心开发 |
| [GETTING_STARTED.md](GETTING_STARTED.md) | 快速开始、安装、基础用法 | 新用户、集成开发 |
| [MODULES/_INDEX.md](MODULES/_INDEX.md) | 所有模块的详细文档索引 | 所有开发者 |
| [架构设计.md](架构设计.md) | 架构设计、设计模式、模块依赖 | 架构师、核心开发 |
| [快速开始.md](快速开始.md) | 快速开始、安装、基础用法 | 新用户、集成开发 |
| [MODULES/模块索引.md](MODULES/模块索引.md) | 所有模块的详细文档索引 | 所有开发者 |
| [贡献指南.md](贡献指南.md) | 开发协作、脚本说明、最小验证集 | 项目贡献者 |
| [运维手册.md](运维手册.md) | 构建/发布/回滚流程与常见问题 | 维护者 |
| [API调用链.md](API调用链.md) | API 调用链（用户交互 → Manager → Engine → 底层引擎） | SDK 维护者 |
## 模块概览
@@ -42,11 +45,11 @@ src/
| 模块 | 路径 | 职责 | 文档 |
|------|------|------|------|
| **BimEngine** | `src/bim-engine.ts` | 主入口类，整合所有功能 | [详情](MODULES/bim-engine.md) |
| **core** | `src/core/` | 事件系统、管理器基类、注册表 | [详情](MODULES/core.md) |
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑 | [详情](MODULES/managers.md) |
| **components** | `src/components/` | 20+ 个 UI 组件 | [详情](MODULES/components.md) |
| **services** | `src/services/` | 主题管理、国际化服务 | [详情](MODULES/services.md) |
| **BimEngine** | `src/bim-engine.ts` | 主入口类，整合所有功能 | 暂无独立文档 |
| **core** | `src/core/` | 事件系统、管理器基类、注册表 | [详情](MODULES/核心模块.md) |
| **managers** | `src/managers/` | 15 个管理器，处理业务逻辑 | [详情](MODULES/管理器模块.md) |
| **components** | `src/components/` | 20+ 个 UI 组件 | [详情](MODULES/组件模块.md) |
| **services** | `src/services/` | 主题管理、国际化服务 | [详情](MODULES/服务模块.md) |
## 架构分层

2
docs/ARCHITECTURE.md → docs/架构设计.md
View File

@@ -126,7 +126,7 @@ registry.emit('engine:model-loaded', { url: 'model.gltf' });
|------|--------|------|
| 核心 | EngineManager | 3D 引擎管理 |
| UI 容器 | ToolbarManager, DialogManager, ButtonGroupManager | 容器组件管理 |
| 交互 | RightKeyManager, PropertyPanelManager, ConstructTreeManagerBtn | 用户交互 |
| 交互 | RightKeyManager, ComponentDetailManager, ConstructTreeManagerBtn | 用户交互 |
| 工具 | MeasureDialogManager, SectionPlaneDialogManager, SectionAxisDialogManager, SectionBoxDialogManager | 3D 操作工具 |
| 漫游 | WalkControlManager, WalkPathDialogManager, WalkPlanViewDialogManager, MapDialogManager | 漫游功能 |

50
docs/贡献指南.md Normal file
View File

@@ -0,0 +1,50 @@
# 贡献指南（CONTRIB）
本文档面向 SDK 开发/维护者，内容以 `package.json` 的 scripts 为单一事实来源。
## 开发环境
- Node.js: 建议使用当前 LTS
- 包管理器: npm（项目脚本默认使用 `npm run ...`）
备注：本仓库当前没有提供 `.env.example`，因此默认不需要额外环境变量。
## 常用命令（Scripts）
| Script | 命令 | 说明 |
|---|---|---|
| `dev` | `vite` | 启动开发环境（通常用于 playground） |
| `build` | `tsc && vite build` | 构建 SDK（产物输出到 `dist/`） |
| `copy:demo` | `mkdir -p demo/lib && cp dist/iflow-engine.es.js dist/iflow-engine.umd.js dist/iflow-engine.umd.js.map demo/lib/` | 复制构建产物到 HTML demo 目录 |
| `copy:demo-draco` | `mkdir -p demo/static/js/draco && cp node_modules/iflow-engine-base/dist/draco/*.js node_modules/iflow-engine-base/dist/draco/*.wasm demo/static/js/draco/` | 复制 draco 解码器到 HTML demo 目录 |
| `copy:demo-all` | `npm run copy:demo && npm run copy:demo-draco` | 一次性准备 HTML demo 需要的全部静态资源 |
| `copy:demo-vue` | `mkdir -p demo-vue/public/lib && cp dist/iflow-engine.es.js dist/iflow-engine.umd.js dist/iflow-engine.umd.js.map demo-vue/public/lib/` | 复制构建产物到 Vue demo 目录 |
| `dev:demo` | `npm run build && npm run copy:demo-all && cd demo && npm run dev` | 构建并启动 HTML demo |
| `dev:demo-vue` | `npm run build && npm run copy:demo-vue && cd demo-vue && npm run dev` | 构建并启动 Vue demo |
| `dev:all` | `npm run dev:demo & npm run dev:demo-vue` | 同时启动两个 demo（并行） |
| `prepublishOnly` | `npm run build` | npm 发布前自动构建 |
## 开发流程（建议）
1. 本地开发：`npm run dev`
2. 修改代码后做一次构建验证：`npm run build`
3. 需要人工验证交互时：
- HTML demo：`npm run dev:demo`
- Vue demo：`npm run dev:demo-vue`
## 测试与验证
当前仓库未配置独立的单元测试脚本。
推荐的最小验证集：
- `npm run build`（保证 TypeScript 编译与 Vite 打包通过）
- 在 `demo/` 或 `demo-vue/` 中进行手动回归（与本次修改相关的功能点）
## 文档维护
- 代码变更后，务必同步更新 `AI_COLLABORATION.md` 的相关部分。
- 如果新增/修改了组件或管理器，建议同步更新 `docs/` 下对应模块文档。
## 过期文档检查（90 天）
按最近一次扫描结果：`docs/` 下没有发现 90 天未更新的文档。

60
docs/运维手册.md Normal file
View File

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