@jnrs/lingshu-smart 2.2.19 → 2.2.21

package/AGENTIC.md

@@ -0,0 +1,1047 @@
+# @jnrs/lingshu-smart API 文档
+
+## ✨ 介绍
+
+巨能前端 2D 数字孪生库，灵枢智造。提供 2D 数字孪生编辑器和运行看板功能，基于 LeaferJS 引擎构建。
+
+## 📦 模块总览
+
+| 模块路径 | 说明 |
+|---------|------|
+| `@jnrs/lingshu-smart` | 主模块，包含类型定义和工具函数 |
+| `@jnrs/lingshu-smart/components` | Vue 组件库（编辑器、预览器） |
+| `@jnrs/lingshu-smart/stores` | Pinia 状态管理 |
+| `@jnrs/lingshu-smart/composables` | Vue 组合式 API |
+| `@jnrs/lingshu-smart/controller` | 控制器类 |
+| `@jnrs/lingshu-smart/types` | TypeScript 类型定义 |
+| `@jnrs/lingshu-smart/utils` | 工具函数 |
+| `@jnrs/lingshu-smart/constants` | 常量配置 |
+| `@jnrs/lingshu-smart/ui` | UI 模型和工厂 |
+| `@jnrs/lingshu-smart/locales` | 国际化配置 |
+
+---
+
+## 📋 API 详情
+
+### @jnrs/lingshu-smart 主模块
+
+#### 类型导出
+
+从主模块导出的所有类型：
+
+##### 枚举 (Enums)
+
+###### EnumStepType
+
+步骤操作类型
+
+```typescript
+enum EnumStepType {
+  UNDO = 'Undo',   // 撤销
+  REDO = 'Redo'    // 重做
+}
+```
+
+###### EnumTag
+
+设备标签枚举
+
+```typescript
+enum EnumTag {
+  TRANSPORT = '搬运设备',
+  MACHINE = '机床',
+  CLEANING = '清洗机',
+  STATION = '装载站',
+  STORAGE = '库',
+  OTHER = '其他'
+}
+```
+
+###### EnumModel
+
+设备类型枚举
+
+```typescript
+enum EnumModel {
+  SINGLE_JOINT_ROBOT = 'SingleJointRobot',      // 单关节机器人
+  DOUBLE_JOINT_ROBOT = 'DoubleJointRobot',      // 双关节机器人
+  RGV = 'Rgv',                                   // RGV
+  MACHINE_TOOL = 'MachineTool',                  // 机床
+  MARKING_MACHINE = 'MarkingMachine',            // 打标机
+  CLEANING_MACHINE = 'CleaningMachine',          // 清洗机
+  LOADING_STATION = 'LoadingStation',            // 上料站
+  PALLET_STORAGE = 'PalletStorage',              // 托盘库
+  TOOL_STORAGE = 'ToolStorage',                  // 刀具库
+  BUFFER_DOCK = 'BufferDock',                    // 缓冲站
+  GROUND_RAIL = 'GroundRail',                    // 地轨
+  FOLLOWING_TUGGER = 'FollowingTugger',          // 跟随牵引车
+  RAIL = 'Rail',                                 // 轨道
+  RESOURCE_STORE = 'ResourceStore'               // 资源库
+}
+```
+
+###### EnumComponent
+
+组件类型枚举
+
+```typescript
+enum EnumComponent {
+  STATION_SLOT = 'StationSlot',  // 工位槽
+  RESOURCE = 'Resource'          // 资源
+}
+```
+
+###### EnumResourceType
+
+资源类型枚举
+
+```typescript
+enum EnumResourceType {
+  PALLET = 'Pallet',  // 托盘
+  TOOL = 'Tool'       // 刀具
+}
+```
+
+###### EnumInteractiveUi
+
+可交互设备类型
+
+```typescript
+type EnumInteractiveUi = EnumModel | EnumComponent
+```
+
+##### 核心类型 (Core Types)
+
+###### IScene
+
+场景配置
+
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| width | `number` | ✓ | 场景宽度 |
+| height | `number` | ✓ | 场景高度 |
+| runtime_width | `number` | - | 运行时宽度（业务数据） |
+| runtime_height | `number` | - | 运行时高度（业务数据） |
+| zoomType | `'fit' \| number` | ✓ | 缩放类型：'fit' 自适应或具体数值 |
+| fill | `FillConfig` | - | 背景填充配置 |
+| texture | `string` | - | 纹理图片 URL |
+
+**FillConfig 类型：**
+
+```typescript
+interface FillConfig {
+  type: 'solid' | 'linear' | 'radial' | 'image'
+  color: string
+  opacity: number
+  stops: { offset: number; color: string }[]
+  url?: string
+  from?: string
+  to?: string
+}
+```
+
+###### ICase
+
+方案（案例）
+
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| uuid | `string` | ✓ | 唯一标识 |
+| isActive | `boolean` | ✓ | 是否为当前激活方案 |
+| title | `string` | ✓ | 方案标题 |
+| scene | `IScene` | ✓ | 场景配置 |
+| layers | `ILayer[]` | ✓ | 图层列表 |
+
+###### ILayer
+
+图层基类
+
+**说明：** ILayer 是图层的基类，具体实现包括 IModel（设备模型）、IStationSlotConfig（工位槽配置）、IResourceConfig（资源配置）等。
+
+###### InteractiveUi
+
+可交互设备类型
+
+```typescript
+type InteractiveUi = ILayer | IStationSlotConfig | IResourceConfig
+```
+
+###### IEventHandler
+
+事件处理器
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| onTap | `(layer: ILayer, data: InteractiveUi) => void` | 快速点击事件（左键单击） |
+| onMenuTap | `(layer: ILayer, data: InteractiveUi) => void` | 右键 tap 事件（右键单击） |
+| onDragEnd | `(layer: ILayer, data: InteractiveUi) => void` | 拖动结束事件 |
+
+###### IContainer
+
+容器配置
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| appDomId | `string \| HTMLElement` | — | APP 容器 DOM ID 或元素 |
+| autoStart | `boolean` | `true` | 是否自动启动引擎 |
+| appEditable | `boolean` | `false` | APP 是否可编辑状态 |
+| actions | `IEventHandler` | — | 事件处理配置 |
+
+##### 工具函数 (Utils)
+
+###### numberLoopGenerator
+
+数字生成器
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| start | `number` | — | 起始值 |
+| end | `number` | — | 结束值 |
+| shouldLoop | `boolean` | `false` | 是否无限循环 |
+
+**返回值：** `Generator<number>` - 数字生成器
+
+**使用示例：**
+
+```typescript
+import { numberLoopGenerator } from '@jnrs/lingshu-smart'
+
+const gen = numberLoopGenerator(1, 10, false)
+for (const num of gen) {
+  console.log(num) // 1, 2, 3, ..., 10
+}
+```
+
+###### linearIncrease
+
+在 n 秒内把变量从值 x 线性递增到 y
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| x | `number` | `0` | 初始值 |
+| y | `number` | `100` | 结束值 |
+| n | `number` | `3` | 递增时长（秒） |
+| rate | `number` | `300` | 帧率（ms） |
+| callback | `(val: number \| string) => void` | — | 回调函数 |
+
+**返回值：** `Promise<void>`
+
+**使用示例：**
+
+```typescript
+import { linearIncrease } from '@jnrs/lingshu-smart'
+
+await linearIncrease(0, 100, 3, 300, (val) => {
+  console.log('当前值:', val)
+})
+```
+
+###### transPercentAndPixel
+
+根据百分比数字转换为像素，或者根据像素转换为百分比
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| val | `number` | — | 百分比数字（0~1）或像素数字 |
+| size | `number` | — | 尺寸，用于计算百分比 |
+| precision | `number` | `3` | 保留的小数位数 |
+| getPercent | `boolean` | `false` | 是否返回百分比 |
+
+**返回值：** `number` - 转换后的值
+
+**使用示例：**
+
+```typescript
+import { transPercentAndPixel } from '@jnrs/lingshu-smart'
+
+// 百分比转像素
+const pixel = transPercentAndPixel(0.5, 1920, 0, false) // 960
+
+// 像素转百分比
+const percent = transPercentAndPixel(960, 1920, 3, true) // 0.5
+```
+
+###### transFraction
+
+百分比转换小数
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| val | `number` | — | 值 |
+| size | `number` | — | 尺寸 |
+
+**返回值：** `number` - 转换后的小数
+
+###### transRuntimeToPixel
+
+运行时数值转换为像素数值
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| val | `number` | — | 运行时数值 |
+| precision | `number` | `0` | 精度 |
+| type | `'width' \| 'height'` | `'width'` | 类型 |
+
+**返回值：** `number` - 像素数值
+
+**注意：** 此函数依赖 `useEditorStore`，仅在编辑器环境中可用。
+
+---
+
+### @jnrs/lingshu-smart/components 模块
+
+#### LingshuSmartEditor
+
+编辑器组件，提供 2D 数字孪生方案的可视化编辑功能。
+
+**Props：**
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| actions | `EditorActions` | `{}` | 事件处理配置 |
+
+**EditorActions 接口：**
+
+```typescript
+interface EditorActions {
+  /**
+   * 加载案例列表
+   * @param id - 可选的案例 ID
+   * @returns Promise<ICase[]>
+   */
+  loadCases?: (id?: string) => Promise<ICase[]>
+
+  /**
+   * 保存方案列表
+   * @param cases - 方案列表
+   */
+  saveCases?: (cases?: ICase[]) => void
+
+  /**
+   * 跳转到预览页面
+   * @param currentCase - 当前方案
+   */
+  handlePreview?: (currentCase?: ICase) => void
+
+  /**
+   * 退出当前页面
+   */
+  handleExit?: () => void
+}
+```
+
+**使用示例：**
+
+```vue
+<template>
+  <LingshuSmartEditor :actions="editorActions" />
+</template>
+
+<script setup>
+import { LingshuSmartEditor } from '@jnrs/lingshu-smart/components'
+
+const editorActions = {
+  async loadCases(id) {
+    const res = await fetch(`/api/cases/${id || ''}`)
+    return res.json()
+  },
+  saveCases(cases) {
+    fetch('/api/cases', {
+      method: 'POST',
+      body: JSON.stringify(cases)
+    })
+  },
+  handlePreview(currentCase) {
+    window.open(`/preview/${currentCase.uuid}`)
+  },
+  handleExit() {
+    window.history.back()
+  }
+}
+</script>
+```
+
+**功能特性：**
+
+- 左侧菜单卡片：设备库、图层管理
+- 中间画布：可视化编辑区域
+- 右侧选项卡片：属性配置面板
+- 顶部控制栏：方案标题编辑、方案管理、步骤记录（撤销/重做）
+- 支持拖拽、缩放、旋转等操作
+- 自动保存和版本管理
+
+---
+
+#### LingshuSmartPreview
+
+预览组件，用于运行和展示 2D 数字孪生方案。
+
+**Props：**
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| actions | `PreviewActions` | `{}` | 事件处理配置 |
+| caseUuid | `string` | — | 案例 UUID |
+
+**PreviewActions 接口：**
+
+```typescript
+interface PreviewActions {
+  /**
+   * 加载案例列表
+   * @param id - 可选的案例 ID
+   * @returns Promise<ICase[]>
+   */
+  loadCases?: (id?: string) => Promise<ICase[]>
+
+  /**
+   * 点击事件
+   * @param layer - 图层
+   * @param data - 设备信息
+   */
+  onTap?: (layer: ILayer, data: InteractiveUi) => void
+
+  /**
+   * 右键点击事件
+   * @param layer - 图层
+   * @param data - 设备信息
+   */
+  onMenuTap?: (layer: ILayer, data: InteractiveUi) => void
+
+  /**
+   * 拖拽结束事件
+   * @param layer - 图层
+   * @param data - 设备信息
+   */
+  onDragEnd?: (layer: ILayer, data: InteractiveUi) => void
+}
+```
+
+**使用示例：**
+
+```vue
+<template>
+  <LingshuSmartPreview
+    :case-uuid="caseUuid"
+    :actions="previewActions"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { LingshuSmartPreview } from '@jnrs/lingshu-smart/components'
+
+const caseUuid = ref('abc-123-def')
+
+const previewActions = {
+  async loadCases() {
+    const res = await fetch('/api/cases')
+    return res.json()
+  },
+  onTap(layer, data) {
+    console.log('点击设备:', data)
+  },
+  onMenuTap(layer, data) {
+    console.log('右键点击:', data)
+  }
+}
+</script>
+```
+
+**功能特性：**
+
+- 只读模式，不支持编辑
+- 支持设备点击、右键菜单交互
+- 自适应窗口大小
+- 自动加载指定案例
+- 支持自定义事件回调
+
+---
+
+### @jnrs/lingshu-smart/stores 模块
+
+#### useDataStore
+
+数据仓库，管理设备菜单、方案列表等全局数据。
+
+**返回值：**
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| equipmentsMenu | `Ref<IEquipmentsMenu[]>` | 设备菜单（预设） |
+| cases | `Ref<ICase[] \| undefined>` | 方案列表 |
+| casesLoading | `Ref<boolean>` | 方案加载状态 |
+| updateCases | `(data?: ICase[]) => void` | 更新方案列表 |
+| selectCase | `(uuid: string) => void` | 切换当前方案 |
+| addCase | `(data?: ICase) => void` | 添加方案 |
+| removeCase | `(uuid: string) => void` | 删除方案 |
+| updateCase | `(uuid: string, data: Partial<ICase>) => void` | 更新方案 |
+
+**使用示例：**
+
+```typescript
+import { useDataStore } from '@jnrs/lingshu-smart/stores'
+
+const dataStore = useDataStore()
+
+// 更新方案列表
+dataStore.updateCases([
+  {
+    uuid: 'case-1',
+    title: '方案1',
+    isActive: true,
+    scene: { /* ... */ },
+    layers: []
+  }
+])
+
+// 切换方案
+dataStore.selectCase('case-1')
+
+// 添加新方案
+dataStore.addCase({
+  uuid: '',
+  title: '新方案',
+  isActive: false,
+  scene: { /* ... */ },
+  layers: []
+})
+
+// 访问方案列表
+console.log(dataStore.cases.value)
+```
+
+---
+
+#### useEditorStore
+
+编辑器仓库，管理编辑器实例、当前方案、场景、图层等状态。
+
+**返回值：**
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| currentCase | `ComputedRef<ICase \| null>` | 当前选择的方案 |
+| scene | `ComputedRef<IScene \| null>` | 当前方案场景 |
+| layers | `ComputedRef<ILayer[]>` | 当前方案图层列表 |
+| currentLayer | `ComputedRef<ILayer \| null>` | 当前选择的图层 |
+| initContainer | `(options: IContainer) => void` | 初始化容器（引擎实例） |
+| updateScene | `() => void` | 修改场景（防抖） |
+| addLayer | `(layer: ILayer) => void` | 添加图层 |
+| removeLayer | `(uuid: string) => void` | 删除图层 |
+| updateLayer | `(uuid: string, data: Partial<ILayer>) => void` | 更新图层 |
+| selectLayer | `(uuid: string) => void` | 选择图层 |
+| resizeContainer | `() => void` | 重置容器大小 |
+| destroyContainer | `() => void` | 销毁容器 |
+| operating | `Ref<ILayerOperating \| null>` | 当前操作状态 |
+
+**使用示例：**
+
+```typescript
+import { useEditorStore } from '@jnrs/lingshu-smart/stores'
+
+const editorStore = useEditorStore()
+
+// 初始化容器
+editorStore.initContainer({
+  appDomId: 'editor-app',
+  appEditable: true,
+  actions: {
+    onTap: (layer, data) => {
+      console.log('点击图层', layer)
+    }
+  }
+})
+
+// 添加图层
+editorStore.addLayer({
+  uuid: 'layer-1',
+  equipmentName: '机器人',
+  x: 100,
+  y: 100,
+  width: 200,
+  height: 200,
+  // ... 其他属性
+})
+
+// 选择图层
+editorStore.selectLayer('layer-1')
+
+// 访问当前方案
+console.log(editorStore.currentCase.value)
+console.log(editorStore.scene.value)
+```
+
+---
+
+#### useAppStore
+
+应用仓库，用于预览模式的容器管理。
+
+**返回值：**
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| currentCase | `ComputedRef<ICase \| null>` | 当前方案 |
+| initContainer | `(options: IContainer, caseUuid: string) => void` | 初始化容器并加载指定案例 |
+| resizeContainer | `() => void` | 重置容器大小 |
+| destroyContainer | `() => void` | 销毁容器 |
+| operating | `Ref<ILayerOperating \| null>` | 当前操作状态 |
+
+**使用示例：**
+
+```typescript
+import { useAppStore } from '@jnrs/lingshu-smart/stores'
+
+const appStore = useAppStore()
+
+// 初始化预览容器
+appStore.initContainer({
+  appDomId: 'preview-app',
+  appEditable: false,
+  actions: {
+    onTap: (layer, data) => {
+      console.log('点击设备', data)
+    }
+  }
+}, 'case-uuid-123')
+```
+
+---
+
+### @jnrs/lingshu-smart/composables 模块
+
+#### useStepRecord
+
+编辑操作记录 Hook，提供撤销/重做功能。
+
+**返回值：**
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| operationRecordStatus | `ComputedRef<{ canUndo: boolean; canRedo: boolean; totalSteps: number; currentIndex: number }>` | 操作记录状态 |
+| recordOperation | `(caseData: ICase[], hash: string) => void` | 记录操作（防抖 300ms） |
+| undo | `() => void` | 撤销操作 |
+| redo | `() => void` | 重做操作 |
+| jumpToStep | `(index: number) => void` | 跳转到任意历史点 |
+| clearRecord | `() => void` | 清空记录 |
+
+**使用示例：**
+
+```typescript
+import { useStepRecord } from '@jnrs/lingshu-smart/composables'
+
+const {
+  operationRecordStatus,
+  recordOperation,
+  undo,
+  redo,
+  jumpToStep
+} = useStepRecord()
+
+// 检查是否可以撤销/重做
+console.log(operationRecordStatus.value.canUndo)
+console.log(operationRecordStatus.value.canRedo)
+
+// 记录操作（通常在数据变更后调用）
+import objectHash from 'object-hash'
+const hash = objectHash(cases.value)
+recordOperation(cases.value, hash)
+
+// 撤销
+undo()
+
+// 重做
+redo()
+
+// 跳转到第 5 步
+jumpToStep(5)
+```
+
+**特性：**
+
+- 最多保存 10 条操作记录
+- 防抖处理（300ms），避免频繁记录
+- 支持跳转到任意历史点
+- 自动检测数据变化，避免重复记录
+- TODO: 未来可迁移至 IndexedDB 以支持持久化
+
+---
+
+### @jnrs/lingshu-smart/controller 模块
+
+#### AppController
+
+主画布、模型容器控制器，基于 LeaferJS 引擎。
+
+**构造函数：**
+
+```typescript
+constructor(options: IContainer = {})
+```
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| options | `IContainer` | `{}` | 容器配置 |
+
+**方法：**
+
+###### start
+
+启动/重启引擎
+
+**返回值：** `void`
+
+###### destroy
+
+销毁引擎（异步销毁，不会立即执行）
+
+**返回值：** `void`
+
+###### setZoom
+
+控制视图的缩放
+
+**参数：**
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| zoomType | `'fit' \| number` | `'fit'` | 缩放类型 |
+| duration | `number` | `0.5` | 动画时长（秒） |
+
+**返回值：** `void`
+
+###### setTree
+
+修改 tree 配置
+
+**参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| data | `IScene` | 场景配置，不传则重置为默认配置 |
+
+**返回值：** `void`
+
+###### getTreeElements
+
+tree 层查找元素
+
+**返回值：** `Array` - 元素数组
+
+###### addModel
+
+添加模型到画布
+
+**参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| layer | `ILayer` | 图层数据 |
+
+**返回值：** `ModelAbs` - 模型实例
+
+###### removeModel
+
+从画布移除模型
+
+**参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| uuid | `string` | 图层 UUID |
+
+**返回值：** `void`
+
+###### updateModel
+
+更新模型属性
+
+**参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| uuid | `string` | 图层 UUID |
+| data | `Partial<ILayer>` | 更新的属性 |
+
+**返回值：** `void`
+
+###### clearAll
+
+清空所有模型
+
+**返回值：** `void`
+
+**使用示例：**
+
+```typescript
+import { AppController } from '@jnrs/lingshu-smart/controller'
+
+const controller = new AppController({
+  appDomId: 'app-container',
+  appEditable: true,
+  autoStart: true,
+  actions: {
+    onTap: (layer, data) => {
+      console.log('点击', data)
+    }
+  }
+})
+
+// 启动引擎
+controller.start()
+
+// 设置场景
+controller.setTree({
+  width: 1920,
+  height: 1080,
+  zoomType: 'fit',
+  fill: { type: 'solid', color: '#fff', opacity: 1, stops: [] }
+})
+
+// 添加模型
+const model = controller.addModel(layerData)
+
+// 更新模型
+controller.updateModel('layer-uuid', { x: 100, y: 100 })
+
+// 移除模型
+controller.removeModel('layer-uuid')
+
+// 销毁
+controller.destroy()
+```
+
+---
+
+#### EditorController
+
+编辑器控制器，提供编辑相关的功能。
+
+**说明：** EditorController 继承自 AppController，额外提供编辑器特有的功能，如选中框、辅助线、网格等。
+
+**主要功能：**
+
+- 图层选中高亮
+- 拖拽移动
+- 旋转、缩放
+- 对齐辅助线
+- 网格显示
+- 层级管理（zIndex）
+
+---
+
+### @jnrs/lingshu-smart/types 模块
+
+详细的类型定义请参考上述"核心类型"部分，包括：
+
+- **场景相关：** IScene, ICase
+- **图层相关：** ILayer, IModel, IStationSlotConfig, IResourceConfig
+- **交互相关：** IEventHandler, IContainer, InteractiveUi
+- **枚举类型：** EnumStepType, EnumTag, EnumModel, EnumComponent, EnumResourceType
+
+所有类型均从 `@jnrs/lingshu-smart` 主模块导出。
+
+---
+
+### @jnrs/lingshu-smart/constants 模块
+
+#### CASE_INIT
+
+新方案默认值
+
+```typescript
+const CASE_INIT: ICase = {
+  uuid: '',
+  title: '',
+  isActive: false,
+  layers: [],
+  scene: {
+    width: 1920,
+    height: 1080,
+    zoomType: 'fit',
+    fill: {
+      type: 'solid',
+      color: '#000',
+      opacity: 1,
+      stops: []
+    },
+    texture: ''
+  }
+}
+```
+
+#### DEFAULT_LAYER
+
+新图层默认值
+
+```typescript
+const DEFAULT_LAYER: IModel = {
+  rawData: { id: '' },
+  uuid: '',
+  equipmentName: '',
+  width: 0,
+  height: 0,
+  x: 0,
+  y: 0,
+  percentX: 0,
+  percentY: 0,
+  rotation: 0,
+  scale: 1,
+  zIndex: 1,
+  visible: true,
+  clickable: true,
+  menuClickable: true,
+  draggable: false,
+  editable: true,
+  selected: false
+}
+```
+
+---
+
+## 🔍 完整使用示例
+
+### 编辑器模式
+
+```vue
+<template>
+  <LingshuSmartEditor :actions="editorActions" />
+</template>
+
+<script setup>
+import { LingshuSmartEditor } from '@jnrs/lingshu-smart/components'
+import { useDataStore } from '@jnrs/lingshu-smart/stores'
+
+const dataStore = useDataStore()
+
+const editorActions = {
+  async loadCases(id) {
+    const res = await fetch(`/api/cases/${id || ''}`)
+    const data = await res.json()
+    dataStore.updateCases(data)
+    return data
+  },
+  saveCases(cases) {
+    fetch('/api/cases', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(cases)
+    })
+  },
+  handlePreview(currentCase) {
+    window.open(`/preview/${currentCase?.uuid}`)
+  },
+  handleExit() {
+    if (confirm('确定要退出吗？')) {
+      window.history.back()
+    }
+  }
+}
+</script>
+```
+
+### 预览模式
+
+```vue
+<template>
+  <LingshuSmartPreview
+    :case-uuid="caseUuid"
+    :actions="previewActions"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { LingshuSmartPreview } from '@jnrs/lingshu-smart/components'
+
+const caseUuid = ref('abc-123-def')
+
+const previewActions = {
+  async loadCases() {
+    const res = await fetch('/api/cases')
+    return res.json()
+  },
+  onTap(layer, data) {
+    console.log('点击设备:', data)
+    // 显示设备详情
+  },
+  onMenuTap(layer, data) {
+    console.log('右键菜单:', data)
+    // 显示右键菜单
+  }
+}
+</script>
+```
+
+### 使用 Store
+
+```typescript
+import { useDataStore, useEditorStore, useStepRecord } from '@jnrs/lingshu-smart/stores'
+
+// 数据管理
+const dataStore = useDataStore()
+dataStore.updateCases(cases)
+dataStore.selectCase('case-uuid')
+
+// 编辑器管理
+const editorStore = useEditorStore()
+editorStore.initContainer({
+  appDomId: 'editor',
+  appEditable: true
+})
+editorStore.addLayer(layerData)
+editorStore.selectLayer('layer-uuid')
+
+// 撤销/重做
+const stepRecord = useStepRecord()
+stepRecord.undo()
+stepRecord.redo()
+```
+
+---
+
+## 📝 注意事项
+
+1. **引擎初始化**：使用前必须调用 `initContainer` 初始化 LeaferJS 引擎
+2. **方案管理**：方案数据通过 `useDataStore` 统一管理，确保数据一致性
+3. **编辑器 vs 预览器**：
+   - 编辑器模式（`appEditable: true`）支持拖拽、旋转、缩放等编辑操作
+   - 预览模式（`appEditable: false`）为只读模式，仅支持交互事件
+4. **性能优化**：
+   - `updateScene` 和 `recordOperation` 均使用防抖处理
+   - 大量图层时建议启用虚拟化渲染
+5. **类型安全**：所有 API 均提供完整的 TypeScript 类型定义
+6. **事件处理**：通过 `actions` 配置自定义事件回调，实现业务逻辑解耦
+7. **资源管理**：组件卸载时记得调用 `destroyContainer` 清理引擎资源
+8. **版本兼容**：基于 LeaferJS 构建，请确保版本兼容性
+
+---
+
+## 🛠 技术栈
+
+- **Vue 3** - 前端框架
+- **TypeScript** - 类型系统
+- **Pinia** - 状态管理
+- **LeaferJS** - 2D 图形引擎
+- **Element Plus** - UI 组件库
+- **object-hash** - 对象哈希计算（用于撤销/重做）
+- **lodash-es** - 工具函数库
+
+---
+
+## 📄 License
+
+UNLICENSED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jnrs/lingshu-smart",
-  "version": "2.2.19",
+  "version": "2.2.21",
   "description": "LingShu Smart 2D Digital Twin System.",
   "keywords": [
     "jnrs",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTIC.md",
     "LICENSE"
   ],
   "exports": {
@@ -45,7 +46,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.22",
     "vue-i18n": "^9.14.5",
-    "@jnrs/shared": "1.1.24"
+    "@jnrs/shared": "1.1.25"
   },
   "devDependencies": {
     "@types/lodash-es": "^4.17.12",