@nokecy/qc-ui 1.1.37 → 1.1.39

package/dist/esm/ag-grid-plus/ag-gridPlus.js

@@ -1,4 +1,5 @@
 import _sumBy from "lodash/sumBy";
+import _isEqual from "lodash/isEqual";
 import _uniqueId from "lodash/uniqueId";
 import _isArray from "lodash/isArray";
 var _excluded = ["style", "loading", "params", "request", "dataSource", "treeKeyName", "treeParentName", "rowData", "gridRef", "headerTitle", "toolBarRender", "search", "hideTool", "onGridReady", "gridKey", "children", "defaultSearchExpand", "overlayNoRowsTemplateText", "queryDefaultRows", "onSelectedRowsChange", "enableClickSelection", "rowSelection", "useNativeTreeFilter", "entityType"];
@@ -60,6 +61,16 @@ var Text = Typography.Text;
 var getSort = function getSort(columnState) {
   return columnState ? "".concat(columnState.colId, " ").concat(columnState.sort) : "";
 };
+
+// 深比较稳定引用:内容不变时返回同一引用。替代 JSON.stringify 作 memo 依赖——
+// 避免每次渲染序列化大对象,且 isEqual 差异早退、对 Date/undefined 比较语义正确 @author nokecy
+function useDeepCompareStable(value) {
+  var ref = useRef(value);
+  if (!_isEqual(ref.current, value)) {
+    ref.current = value;
+  }
+  return ref.current;
+}
 function AgGridPlus(props) {
   var style = props.style,
     loadingProps = props.loading,
@@ -103,6 +114,8 @@ function AgGridPlus(props) {
   var gridRef = useRef();
   var apiRef = useRef();
   var allColDefsRef = useRef([]);
+  // 请求序号:只接受最新一次请求的响应,防止快速翻页/连续查询时慢请求乱序覆盖新结果 @author nokecy
+  var requestSeqRef = useRef(0);
 
   // 【新增】缓存初始的 columnDefs，用于保留原始 headerName
   // 这个值在组件生命周期中保持不变，不会被列方案修改
@@ -112,18 +125,18 @@ function AgGridPlus(props) {
   var rowIdCacheRef = useRef(new WeakMap());
   var rowIdCounterRef = useRef(0);
 
-  /**
-   * 【新增】智能生成唯一行 ID 的降级函数
-   *
-   * 策略（按优先级）：
-   * 1. 尝试常见 ID 字段：id, _id, key, uid, uuid
-   *    - 支持基本类型：string, number
-   *    - 支持对象类型：提取 value, id 属性
-   * 2. 如果对象在 WeakMap 中已有缓存，直接返回
-   * 3. 生成新的唯一 ID：grid-key-{counter}-{timestamp}
-   *
-   * @param data 行数据对象
-   * @returns 唯一的行 ID 字符串
+  /**
+   * 【新增】智能生成唯一行 ID 的降级函数
+   *
+   * 策略（按优先级）：
+   * 1. 尝试常见 ID 字段：id, _id, key, uid, uuid
+   *    - 支持基本类型：string, number
+   *    - 支持对象类型：提取 value, id 属性
+   * 2. 如果对象在 WeakMap 中已有缓存，直接返回
+   * 3. 生成新的唯一 ID：grid-key-{counter}-{timestamp}
+   *
+   * @param data 行数据对象
+   * @returns 唯一的行 ID 字符串
    */
   var generateUniqueRowId = useCallback(function (data) {
     if (!data || _typeof(data) !== 'object') {
@@ -252,18 +265,18 @@ function AgGridPlus(props) {
     advancedQueryRules = _useState24[0],
     setAdvancedQueryRules = _useState24[1];
 
-  /**
-   * 【P1 架构优化】使用单向数据流架构
-   *
-   * 数据流层次：
-   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
-   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
-   * 3. UI State: Context State (仅用于 UI 交互)
-   *
-   * 优势：
-   * - 清晰的数据流向（单向可追踪）
-   * - 消除状态同步冲突（单一数据源）
-   * - 架构清晰度 +60%，Bug -40%
+  /**
+   * 【P1 架构优化】使用单向数据流架构
+   *
+   * 数据流层次：
+   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
+   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
+   * 3. UI State: Context State (仅用于 UI 交互)
+   *
+   * 优势：
+   * - 清晰的数据流向（单向可追踪）
+   * - 消除状态同步冲突（单一数据源）
+   * - 架构清晰度 +60%，Bug -40%
    */
   var schemeDataFlow = useSchemeDataFlow(gridKey || '', allColDefsRef.current, {
     columnSchemes: columnSchemes,
@@ -345,14 +358,14 @@ function AgGridPlus(props) {
     }
   }, [rowData]);
 
-  /**
-   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
-   *
-   * 优势：
-   * 1. 使用已派生的状态，避免重复计算
-   * 2. 单向数据流，状态同步更可靠
-   * 3. 性能提升 67%，代码更清晰
-   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
+  /**
+   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
+   *
+   * 优势：
+   * 1. 使用已派生的状态，避免重复计算
+   * 2. 单向数据流，状态同步更可靠
+   * 3. 性能提升 67%，代码更清晰
+   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
    */
   useEffect(function () {
     if (!gridKey || !apiRef.current) return;
@@ -410,39 +423,38 @@ function AgGridPlus(props) {
   }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, derivedColumnState, ready // 添加 ready 依赖，确保 Grid 初始化完成后再应用方案
   ]);
 
-  /**
-   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
-   *
-   * 场景：
-   * - 用户删除当前正在使用的方案
-   * - currentColumnScheme?.id 从有值变为 null
-   *
-   * 行为：
-   * - 重置列状态为初始状态（默认顺序、宽度等）
-   * - 清除所有过滤器
-   * - 清除列样式配置
-   *
-   * 优势：
-   * - 符合单向数据流架构
-   * - 适用于所有方案切换场景（删除/取消选择）
-   * - 用户体验好，自动恢复到初始状态
+  /**
+   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
+   *
+   * 场景：
+   * - 用户删除当前正在使用的方案
+   * - currentColumnScheme?.id 从有值变为 null
+   *
+   * 行为：
+   * - 重置列状态为初始状态（默认顺序、宽度等）
+   * - 清除所有过滤器
+   * - 清除列样式配置
+   *
+   * 优势：
+   * - 符合单向数据流架构
+   * - 适用于所有方案切换场景（删除/取消选择）
+   * - 用户体验好，自动恢复到初始状态
    */
   var prevSchemeIdRef = useRef(currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id);
   useEffect(function () {
     if (!gridKey || !apiRef.current || !ready) return;
     var prevSchemeId = prevSchemeIdRef.current;
     var currentSchemeId = currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id;
+
     // 检测方案被删除：从有值变为 null/undefined
     if (prevSchemeId && !currentSchemeId) {
       Promise.resolve().then(function () {
         if (!apiRef.current) return;
 
         // 1. 重置列状态为初始状态
-
         apiRef.current.resetColumnState();
 
         // 2. 清除所有过滤器
-
         apiRef.current.setFilterModel(null);
 
         // 3. 清除列样式配置
@@ -602,7 +614,7 @@ function AgGridPlus(props) {
     columnDefs = columnDefs.map(function (col) {
       return processColumnDefRecursively(col);
     });
-    extensibleColumns && gridKey && extensibleColumns[gridKey] && extensibleColumns[gridKey].map(function (column) {
+    extensibleColumns && gridKey && extensibleColumns[gridKey] && extensibleColumns[gridKey].forEach(function (column) {
       columnDefs.push({
         field: column.name,
         headerName: column.displayName,
@@ -664,16 +676,10 @@ function AgGridPlus(props) {
     return cols;
   }, [React.Children.count(children), props.columnDefs, extensibleColumns, gridKey, entityType, hostEntityExtensions]);
 
-  // 稳定化 gridParams 和 sortColumn 的引用
-  var stableGridParams = useMemo(function () {
-    return gridParams;
-  }, [JSON.stringify(gridParams)]);
-  var stableSortColumn = useMemo(function () {
-    return sortColumn;
-  }, [JSON.stringify(sortColumn)]);
-  var stableQueryFilter = useMemo(function () {
-    return queryFilter;
-  }, [JSON.stringify(queryFilter)]);
+  // 稳定化 gridParams 和 sortColumn 的引用(深比较,内容不变即复用旧引用)
+  var stableGridParams = useDeepCompareStable(gridParams);
+  var stableSortColumn = useDeepCompareStable(sortColumn);
+  var stableQueryFilter = useDeepCompareStable(queryFilter);
 
   // AG-Grid v33+ 行选择配置（使用对象 API）
   var rowSelectionConfig = useMemo(function () {
@@ -757,8 +763,12 @@ function AgGridPlus(props) {
         maxResultCount: pagination.pageSize,
         sorter: getSort(stableSortColumn)
       });
+      var requestSeq = ++requestSeqRef.current;
       requestRef.current(params, undefined, queryFilter).then(function (response) {
         var _apiRef$current2;
+        // 过期响应(期间已发起更新的请求),直接丢弃 @author nokecy
+        if (requestSeq !== requestSeqRef.current) return;
+
         // 验证响应数据格式
         if (!response || _typeof(response) !== 'object') {
           throw new GridPlusError('服务器返回数据格式错误', ErrorType.DATA_FORMAT_ERROR, ErrorSeverity.HIGH, {
@@ -834,6 +844,8 @@ function AgGridPlus(props) {
           });
         }
       }).catch(function (error) {
+        // 过期请求的失败不再提示/改状态,避免干扰最新请求 @author nokecy
+        if (requestSeq !== requestSeqRef.current) return;
         setLoading(false);
 
         // 包装错误为 GridPlusError
@@ -1024,16 +1036,15 @@ function AgGridPlus(props) {
     });
   };
   var avgFun = function avgFun(field, displayedData) {
-    var sum = _sumBy(displayedData, function (cur) {
-      if (cur && isValidNumber(cur[field]) && cur[field] !== undefined && cur[field] !== null) {
-        return cur[field];
-      }
-      return 0;
+    // 修正:分子分母口径统一为「有效数字」,避免 count 误用数组(恒真)及除零得 NaN @author nokecy
+    var validValues = displayedData.filter(function (cur) {
+      return cur && isValidNumber(cur[field]);
     });
-    var count = displayedData.filter(function (cur) {
-      return cur && cur[field] !== undefined && cur[field] !== null;
+    if (validValues.length === 0) return 0;
+    var sum = _sumBy(validValues, function (cur) {
+      return cur[field];
     });
-    return count ? sum / count.length : 0;
+    return sum / validValues.length;
   };
   var standardDeviationFun = function standardDeviationFun(field, displayedData) {
     var validValues = displayedData.filter(function (cur) {
@@ -1121,13 +1132,13 @@ function AgGridPlus(props) {
     calculateSum();
   };
 
-  /**
-   * 【P0 + P1 优化】列定义 - 优先使用派生状态
-   *
-   * 单向数据流优势：
-   * 1. 优先使用已派生的 derivedColumnDefs（避免重复计算）
-   * 2. 仅在无方案时使用默认逻辑
-   * 3. 性能提升 94%，架构清晰度 +60%
+  /**
+   * 【P0 + P1 优化】列定义 - 优先使用派生状态
+   *
+   * 单向数据流优势：
+   * 1. 优先使用已派生的 derivedColumnDefs（避免重复计算）
+   * 2. 仅在无方案时使用默认逻辑
+   * 3. 性能提升 94%，架构清晰度 +60%
    */
   var colDefs = useMemo(function () {
     // 【优先使用派生状态】如果有派生的列定义，直接使用
@@ -1174,7 +1185,9 @@ function AgGridPlus(props) {
     return processedColumns;
   }, [
   // 【关键】优先依赖派生状态
-  derivedColumnDefs, React.Children.count(children), props.columnDefs, extensibleColumns, columnCellClass, allColDefsRef.current]);
+  derivedColumnDefs, React.Children.count(children), props.columnDefs, extensibleColumns, columnCellClass,
+  // ref.current 变更不触发重渲染,作依赖无效;改依赖真正的数据源 allColDefs(memo 值) @author nokecy
+  allColDefs]);
 
   // 构建查询表单项（带 order 属性）
   var queryFormItems = useMemo(function () {
@@ -1252,10 +1265,10 @@ function AgGridPlus(props) {
     return {
       extensibleColumns: extensibleColumns,
       columnState: gridPlusColumnState,
-      allColDefs: allColDefsRef.current,
-      // 【修复】传入原始完整的列定义
+      allColDefs: allColDefs,
+      // 直接用 memo 值(与 ref 同源,引用变化能正确触发 memo 更新) @author nokecy
       initialColumnDefs: initialColumnDefsRef.current,
-      // 【新增】传入初始列定义（用于获取原始 headerName）
+      // 初始列定义在 allColDefs 首次计算时填充,之后不变（用于获取原始 headerName）
       onSaveColumnState: onSaveColumnState,
       applyToGlobal: applyToGlobal,
       resetCurrent: resetCurrent,
@@ -1290,11 +1303,9 @@ function AgGridPlus(props) {
       // ========== 实体扩展字段配置 @author nokecy ==========
       hostEntityExtensions: hostEntityExtensions
     };
-  }, [extensibleColumns, gridPlusColumnState, allColDefsRef.current,
-  // 【修复】添加到依赖数组
-  initialColumnDefsRef.current,
-  // 【新增】添加初始列定义到依赖数组
-  onSaveColumnState, applyToGlobal, resetCurrent, resetAll, currentQueryScheme, queryItemsOrder, queryFormItems,
+  }, [extensibleColumns, gridPlusColumnState,
+  // ref.current 作依赖无效(变更不触发重渲染);依赖数据源 allColDefs,initialColumnDefs 随其首次计算填充 @author nokecy
+  allColDefs, onSaveColumnState, applyToGlobal, resetCurrent, resetAll, currentQueryScheme, queryItemsOrder, queryFormItems,
   // 方案管理依赖
   columnSchemes, querySchemes, currentSchemes, schemesLoading, lastSyncTime, saveColumnScheme, deleteColumnScheme, saveQueryScheme, deleteQueryScheme, setCurrentColumnScheme, setCurrentQueryScheme, refreshSchemes, getColumnSchemes, getQuerySchemes, getCurrentScheme,
   // 全局配置依赖

package/dist/esm/ag-grid-plus/context/gridContext.js

@@ -1,26 +1,26 @@
 import React from "react";
 
-/**
- * 方案管理 API 接口
- *
- * ⚠️ 必须通过 useSchemeManager Hook 创建，然后传入 Provider
- *
- * @example
- * ```tsx
- * const adapter = useMemo(() => new BackendApiSchemeAdapter({ ... }), []);
- * const schemeManager = useSchemeManager({ adapter, autoLoad: true });
- *
- * <GridPlusContext.Provider value={{
- *   ...otherValues,
- *   ...schemeManager  // 展开方案管理状态
- * }}>
- * ```
+/**
+ * 方案管理 API 接口
+ *
+ * ⚠️ 必须通过 useSchemeManager Hook 创建，然后传入 Provider
+ *
+ * @example
+ * ```tsx
+ * const adapter = useMemo(() => new BackendApiSchemeAdapter({ ... }), []);
+ * const schemeManager = useSchemeManager({ adapter, autoLoad: true });
+ *
+ * <GridPlusContext.Provider value={{
+ *   ...otherValues,
+ *   ...schemeManager  // 展开方案管理状态
+ * }}>
+ * ```
  */
 
-/**
- * GridPlus Context 值接口
- *
- * ⚠️ 必须包含方案管理 API，通过 useSchemeManager Hook 创建后传入
+/**
+ * GridPlus Context 值接口
+ *
+ * ⚠️ 必须包含方案管理 API，通过 useSchemeManager Hook 创建后传入
  */
 
 export var GridPlusContext = /*#__PURE__*/React.createContext({

package/dist/esm/ag-grid-plus/context/useSchemeDataFlow.js

@@ -5,38 +5,39 @@ function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key i
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 import { useMemo } from 'react';
+import { logger } from "../utils/logger";
 
-/**
- * 【P1 架构优化】单向数据流 Hook
- *
- * 建立清晰的数据流层次：
- * 1. Source of Truth: Scheme State (通过参数传入)
- * 2. Derived State: Grid State (通过 useMemo 派生)
- * 3. UI State: Context State (仅用于 UI 交互)
- *
- * 优势：
- * - 架构清晰度 +60%（单向数据流易于追踪）
- * - Bug 减少率 -40%（消除状态冲突）
- * - 状态同步复杂度降低 70%
+/**
+ * 【P1 架构优化】单向数据流 Hook
+ *
+ * 建立清晰的数据流层次：
+ * 1. Source of Truth: Scheme State (通过参数传入)
+ * 2. Derived State: Grid State (通过 useMemo 派生)
+ * 3. UI State: Context State (仅用于 UI 交互)
+ *
+ * 优势：
+ * - 架构清晰度 +60%（单向数据流易于追踪）
+ * - Bug 减少率 -40%（消除状态冲突）
+ * - 状态同步复杂度降低 70%
  */
 
-/**
- * 方案数据接口
+/**
+ * 方案数据接口
  */
 
-/**
- * 数据源层 - 获取方案数据（单一数据源）
- *
- * @param gridKey - Grid 唯一标识
- * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
- * @returns 方案数据源对象
+/**
+ * 数据源层 - 获取方案数据（单一数据源）
+ *
+ * @param gridKey - Grid 唯一标识
+ * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
+ * @returns 方案数据源对象
  */
 export function useSchemeSource(gridKey, schemeData) {
   var columnSchemes = schemeData.columnSchemes,
     querySchemes = schemeData.querySchemes,
     currentSchemes = schemeData.currentSchemes;
   return useMemo(function () {
-    var _currentSchemes$gridK, _currentSchemes$gridK2;
+    var _currentSchemes$gridK, _currentSchemes$gridK2, _currentColumnScheme;
     var schemes = (columnSchemes === null || columnSchemes === void 0 ? void 0 : columnSchemes[gridKey]) || [];
     var currentColumnSchemeId = currentSchemes === null || currentSchemes === void 0 || (_currentSchemes$gridK = currentSchemes[gridKey]) === null || _currentSchemes$gridK === void 0 ? void 0 : _currentSchemes$gridK.columnSchemeId;
 
@@ -104,6 +105,15 @@ export function useSchemeSource(gridKey, schemeData) {
         isUsingGlobalQueryFallback = true;
       }
     }
+    logger.debug('[useSchemeSource] 方案数据源:', {
+      gridKey: gridKey,
+      schemes: schemes,
+      currentColumnSchemeId: currentColumnSchemeId,
+      currentColumnScheme: currentColumnScheme,
+      hasCurrentScheme: !!currentColumnScheme,
+      isUsingGlobalFallback: isUsingGlobalFallback,
+      columnConfigLength: (_currentColumnScheme = currentColumnScheme) === null || _currentColumnScheme === void 0 || (_currentColumnScheme = _currentColumnScheme.columnConfig) === null || _currentColumnScheme === void 0 ? void 0 : _currentColumnScheme.length
+    });
     return {
       // 列方案
       columnSchemes: schemes,
@@ -121,24 +131,41 @@ export function useSchemeSource(gridKey, schemeData) {
   }, [columnSchemes, querySchemes, currentSchemes, gridKey]);
 }
 
-/**
- * 派生层 - 计算 Grid 状态（只读派生）
- *
- * @param currentScheme - 当前列方案
- * @param allColDefs - 原始列定义
- * @returns 派生的 Grid 列定义
+/**
+ * 派生层 - 计算 Grid 状态（只读派生）
+ *
+ * @param currentScheme - 当前列方案
+ * @param allColDefs - 原始列定义
+ * @returns 派生的 Grid 列定义
  */
 export function useDerivedGridState(currentScheme, allColDefs) {
   return useMemo(function () {
+    var _currentScheme$column;
+    logger.debug('[useDerivedGridState] 输入参数:', {
+      hasScheme: !!currentScheme,
+      schemeId: currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id,
+      configLength: currentScheme === null || currentScheme === void 0 || (_currentScheme$column = currentScheme.columnConfig) === null || _currentScheme$column === void 0 ? void 0 : _currentScheme$column.length,
+      allColDefsLength: allColDefs === null || allColDefs === void 0 ? void 0 : allColDefs.length
+    });
     if (!(currentScheme !== null && currentScheme !== void 0 && currentScheme.columnConfig) || !allColDefs || allColDefs.length === 0) {
+      logger.debug('[useDerivedGridState] 返回 null (缺少必要数据)');
       return null;
     }
     try {
+      var _result$;
       var _require = require("../setting/columnGroupUtils"),
         flatConfigToGridState = _require.flatConfigToGridState;
 
       // 转换并缓存结果
       var result = flatConfigToGridState(currentScheme.columnConfig, allColDefs);
+      logger.debug('[useDerivedGridState] 转换成功:', {
+        resultLength: result === null || result === void 0 ? void 0 : result.length,
+        columnOrder: result === null || result === void 0 ? void 0 : result.map(function (col) {
+          return col.field;
+        }),
+        firstColumn: result === null || result === void 0 || (_result$ = result[0]) === null || _result$ === void 0 ? void 0 : _result$.field,
+        fullResult: result
+      });
       return result;
     } catch (error) {
       console.error('[useDerivedGridState] 转换失败:', error);
@@ -148,12 +175,12 @@ export function useDerivedGridState(currentScheme, allColDefs) {
   currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
 }
 
-/**
- * 派生层 - 计算列样式状态（只读派生）
- *
- * @param currentScheme - 当前列方案
- * @param allColDefs - 原始列定义（用于检测新增列）
- * @returns 派生的列状态配置
+/**
+ * 派生层 - 计算列样式状态（只读派生）
+ *
+ * @param currentScheme - 当前列方案
+ * @param allColDefs - 原始列定义（用于检测新增列）
+ * @returns 派生的列状态配置
  */
 export function useDerivedColumnState(currentScheme, allColDefs) {
   return useMemo(function () {
@@ -166,6 +193,15 @@ export function useDerivedColumnState(currentScheme, allColDefs) {
 
       // 转换列状态，传入原始列定义以检测新增列
       var result = flatConfigToColumnState(currentScheme.columnConfig, allColDefs);
+      logger.debug('[useDerivedColumnState] 转换结果:', {
+        schemeId: currentScheme.id,
+        columnConfigLength: currentScheme.columnConfig.length,
+        resultLength: result === null || result === void 0 ? void 0 : result.length,
+        columnOrder: result === null || result === void 0 ? void 0 : result.map(function (r) {
+          return r.colId;
+        }),
+        fullResult: result
+      });
       return result;
     } catch (error) {
       console.error('[useDerivedColumnState] 转换失败:', error);
@@ -175,30 +211,30 @@ export function useDerivedColumnState(currentScheme, allColDefs) {
   currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
 }
 
-/**
- * 统一的方案数据流 Hook（组合版）
- *
- * @param gridKey - Grid 唯一标识
- * @param allColDefs - 原始列定义
- * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
- * @returns 完整的方案数据流对象
- *
- * @example
- * ```tsx
- * function AgGridPlus({ gridKey }) {
- *   const allColDefsRef = useRef([]);
- *   const { columnSchemes, querySchemes, currentSchemes } = useGridSchemes();
- *
- *   const schemeDataFlow = useSchemeDataFlow(
- *     gridKey,
- *     allColDefsRef.current,
- *     { columnSchemes, querySchemes, currentSchemes }
- *   );
- *
- *   // 只读访问数据
- *   const { currentColumnScheme, derivedColumnDefs } = schemeDataFlow;
- * }
- * ```
+/**
+ * 统一的方案数据流 Hook（组合版）
+ *
+ * @param gridKey - Grid 唯一标识
+ * @param allColDefs - 原始列定义
+ * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
+ * @returns 完整的方案数据流对象
+ *
+ * @example
+ * ```tsx
+ * function AgGridPlus({ gridKey }) {
+ *   const allColDefsRef = useRef([]);
+ *   const { columnSchemes, querySchemes, currentSchemes } = useGridSchemes();
+ *
+ *   const schemeDataFlow = useSchemeDataFlow(
+ *     gridKey,
+ *     allColDefsRef.current,
+ *     { columnSchemes, querySchemes, currentSchemes }
+ *   );
+ *
+ *   // 只读访问数据
+ *   const { currentColumnScheme, derivedColumnDefs } = schemeDataFlow;
+ * }
+ * ```
  */
 export function useSchemeDataFlow(gridKey, allColDefs, schemeData) {
   // 1. 数据源层（Source of Truth）