@jnrs/lingshu-smart 2.2.24 → 2.2.27

package/AGENTS.md

@@ -0,0 +1,689 @@
+# @jnrs/lingshu-smart API 文档
+
+## ✨ 介绍
+
+巨能前端 2D 数字孪生系统，即「灵枢智造」。提供 2D 数字孪生编辑器和运行看板功能，基于 LeaferJS 引擎构建。
+
+---
+
+## 🚀 Vue 模块使用说明（Playground 示例）
+
+工程内 `src/playground/` 提供了两个最小集成示例，分别对应**编辑模式**与**预览/运行模式**。业务侧接入时，可直接参考这两个文件的结构。
+
+| 文件               | 组件                  | 场景                              |
+| ------------------ | --------------------- | --------------------------------- |
+| `EditPageDemo.vue` | `LingshuSmartEditor`  | 方案可视化编辑                    |
+| `ViewPageDemo.vue` | `LingshuSmartPreview` | 方案运行看板 + WebSocket 实时驱动 |
+
+---
+
+### EditPageDemo.vue — 编辑器模式
+
+**职责：** 加载方案列表、保存方案、跳转预览、退出编辑页。编辑器内部自行管理画布与图层，业务层只需实现 `actions` 回调。
+
+**核心结构：**
+
+```vue
+<script setup lang="ts">
+import type { ICase } from '@/types'
+import LingshuSmartEditor from '@/components/editor/index.vue'
+
+const loadCases = async (requestId?: string): Promise<ICase[]> => {
+  const res = await fetch(`/json/cases.json?requestId=${requestId}`)
+  const data = await res.json()
+  return data.data
+}
+
+const saveCases = (data?: ICase[]) => {
+  /* 持久化到后端 */
+}
+const handlePreview = (currentCase?: ICase) => {
+  window.open(`/preview/${currentCase?.uuid}`)
+}
+const handleExit = () => {
+  /* 退出逻辑 */
+}
+</script>
+
+<template>
+  <LingshuSmartEditor :actions="{ loadCases, saveCases, handlePreview, handleExit }" />
+</template>
+```
+
+**EditorActions 回调说明：**
+
+| 回调            | 类型                                | 触发时机                    | 说明                                                |
+| --------------- | ----------------------------------- | --------------------------- | --------------------------------------------------- |
+| `loadCases`     | `(id?: string) => Promise<ICase[]>` | 编辑器初始化 / 方案管理弹窗 | **必填**。返回方案列表，组件内部写入 `useDataStore` |
+| `saveCases`     | `(cases?: ICase[]) => void`         | 点击保存按钮                | 将当前全部方案提交后端                              |
+| `handlePreview` | `(currentCase?: ICase) => void`     | 点击预览按钮                | 通常跳转至预览页并携带 `uuid`                       |
+| `handleExit`    | `() => void`                        | 点击退出按钮                | 返回上一页或关闭窗口                                |
+
+**注意：** 编辑模式不涉及 `onMessage` / `operating`。设备运转动画仅在预览看板中通过 WebSocket 驱动。
+
+---
+
+### ViewPageDemo.vue — 预览/运行模式
+
+**职责：** 加载并展示指定方案、响应用户交互、接收 WebSocket 消息并驱动设备动画。
+
+**核心结构：**
+
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+import type { ICase, ILayer, ILayerOperating, InteractiveUi } from '@/types'
+import { EnumModel } from '@/types'
+import { transRuntimeToPixel } from '@/utils'
+import LingshuSmartPreview from '@/components/preview/index.vue'
+
+const lingshuSmartPreviewRef = ref()
+const currentCaseId = ref('')
+
+const currentCase = computed(() => lingshuSmartPreviewRef.value?.currentCase)
+
+const loadCases = async (requestId?: string): Promise<ICase[]> => {
+  /* 同编辑器 */
+}
+
+// 交互事件（可选）
+const onTap = (layer: ILayer, data: InteractiveUi) => {
+  /* 左键点击 */
+}
+const onMenuTap = (layer: ILayer, data: InteractiveUi) => {
+  /* 右键点击 */
+}
+const onDragEnd = (layer: ILayer, data: InteractiveUi) => {
+  /* 拖拽结束 */
+}
+
+// 驱动设备运转 — 转发至预览组件 expose 的方法
+const operating = (data: ILayerOperating) => {
+  lingshuSmartPreviewRef.value?.operating(data)
+}
+
+// WebSocket 消息入口 — 见下文「onMessage 编写指南」
+const onMessage = (rawMessage: any) => {
+  /* ... */
+}
+
+onMounted(() => {
+  // 从 URL 解析方案 UUID，例如 /preview/abc-123
+  const VIEW_PATH = '/preview/'
+  if (location.pathname.includes(VIEW_PATH)) {
+    currentCaseId.value = location.pathname.split(VIEW_PATH)[1]
+  }
+})
+</script>
+
+<template>
+  <LingshuSmartPreview
+    ref="lingshuSmartPreviewRef"
+    :case-uuid="currentCaseId"
+    :actions="{ loadCases, onTap, onMenuTap, onDragEnd }"
+  />
+</template>
+```
+
+**PreviewActions 回调说明：**
+
+| 回调        | 类型                                | 触发时机               | 说明                                    |
+| ----------- | ----------------------------------- | ---------------------- | --------------------------------------- |
+| `loadCases` | `(id?: string) => Promise<ICase[]>` | 方案列表为空时自动调用 | **必填**。与编辑器共用同一数据源        |
+| `onTap`     | `(layer, data) => void`             | 左键点击设备/子组件    | `layer` 为父图层，`data` 为实际点击目标 |
+| `onMenuTap` | `(layer, data) => void`             | 右键点击               | 可用于弹出上下文菜单                    |
+| `onDragEnd` | `(layer, data) => void`             | 拖拽结束               | 预览模式下部分设备支持拖拽              |
+
+**Preview 组件 expose：**
+
+| 属性/方法     | 类型                              | 说明                 |
+| ------------- | --------------------------------- | -------------------- |
+| `currentCase` | `ICase \| null`                   | 当前加载的方案       |
+| `operating`   | `(data: ILayerOperating) => void` | 驱动指定设备运转动画 |
+
+**Props：**
+
+| 属性            | 类型             | 默认值    | 说明                        |
+| --------------- | ---------------- | --------- | --------------------------- |
+| `caseUuid`      | `string`         | —         | **必填**。要展示的方案 UUID |
+| `actions`       | `PreviewActions` | `{}`      | 事件与数据加载回调          |
+| `appHittable`   | `boolean`        | `true`    | 画布是否可交互              |
+| `appFill`       | `string`         | `#424242` | 容器背景色                  |
+| `hideSceneFill` | `boolean`        | `false`   | 是否隐藏场景背景            |
+
+---
+
+## 📡 onMessage 编写指南
+
+预览看板通过 WebSocket（或 SSE、轮询等）接收后端推送，在 `onMessage` 中将原始消息**转换为 `ILayerOperating`**，再调用 `operating()` 驱动画布。
+
+### 数据流
+
+```
+WebSocket 原始消息
+  → onMessage 校验 & 解析
+  → 按 payload.type 分支映射
+  → operating(ILayerOperating)
+  → AppController.businessMap 匹配 `${className}_${id}`
+  → 对应 ModelAbs.handleOperation → 子组件动画
+```
+
+### 消息格式约定
+
+参考 `src/playground/mockWebSocketData.ts`，推荐外层结构：
+
+```typescript
+interface WebSocketMessage {
+  traceId: string // 链路追踪 ID
+  type: 'update' // 消息类型，目前仅处理 'update'
+  payload: Payload // 业务载荷，内含 payload.type 标识设备/资源
+}
+```
+
+**入口校验模板：**
+
+```typescript
+const onMessage = (rawMessage: any) => {
+  if (!rawMessage?.type || !rawMessage?.payload) {
+    console.warn('无效的 WebSocket 消息格式', rawMessage)
+    return
+  }
+
+  const { type, payload } = rawMessage
+
+  if (type === 'update') {
+    switch (payload.type) {
+      case 'Resource':
+        /* 资源增删 */ break
+      case 'MachineTool':
+        /* 机床状态 */ break
+      case 'ResourceStore':
+        /* 资源库/随行托 */ break
+      case 'SingleJointRobot':
+        /* 单关节机器人 */ break
+      case 'DoubleJointRobot':
+        /* 双关节机器人 */ break
+      case 'Rgv':
+        /* RGV */ break
+      case 'LoadingStation':
+        /* 装载站 */ break
+      case 'MarkingMachine':
+        /* 打标机 */ break
+      case 'CleaningMachine':
+        /* 清洗机 */ break
+      case 'Rail':
+        /* 轨道拖链 */ break
+    }
+  }
+}
+```
+
+### 匹配规则（重要）
+
+`operating()` 通过 `className + id` 定位画布上的设备：
+
+- `id` 作为前后端对于设备的唯一识别字段
+- `rawData` 为后端接口返回的原始数据 payload，其中包含 id 属性，如果设备注册了交互事件，则该对象会存在于回调函数的返回值中，供“点击设备后弹窗展示设备详情”等业务需求使用
+- `className` 使用 `EnumModel` 枚举值，例如 `EnumModel.MACHINE_TOOL`
+- 资源增删时，`addType` / `removeType` 为目标设备的 `className`，`addId` / `removeId` 为目标设备 `id`
+
+匹配失败时控制台输出：`模型操作失败: 模型未匹配到`。
+
+### 各业务场景映射示例
+
+#### 1. 资源增删（`payload.type === 'Resource'`）
+
+Resource 不在编辑器中进行维护，是根据业务数据动态添加或删除的一类 UI 图形，如“托盘”、“刀具”。
+同一消息可同时包含新增与移除操作。
+
+```typescript
+// 新增资源到设备工位
+if (payload.addType && payload.addId) {
+  operating({
+    className: payload.addType, // 如 EnumModel.MACHINE_TOOL
+    id: payload.addId,
+    rawData: payload,
+    resource: {
+      handleType: 'add',
+      resourceType: payload.resourceType, // EnumResourceType.PALLET | TOOL
+      name: payload.name,
+      color: payload.status === 3 ? 'green' : '#424242',
+      index: payload.addSiteNumber, // 工位槽索引
+      rawData: payload
+    }
+  })
+}
+
+// 从设备工位移除资源
+if (payload.removeType && payload.removeId) {
+  operating({
+    className: payload.removeType,
+    id: payload.removeId,
+    rawData: payload,
+    resource: {
+      handleType: 'remove',
+      resourceType: payload.resourceType,
+      index: payload.removeSiteNumber,
+      rawData: payload
+    }
+  })
+}
+```
+
+#### 2. 机床（`payload.type === 'MachineTool'`）
+
+```typescript
+operating({
+  className: EnumModel.MACHINE_TOOL,
+  id: payload.id,
+  rawData: payload,
+  light: {
+    color: payload.status === 2 ? 'green' : '#424242',
+    blinking: payload.status !== 2,
+    rotating: payload.status === 2
+  },
+  progress: {
+    percent: payload.percent, // 0 ~ 1
+    textContent: payload.status === 2 ? '运行中' : '待机中'
+  },
+  entrance: {
+    isIn: payload.isIn,
+    isOut: payload.isOut
+  },
+  stationRotatable: payload.stationRotatable // false 横向 / true 纵向
+})
+```
+
+#### 3. 资源库 / 随行托（`payload.type === 'ResourceStore'`）
+
+```typescript
+operating({
+  className: EnumModel.RESOURCE_STORE,
+  id: payload.id,
+  rawData: payload,
+  light: {
+    color: payload.status === 2 ? 'green' : '#424242',
+    blinking: payload.status === 2
+  },
+  x: transRuntimeToPixel(payload.x, 1, 'width') // 沿轨道移动时需转换
+})
+```
+
+#### 4. 单关节机器人（`payload.type === 'SingleJointRobot'`）
+
+```typescript
+operating({
+  className: EnumModel.SINGLE_JOINT_ROBOT,
+  id: payload.id,
+  rawData: payload,
+  light: {
+    color: payload.status === 2 ? 'green' : '#424242',
+    blinking: payload.status === 2
+  },
+  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  j1: payload.j1, // 一级关节角度（度）
+  currentFixture: payload.currentFixture // EnumResourceType.PALLET | TOOL
+})
+```
+
+#### 5. 双关节机器人（`payload.type === 'DoubleJointRobot'`）
+
+```typescript
+operating({
+  className: EnumModel.DOUBLE_JOINT_ROBOT,
+  id: payload.id,
+  rawData: payload,
+  light: {
+    color: payload.status === 0 ? '#f30' : '#424242'
+  },
+  currentFixture: payload.currentFixture,
+  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  j1: payload.j1,
+  j2: payload.j2
+})
+```
+
+#### 6. 装载站（`payload.type === 'LoadingStation'`）
+
+```typescript
+operating({
+  className: EnumModel.LOADING_STATION,
+  id: payload.id,
+  rawData: payload,
+  light: { color: payload.status === 2 ? 'green' : '#424242', blinking: payload.status === 2 },
+  progress: { percent: payload.percent, textContent: payload.textContent },
+  entrance: { isIn: payload.isIn, isOut: payload.isOut },
+  stationRotatable: payload.stationRotatable
+})
+```
+
+#### 7. 打标机（`payload.type === 'MarkingMachine'`）
+
+```typescript
+operating({
+  className: EnumModel.MARKING_MACHINE,
+  id: payload.id,
+  rawData: payload,
+  light: { color: payload.lightColor, blinking: payload.blinking },
+  progress: { percent: payload.percent, textContent: payload.textContent },
+  entrance: { isIn: payload.isIn, isOut: payload.isOut },
+  laserSiteNumberArray: payload.laserSiteNumberArray // { site, active }[]
+})
+```
+
+#### 8. 清洗机（`payload.type === 'CleaningMachine'`）
+
+```typescript
+operating({
+  className: EnumModel.CLEANING_MACHINE,
+  id: payload.id,
+  rawData: payload,
+  light: { color: payload.lightColor, blinking: payload.blinking },
+  progress: { percent: payload.percent, textContent: payload.textContent },
+  entrance: { isIn: payload.isIn, isOut: payload.isOut }
+})
+```
+
+#### 9. RGV（`payload.type === 'Rgv'`）
+
+```typescript
+operating({
+  className: EnumModel.RGV,
+  id: payload.id,
+  rawData: payload,
+  light: { color: payload.lightColor, blinking: payload.blinking },
+  x: transRuntimeToPixel(payload.x, 1, 'width'),
+  j1: payload.j1, // 旋转角度
+  forkXY: payload.forkXY, // 货叉横向移动比例 0~1
+  forkZ: payload.forkZ // 货叉升降比例 0~1
+})
+```
+
+#### 10. 轨道拖链（`payload.type === 'Rail'`）
+
+```typescript
+operating({
+  className: EnumModel.RAIL,
+  id: payload.id, // 轨道图层 id
+  rawData: payload,
+  x: payload.x, // 拖链位置（像素，无需 runtime 转换）
+  botId: payload.botId // 关联的移动设备 rawData.id
+})
+```
+
+### 运行时坐标转换
+
+后端推送的 `x` / `y` 通常为**物理/runtime 坐标**（如毫米），画布使用**像素坐标**。转换公式：
+
+```typescript
+import { transRuntimeToPixel } from '@jnrs/lingshu-smart'
+
+// 宽方向：pixel = runtimeVal * (scene.width / scene.runtime_width)
+const pixelX = transRuntimeToPixel(payload.x, 1, 'width')
+const pixelY = transRuntimeToPixel(payload.y, 1, 'height')
+```
+
+**前提：** 方案 `IScene` 中需配置 `runtime_width` / `runtime_height`。该函数读取 `useEditorStore().scene`，预览页需确保场景数据已加载。
+
+### WebSocket 接入示例
+
+```typescript
+onMounted(() => {
+  const ws = new WebSocket('wss://your-server/ws')
+  ws.onmessage = (event) => {
+    try {
+      onMessage(JSON.parse(event.data))
+    } catch (e) {
+      console.error('WebSocket 消息解析失败', e)
+    }
+  }
+})
+```
+
+本地调试可复用 `mockWebSocketData.ts` 中的 `firstBatchMessages` / `secondBatchMessages`。
+
+---
+
+## 📊 ILayerOperating 类型参考
+
+`ILayerOperating` 是设备层运转状态的**联合类型**，用于 `operating()` 入参。所有子类型均继承基类 `IModelOperating`，并通过 `className` 字段区分具体设备。
+
+### 基类 IModelOperating
+
+| 属性        | 类型                 | 必填 | 说明                                |
+| ----------- | -------------------- | ---- | ----------------------------------- |
+| `id`        | `string`             | ✓    | 业务设备 ID，对应图层 `rawData.id`  |
+| `className` | `EnumModel`          | ✓    | 设备类型枚举，用于 businessMap 匹配 |
+| `rawData`   | `IRowData`           | ✓    | 原始业务数据，建议传入完整 payload  |
+| `resource`  | `IResourceOperating` | —    | 工位槽资源增删（多设备共用）        |
+
+### 联合类型 ILayerOperating
+
+```typescript
+type ILayerOperating =
+  | IMachineToolOperating
+  | ILoadingStationOperating
+  | IMarkingMachineOperating
+  | ICleaningMachineOperating
+  | ISingleJointRobotOperating
+  | IDoubleJointRobotOperating
+  | IRGVOperating
+  | IRailOperating
+  | IResourceStoreOperating
+```
+
+### 子类型一览
+
+| 类型                         | className            | 特有属性                                                           | 子组件能力                                         | 典型 payload.type  |
+| ---------------------------- | -------------------- | ------------------------------------------------------------------ | -------------------------------------------------- | ------------------ |
+| `IMachineToolOperating`      | `MACHINE_TOOL`       | `light?`, `progress?`, `entrance?`, `stationRotatable?`            | 状态灯（含旋转）、进度条、出入口、工位槽           | `MachineTool`      |
+| `ILoadingStationOperating`   | `LOADING_STATION`    | `light?`, `progress?`, `entrance?`, `stationRotatable?`            | 状态灯（无旋转）、进度条、出入口、工位槽           | `LoadingStation`   |
+| `IMarkingMachineOperating`   | `MARKING_MACHINE`    | `light?`, `progress?`, `entrance?`, `laserSiteNumberArray?`        | 状态灯、进度条、出入口、工位槽、激光工位指示       | `MarkingMachine`   |
+| `ICleaningMachineOperating`  | `CLEANING_MACHINE`   | `light?`, `progress?`, `entrance?`                                 | 状态灯、进度条、出入口、工位槽                     | `CleaningMachine`  |
+| `ISingleJointRobotOperating` | `SINGLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `currentFixture?`, `resource?`        | 双状态灯、轨道位移、关节旋转、夹具切换、双工位槽   | `SingleJointRobot` |
+| `IDoubleJointRobotOperating` | `DOUBLE_JOINT_ROBOT` | `light?`, `x?`, `y?`, `j1?`, `j2?`, `currentFixture?`, `resource?` | 双状态灯、轨道位移、双关节旋转、夹具切换、双工位槽 | `DoubleJointRobot` |
+| `IRGVOperating`              | `RGV`                | `light?`, `x?`, `j1?`, `forkXY?`, `forkZ?`, `resource?`            | 双状态灯、轨道位移、旋转、货叉 XY/Z、双工位槽      | `Rgv`              |
+| `IRailOperating`             | `RAIL`               | `x?`, `botId?`                                                     | 拖链动画（关联 botId 的设备移动时拖链跟随）        | `Rail`             |
+| `IResourceStoreOperating`    | `RESOURCE_STORE`     | `light?`, `x?`, `resource?`                                        | 状态灯、轨道位移、托盘/刀具工位槽                  | `ResourceStore`    |
+
+### 子类型字段详情
+
+#### IMachineToolOperating
+
+| 属性               | 类型                 | 说明                                    |
+| ------------------ | -------------------- | --------------------------------------- |
+| `light`            | `ILightOperating`    | 支持 `rotating`（运行中旋转灯效）       |
+| `progress`         | `IProgressOperating` | 加工进度 0~1                            |
+| `entrance`         | `IEntranceOperating` | 物料入口/出口动画                       |
+| `stationRotatable` | `boolean`            | 工位容器方向：`false` 横向，`true` 纵向 |
+| `resource`         | `IResourceOperating` | 托盘等资源增删                          |
+
+#### ILoadingStationOperating
+
+| 属性               | 类型                                | 说明           |
+| ------------------ | ----------------------------------- | -------------- |
+| `light`            | `Omit<ILightOperating, 'rotating'>` | 不支持旋转灯效 |
+| `progress`         | `IProgressOperating`                | 装载进度       |
+| `entrance`         | `IEntranceOperating`                | 出入口状态     |
+| `stationRotatable` | `boolean`                           | 工位容器方向   |
+| `resource`         | `IResourceOperating`                | 工位槽资源     |
+
+#### IMarkingMachineOperating
+
+| 属性                   | 类型                                | 说明               |
+| ---------------------- | ----------------------------------- | ------------------ |
+| `light`                | `Omit<ILightOperating, 'rotating'>` | 状态灯             |
+| `progress`             | `IProgressOperating`                | 打标进度           |
+| `entrance`             | `IEntranceOperating`                | 出入口             |
+| `laserSiteNumberArray` | `ILaserSiteState[]`                 | 各激光工位打标状态 |
+| `resource`             | `IResourceOperating`                | 工位槽资源         |
+
+**ILaserSiteState：**
+
+| 属性     | 类型      | 说明         |
+| -------- | --------- | ------------ |
+| `site`   | `number`  | 工位序号     |
+| `active` | `boolean` | 是否正在打标 |
+
+#### ICleaningMachineOperating
+
+| 属性       | 类型                                | 说明       |
+| ---------- | ----------------------------------- | ---------- |
+| `light`    | `Omit<ILightOperating, 'rotating'>` | 状态灯     |
+| `progress` | `IProgressOperating`                | 清洗进度   |
+| `entrance` | `IEntranceOperating`                | 出入口     |
+| `resource` | `IResourceOperating`                | 工位槽资源 |
+
+#### ISingleJointRobotOperating
+
+| 属性             | 类型                 | 说明                        |
+| ---------------- | -------------------- | --------------------------- |
+| `light`          | `ILightOperating`    | 双灯同步更新                |
+| `x`              | `number`             | 沿轨道水平位移（像素）      |
+| `y`              | `number`             | 垂直位移（像素）            |
+| `j1`             | `number`             | 一级关节角度（度）          |
+| `currentFixture` | `EnumResourceType`   | 当前夹具：`Pallet` / `Tool` |
+| `resource`       | `IResourceOperating` | 托盘/刀具工位槽             |
+
+#### IDoubleJointRobotOperating
+
+| 属性             | 类型                 | 说明                   |
+| ---------------- | -------------------- | ---------------------- |
+| `light`          | `ILightOperating`    | 双灯同步更新           |
+| `x`              | `number`             | 沿轨道水平位移（像素） |
+| `y`              | `number`             | 垂直位移（像素）       |
+| `j1`             | `number`             | 一级关节角度（度）     |
+| `j2`             | `number`             | 二级关节角度（度）     |
+| `currentFixture` | `EnumResourceType`   | 当前夹具类型           |
+| `resource`       | `IResourceOperating` | 托盘/刀具工位槽        |
+
+#### IRGVOperating
+
+| 属性       | 类型                 | 说明                 |
+| ---------- | -------------------- | -------------------- |
+| `light`    | `ILightOperating`    | 双灯同步更新         |
+| `x`        | `number`             | 沿轨道位移（像素）   |
+| `j1`       | `number`             | 车体旋转角度（度）   |
+| `forkXY`   | `number`             | 货叉横向移动比例 0~1 |
+| `forkZ`    | `number`             | 货叉升降比例 0~1     |
+| `resource` | `IResourceOperating` | 托盘/刀具工位槽      |
+
+#### IRailOperating
+
+| 属性    | 类型     | 说明                        |
+| ------- | -------- | --------------------------- |
+| `x`     | `number` | 拖链延伸位置（像素）        |
+| `botId` | `string` | 关联移动设备的 `rawData.id` |
+
+#### IResourceStoreOperating
+
+| 属性       | 类型                 | 说明                           |
+| ---------- | -------------------- | ------------------------------ |
+| `light`    | `ILightOperating`    | 状态灯                         |
+| `x`        | `number`             | 沿轨道位移（像素，随行托场景） |
+| `resource` | `IResourceOperating` | 托盘/刀具工位槽增删            |
+
+### 子组件运转类型（IComponentOperating）
+
+被 `ILayerOperating` 各字段引用的子组件操作类型，定义于 `src/types/components/operating.types.ts`：
+
+| 类型                 | 用途       | 字段                                                                                     |
+| -------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `ILightOperating`    | 状态灯     | `color`（必填）, `blinking?`, `rotating?`                                                |
+| `IProgressOperating` | 进度条     | `percent`（0~1）, `textContent`                                                          |
+| `IEntranceOperating` | 出入口     | `isIn`, `isOut`                                                                          |
+| `IResourceOperating` | 工位槽资源 | `resourceType`, `index`, `handleType`（`'add'\|'remove'`）, `rawData`, `name?`, `color?` |
+
+---
+
+## 📦 模块总览
+
+| 模块路径                         | 说明                           |
+| -------------------------------- | ------------------------------ |
+| `@jnrs/lingshu-smart`            | 主模块，包含类型定义和工具函数 |
+| `@jnrs/lingshu-smart/components` | Vue 组件库（编辑器、预览器）   |
+| `@jnrs/lingshu-smart/locales`    | 国际化配置                     |
+
+---
+
+## 📋 API 详情
+
+### @jnrs/lingshu-smart 主模块
+
+#### 枚举 (Enums)
+
+**EnumModel — 设备类型**
+
+| 枚举值               | 说明         |
+| -------------------- | ------------ |
+| `SINGLE_JOINT_ROBOT` | 单关节机器人 |
+| `DOUBLE_JOINT_ROBOT` | 双关节机器人 |
+| `RGV`                | RGV          |
+| `MACHINE_TOOL`       | 机床         |
+| `MARKING_MACHINE`    | 打标机       |
+| `CLEANING_MACHINE`   | 清洗机       |
+| `LOADING_STATION`    | 装载站       |
+| `RAIL`               | 轨道         |
+| `RESOURCE_STORE`     | 资源库       |
+
+**EnumResourceType — 资源类型**
+
+| 枚举值   | 说明 |
+| -------- | ---- |
+| `PALLET` | 托盘 |
+| `TOOL`   | 刀具 |
+
+#### 核心类型
+
+**IScene — 场景配置**
+
+| 属性             | 类型              | 必填 | 说明                                 |
+| ---------------- | ----------------- | ---- | ------------------------------------ |
+| `width`          | `number`          | ✓    | 场景宽度（像素）                     |
+| `height`         | `number`          | ✓    | 场景高度（像素）                     |
+| `runtime_width`  | `number`          | —    | 运行时宽度（物理单位，用于坐标转换） |
+| `runtime_height` | `number`          | —    | 运行时高度                           |
+| `zoomType`       | `'fit' \| number` | ✓    | 缩放：`'fit'` 自适应或具体数值       |
+| `fill`           | `FillConfig`      | —    | 背景填充                             |
+| `texture`        | `string`          | —    | 纹理 URL                             |
+
+**ICase — 方案**
+
+| 属性       | 类型       | 必填 | 说明     |
+| ---------- | ---------- | ---- | -------- |
+| `uuid`     | `string`   | ✓    | 唯一标识 |
+| `isActive` | `boolean`  | ✓    | 是否激活 |
+| `title`    | `string`   | ✓    | 标题     |
+| `scene`    | `IScene`   | ✓    | 场景     |
+| `layers`   | `ILayer[]` | ✓    | 图层列表 |
+
+#### 工具函数
+
+| 函数                                                       | 说明                                                 |
+| ---------------------------------------------------------- | ---------------------------------------------------- |
+| `numberLoopGenerator(start, end, shouldLoop?)`             | 数字生成器                                           |
+| `linearIncrease(x, y, n, rate, callback)`                  | n 秒内线性递增                                       |
+| `transPercentAndPixel(val, size, precision?, getPercent?)` | 百分比 ↔ 像素                                       |
+| `transFraction(val, size)`                                 | 百分比转小数                                         |
+| `transRuntimeToPixel(val, precision?, type?)`              | 运行时坐标 → 像素（依赖 scene.runtime_width/height） |
+
+---
+
+## 📝 注意事项
+
+1. **编辑器 vs 预览：** 编辑模式配置 `EditorActions`；预览模式配置 `PreviewActions` + `onMessage` → `operating`
+2. **ID 匹配：** `operating` 的 `id` 必须与方案图层 `rawData.id` 一致，否则静默失败（在前端层面该值即为编辑器组件中业务数据配置中必填项 id 的值，需根据后端预先提供的设备 id 在编辑器中进行配置）
+3. **坐标系：** 轨道类设备的 `x` 通常需 `transRuntimeToPixel` 转换；`IRailOperating.x` 直接使用像素
+4. **资源消息：** `Resource` 类型不对应独立图层，通过目标设备的 `resource` 字段操作工位槽
+5. **引擎生命周期：** 组件卸载时自动 `destroyContainer`；手动集成需自行销毁
+6. **类型安全：** 所有 API 均导出 TypeScript 类型，推荐 `import type { ILayerOperating, EnumModel } from '@jnrs/lingshu-smart'`
+
+---
+
+## 🛠 技术栈
+
+- Vue 3 + TypeScript + Pinia
+- LeaferJS 2D 图形引擎
+- Element Plus UI
+
+---

package/README.md

@@ -60,4 +60,4 @@ interface EditorActions {
 }
 ```
 
-详细文档请查看 `AGENTIC.md`
+详细文档请查看 `AGENTS.md`