现版本

docs/外部API总览.md

@@ -0,0 +1,174 @@
+# iflow-engine 外部 API（第三方接入）
+
+## 1) 获取构件树 `getConstructTreeData()`
+
+### 所属模块
+
+- 调用入口：`bimEngine.engine`
+- 源码位置：`src/managers/engine-manager.ts`
+
+### 方法签名
+
+```ts
+getConstructTreeData(): {
+  level: EngineModelData[];
+  type: EngineModelData[];
+  major: EngineModelData[];
+}
+```
+
+### 入参
+
+- 无入参。
+
+### 返回值
+
+- 返回一个对象，包含三类构件树：
+  - `level`: 楼层树
+  - `type`: 类型树
+  - `major`: 专业树
+
+```ts
+type EngineTreeNode = {
+  name?: string;
+  id?: string | null;
+  ids?: string[] | null;
+  children?: EngineTreeNode[] | null;
+  isLeaf?: boolean;
+};
+
+type EngineModelData = {
+  name?: string;
+  url: string;
+  children?: EngineTreeNode[] | null;
+};
+```
+
+### 行为约定
+
+- 当 3D 引擎未初始化（`engine.initialize(...)` 未成功）时，返回：
+
+```ts
+{ level: [], type: [], major: [] }
+```
+
+### 调用示例
+
+```ts
+const treeData = bimEngine.engine?.getConstructTreeData();
+
+if (treeData) {
+  console.log('level tree:', treeData.level);
+  console.log('type tree:', treeData.type);
+  console.log('major tree:', treeData.major);
+}
+```
+
+---
+
+## 2) 获取构件信息 `getComponentProperties(url, id, callback)`
+
+### 所属模块
+
+- 调用入口：`bimEngine.engine`
+- 源码位置：`src/managers/engine-manager.ts`
+
+### 方法签名
+
+```ts
+getComponentProperties(url: string, id: string, callback: (data: any) => void): void
+```
+
+### 入参
+
+- `url: string`：构件所属模型 URL
+- `id: string`：构件 ID
+- `callback: (data: any) => void`：异步回调，返回构件属性
+
+### 调用示例
+
+```ts
+bimEngine.engine?.getComponentProperties(modelUrl, componentId, (data) => {
+  console.log('component properties:', data);
+});
+```
+
+---
+
+## 3) 高亮指定构件 `highlightModel(models)`
+
+### 所属模块
+
+- 调用入口：`bimEngine.engine?.getEngineComponent()`
+- 源码位置：`src/components/engine/index.ts`
+
+### 方法签名
+
+```ts
+highlightModel(models: { url: string; ids: number[] }[]): void
+```
+
+### 入参
+
+- `models`：构件列表（可批量）
+  - `url: string`：模型 URL
+  - `ids: number[]`：要高亮的构件 ID 数组
+
+### 调用示例
+
+```ts
+bimEngine.engine?.getEngineComponent()?.highlightModel([
+  { url: modelUrl, ids: [350518] }
+]);
+```
+
+---
+
+## 4) 剖切指定构件（推荐流程）
+
+当前引擎提供的是“剖切盒适配已高亮构件”的能力，推荐按两步调用：
+
+1. 先高亮目标构件：`highlightModel(...)`
+2. 再执行剖切盒适配：`fitSectionBoxToModel()`
+
+### 方法签名
+
+```ts
+fitSectionBoxToModel(): void
+```
+
+### 调用示例
+
+```ts
+const engineComp = bimEngine.engine?.getEngineComponent();
+
+engineComp?.highlightModel([{ url: modelUrl, ids: [350518] }]);
+engineComp?.fitSectionBoxToModel();
+```
+
+---
+
+## 5) 隐藏其他构件 `isolateModels(models)`
+
+### 所属模块
+
+- 调用入口：`bimEngine.engine?.getEngineComponent()`
+- 源码位置：`src/components/engine/index.ts`
+
+### 方法签名
+
+```ts
+isolateModels(models: { url: string; ids: number[] }[]): void
+```
+
+### 入参
+
+- `models`：要保留显示的构件（其他构件将隐藏）
+
+### 调用示例
+
+```ts
+bimEngine.engine?.getEngineComponent()?.isolateModels([
+  { url: modelUrl, ids: [350518] }
+]);
+```

docs/文档索引.md

@@ -26,6 +26,7 @@
 | [贡献指南.md](贡献指南.md) | 开发协作、脚本说明、最小验证集 | 项目贡献者 |
 | [运维手册.md](运维手册.md) | 构建/发布/回滚流程与常见问题 | 维护者 |
 | [API调用链.md](API调用链.md) | API 调用链（用户交互 → Manager → Engine → 底层引擎） | SDK 维护者 |
+| [外部API总览.md](外部API总览.md) | 外部可调用 API 全量清单（按模块） | SDK 集成开发 |
 | [MODULES/设置系统.md](MODULES/设置系统.md) | 设置系统架构、API、第三方预设接入 | 所有开发者 |
 ## 模块概览