@miot-rn/common-component 1.0.3 → 1.0.4

package/dist/specs/instance-parser.js

@@ -132,7 +132,7 @@ function getIidsGetter() {
     }
 
     // 获取目标模块
-    const targetModule = findModuleByKeyAndDescription(normalizedMKey, normalizedMDescription);
+    const targetModule = findModule(normalizedMKey, normalizedMDescription);
     // console.log('targetModule---', targetModule);
 
     if (!targetModule && mkey) {
@@ -226,8 +226,10 @@ function getIidsGetter() {
         // 添加模块信息
         if (mkey && targetModule) {
           spec.miid = targetModule?.iid;
-          spec.mkey = mkey || parseSpecType(targetModule?.type).key;
-          spec.mDescription = normalizedMDescription;
+          spec.mkey = parseSpecType(targetModule?.type).key || mkey;
+          if (normalizedMDescription) {
+            spec.mDescription = normalizedMDescription;
+          }
         }
 
         // 将最新版本的结果添加到数组开头
@@ -557,25 +559,25 @@ function getTargetModule(miid) {
 }
 
 /**
- * 根据mkey和mDescription查找模块
+ * 查找匹配的模块。
+ * - mkey 通过 module.type 解析（与 service/property 保持一致口径）
+ * - mDescription 仅在提供时用于二次消歧（同 name 存在多个 module 的场景）
  * @param {string} mkey - 模块键
  * @param {string} mDescription - 模块描述（可选）
  * @returns {Object|null} - 返回目标模块对象或null
  */
-function findModuleByKeyAndDescription(mkey, mDescription) {
+function findModule(mkey, mDescription) {
   const normalizedMKey = safeTrim(mkey);
   const normalizedMDescription = safeTrim(mDescription);
   // 如果是版本3
   if (CachedSpecVersion === 3) {
     return (CachedInstance.modules || []).find(module => {
-      const moduleDescription = safeTrim(module?.description);
-      const moduleName = safeTrim(module?.name);
-      // 如果提供了mDescription，同时匹配mkey和mDescription
+      if (parseSpecType(module?.type).key !== normalizedMKey) return false;
+      // 提供了 mDescription 时同时匹配 module.description
       if (normalizedMDescription) {
-        return moduleName === normalizedMKey && moduleDescription === normalizedMDescription;
+        return safeTrim(module?.description) === normalizedMDescription;
       }
-      // 只匹配mkey
-      return moduleName === normalizedMKey;
+      return true;
     });
   }
   // 如果是版本2，返回整个实例

package/dist/store/useGlobalSpecManager.d.ts

@@ -4,10 +4,13 @@ export { toKey };
 declare const useGlobalSpecManager: import("zustand").UseBoundStore<import("zustand").StoreApi<{
     specsMetaInfo: {};
     specsState: {};
+    pendingKeys: Set<unknown>;
     eventListeners: {};
     subscribedSpecs: Set<unknown>;
     specUpdateListeners: never[];
     addSpecUpdateListener: (listener: any) => () => void;
+    _deferRemovePendingKey: (key: string) => void;
+    _rollbackOptimisticSpec: (key: string, failedValue: any) => boolean;
     fetchSpecs: (specs: any, datasource?: number, batchUpdate?: boolean) => Promise<({
         code: number;
         message: string;

package/dist/store/useGlobalSpecManager.js

@@ -9,11 +9,20 @@ 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";
+/* 刻意不带 .js 后缀：本文件其余 '../xxx.js' 导入在单测里都被 jest.mock(..., { virtual: true }) 拦掉了，
+   而 subscribe-log 没有被 mock，带 .js 会导致 jest 解析不到真实的 .ts 文件。 */
+import { reportSubLog } from "../utils/subscribe-log";
 
 /* eslint-disable no-console */
 
 const toKey = encodeProp;
 export { toKey };
+
+// 同一个 spec 操作完成后，延迟处理订阅推送，避免固件旧值覆盖乐观更新值
+const DELAY_TIME = 2000;
+
+// 同一个 spec 快速连续设置时，首次立即发送，后续合并为最后一次值延迟发送
+const DEBOUNCE_SET_INTERVAL = 1000;
 const TAG = 'GlobalSpecManager';
 const GlobalSpecManagerErrorCode = {
   SUCCESS: 0,
@@ -49,8 +58,16 @@ const LogFilter = (key, value) => {
   return ['service', 'prop', 'event', 'arguments'].includes(key) ? undefined : value;
 };
 
-// setSpec 节流：以 siid:piid 为 key，500ms 内第一次立即执行，冷却期内丢弃
-const _setSpecLastExecTime = {};
+// 最近一次真实确认的 spec 值，仅用于乐观更新失败回滚，不放入 zustand state
+const _confirmedState = new Map();
+// 每个 pending key 对应的延迟释放 timer，不放入 zustand state
+const _pendingTimers = new Map();
+// pending 期间暂存的最新 push 值，timer 到期后按策略应用
+const _pendingPushCache = new Map();
+// 每个 key 当前正在进行中的 set 请求计数，用于避免连续 set 时提前释放 pending
+const _pendingSetCounts = new Map();
+// setSpec 防抖状态：{ [key]: { timer, lastSpec } }
+const _debounceState = new Map();
 
 /*
   负责管理设备Spec的全局Manager
@@ -73,6 +90,11 @@ const useGlobalSpecManager = create((set, get) => ({
    */
   specsState: {},
   /*
+  当前处于乐观更新待确认的 key 集合。
+  订阅推送在 pending 期间先缓存，不直接覆盖本地乐观值。
+  */
+  pendingKeys: new Set(),
+  /*
   储存每个spec event 监听器
    */
   eventListeners: {},
@@ -109,6 +131,155 @@ const useGlobalSpecManager = create((set, get) => ({
       }));
     };
   },
+  /**
+   * 延迟从 pendingKeys 移除指定 key。
+   * 同一 key 多次调用会重置 timer，以最后一次 set 成功或操作为准。
+   */
+  _deferRemovePendingKey: key => {
+    const timer = _pendingTimers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+    }
+    _pendingTimers.set(key, setTimeout(() => {
+      const pendingSetCount = _pendingSetCounts.get(key) || 0;
+      if (pendingSetCount > 0) {
+        _pendingTimers.delete(key);
+        get()._deferRemovePendingKey(key);
+        return;
+      }
+      const hasCached = _pendingPushCache.has(key);
+      set(state => {
+        const newPending = new Set(state.pendingKeys);
+        newPending.delete(key);
+        return {
+          pendingKeys: newPending
+        };
+      });
+      _pendingTimers.delete(key);
+      if (hasCached) {
+        const cachedSpec = _pendingPushCache.get(key);
+        _pendingPushCache.delete(key);
+        const latestState = get();
+        const isValueChanged = !deepEqual(latestState.specsState[key], cachedSpec.value);
+        if (cachedSpec.value != null) {
+          const metaInfo = {
+            ...(latestState.specsMetaInfo[key] || {}),
+            updateTime: cachedSpec.updateTime,
+            specDataSource: cachedSpec.specDataSource
+          };
+          _confirmedState.set(key, {
+            value: cachedSpec.value,
+            metaInfo
+          });
+          if (isValueChanged) {
+            set(state => ({
+              specsState: {
+                ...state.specsState,
+                [key]: cachedSpec.value
+              },
+              specsMetaInfo: {
+                ...state.specsMetaInfo,
+                [key]: metaInfo
+              }
+            }));
+          } else {
+            set(state => ({
+              specsMetaInfo: {
+                ...state.specsMetaInfo,
+                [key]: metaInfo
+              }
+            }));
+          }
+          get().specUpdateListeners.forEach(listener => {
+            listener({
+              type: 'prop',
+              key,
+              data: {
+                value: cachedSpec.value,
+                updateTime: cachedSpec.updateTime,
+                specDataSource: cachedSpec.specDataSource
+              },
+              triggerType: isValueChanged ? 'prop_changed' : 'prop_changed_time_only'
+            });
+          });
+        }
+      }
+    }, DELAY_TIME));
+  },
+  _rollbackOptimisticSpec: (key, failedValue) => {
+    const latestState = get();
+    if (!deepEqual(latestState.specsState[key], failedValue)) {
+      return false;
+    }
+    const timer = _pendingTimers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      _pendingTimers.delete(key);
+    }
+    const hasCachedPush = _pendingPushCache.has(key);
+    const confirmed = _confirmedState.get(key);
+    let shouldKeepValue = !!confirmed;
+    let rollbackValue = confirmed?.value;
+    let rollbackMetaInfo = confirmed?.metaInfo;
+    if (hasCachedPush) {
+      const cachedSpec = _pendingPushCache.get(key);
+      shouldKeepValue = true;
+      rollbackValue = cachedSpec.value;
+      rollbackMetaInfo = {
+        ...(rollbackMetaInfo || {}),
+        updateTime: cachedSpec.updateTime,
+        specDataSource: cachedSpec.specDataSource
+      };
+    }
+    _pendingPushCache.delete(key);
+    const nextMetaInfo = shouldKeepValue ? {
+      ...(rollbackMetaInfo || {}),
+      specDataSource: rollbackMetaInfo?.specDataSource || 'rollback'
+    } : undefined;
+    if (shouldKeepValue) {
+      _confirmedState.set(key, {
+        value: rollbackValue,
+        metaInfo: nextMetaInfo
+      });
+    } else {
+      _confirmedState.delete(key);
+    }
+    set(state => {
+      const newPending = new Set(state.pendingKeys);
+      const newSpecsState = {
+        ...state.specsState
+      };
+      const newMetaInfo = {
+        ...state.specsMetaInfo
+      };
+      newPending.delete(key);
+      if (shouldKeepValue) {
+        newSpecsState[key] = rollbackValue;
+        newMetaInfo[key] = nextMetaInfo;
+      } else {
+        delete newSpecsState[key];
+        delete newMetaInfo[key];
+      }
+      return {
+        pendingKeys: newPending,
+        specsState: newSpecsState,
+        specsMetaInfo: newMetaInfo
+      };
+    });
+    get().specUpdateListeners.forEach(listener => {
+      listener({
+        type: 'prop',
+        key,
+        data: {
+          value: rollbackValue,
+          updateTime: nextMetaInfo?.updateTime,
+          specDataSource: nextMetaInfo?.specDataSource || 'rollback'
+        },
+        triggerType: 'set'
+      });
+    });
+    return true;
+  },
   /**
    * 主动读取设备Spec属性
    * @async
@@ -151,6 +322,14 @@ const useGlobalSpecManager = create((set, get) => ({
           // 非批量模式：立即更新 state
           const specDataSource = results[0]?.specDataSource;
           if (!batchUpdate) {
+            _confirmedState.set(key, {
+              value: results[0].value,
+              metaInfo: {
+                ...(get().specsMetaInfo[key] || {}),
+                updateTime,
+                specDataSource
+              }
+            });
             set(state => ({
               specsState: {
                 ...state.specsState,
@@ -207,12 +386,16 @@ const useGlobalSpecManager = create((set, get) => ({
           key: toKey(spec)
         };
       } catch (error) {
-        console.error(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 读取 spec 异常: ${JSON.stringify(error, LogFilter, 2)}`);
+        // Error 对象的属性非枚举，JSON.stringify 会得到 {}，改成显式取 message/stack，
+        // 同时把 spec 关键字段一并打印，方便定位是哪个 piid 崩掉。
+        const errMsg = error?.message || (typeof error === 'string' ? error : String(error));
+        const errStack = error?.stack ? `\n${error.stack}` : '';
+        console.warn(`[STD-LOCK][${TAG}][fetchSpecs][${new Date().toISOString()}] 读取 spec 异常 ` + `spec={siid:${spec.siid},piid:${spec.piid},pkey:${spec.pkey || '-'}}: ${errMsg}${errStack}`);
         return {
           code: GlobalSpecManagerErrorCode.FETCH_REQUEST_FAILED,
           message: 'getProps出现异常',
           rawErrorCode: error?.code,
-          rawErrorMessage: error?.message
+          rawErrorMessage: errMsg
         };
       }
     });
@@ -222,6 +405,16 @@ const useGlobalSpecManager = create((set, get) => ({
     if (batchUpdate) {
       const successResults = results.filter(r => r.code === 0);
       if (successResults.length > 0) {
+        successResults.forEach(res => {
+          _confirmedState.set(res.key, {
+            value: res.value,
+            metaInfo: {
+              ...(get().specsMetaInfo[res.key] || {}),
+              updateTime: res.updateTime,
+              specDataSource: res.specDataSource
+            }
+          });
+        });
         set(state => ({
           specsState: successResults.reduce((acc, res) => {
             acc[res.key] = res.value;
@@ -285,44 +478,74 @@ const useGlobalSpecManager = create((set, get) => ({
           message: '无效的属性设置对象'
         };
       }
+      const key = toKey(spec);
+      const value = spec.value;
+      const optimisticTime = Math.floor(Date.now() / 1000);
+      set(state => {
+        const newPending = new Set(state.pendingKeys);
+        newPending.add(key);
+        return {
+          pendingKeys: newPending,
+          specsState: {
+            ...state.specsState,
+            [key]: value
+          },
+          specsMetaInfo: {
+            ...state.specsMetaInfo,
+            [key]: {
+              ...(state.specsMetaInfo[key] || {}),
+              updateTime: optimisticTime,
+              specDataSource: 'optimistic'
+            }
+          }
+        };
+      });
+      _pendingPushCache.delete(key);
+      _pendingSetCounts.set(key, (_pendingSetCounts.get(key) || 0) + 1);
+      get()._deferRemovePendingKey(key);
+      get().specUpdateListeners.forEach(listener => {
+        listener({
+          type: 'prop',
+          key,
+          data: {
+            value,
+            updateTime: optimisticTime,
+            specDataSource: 'optimistic'
+          },
+          triggerType: 'set'
+        });
+      });
       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
-                }
+          const nextCount = Math.max((_pendingSetCounts.get(key) || 1) - 1, 0);
+          if (nextCount > 0) {
+            _pendingSetCounts.set(key, nextCount);
+          } else {
+            _pendingSetCounts.delete(key);
+          }
+          _confirmedState.set(key, {
+            value,
+            metaInfo: {
+              ...(get().specsMetaInfo[key] || {}),
+              updateTime,
+              specDataSource
+            }
+          });
+          set(state => ({
+            specsMetaInfo: {
+              ...state.specsMetaInfo,
+              [key]: {
+                ...(state.specsMetaInfo[key] || {}),
+                updateTime,
+                specDataSource
               }
-            }));
-
-            // 触发监听器
-            get().specUpdateListeners.forEach(listener => {
-              listener({
-                type: 'prop',
-                key,
-                data: {
-                  value,
-                  updateTime,
-                  specDataSource
-                },
-                triggerType: 'set'
-              });
-            });
+            }
+          }));
+          get()._deferRemovePendingKey(key);
+          if (!batchUpdate) {
             return {
               code: GlobalSpecManagerErrorCode.SUCCESS,
               message: '设置成功',
@@ -333,8 +556,6 @@ const useGlobalSpecManager = create((set, get) => ({
               }
             };
           }
-
-          // 批量模式：仅收集结果不更新 state
           return {
             code: GlobalSpecManagerErrorCode.SUCCESS,
             key,
@@ -345,6 +566,15 @@ const useGlobalSpecManager = create((set, get) => ({
           };
         }
         console.log(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 设置 spec 失败: ${JSON.stringify(results[0], LogFilter, 2)}`);
+        const nextCount = Math.max((_pendingSetCounts.get(key) || 1) - 1, 0);
+        if (nextCount > 0) {
+          _pendingSetCounts.set(key, nextCount);
+        } else {
+          _pendingSetCounts.delete(key);
+          if (!get()._rollbackOptimisticSpec(key, value)) {
+            get()._deferRemovePendingKey(key);
+          }
+        }
         return {
           code: GlobalSpecManagerErrorCode.SET_REQUEST_FAILED,
           message: 'setProps失败',
@@ -353,6 +583,15 @@ const useGlobalSpecManager = create((set, get) => ({
         };
       } catch (error) {
         console.error(`[STD-LOCK][${TAG}][setSpecs][${new Date().toISOString()}] 设置 spec 异常: ${JSON.stringify(error, LogFilter, 2)}`);
+        const nextCount = Math.max((_pendingSetCounts.get(key) || 1) - 1, 0);
+        if (nextCount > 0) {
+          _pendingSetCounts.set(key, nextCount);
+        } else {
+          _pendingSetCounts.delete(key);
+          if (!get()._rollbackOptimisticSpec(key, value)) {
+            get()._deferRemovePendingKey(key);
+          }
+        }
         return {
           code: GlobalSpecManagerErrorCode.SET_REQUEST_FAILED,
           message: 'setProps出现异常',
@@ -367,6 +606,16 @@ const useGlobalSpecManager = create((set, get) => ({
     if (batchUpdate) {
       const successResults = results.filter(r => r.code === 0);
       if (successResults.length > 0) {
+        successResults.forEach(res => {
+          _confirmedState.set(res.key, {
+            value: res.value,
+            metaInfo: {
+              ...(get().specsMetaInfo[res.key] || {}),
+              updateTime: res.updateTime,
+              specDataSource: res.specDataSource
+            }
+          });
+        });
         set(state => ({
           specsState: successResults.reduce((acc, res) => {
             acc[res.key] = res.value;
@@ -377,7 +626,8 @@ const useGlobalSpecManager = create((set, get) => ({
           specsMetaInfo: successResults.reduce((acc, res) => {
             acc[res.key] = {
               ...(state.specsMetaInfo[res.key] || {}),
-              updateTime: res.updateTime
+              updateTime: res.updateTime,
+              specDataSource: res.specDataSource
             };
             return acc;
           }, {
@@ -420,23 +670,73 @@ const useGlobalSpecManager = create((set, get) => ({
         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];
+    const key = toKey(specToSet);
+    const existing = _debounceState.get(key);
+    if (!existing) {
+      console.log(`[STD-LOCK][${TAG}][setSpec][${new Date().toISOString()}] 防抖首次立即发送 key=${key}, value=${JSON.stringify(specToSet.value)}`);
+      const timer = setTimeout(() => {
+        const state = _debounceState.get(key);
+        if (state && state.lastSpec) {
+          const trailingSpec = state.lastSpec;
+          _debounceState.delete(key);
+          get().setSpecs([trailingSpec], false);
+        } else {
+          _debounceState.delete(key);
+        }
+      }, DEBOUNCE_SET_INTERVAL);
+      _debounceState.set(key, {
+        timer,
+        lastSpec: null
+      });
+      try {
+        const results = await get().setSpecs([specToSet], false);
+        return results[0];
+      } catch (error) {
+        return {
+          code: GlobalSpecManagerErrorCode.SET_REQUEST_FAILED,
+          message: 'setSpec leading 异常',
+          rawErrorCode: error?.code,
+          rawErrorMessage: error?.message
+        };
+      }
     }
-
-    // 冷却期内，直接丢弃
-    console.log(`[STD-LOCK====][${TAG}][setSpec][throttle][${new Date().toISOString()}] 被节流丢弃 key=${throttleKey}, value=${JSON.stringify(specToSet.value)}, elapsed=${elapsed}ms, remaining=${500 - elapsed}ms`);
+    console.log(`[STD-LOCK][${TAG}][setSpec][${new Date().toISOString()}] 防抖缓存更新 key=${key}, value=${JSON.stringify(specToSet.value)}`);
+    _pendingPushCache.delete(key);
+    get()._deferRemovePendingKey(key);
+    existing.lastSpec = specToSet;
+    clearTimeout(existing.timer);
+    existing.timer = setTimeout(() => {
+      const state = _debounceState.get(key);
+      if (state && state.lastSpec) {
+        const trailingSpec = state.lastSpec;
+        _debounceState.delete(key);
+        get().setSpecs([trailingSpec], false);
+      } else {
+        _debounceState.delete(key);
+      }
+    }, DEBOUNCE_SET_INTERVAL);
+    set(state => ({
+      specsState: {
+        ...state.specsState,
+        [key]: specToSet.value
+      }
+    }));
+    get().specUpdateListeners.forEach(listener => {
+      listener({
+        type: 'prop',
+        key,
+        data: {
+          value: specToSet.value
+        },
+        triggerType: 'set'
+      });
+    });
     return {
-      code: 0,
-      message: 'throttled: dropped'
+      code: GlobalSpecManagerErrorCode.SUCCESS,
+      message: '已缓存，等待防抖发送',
+      data: {
+        value: specToSet.value
+      }
     };
   },
   /**
@@ -556,6 +856,18 @@ const useGlobalSpecManager = create((set, get) => ({
             });
           });
         } else {
+          // 同一个 spec 正在乐观更新待确认时，先缓存推送值，延迟到 pending 释放后再判断是否应用。
+          if (latestState.pendingKeys.has(key)) {
+            if (updatedSpec.value != null) {
+              _pendingPushCache.set(key, {
+                value: updatedSpec.value,
+                updateTime,
+                specDataSource: updatedSpec.specDataSource
+              });
+            }
+            return;
+          }
+
           // 属性：根据更新时间和值变化决定是否更新状态
           const localUpdateTime = latestState.specsMetaInfo[key]?.updateTime || 0; // 初始状态默认旧时间为0
           // 这里对于updateTime相等的情况，需要处理，因为设备时间戳是秒级
@@ -572,6 +884,14 @@ const useGlobalSpecManager = create((set, get) => ({
             if (isValueChanged) {
               // 值变化：更新值和时间
               console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 推送::属性变更 ${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+              _confirmedState.set(key, {
+                value: updatedSpec.value,
+                metaInfo: {
+                  ...(get().specsMetaInfo[key] || {}),
+                  updateTime,
+                  specDataSource
+                }
+              });
               set(state => ({
                 specsState: {
                   ...state.specsState,
@@ -602,6 +922,14 @@ const useGlobalSpecManager = create((set, get) => ({
             } else {
               // 值未变化：仅更新时间
               console.log(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅到的 spec 推送::仅更新时间 ${JSON.stringify(updatedSpec, LogFilter, 2)}`);
+              _confirmedState.set(key, {
+                value: updatedSpec.value,
+                metaInfo: {
+                  ...(get().specsMetaInfo[key] || {}),
+                  updateTime,
+                  specDataSource
+                }
+              });
               set(state => ({
                 specsMetaInfo: {
                   ...state.specsMetaInfo,
@@ -633,6 +961,16 @@ const useGlobalSpecManager = create((set, get) => ({
       }, {
         publishImmediately: true
       });
+      // 底层 std-spec 的 listenMessages 失败时，mapError 会让 Promise 变成 resolve，
+      // 且 resolve 出来的是 prop 数组而非 { props, unsubscribe }，导致此处拿到的 props 为 undefined。
+      // 这种"假成功"过去完全静默，这里显式识别并打日志。
+      const isSubscribeSuspicious = !subscription || typeof subscription.unsubscribe !== 'function' || !subscription.props;
+      if (isSubscribeSuspicious) {
+        reportSubLog(`[SPEC-SUB][${TAG}][subscribeSpecs][fail][${new Date().toISOString()}] 订阅未真正生效（底层返回结构异常，推送将收不到）, specCount=${newSpecs.length}, result=${JSON.stringify(subscription, LogFilter, 2)}`, 'error');
+      } else {
+        reportSubLog(`[SPEC-SUB][${TAG}][subscribeSpecs][success][${new Date().toISOString()}] 订阅成功, specCount=${newSpecs.length}, subscribedPropCount=${subscription.props?.length}`);
+      }
+
       // 记录新订阅的 spec key
       newSpecs.forEach(spec => {
         const key = toKey(spec);
@@ -647,6 +985,7 @@ const useGlobalSpecManager = create((set, get) => ({
 
       // 返回取消订阅函数（清除订阅记录）
       return () => {
+        reportSubLog(`[SPEC-SUB][${TAG}][subscribeSpecs][unsubscribe][${new Date().toISOString()}] 取消订阅, specCount=${newSpecs.length}, keys=${JSON.stringify(newSpecs.map(toKey))}`);
         subscription.unsubscribe();
         newSpecs.forEach(spec => {
           const key = toKey(spec);
@@ -658,9 +997,11 @@ const useGlobalSpecManager = create((set, get) => ({
             };
           });
         });
+        reportSubLog(`[SPEC-SUB][${TAG}][subscribeSpecs][unsubscribe-done][${new Date().toISOString()}] 取消订阅完成, 剩余已订阅=${get().subscribedSpecs.size}`);
       };
     } catch (error) {
       console.error(`[STD-LOCK][${TAG}][subscribeSpecs][${new Date().toISOString()}] 订阅异常: ${JSON.stringify(error, null, 2)}`);
+      reportSubLog(`[SPEC-SUB][${TAG}][subscribeSpecs][fail][${new Date().toISOString()}] 订阅抛异常, specCount=${specs.length}, code=${error?.code}, message=${error?.message}`, 'error');
       return () => {};
     }
   },

package/dist/store/useGlobalSpecManager.test.d.ts

@@ -0,0 +1 @@
+export {};