feat(all): 更新文档

packages/docs/api/manager/ClippingManager.md

@@ -9,11 +9,20 @@ outline: [2, 3]
 
 ## 类：`ClippingManager`
 
-- 作用：剖切管理器 管理剖切组和任意数量的剖切面（通过 addPlane 手动创建）
+- 作用：剖切管理器，负责剖切对象收拢、剖切平面管理，以及单面剖切补面（CSG）结果生成。
+
+## 剖切补面能力说明
+
+`single` 平面启用后，管理器会在 `clippingGroup` 中按名称查找目标网格，执行一次“目标网格 - 刀具体”的 CSG 运算，将结果放到 `singlePlaneCapGroup`，并临时隐藏原网格。
+
+- 目标网格通过 `setSinglePlaneCapTargetByName` 指定。
+- 开关通过 `setSinglePlaneCapEnabled` 控制。
+- 仅当剖切平面与目标网格包围盒相交时才生成结果。
+- 平面移动时自动刷新补面结果。
 
 ### 构造函数
 
-#### `new ClippingManager(viewer: Viewer)`
+#### `new ClippingManager(viewer: Viewer, options?: IClippingManagerOptions)`
 
 - 作用：创建 ClippingManager 实例。
 
@@ -22,6 +31,7 @@ outline: [2, 3]
 | 参数名 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+| `options` | `IClippingManagerOptions` | 否 | 剖切管理配置，支持默认补面目标网格和默认启用状态。 |
 
 - 出参：`ClippingManager`
 - 返回说明：返回当前类实例。
@@ -39,6 +49,16 @@ outline: [2, 3]
 | `scene` | `public` | `THREE.Scene` | 用于保存 `scene` 对应的数据。 |
 | `viewer` | `public` | `Viewer` | 用于保存 `viewer` 对应的数据。 |
 | `planeHelperGroup` | `public` | `THREE.Group` | 平面辅助对象组 |
+| `singlePlaneCapGroup` | `public` | `THREE.Group` | 单面剖切补面结果组 |
+
+### 接口
+
+#### `IClippingManagerOptions`
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `singlePlaneCapMeshName` | `string` | 否 | 单面剖切补面的目标网格名称，对应 `THREE.Mesh.name`。 |
+| `singlePlaneCapEnabled` | `boolean` | 否 | 是否默认启用单面剖切补面。 |
 
 ### 方法
 
@@ -91,6 +111,50 @@ outline: [2, 3]
 - 出参：`ClippingPlane \| undefined`
 - 返回说明：返回 `ClippingPlane | undefined`。
 
+#### `setSinglePlaneCapTargetByName(meshName: string | null): void`
+
+- 作用：设置单面剖切补面的目标网格名称。仅对 `single` 剖切面生效。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `meshName` | `string \| null` | 是 | 目标网格名称，传入 `null` 可关闭补面。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setSinglePlaneCapEnabled(enabled: boolean): void`
+
+- 作用：设置单面剖切补面是否启用。仅对 `single` 剖切面生效。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | 是 | 是否启用单面剖切补面。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getSinglePlaneCapEnabled(): boolean`
+
+- 作用：获取当前单面剖切补面的启用状态。
+
+- 入参：无
+
+- 出参：`boolean`
+- 返回说明：返回当前是否启用单面剖切补面。
+
+#### `getSinglePlaneCapTargetName(): string | null`
+
+- 作用：获取当前单面剖切补面的目标网格名称。
+
+- 入参：无
+
+- 出参：`string \| null`
+- 返回说明：返回当前配置的目标网格名称。
+
 #### `autoPlanePosition(offset: number = 2): void`
 
 - 作用：根据剖切组包围盒自动定位 X/Y/Z 三个剖切面 必须先调用 addDefaultPlanes() 注册剖切面
@@ -106,7 +170,7 @@ outline: [2, 3]
 
 #### `addClippingObjectsByUuid(uuids: Array<string>): void`
 
-- 作用：─── 剖切组对象管理（保持不变）────────────────────────────────────────
+- 作用：按 uuid 将场景对象加入剖切组。
 
 - 入参：
 
@@ -119,7 +183,7 @@ outline: [2, 3]
 
 #### `addClippingObjects(objects: Array<THREE.Object3D>): void`
 
-- 作用：添加 Clipping Objects。
+- 作用：批量加入剖切组，并触发单面补面刷新。
 
 - 入参：
 
@@ -132,7 +196,7 @@ outline: [2, 3]
 
 #### `addClippingToObject(object: THREE.Object3D): void`
 
-- 作用：添加 Clipping To Object。
+- 作用：将对象从原父节点迁入剖切组，并保留原始变换信息。
 
 - 入参：
 
@@ -145,7 +209,7 @@ outline: [2, 3]
 
 #### `removeClippingObjectsByUuid(uuids: Array<string>): void`
 
-- 作用：移除 Clipping Objects By Uuid。
+- 作用：按 uuid 从剖切组移除对象并恢复原父节点与原始变换。
 
 - 入参：
 
@@ -158,7 +222,7 @@ outline: [2, 3]
 
 #### `clearClippingGroups(): void`
 
-- 作用：清理 Clipping Groups。
+- 作用：清空剖切组对象、移除平面辅助，并刷新补面状态。
 
 - 入参：无
 
@@ -167,7 +231,7 @@ outline: [2, 3]
 
 #### `clearClippingPlanes(): void`
 
-- 作用：清理 Clipping Planes。
+- 作用：清空所有剖切平面并解绑单面补面监听。
 
 - 入参：无
 
@@ -176,7 +240,7 @@ outline: [2, 3]
 
 #### `hideClippingPlanes(): void`
 
-- 作用：执行 hide Clipping Planes 相关逻辑。
+- 作用：隐藏历史平面辅助对象。
 
 - 入参：无
 
@@ -185,7 +249,7 @@ outline: [2, 3]
 
 #### `computeBoundingBox(): THREE.Box3`
 
-- 作用：执行 compute Bounding Box 相关逻辑。
+- 作用：计算当前剖切组中网格对象的世界包围盒。
 
 - 入参：无
 
@@ -207,7 +271,7 @@ outline: [2, 3]
 
 #### `startClipping(): void`
 
-- 作用：执行 start Clipping 相关逻辑。
+- 作用：将剖切状态设为启用并发出 `clippingStart` 事件。
 
 - 入参：无
 
@@ -216,7 +280,7 @@ outline: [2, 3]
 
 #### `stopClipping(): void`
 
-- 作用：执行 stop Clipping 相关逻辑。
+- 作用：将剖切状态设为关闭并发出 `clippingEnd` 事件。
 
 - 入参：无
 
@@ -234,8 +298,35 @@ outline: [2, 3]
 
 ## 构造示例
 
-- 当前 Demo 中没有直接展示 `ClippingManager` 的构造调用。
+- `Viewer` 初始化时会自动创建 `ClippingManager`，可通过 `Viewer` 选项透传剖切补面默认配置。
+
+```ts
+import { Viewer } from "@deep/engine";
+
+const viewer = new Viewer("app", {
+	clipping: {
+		singlePlaneCapMeshName: "地层网格",
+		singlePlaneCapEnabled: true,
+	},
+});
+```
 
 ## 函数示例
 
-- 当前 Demo 中没有直接展示 `ClippingManager` 的公开方法调用。
+- 单面剖切补面的典型流程：
+
+```ts
+const [planeX, planeY, planeZ] = viewer.clipping.addDefaultPlanes();
+
+const singlePlane = viewer.clipping.addPlane("single", {
+	normal: new THREE.Vector3(1, 0, 0),
+	color: new THREE.Color(0xffff00),
+});
+
+viewer.clipping.addClippingObjects([targetObject]);
+viewer.clipping.setSinglePlaneCapTargetByName("地层网格");
+viewer.clipping.setSinglePlaneCapEnabled(true);
+
+// 平面位姿变化会自动刷新补面结果
+singlePlane.setTransformMode("translate");
+```