@jnrs/lingshu-smart 2.2.32 → 2.2.34

package/AGENTS.md

@@ -164,7 +164,7 @@ WebSocket 原始消息
   → onMessage 校验 & 解析
   → 按 payload.type 分支映射
   → operating(ILayerOperating)
-  → AppController.businessMap 匹配 `${className}_${id}`
+  → AppController.businessMap 三级匹配 `${className}_${id}` → 工位号
   → 对应 ModelAbs.handleOperation → 子组件动画
 ```
 
@@ -220,12 +220,13 @@ const onMessage = (rawMessage: any) => {
 
 ### 匹配规则（重要）
 
-`operating()` 通过 `className + id` 定位画布上的设备：
+`operating()` 通过三级匹配定位画布上的设备：`className → id → 工位号`：
 
 - `id` 作为前后端对于设备的唯一识别字段
-- `rawData` 为后端接口返回的原始数据 payload，其中包含 id 属性，如果设备注册了交互事件，则该对象会存在于回调函数的返回值中，供“点击设备后弹窗展示设备详情”等业务需求使用
+- `rawData` 为后端接口返回的原始数据 payload，其中包含 id 属性，如果设备注册了交互事件，则该对象会存在于回调函数的返回值中，供"点击设备后弹窗展示设备详情"等业务需求使用
 - `className` 使用 `EnumModel` 枚举值，例如 `EnumModel.MACHINE_TOOL`
 - 资源增删时，`addType` / `removeType` 为目标设备的 `className`，`addId` / `removeId` 为目标设备 `id`
+- **工位号匹配（三级）**：当同一 `id` 的设备（如 `ResourceStore`）在画布上被拆分为多个 UI（不同工位号范围）时，`businessMap` 以数组存储同 `className + id` 的多个模型，再通过 `resource.index`（工位号）匹配到具体 UI。模型通过 `containsStationIndex` 方法判断是否包含该工位号。仅有一个模型时直接使用，无需工位号匹配
 
 匹配失败时控制台输出：`模型操作失败: 模型未匹配到`。
 
@@ -690,6 +691,58 @@ type ILayerOperating =
 4. **资源消息：** `Resource` 类型不对应独立图层，通过目标设备的 `resource` 字段操作工位槽
 5. **引擎生命周期：** 组件卸载时自动 `destroyContainer`；手动集成需自行销毁
 6. **类型安全：** 所有 API 均导出 TypeScript 类型，推荐 `import type { ILayerOperating, EnumModel } from '@jnrs/lingshu-smart'`
+7. **调试模式：** 500ms 内点击主容器（`#lingshu-smart`）10 次可打开调试配置面板，支持运行时配置日志等级、阴影/动画开关、FPS 限制、交互禁用、性能统计。配置通过 `localStorage` 持久化，详见 README「调试功能」章节。
+
+---
+
+## 🐛 调试系统
+
+### 架构
+
+| 模块                               | 职责                                                             |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `utils/logger.ts`                  | 统一日志工具，支持 tag 着色、LogLevel 过滤、`operating` 追踪级别 |
+| `utils/debug-flags.ts`             | 模块级动画标志位，供 UI 组件直接导入控制循环动画                 |
+| `utils/performance-stats.ts`       | 性能统计工具，记录运行时长和 WebSocket 数据接收量                |
+| `stores/useDebugStore.ts`          | 全局调试配置 Pinia store，localStorage 持久化                    |
+| `composables/useDebugEasterEgg.ts` | 调试触发检测：500ms 内 10 次点击打开面板                         |
+| `components/debug/DebugPanel.vue`  | 调试配置对话框 UI                                                |
+| `controller/AppController.ts`      | 提供 `toggleShadows` / `toggleAnimations` / `setFps` 方法        |
+
+### 日志系统
+
+```typescript
+import { createLogger, setLogLevel } from '@/utils/logger'
+
+const logger = createLogger('MyModule')
+logger.log('消息') // LOG:MyModule 消息（彩色单徽章）
+logger.operating('操作, data=%o', data) // OPERATING:MyModule 操作, data={...}（紫色徽章）
+logger.warn('警告') // [WARN:MyModule] 警告（浏览器默认样式）
+```
+
+- `log`/`info`/`operating` 级别：使用彩色单徽章（`LEVEL:Tag` 合并显示）
+- `warn`/`error` 级别：纯文本前缀 `[LEVEL:Tag]`
+- `operating` 级别：用于追踪 UI 模型操作指令，在 `ModelAbs.handleOperation` 和 `ComponentAbs.handleOperation` 中自动埋点
+- 日志等级优先级：`none` < `error` < `warn` < `info` < `log` < `operating`
+- 默认：开发环境 `log`（全开），生产环境 `warn`
+
+### 调试配置项
+
+| 配置项       | store 字段             | AppController 方法        |
+| ------------ | ---------------------- | ------------------------- |
+| 日志显示等级 | `logLevel`             | `setLogLevel()`           |
+| 显示内外阴影 | `shadowsEnabled`       | `toggleShadows()`         |
+| 启用全局动画 | `animationsEnabled`    | `toggleAnimations()`      |
+| 全局 FPS     | `fpsMode`              | `setFps()`                |
+| 禁止所有交互 | `interactionsDisabled` | CSS `pointer-events`      |
+| 性能统计     | —                      | `trackWebSocketMessage()` |
+
+- **动画开关**：通过标志位控制循环动画（灯闪烁、入口通道动画等），关闭后保留静态状态（如灯颜色保持不变），不影响一次性动画（如机器人摆臂、进度条动画）
+- **阴影开关**：递归遍历所有元素切换 `shadow`/`innerShadow` 的 `visible` 属性，同时处理 `ShadowCanvas` 元素（`createShadow` 工厂创建的 Canvas 阴影）的 `visible` 属性
+
+### localStorage 存储
+
+统一 key 为 `lingshu-smart`，debug 配置存储在 `debug` 子对象中，与 `useDataStore` 的持久化数据共享同一 key。
 
 ---
 

package/README.md

@@ -49,3 +49,143 @@ import { transRuntimeToPixel, transPercentToPixel } from '@jnrs/lingshu-smart'
 ```
 
 详细文档请查看 [AGENTS.md](./AGENTS.md)
+
+## 🐛 调试功能
+
+本库内置了全局调试系统，支持运行时动态配置日志等级、渲染效果和交互状态，适用于开发环境排查问题或生产环境现场调试。
+
+### 调试模式触发
+
+在编辑器或预览页面中，500ms 内快速点击主容器（`#lingshu-smart`）10 次即可触发调试模式确认对话框，确认后打开调试配置面板。此操作类似 Android 系统的"开发者模式"快捷入口。
+
+> 该触发方式基于 DOM 原生 `click` 事件绑定，不受"禁止所有交互"配置的影响。
+
+### 调试配置面板
+
+| 配置项        | 说明                                                                                                     |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| 日志显示等级  | `none`（静默）/ `error` / `warn` / `info` / `log`（全部显示）/ `operating`（全部显示 + UI 模型操作追踪） |
+| 显示内外阴影  | 全局开关所有 Leafer 图形的 `shadow` / `innerShadow` 效果（含 ShadowCanvas 绘制阴影）                     |
+| 启用全局动画  | 全局开关循环动画（如灯闪烁、入口通道动画），关闭后保留静态状态（如灯颜色保持不变），不影响一次性动画     |
+| 全局 FPS      | 限制 Leafer 渲染帧率：`auto`（不限制）/ `30` / `60` / `120` FPS                                          |
+| 禁止所有交互  | 通过 CSS `pointer-events: none` 禁用主容器内所有子元素交互，调试模式开关不受此限制                       |
+| 语言/Language | 切换调试面板和性能统计的显示语言：`中文` / `English`                                                     |
+| 性能统计      | 显示页面运行开始时间、持续运行时长、WebSocket 消息接收次数和数据量                                       |
+
+### 日志系统
+
+日志工具 `createLogger(tag)` 创建带标签的 Logger 实例，输出格式为 `[等级:Tag] 消息内容`：
+
+- `log` / `info` / `operating` 级别：使用彩色单徽章样式（`LEVEL:Tag` 合并显示）
+- `warn` / `error` 级别：保留浏览器默认样式，以纯文本前缀显示
+
+```typescript
+import { createLogger, setLogLevel, type LogLevel } from '@jnrs/lingshu-smart/utils/logger'
+
+const logger = createLogger('MyModule')
+logger.log('模型已加载, uuid=%s', uuid) // LOG:MyModule 模型已加载, uuid=xxx
+logger.warn('配置缺失: %s', key) // [WARN:MyModule] 配置缺失: xxx
+logger.operating('执行操作, data=%o', data) // OPERATING:MyModule 执行操作, data={...}
+
+// 代码层面设置日志等级（优先级低于调试面板的运行时配置）
+setLogLevel('warn' as LogLevel) // 仅显示 warn + error
+```
+
+#### operating 日志级别
+
+`operating` 是最详细的日志级别，用于追踪 UI 模型的操作指令。在 `ModelAbs.handleOperation` 和 `ComponentAbs.handleOperation` 中自动埋点，记录模型的 `className`、`uuid`、`businessId` 和接收到的 `operating` 数据，便于追溯 WebSocket 数据与前端 UI 动作的对应关系，定位问题是后端数据返回有误还是前端 UI 显示有误。
+
+### 性能统计
+
+通过 `trackWebSocketMessage(data)` 记录 WebSocket 消息接收，在调试面板中实时显示运行时长和数据接收量：
+
+```typescript
+import { trackWebSocketMessage } from '@jnrs/lingshu-smart/utils/performance-stats'
+
+// 在 WebSocket onmessage 回调中调用
+ws.onmessage = (event) => {
+  trackWebSocketMessage(event.data)
+  // ... 业务处理
+}
+```
+
+### 配置持久化
+
+所有调试配置通过 `localStorage` 持久化存储，key 为 `@jnrs/lingshu-smart/debug`：
+
+```json
+{
+  "logLevel": "log",
+  "shadowsEnabled": true,
+  "animationsEnabled": true,
+  "fpsMode": "auto",
+  "interactionsDisabled": false,
+  "locale": "zhCn"
+}
+```
+
+页面刷新后自动恢复上次配置。如需重置，点击调试面板中的"恢复默认"按钮。
+
+## 🌐 国际化
+
+本库内置 vue-i18n 国际化支持，默认提供中文（`zhCn`）和英文（`en`）两种语言，涵盖调试面板、性能统计等模块。
+
+### 在宿主项目中切换语言
+
+通过 `useDebugStore` 的 `setLocale` 方法切换语言，切换后库内所有组件文本实时更新：
+
+```typescript
+import { useDebugStore } from '@jnrs/lingshu-smart/stores/useDebugStore'
+
+const debugStore = useDebugStore()
+
+// 切换为英文
+debugStore.setLocale('en')
+
+// 切换为中文
+debugStore.setLocale('zhCn')
+```
+
+### 自定义或扩展翻译
+
+如需覆盖现有翻译或添加新的语言，通过 vue-i18n 的 `mergeLocaleMessage` 合并：
+
+```typescript
+import i18n from '@jnrs/lingshu-smart/locales/i18next'
+
+// 覆盖中文翻译
+i18n.global.mergeLocaleMessage('zhCn', {
+  perf: {
+    panelButton: '监控面板'
+  }
+})
+
+// 添加新语言
+i18n.global.mergeLocaleMessage('ja', {
+  perf: {
+    title: 'ライブモニター',
+    status: '実行中'
+  }
+})
+```
+
+### 与宿主项目 i18n 集成
+
+如果宿主项目已使用 vue-i18n，可选择以下方案：
+
+1. **独立模式**（推荐）：库内部 i18n 实例独立运行，通过 `setLocale` 同步语言，互不干扰。
+2. **共享模式**：将库的 messages 合并到宿主项目的 i18n 实例中，统一管理。
+
+```typescript
+// 方案1：监听宿主语言变化，同步到库
+import { watch } from 'vue'
+import { useDebugStore } from '@jnrs/lingshu-smart/stores/useDebugStore'
+
+const debugStore = useDebugStore()
+watch(
+  () => hostI18n.global.locale.value,
+  (lang) => {
+    debugStore.setLocale(lang === 'zh-CN' ? 'zhCn' : 'en')
+  }
+)
+```

package/dist/components/debug/DebugPanel.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/debug/PerformanceStats.vue.d.ts

@@ -0,0 +1,42 @@
+type Layout = 'stacked' | 'inline';
+type __VLS_Props = {
+    /** 统计面板布局，'stacked' 表示堆叠布局，'inline' 表示行内布局 */
+    layout?: Layout;
+    /** 是否可收起/展开 */
+    collapsible?: boolean;
+    /** 是否显示 header（脉冲+标题+状态），默认 true */
+    showHeader?: boolean;
+    /** 整体高度，如 '40px'，仅 inline 布局下生效 */
+    height?: string;
+    /** 定位模式，'static' 时不启用定位 */
+    position?: 'static' | 'fixed' | 'absolute';
+    /** 定位 top，仅 position 非 static 时生效 */
+    top?: string;
+    /** 定位 bottom，仅 position 非 static 时生效 */
+    bottom?: string;
+    /** 定位 left，仅 position 非 static 时生效 */
+    left?: string;
+    /** 定位 right，仅 position 非 static 时生效 */
+    right?: string;
+    /** 整体宽度，如 '100%' 或 '360px' */
+    width?: string;
+    /** WebSocket 新消息，传入后自动累加统计（用 watch 监听变化） */
+    message?: unknown;
+    /** WebSocket 连接状态，传入后自动同步 */
+    connected?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {
+    toggleCollapse: () => void;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    width: string;
+    height: string;
+    left: string;
+    right: string;
+    top: string;
+    bottom: string;
+    layout: Layout;
+    collapsible: boolean;
+    showHeader: boolean;
+    position: "static" | "fixed" | "absolute";
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/debug/ScriptRunner/ConfigPanel.vue.d.ts

@@ -0,0 +1,36 @@
+import { ScriptStep, ScriptFieldConfig } from './script';
+/** 设备/资源下拉选项 */
+interface DeviceOption {
+    label: string;
+    value: string;
+    className: string;
+    nameplate: string;
+}
+type __VLS_Props = {
+    selectedStep: ScriptStep | null | undefined;
+    selectedFieldConfigs: ScriptFieldConfig[];
+    deviceOptions: DeviceOption[];
+    resourceDeviceOptions: DeviceOption[];
+    statusDisplayColor: string;
+    selectedDeviceValue: string;
+    addDeviceValue: string;
+    removeDeviceValue: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    copy: (uid: string) => any;
+    delete: (uid: string) => any;
+    "update:selectedDeviceValue": (value: string) => any;
+    "update:addDeviceValue": (value: string) => any;
+    "update:removeDeviceValue": (value: string) => any;
+    "move-up": (uid: string) => any;
+    "move-down": (uid: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCopy?: ((uid: string) => any) | undefined;
+    onDelete?: ((uid: string) => any) | undefined;
+    "onUpdate:selectedDeviceValue"?: ((value: string) => any) | undefined;
+    "onUpdate:addDeviceValue"?: ((value: string) => any) | undefined;
+    "onUpdate:removeDeviceValue"?: ((value: string) => any) | undefined;
+    "onMove-up"?: ((uid: string) => any) | undefined;
+    "onMove-down"?: ((uid: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/components/debug/ScriptRunner/LogPanel.vue.d.ts

@@ -0,0 +1,19 @@
+/** 日志条目（对应 WebSocket 消息结构） */
+export interface LogEntry {
+    datetime: string;
+    type: string;
+    traceId: string;
+    payload: any;
+}
+type __VLS_Props = {
+    logs: LogEntry[];
+    maxLogCount: number;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    copy: () => any;
+    clear: () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCopy?: (() => any) | undefined;
+    onClear?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/components/debug/ScriptRunner/StepsPanel.vue.d.ts

@@ -0,0 +1,42 @@
+import { ScriptStep, ScriptTemplate } from './script';
+type __VLS_Props = {
+    scriptSteps: ScriptStep[];
+    selectedStepUid: string;
+    isRunning: boolean;
+    isLooping: boolean;
+    currentStepIndex: number;
+    breakpointUids: Record<string, boolean>;
+    isPaused: boolean;
+    pausedUid: string;
+    runSeq: number;
+    statusText: string;
+    allChecked: boolean;
+    isIndeterminate: boolean;
+    scriptTemplates: ScriptTemplate[];
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    add: () => any;
+    select: (uid: string) => any;
+    stop: () => any;
+    "update:allChecked": (value: boolean) => any;
+    "update:isLooping": (value: boolean) => any;
+    "toggle-breakpoint": (uid: string) => any;
+    "clear-all": () => any;
+    run: () => any;
+    "continue-run": () => any;
+    "step-next": () => any;
+    "load-template": (name: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onAdd?: (() => any) | undefined;
+    onSelect?: ((uid: string) => any) | undefined;
+    onStop?: (() => any) | undefined;
+    "onUpdate:allChecked"?: ((value: boolean) => any) | undefined;
+    "onUpdate:isLooping"?: ((value: boolean) => any) | undefined;
+    "onToggle-breakpoint"?: ((uid: string) => any) | undefined;
+    "onClear-all"?: (() => any) | undefined;
+    onRun?: (() => any) | undefined;
+    "onContinue-run"?: (() => any) | undefined;
+    "onStep-next"?: (() => any) | undefined;
+    "onLoad-template"?: ((name: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/components/debug/ScriptRunner/index.vue.d.ts

@@ -0,0 +1,16 @@
+import { ILayer } from '../../../types';
+type __VLS_Props = {
+    /** 当前方案的设备图层列表 */
+    layers?: ILayer[];
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {
+    open: () => void;
+    isRunning: import('vue').Ref<boolean, boolean>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    message: (message: any) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onMessage?: ((message: any) => any) | undefined;
+}>, {
+    layers: ILayer[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/debug/ScriptRunner/script.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @File   : script.ts
+ * @Desc.  : 模拟运行脚本的设备字段配置与预设模板
+ */
+/** 字段配置 */
+export interface ScriptFieldConfig {
+    key: string;
+    label: string;
+    type: 'input' | 'select' | 'switch' | 'number' | 'color';
+    options?: {
+        label: string;
+        value: string | number;
+    }[];
+    default?: any;
+    step?: number;
+    min?: number;
+    max?: number;
+}
+/** 脚本步骤 */
+export interface ScriptStep {
+    uid: string;
+    deviceType: string;
+    deviceId: string;
+    delay: number;
+    enabled: boolean;
+    params: Record<string, any>;
+}
+/** 脚本模板 */
+export interface ScriptTemplate {
+    name: string;
+    description: string;
+    steps: Omit<ScriptStep, 'uid'>[];
+}
+/** 设备类型选项 */
+export declare const deviceTypeOptions: {
+    label: string;
+    value: string;
+}[];
+/** 资源类型选项 */
+export declare const resourceTypeOptions: {
+    label: string;
+    value: string;
+}[];
+/** 通用状态字典：状态值/文本/颜色三要素，供「状态」下拉选择与状态灯颜色展示使用 */
+export interface CommonStatusOption {
+    label: string;
+    value: number;
+    displayColor: string;
+}
+export declare const commonDict: CommonStatusOption[];
+/** 资源状态字典：资源增删专用，状态值/文本/颜色三要素 */
+export declare const resourceDict: CommonStatusOption[];
+/** 可作为资源容器的设备类型 */
+export declare const containerDeviceOptions: {
+    label: string;
+    value: string;
+}[];
+/** 各设备类型的字段配置 */
+export declare const deviceFieldConfigs: Record<string, ScriptFieldConfig[]>;
+/**
+ * 模板说明：
+ * - 每个步骤的 deviceId 留空，由 loadTemplate 根据当前方案自动回填
+ * - 单设备模板总时长 ≤ 3 秒
+ * - 完整生产流程展示资源跨设备搬运全流程
+ * - 状态值：0=待机，1=运行，2=报警（见 commonDict）
+ * - x 值每步增量 ≤ 0.03，整体移动幅度小（轻微移动）
+ */
+export declare const scriptTemplates: ScriptTemplate[];
+/** 获取设备类型中文标签 */
+export declare function getDeviceLabel(deviceType: string): string;
+/** 为指定设备类型创建默认参数 */
+export declare function createDefaultParams(deviceType: string): Record<string, any>;