@miot-rn/common-component 1.0.1

package/dist/store/useGlobalSpecManager.js

@@ -0,0 +1,867 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// @ts-nocheck
+/*
+  https://github.com/pmndrs/zustand
+*/
+// @ts-ignore
+import { create } from 'zustand';
+import { useEffect, useRef } from 'react';
+import { getProps, setProps, doAction as _doAction, subscribe } from "../service/specs/index.js";
+import { encodeProp } from "../utils/spec.js";
+import { deepEqual } from "../utils/objects.js";
+
+/* eslint-disable no-console */
+
+const toKey = encodeProp;
+export { toKey };
+const TAG = 'GlobalSpecManager';
+const GlobalSpecManagerErrorCode = {
+  SUCCESS: 0,
+  // 全局公共错误
+  INVALID_PARAM: -101000,
+  // 参数无效（通用）
+  // fetchSpecs 方法错误
+  FETCH_INVALID_SPEC: -101101,
+  // fetchSpecs: 无效的 spec 对象
+  FETCH_REQUEST_FAILED: -101102,
+  // fetchSpecs: 请求失败
+  // setSpecs 方法错误
+  SET_INVALID_SPEC: -101201,
+  // setSpecs: 无效的属性设置对象
+  SET_REQUEST_FAILED: -101202,
+  // setSpecs: 请求失败
+  // ACTION 方法错误
+  ACTION_INVALID_PARAM: -101301,
+  // action: 无效的参数
+  ACTION_EXECUTION_FAILED: -101302,
+  // action: 执行失败
+  // subscribeSpecs 方法错误
+  SUBSCRIBE_INVALID_SPEC: -101401,
+  // subscribeSpecs: 无效的 spec 对象
+  SUBSCRIBE_NO_PIID_OR_EIID: -101402,
+  // subscribeSpecs: 缺少 piid/eiid
+  // onEvent 方法错误
+  ON_EVENT_INVALID_EVENT_SPEC: -101501,
+  // onEvent: 无效的事件 spec
+  ON_EVENT_INVALID_LISTENER: -101502 // onEvent: 无效的监听器
+};
+const LogFilter = (key, value) => {
+  return ['service', 'prop', 'event', 'arguments'].includes(key) ? undefined : value;
+};
+
+// setSpec 节流：以 siid:piid 为 key，500ms 内第一次立即执行，冷却期内丢弃
+const _setSpecLastExecTime = {};
+
+/*
+  负责管理设备Spec的全局Manager
+  PS.
+  1、无法感知数据是来源于蓝牙直连或服务端
+  2、不负责维护设备Spec的历史数据
+*/
+const useGlobalSpecManager = create((set, get) => ({
+  /*
+  储存每个 spec 的元信息，
+  { 
+    [specKey]: { 
+      updateTime: number 
+    } 
+  }
+  */
+  specsMetaInfo: {},
+  /*
+  储存每个 spec 的state
+   */
+  specsState: {},
+  /*
+  储存每个spec event 监听器
+   */
+  eventListeners: {},
+  /*
+  订阅的spec列表，内部使用
+   */
+  subscribedSpecs: new Set(),
+  /* 
+  注入的二方监听器，value或metaInfo更新时触发
+  */
+  specUpdateListeners: [],
+  /**
+   * 注册Spec更新监听器
+   * @function addSpecUpdateListener
+   * @memberof useGlobalSpecManager
+   * @param {Function} listener - 监听器函数
+   * @returns {Function} 返回移除监听器的函数
+   */
+  // @ts-ignore
+  addSpecUpdateListener: listener => {
+    if (typeof listener !== 'function') {
+      console.log(`[STD-LOCK][${TAG}][addSpecUpdateListener] 监听器必须为函数类型`);
+      return () => {};
+    }
+
+    // @ts-ignore
+    set(state => ({
+      specUpdateListeners: [...state.specUpdateListeners, listener]
+    }));
+    return () => {
+      // @ts-ignore
+      set(state => ({
+        specUpdateListeners: state.specUpdateListeners.filter(l => l !== listener)
+      }));
+    };
+  },
+  /**
+   * 主动读取设备Spec属性
+   * @async
+   * @function fetchSpecs
+   * @memberof useGlobalSpecManager
+   * @param {Array<object>} specs - Spec对象数组，每个对象必须包含 siid 属性
+   * @param {boolean} [fromSource=true] - 是否强制从源获取数据
+   * @param {boolean} [batchUpdate=false] - 是否批量更新状态
+   * @returns {Promise<Array<object>>} 返回包含每个Spec读取结果的数组
+   * @throws {Error} 当入参无效或读取过程中发生异常时抛出错误
+   */
+  fetchSpecs: async (specs, fromSource = true, batchUpdate = false) => {
+    // 边界验证：specs 必须是数组且非空
+    if (!Array.isArray(specs) || specs.length === 0) {
+      console.log(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 入参 specs 必须为非空数组`);
+      return [{
+        code: GlobalSpecManagerErrorCode.INVALID_PARAM,
+        message: '入参 specs 必须为非空数组'
+      }];
+    }
+    const promises = specs.map(async spec => {
+      if (!spec || typeof spec !== 'object' || !spec.siid || !spec.piid) {
+        console.log(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 无效的 spec 对象: ${JSON.stringify(spec, LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.FETCH_INVALID_SPEC,
+          message: '无效的 spec 对象',
+          spec
+        };
+      }
+      try {
+        const key = toKey(spec);
+        const results = await getProps([{
+          ...spec,
+          fromSource
+        }], {
+          fromSourceIfNeed: fromSource
+        });
+        // data manager返回的结果code是0，但value是null，需要两者都判断
+        if (results[0]?.code === 0 && results[0]?.value != null) {
+          const updateTime = Math.floor(Date.now() / 1000);
+
+          // 非批量模式：立即更新 state
+          const specDataSource = results[0]?.specDataSource;
+          if (!batchUpdate) {
+            set(state => ({
+              specsState: {
+                ...state.specsState,
+                [key]: results[0].value
+              },
+              specsMetaInfo: {
+                ...state.specsMetaInfo,
+                [key]: {
+                  ...(state.specsMetaInfo[key] || {}),
+                  updateTime,
+                  specDataSource
+                }
+              }
+            }));
+
+            // 触发监听器
+            get().specUpdateListeners.forEach(listener => {
+              listener({
+                type: 'prop',
+                key,
+                data: {
+                  value: results[0].value,
+                  updateTime,
+                  specDataSource
+                },
+                triggerType: 'fetch'
+              });
+            });
+            return {
+              code: GlobalSpecManagerErrorCode.SUCCESS,
+              message: '读取成功',
+              data: {
+                value: results[0].value,
+                updateTime,
+                specDataSource
+              }
+            };
+          }
+
+          // 批量模式：仅收集结果不更新 state
+          return {
+            code: GlobalSpecManagerErrorCode.SUCCESS,
+            key,
+            value: results[0].value,
+            updateTime,
+            specDataSource,
+            message: '读取成功'
+          };
+        }
+        console.log(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 读取 spec 失败: ${JSON.stringify(results[0], LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.FETCH_REQUEST_FAILED,
+          message: '无返回结果',
+          key: toKey(spec)
+        };
+      } catch (error) {
+        console.error(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 读取 spec 异常: ${JSON.stringify(error, LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.FETCH_REQUEST_FAILED,
+          message: 'getProps出现异常',
+          rawErrorCode: error?.code,
+          rawErrorMessage: error?.message
+        };
+      }
+    });
+    const results = await Promise.all(promises);
+
+    // 批量模式：统一更新 state
+    if (batchUpdate) {
+      const successResults = results.filter(r => r.code === 0);
+      if (successResults.length > 0) {
+        set(state => ({
+          specsState: successResults.reduce((acc, res) => {
+            acc[res.key] = res.value;
+            return acc;
+          }, {
+            ...state.specsState
+          }),
+          specsMetaInfo: successResults.reduce((acc, res) => {
+            acc[res.key] = {
+              ...(state.specsMetaInfo[res.key] || {}),
+              updateTime: res.updateTime,
+              specDataSource: res.specDataSource
+            };
+            return acc;
+          }, {
+            ...state.specsMetaInfo
+          })
+        }));
+
+        // 批量触发监听器
+        successResults.forEach(res => {
+          get().specUpdateListeners.forEach(listener => {
+            listener({
+              type: 'prop',
+              key: res.key,
+              data: {
+                value: res.value,
+                updateTime: res.updateTime,
+                specDataSource: res.specDataSource
+              },
+              triggerType: 'fetch'
+            });
+          });
+        });
+      }
+    }
+    return results;
+  },
+  /**
+   * 主动设置设备Spec属性
+   * @async
+   * @function setSpecs
+   * @memberof useGlobalSpecManager
+   * @param {Array<object>} specsToSet - 要设置的Spec对象数组，每个对象必须包含 siid、piid 和 value
+   * @param {boolean} [batchUpdate=false] - 是否批量更新状态
+   * @returns {Promise<Array<object>>} 返回包含每个Spec设置结果的数组
+   */
+  setSpecs: async (specsToSet, batchUpdate = false) => {
+    if (!Array.isArray(specsToSet) || specsToSet.length === 0) {
+      console.log(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 入参 specsToSet 必须为非空数组`);
+      return [{
+        code: GlobalSpecManagerErrorCode.INVALID_PARAM,
+        message: '入参 specsToSet 必须为非空数组'
+      }];
+    }
+    const promises = specsToSet.map(async spec => {
+      if (!spec || typeof spec !== 'object' || !spec.siid || !spec.piid || spec.value == null) {
+        console.log(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 无效的属性设置对象，需包含 siid、piid 和 value: ${JSON.stringify(spec, LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.SET_INVALID_SPEC,
+          message: '无效的属性设置对象'
+        };
+      }
+      try {
+        const key = toKey(spec);
+        const value = spec.value;
+        const results = await setProps([spec]);
+        if (results[0]?.code === 0) {
+          const updateTime = Math.floor(Date.now() / 1000);
+          const specDataSource = results[0]?.specDataSource;
+
+          // 非批量模式：立即更新 state
+          if (!batchUpdate) {
+            set(state => ({
+              specsState: {
+                ...state.specsState,
+                [key]: value
+              },
+              specsMetaInfo: {
+                ...state.specsMetaInfo,
+                [key]: {
+                  ...(state.specsMetaInfo[key] || {}),
+                  updateTime,
+                  specDataSource
+                }
+              }
+            }));
+
+            // 触发监听器
+            get().specUpdateListeners.forEach(listener => {
+              listener({
+                type: 'prop',
+                key,
+                data: {
+                  value,
+                  updateTime,
+                  specDataSource
+                },
+                triggerType: 'set'
+              });
+            });
+            return {
+              code: GlobalSpecManagerErrorCode.SUCCESS,
+              message: '设置成功',
+              data: {
+                value,
+                updateTime,
+                specDataSource
+              }
+            };
+          }
+
+          // 批量模式：仅收集结果不更新 state
+          return {
+            code: GlobalSpecManagerErrorCode.SUCCESS,
+            key,
+            value,
+            updateTime,
+            specDataSource,
+            message: '设置成功'
+          };
+        }
+        console.log(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 设置 spec 失败: ${JSON.stringify(results[0], LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.SET_REQUEST_FAILED,
+          message: 'setProps失败',
+          rawErrorCode: results[0]?.code,
+          rawErrorMessage: ''
+        };
+      } catch (error) {
+        console.error(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 设置 spec 异常: ${JSON.stringify(error, LogFilter, 2)}`);
+        return {
+          code: GlobalSpecManagerErrorCode.SET_REQUEST_FAILED,
+          message: 'setProps出现异常',
+          rawErrorCode: error?.code,
+          rawErrorMessage: error?.message
+        };
+      }
+    });
+    const results = await Promise.all(promises);
+
+    // 批量模式：统一更新 state
+    if (batchUpdate) {
+      const successResults = results.filter(r => r.code === 0);
+      if (successResults.length > 0) {
+        set(state => ({
+          specsState: successResults.reduce((acc, res) => {
+            acc[res.key] = res.value;
+            return acc;
+          }, {
+            ...state.specsState
+          }),
+          specsMetaInfo: successResults.reduce((acc, res) => {
+            acc[res.key] = {
+              ...(state.specsMetaInfo[res.key] || {}),
+              updateTime: res.updateTime
+            };
+            return acc;
+          }, {
+            ...state.specsMetaInfo
+          })
+        }));
+
+        // 批量触发监听器
+        successResults.forEach(res => {
+          get().specUpdateListeners.forEach(listener => {
+            listener({
+              type: 'prop',
+              key: res.key,
+              data: {
+                value: res.value,
+                updateTime: res.updateTime
+              },
+              triggerType: 'set'
+            });
+          });
+        });
+      }
+    }
+    return results;
+  },
+  /**
+   * 主动设置单个设备Spec属性
+   * @async
+   * @function setSpec
+   * @memberof useGlobalSpecManager
+   * @param {object} specToSet - 要设置的单个Spec对象，必须包含 siid、piid 和 value
+   * @param {boolean} [batchUpdate=false] - 是否批量更新状态
+   * @returns {Promise<object>} 返回Spec设置结果
+   */
+  setSpec: async specToSet => {
+    if (!specToSet || typeof specToSet !== 'object' || !specToSet.siid || !specToSet.piid || specToSet.value == null) {
+      console.log(`[STD-LOCK][${TAG}][setSpec][${new Date().toISOString()}] 入参必须为有效的spec对象，需包含 siid、piid 和 value: ${JSON.stringify(specToSet, LogFilter, 2)}`);
+      return {
+        code: GlobalSpecManagerErrorCode.INVALID_PARAM,
+        message: '入参必须为有效的spec对象'
+      };
+    }
+    const throttleKey = `${specToSet.miid}:${specToSet.siid}:${specToSet.piid}`;
+    const now = Date.now();
+    const lastExec = _setSpecLastExecTime[throttleKey] || 0;
+    const elapsed = now - lastExec;
+    if (elapsed >= 500) {
+      // 冷却期已过，立即执行
+      console.log(`[STD-LOCK====][${TAG}][setSpec][throttle][${new Date().toISOString()}] 立即执行 key=${throttleKey}, value=${JSON.stringify(specToSet.value)}, elapsed=${elapsed}ms`);
+      _setSpecLastExecTime[throttleKey] = now;
+      const results = await get().setSpecs([specToSet], false);
+      return results[0];
+    }
+
+    // 冷却期内，直接丢弃
+    console.log(`[STD-LOCK====][${TAG}][setSpec][throttle][${new Date().toISOString()}] 被节流丢弃 key=${throttleKey}, value=${JSON.stringify(specToSet.value)}, elapsed=${elapsed}ms, remaining=${500 - elapsed}ms`);
+    return {
+      code: 0,
+      message: 'throttled: dropped'
+    };
+  },
+  /**
+   * 执行设备操作
+   * @async
+   * @function doAction
+   * @memberof useGlobalSpecManager
+   * @param {object} spec - 操作对象，必须包含 siid、aiid 和 in
+   * @returns {Promise<object>} 返回操作结果
+   */
+  doAction: async spec => {
+    if (!spec || typeof spec !== 'object' || !spec.siid || !spec.aiid || spec.in == null) {
+      console.log(`[STD-LOCK][${TAG}][doAction][${new Date().toISOString()}] 无效的action对象，需包含 siid、aiid 和 in: ${JSON.stringify(spec, LogFilter, 2)}`);
+      return {
+        code: GlobalSpecManagerErrorCode.ACTION_INVALID_PARAM,
+        message: '无效的action对象'
+      };
+    }
+    try {
+      const res = await _doAction(spec);
+      if ([0, 1].includes(res?.code)) {
+        return {
+          code: GlobalSpecManagerErrorCode.SUCCESS,
+          message: '执行成功',
+          data: res?.out ?? []
+        };
+      }
+      console.log(`[STD-LOCK][${TAG}][doAction][${new Date().toISOString()}] 执行action失败: ${JSON.stringify(res, LogFilter, 2)}`);
+      return {
+        code: GlobalSpecManagerErrorCode.ACTION_EXECUTION_FAILED,
+        message: '执行action失败',
+        rawErrorCode: res?.code,
+        rawErrorMessage: res?.message,
+        data: res
+      };
+    } catch (error) {
+      if (__DEV__ && console.warn) {
+        console.warn(`[STD-LOCK][${TAG}][doAction][${new Date().toISOString()}] 执行action异常: ${JSON.stringify(error, LogFilter, 2)}`);
+      }
+      return {
+        code: GlobalSpecManagerErrorCode.ACTION_EXECUTION_FAILED,
+        message: '执行action异常',
+        rawErrorCode: error?.code,
+        rawErrorMessage: error?.message
+      };
+    }
+  },
+  /**
+   * 订阅Spec属性或事件
+   * @async
+   * @function subscribeSpecs
+   * @memberof useGlobalSpecManager
+   * @param {Array<object>} specs - 要订阅的Spec对象数组
+   * @returns {Function} 成功时返回取消订阅的函数，失败/错误时返回空函数
+   */
+  subscribeSpecs: async specs => {
+    if (!Array.isArray(specs) || specs.length === 0) {
+      console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 入参 specs 必须为非空数组`);
+      return () => {};
+    }
+    try {
+      const currentState = get();
+      const newSpecs = specs.filter(spec => {
+        if (!spec || typeof spec !== 'object' || !spec.siid) {
+          console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 无效的 spec 对象: ${JSON.stringify(spec, LogFilter, 2)}`);
+          return false;
+        }
+        if (spec.eiid == null && spec.piid == null) {
+          console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] spec 需包含 piid（属性）或 eiid（事件）: ${JSON.stringify(spec, LogFilter, 2)}`);
+          return false;
+        }
+        const key = toKey(spec);
+        return !currentState.subscribedSpecs.has(key);
+      });
+      if (newSpecs.length === 0) {
+        console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 无新订阅 spec 对象: ${JSON.stringify(specs, LogFilter, 2)}`);
+        return () => {}; // 无新订阅，返回空取消函数
+      }
+      console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 新订阅 spec 对象: ${JSON.stringify(newSpecs, LogFilter, 2)}`);
+      const subscription = await subscribe(newSpecs, updatedSpec => {
+        if (!updatedSpec) {
+          console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 消息推送为空`);
+          return;
+        }
+        const updateTime = updatedSpec.updateTime ?? Math.floor(Date.now() / 1000);
+        const key = toKey(updatedSpec);
+        const {
+          eiid
+        } = updatedSpec;
+        const latestState = get();
+        if (eiid) {
+          // 事件：触发所有注册的监听器（使用最新状态）
+          console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 事件推送: ${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+          console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 触发事件监听器: key=${key}, eventListeners=${JSON.stringify(latestState.eventListeners, null, 2)}, listener=${JSON.stringify(latestState.eventListeners[key], null, 2)}`);
+          const listeners = latestState.eventListeners[key] || [];
+          listeners.forEach(listener => {
+            try {
+              listener({
+                ...updatedSpec,
+                triggerType: 'event'
+              });
+            } catch (error) {
+              console.error(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 事件监听器执行失败: ${JSON.stringify(error, null, 2)}`);
+            }
+          });
+          get().specUpdateListeners.forEach(listener => {
+            listener({
+              type: 'event',
+              // 明确类型为事件
+              key,
+              data: {
+                value: updatedSpec,
+                // 事件参数（完整的事件 spec）
+                updateTime
+              },
+              triggerType: 'event'
+            });
+          });
+        } else {
+          // 属性：根据更新时间和值变化决定是否更新状态
+          const localUpdateTime = latestState.specsMetaInfo[key]?.updateTime || 0; // 初始状态默认旧时间为0
+          // 这里对于updateTime相等的情况，需要处理，因为设备时间戳是秒级
+          const isNewerUpdateTime = updatedSpec.updateTime == null ? true : updatedSpec.updateTime >= localUpdateTime;
+          const isValueChanged = !deepEqual(latestState.specsState[key], updatedSpec.value);
+
+          // 仅在updateTime比本地记录时间更晚时处理
+          if (isNewerUpdateTime) {
+            // 传入值为空，非法，不处理
+            if (updatedSpec.value == null) {
+              return;
+            }
+            const specDataSource = updatedSpec.specDataSource;
+            if (isValueChanged) {
+              // 值变化：更新值和时间
+              console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 推送::属性变更 ${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+              set(state => ({
+                specsState: {
+                  ...state.specsState,
+                  [key]: updatedSpec.value
+                },
+                specsMetaInfo: {
+                  ...state.specsMetaInfo,
+                  [key]: {
+                    ...(state.specsMetaInfo[key] || {}),
+                    updateTime,
+                    specDataSource
+                  }
+                }
+              }));
+              get().specUpdateListeners.forEach(listener => {
+                listener({
+                  type: 'prop',
+                  // 明确类型为属性
+                  key,
+                  data: {
+                    value: updatedSpec.value,
+                    updateTime,
+                    specDataSource
+                  },
+                  triggerType: 'prop_changed'
+                });
+              });
+            } else {
+              // 值未变化：仅更新时间
+              console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 推送::仅更新时间 ${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+              set(state => ({
+                specsMetaInfo: {
+                  ...state.specsMetaInfo,
+                  [key]: {
+                    ...(state.specsMetaInfo[key] || {}),
+                    updateTime,
+                    specDataSource
+                  }
+                }
+              }));
+              get().specUpdateListeners.forEach(listener => {
+                listener({
+                  type: 'prop',
+                  // 明确类型为属性
+                  key,
+                  data: {
+                    value: updatedSpec.value,
+                    updateTime,
+                    specDataSource
+                  },
+                  triggerType: 'prop_changed_time_only'
+                });
+              });
+            }
+          } else {
+            console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 推送::旧数据\nlocalUpdateTime: ${localUpdateTime} isValueChanged: ${isValueChanged} \n${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+          }
+        }
+      }, {
+        publishImmediately: true
+      });
+      // 记录新订阅的 spec key
+      newSpecs.forEach(spec => {
+        const key = toKey(spec);
+        set(state => {
+          const newSubscribed = new Set(state.subscribedSpecs);
+          newSubscribed.add(key);
+          return {
+            subscribedSpecs: newSubscribed
+          };
+        });
+      });
+
+      // 返回取消订阅函数（清除订阅记录）
+      return () => {
+        subscription.unsubscribe();
+        newSpecs.forEach(spec => {
+          const key = toKey(spec);
+          set(state => {
+            const newSubscribed = new Set(state.subscribedSpecs);
+            newSubscribed.delete(key);
+            return {
+              subscribedSpecs: newSubscribed
+            };
+          });
+        });
+      };
+    } catch (error) {
+      console.error(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅异常: ${JSON.stringify(error, null, 2)}`);
+      return () => {};
+    }
+  },
+  /**
+   * 注册事件监听器
+   * @function onEvent
+   * @memberof useGlobalSpecManager
+   * @param {object} eventSpec - 事件Spec对象，必须包含 siid 和 eiid
+   * @param {Function} listener - 事件监听器函数
+   * @returns {Function|object} 成功时返回移除监听器的函数，失败/错误时返回空函数
+   */
+  onEvent: (eventSpec, listener) => {
+    if (!eventSpec || typeof eventSpec !== 'object' || !eventSpec.siid || !eventSpec.eiid) {
+      console.log(`[STD-LOCK][${TAG}][onEvent][${new Date().toISOString()}] 无效的事件 spec，需包含 siid 和 eiid: ${JSON.stringify(eventSpec, LogFilter, 2)}`);
+      // return { code: GlobalSpecManagerErrorCode.ON_EVENT_INVALID_EVENT_SPEC, message: '无效的事件 spec' };
+      return () => {};
+    }
+    if (typeof listener !== 'function') {
+      console.log(`[STD-LOCK][${TAG}][onEvent][${new Date().toISOString()}] 监听器必须是函数类型: ${typeof listener}`);
+      // return { code: GlobalSpecManagerErrorCode.ON_EVENT_INVALID_LISTENER, message: '监听器必须是函数类型' };
+      return () => {};
+    }
+    const eventKey = toKey(eventSpec);
+    console.log(`[STD-LOCK][${TAG}][onEvent][${new Date().toISOString()}] 注册事件监听器: eventKey=${eventKey}`);
+    set(state => ({
+      eventListeners: {
+        ...state.eventListeners,
+        [eventKey]: [...(state.eventListeners[eventKey] || []), listener]
+      }
+    }));
+    return () => {
+      set(state => ({
+        eventListeners: {
+          ...state.eventListeners,
+          [eventKey]: (state.eventListeners[eventKey] || []).filter(l => l !== listener)
+        }
+      }));
+    };
+  },
+  /**
+   * 获取Spec状态
+   * @function getSpecState
+   * @memberof useGlobalSpecManager
+   * @param {object|string} spec - Spec对象或Spec键
+   * @returns {*} 返回Spec的值
+   */
+  getSpecState: spec => {
+    const key = typeof spec === 'string' ? spec : toKey(spec);
+    return get().specsState[key];
+  },
+  /**
+   * 获取Spec元信息
+   * @function getSpecMetaInfo
+   * @memberof useGlobalSpecManager
+   * @param {object|string} spec - Spec对象或Spec键
+   * @returns {object|null} 返回Spec的元信息对象或 null
+   */
+  getSpecMetaInfo: spec => {
+    const key = typeof spec === 'string' ? spec : toKey(spec);
+    return get().specsMetaInfo[key];
+  }
+}));
+export default useGlobalSpecManager;
+export { useGlobalSpecManager };
+
+/**
+ * 用于获取Spec状态的 React Hook
+ * @function useSpecState
+ * @param {object|string} spec - Spec对象或Spec键
+ * @returns {*} 返回Spec的当前值
+ */
+export const useSpecState = spec => {
+  return useGlobalSpecManager(state => state.getSpecState(spec));
+};
+
+/**
+ * 用于获取Spec元信息的 React Hook
+ * @function useSpecMetaInfo
+ * @param {object|string} spec - Spec对象或Spec键
+ * @returns {object|null} 返回Spec的元信息对象或 null
+ */
+export const useSpecMetaInfo = spec => {
+  return useGlobalSpecManager(state => state.getSpecMetaInfo(spec));
+};
+
+// 注册 Spec 更新监听器
+export const useSpecUpdateListener = listener => {
+  const listenerRef = useRef(listener);
+
+  // 始终保持最新的 listener 内容
+  useEffect(() => {
+    listenerRef.current = listener;
+  }, [listener]);
+  useEffect(() => {
+    // 注册一个稳定引用的 wrapper 函数
+    const wrappedListener = (...args) => {
+      if (listenerRef.current) {
+        listenerRef.current(...args);
+      }
+    };
+
+    // 只在挂载时添加一次
+    const removeListener = useGlobalSpecManager.getState().addSpecUpdateListener(wrappedListener);
+    return () => removeListener();
+  }, []);
+};
+
+// 注册事件监听器
+export const useEventListener = (eventSpec, listener) => {
+  useEffect(() => {
+    const removeListener = useGlobalSpecManager.getState().onEvent(eventSpec, listener);
+    return () => typeof removeListener === 'function' && removeListener();
+  }, [eventSpec, listener]);
+
+  // 可选返回 removeListener 函数
+  return () => {
+    const state = useGlobalSpecManager.getState();
+    const fn = state.onEvent(eventSpec, listener);
+    if (typeof fn === 'function') fn();
+  };
+};
+
+// ----------------- normal function
+
+/**
+ * 添加全局 Spec 更新监听器
+ * @param listener 更新回调函数
+ * @returns 取消监听函数
+ */
+export const addSpecUpdateListener = listener => {
+  return useGlobalSpecManager.getState().addSpecUpdateListener(listener);
+};
+
+/**
+ * 读取设备 spec
+ * @param specs Spec 对象数组
+ * @param fromSource 是否强制从设备/服务端获取
+ * @param batchUpdate 是否批量更新状态
+ */
+export const fetchSpecs = async (specs, fromSource = true, batchUpdate = false) => {
+  return useGlobalSpecManager.getState().fetchSpecs(specs, fromSource, batchUpdate);
+};
+
+/**
+ * 设置设备 specs
+ * @param specsToSet Spec 对象数组，每个对象必须包含 siid, piid, value
+ * @param batchUpdate 是否批量更新状态
+ */
+export const setSpecs = async (specsToSet, batchUpdate = false) => {
+  return useGlobalSpecManager.getState().setSpecs(specsToSet, batchUpdate);
+};
+
+/**
+ * 设置设备 spec
+ * @param specToSet Spec 对象，必须包含 siid, piid, value
+ */
+export const setSpec = async specToSet => {
+  return useGlobalSpecManager.getState().setSpec(specToSet);
+};
+
+/**
+ * 执行设备操作
+ * @param spec 操作对象，必须包含 siid, aiid 和 in
+ */
+export const doAction = async spec => {
+  return useGlobalSpecManager.getState().doAction(spec);
+};
+
+/**
+ * 订阅 Spec 并返回取消订阅函数
+ * @param specs Spec 对象数组
+ * @returns 取消订阅函数
+ */
+export const subscribeSpecs = async specs => {
+  return useGlobalSpecManager.getState().subscribeSpecs(specs);
+};
+
+/**
+ * 注册事件监听器
+ * @param eventSpec 事件对象，必须包含 siid 和 eiid
+ * @param listener 事件回调
+ * @returns 取消监听函数
+ */
+export const onEvent = (eventSpec, listener) => {
+  return useGlobalSpecManager.getState().onEvent(eventSpec, listener);
+};
+
+/**
+ * 获取 Spec 当前值
+ * @param spec Spec 对象或 Spec key
+ */
+export const getSpecState = spec => {
+  return useGlobalSpecManager.getState().getSpecState(spec);
+};
+
+/**
+ * 获取 Spec 元信息
+ * @param spec Spec 对象或 Spec key
+ */
+export const getSpecMetaInfo = spec => {
+  return useGlobalSpecManager.getState().getSpecMetaInfo(spec);
+};