@hzab/data-model 1.8.8 → 1.8.9-alpha.0

package/src/ArrayUtils.js

@@ -1,539 +1,539 @@
-import { nanoid } from "nanoid";
-import _ from "lodash";
-import dayjs from "dayjs";
-
-export const STATE_CODE = {
-  SUC: 200,
-  NOT_FOUNT: 404,
-  ERR: 500,
-  ERR_INPUT_ID: 501,
-};
-
-/**
- * 数组模拟数据库存储
- * TODO: FormData? 考虑到文件存储问题
- */
-export class ArrayUtils {
-  _idKey = "id";
-  _list = [];
-  constructor(params) {
-    const { idKey = "id", list } = params;
-    /** 子项唯一标志字段 */
-    this._idKey = idKey || "id";
-    /** 列表数据 */
-    this._list = list || [];
-  }
-
-  /**
-   * 通过 id 获取子项
-   * @param {*} id
-   * @returns
-   */
-  findItemById(id) {
-    if (this._hasId(id)) {
-      return null;
-    }
-    const { _idKey } = this;
-    return _.cloneDeep(this._list.find((it) => it[_idKey] === id));
-  }
-
-  /**
-   * 通过 id 获取子项
-   * @param {*} id
-   * @returns
-   */
-  findItem(query = {}, options = {}) {
-    const { fuzzy = false, ignoreCase = false } = options;
-    const id = query[this._idKey];
-
-    if (!this._hasId(id)) {
-      return this.findItemById(id);
-    }
-
-    const validQuery = this._filterEmptyQuery(query);
-    if (_.isEmpty(validQuery)) {
-      return null;
-    }
-
-    const matchItem = this._list.find((item) => {
-      return this._isItemMatchQuery(item, validQuery, { fuzzy, ignoreCase });
-    });
-
-    return matchItem ? _.cloneDeep(matchItem) : null;
-  }
-
-  /**
-   * 通过 query 筛选列表（支持多条件筛选、分页、排序）
-   * @param {Object} query - 综合查询参数
-   * @param {number} [query.pageNum=1] - 页码（默认1）
-   * @param {number} [query.pageSize=10] - 每页条数（默认10）
-   * @param {string|string[]} [query.sortKey] - 排序字段（支持嵌套路径，如 'user.age'）
-   * @param {string} [query.sortType='desc'] - 排序方式（desc/asc）
-   * @param {string} [query.orderByColumn] - 兼容旧排序字段参数
-   * @param {string} [query.isAsc] - 兼容旧排序方式参数
-   * @param {Object} [options={}] - 查询选项
-   * @param {boolean} [options.fuzzy=false] - 字符串字段是否开启模糊匹配
-   * @param {boolean} [options.ignoreCase=true] - 模糊匹配时是否忽略大小写
-   * @returns {Object} 分页结果
-   * @returns {Object[]} result.list - 筛选后的列表（深拷贝）
-   * @returns {Object} result.pagination - 分页信息（current/total/pageSize）
-   */
-  findListByQuery(query = {}, options = {}) {
-    const {
-      pageNum = 1,
-      pageSize = 10,
-      sortKey,
-      sortType,
-      orderByColumn,
-      isAsc,
-      ...filterQuery // 提取筛选条件（排除分页排序参数）
-    } = query;
-
-    const { fuzzy = true, ignoreCase = false } = options;
-
-    // 数据筛选（基于 query 条件）
-    let filteredList = [...this._list];
-    const validFilterQuery = this._filterEmptyQuery(filterQuery);
-
-    if (!_.isEmpty(validFilterQuery)) {
-      filteredList = filteredList.filter((item) => {
-        return this._isItemMatchQuery(item, validFilterQuery, { fuzzy, ignoreCase });
-      });
-    }
-
-    // 数据排序（基于筛选后的数据）
-    const sortedList = this.getSortList(
-      sortKey || orderByColumn,
-      sortType || isAsc,
-      filteredList, // 传入筛选后列表，避免排序影响原数据
-    );
-
-    // 分页处理（边界校验）
-    const pagination = {
-      current: Math.max(1, pageNum), // 页码最小为1
-      pageSize: Math.max(1, pageSize), // 每页条数最小为1
-      total: filteredList.length,
-    };
-
-    // 计算分页截取范围
-    const startIndex = (pagination.current - 1) * pagination.pageSize;
-    const endIndex = startIndex + pagination.pageSize;
-    const paginatedList = sortedList.slice(startIndex, endIndex);
-
-    return {
-      list: _.cloneDeep(paginatedList),
-      pagination: { ...pagination },
-    };
-  }
-
-  /**
-   * 对目标数据进行多维度排序
-   * @param {string|string[]|Object[]} sortKey - 排序字段配置
-   * @param {string} sortType - 排序方式（desc/asc）
-   * @param {Object[]} [customList] - 自定义排序列表（默认使用内部 _list）
-   * @returns {Object[]} 排序后的列表
-   */
-  getSortList(sortKey, sortType, customList) {
-    const sourceList = customList || this._list;
-    const _list = _.cloneDeep(sourceList);
-
-    // 无排序条件时直接返回原列表
-    if (!sortKey && !sortType) {
-      return _list;
-    }
-
-    // 统一排序字段格式为数组
-    const paths = Array.isArray(sortKey) ? sortKey : [sortKey];
-
-    _list.sort((a, b) => {
-      return this.compareData(a, b, { paths, sortType, pathIdx: 0 });
-    });
-
-    return _list;
-  }
-
-  /**
-   * 比较两个数据对象的排序顺序（支持多字段优先级排序）
-   * @param {Object} dataA - 比较对象A
-   * @param {Object} dataB - 比较对象B
-   * @param {Object} opt - 比较配置
-   * @param {string[]|Object[]} opt.paths - 排序字段路径数组
-   * @param {number} opt.pathIdx - 当前比较的字段索引
-   * @param {string} opt.sortType - 排序方式（desc/asc）
-   * @returns {number} 排序结果（-1/0/1）
-   */
-  compareData(dataA, dataB, opt = {}) {
-    const { paths, pathIdx = 0, sortType = "desc" } = opt;
-    const currentPath = paths[pathIdx];
-
-    // 处理自定义比较逻辑
-    if (currentPath && typeof currentPath === "object" && typeof currentPath.customCompare === "function") {
-      const direction = sortType === "asc" ? -1 : 1;
-      return direction * currentPath.customCompare(dataA, dataB, opt);
-    }
-
-    // 提取实际字段路径（支持配置对象格式）
-    const path = typeof currentPath === "object" ? currentPath.path : currentPath;
-    if (!path) {
-      return 0;
-    }
-
-    // 确定排序方向（支持按字段单独配置排序方式）
-    let direction = 1;
-    let _sortType = sortType;
-    if (typeof _sortType === "object") {
-      _sortType = _sortType[path] || "desc";
-    }
-    if (_sortType === "asc") {
-      direction = -1;
-    }
-
-    // 获取并处理字段值（支持日期转换、自定义格式化）
-    const valueA = this.handleValByKey(dataA, currentPath);
-    const valueB = this.handleValByKey(dataB, currentPath);
-
-    // 数值比较
-    if (valueA < valueB) {
-      return -1 * direction;
-    }
-    if (valueA > valueB) {
-      return 1 * direction;
-    }
-
-    // 当前字段值相等时，使用下一个优先级字段排序
-    if (pathIdx + 1 < paths.length) {
-      return this.compareData(dataA, dataB, { ...opt, pathIdx: pathIdx + 1 });
-    }
-
-    // 所有字段都相等时，保持原有顺序
-    return 0;
-  }
-
-  /**
-   * 根据路径获取并处理字段值（支持嵌套路径、类型转换、自定义格式化）
-   * @param {Object} data - 数据源对象
-   * @param {string|Object} pathConfig - 字段配置
-   * @param {string} [pathConfig.path] - 字段路径（如 'user.address.city'）
-   * @param {string} [pathConfig.type] - 字段类型（支持 'date' 自动转时间戳）
-   * @param {Function} [pathConfig.customFormat] - 自定义值处理函数
-   * @returns {*} 处理后的字段值
-   */
-  handleValByKey(data, pathConfig) {
-    // 处理字符串路径
-    if (typeof pathConfig === "string") {
-      return _.get(data, pathConfig);
-    }
-
-    // 处理空配置
-    if (_.isNil(pathConfig)) {
-      return undefined;
-    }
-
-    // 处理对象配置
-    if (typeof pathConfig === "object") {
-      let val = _.get(data, pathConfig.path);
-
-      // 日期类型转换为时间戳（便于数值比较）
-      if (pathConfig.type === "date") {
-        val = dayjs(val).isValid() ? dayjs(val).valueOf() : 0;
-      }
-
-      // 自定义值格式化
-      if (typeof pathConfig.customFormat === "function") {
-        val = pathConfig.customFormat(val, data);
-      }
-
-      return val;
-    }
-
-    return undefined;
-  }
-
-  /**
-   * 获取完整列表
-   */
-  findAllList() {
-    return _.cloneDeep(this._list);
-  }
-
-  /**
-   * 获取总数
-   * @returns
-   */
-  getCount() {
-    return this._list.length;
-  }
-
-  /**
-   * push 数据
-   * @param {*} data
-   */
-  pushItem(data) {
-    // TODO: id 去重
-    const items = Array.isArray(data) ? data : [data];
-    items.forEach((item) => {
-      const cloneItem = _.cloneDeep(item);
-      this._setId(cloneItem);
-      this._setCreateTime(cloneItem);
-      this._list.push(cloneItem);
-    });
-    return STATE_CODE.SUC;
-  }
-
-  /**
-   * unshift 数据
-   * @param {*} data
-   */
-  unshiftItem(data) {
-    // TODO: id 去重
-    const item = _.cloneDeep(data);
-    this._setId(item);
-    this._setCreateTime(item);
-    this._list.unshift(item);
-    return STATE_CODE.SUC;
-  }
-
-  /**
-   * 根据 id 更新子项——直接替换
-   * @param {Object} data
-   * @returns
-   */
-  replaceItem(data) {
-    const { _idKey, _list } = this;
-    const id = data[_idKey];
-    if (this._hasId(id)) {
-      return STATE_CODE.ERR_INPUT_ID;
-    }
-    const idx = _list.findIndex((it) => it[_idKey] === id);
-    if (idx < 0) {
-      return STATE_CODE.NOT_FOUNT;
-    }
-    _list.splice(idx, 1, data);
-    this._setUpdateTime(data);
-    return STATE_CODE.SUC;
-  }
-
-  /**
-   * 根据 id 更新子项——仅修改传入的数据
-   * @param {Object} data
-   * @returns
-   */
-  updateItemValue(data) {
-    const { _idKey, _list } = this;
-    const id = data[_idKey];
-    if (this._hasId(id)) {
-      return STATE_CODE.ERR_INPUT_ID;
-    }
-    const item = _list.find((it) => it[_idKey] === id);
-    if (!item) {
-      return STATE_CODE.NOT_FOUNT;
-    }
-    Object.keys(data).forEach((key) => {
-      item[key] = data[key];
-    });
-    this._setUpdateTime(data);
-    return STATE_CODE.SUC;
-  }
-
-  /**
-   * 删除子项
-   * @param {*} id
-   * @param {*} data
-   * @returns
-   */
-  delItem(id) {
-    const { _idKey, _list } = this;
-    if (this._hasId(id)) {
-      return STATE_CODE.ERR_INPUT_ID;
-    }
-    const idx = _list.findIndex((it) => it[_idKey] === id);
-    if (idx < 0) {
-      return STATE_CODE.NOT_FOUNT;
-    }
-    _list.splice(idx, 1);
-    return STATE_CODE.SUC;
-  }
-
-  /**
-   * 检查单个 item 是否匹配所有 query 条件
-   * @private
-   * @param {Object} item - 待检查的列表项
-   * @param {Object} query - 查询条件
-   * @param {Object} options - 匹配选项
-   * @param {boolean} options.fuzzy - 是否开启模糊匹配
-   * @param {boolean} options.ignoreCase - 模糊匹配是否忽略大小写
-   * @returns {boolean} 是否匹配所有条件
-   */
-  _isItemMatchQuery(item, query, { fuzzy, ignoreCase }) {
-    // 遍历所有查询条件，必须全部满足才返回 true
-    return Object.entries(query).every(([key, targetValue]) => {
-      // 获取 item 中对应字段的值（支持嵌套路径，如 'user.name'）
-      const itemValue = _.get(item, key);
-
-      // 处理空值情况（null/undefined 仅匹配 null/undefined）
-      if (_.isNil(itemValue)) {
-        return _.isNil(targetValue);
-      }
-
-      // 处理数组类型查询（支持 in 操作，如 { status: [1, 2] }）
-      if (Array.isArray(targetValue)) {
-        return targetValue.some((val) => this._compareSingleValue(itemValue, val, fuzzy, ignoreCase));
-      }
-
-      // 处理范围查询（如 { age: { $gt: 18, $lt: 30 } }）
-      if (typeof targetValue === "object" && !Array.isArray(targetValue)) {
-        return this._handleRangeQuery(itemValue, targetValue);
-      }
-
-      // 处理普通值匹配（精确/模糊）
-      return this._compareSingleValue(itemValue, targetValue, fuzzy, ignoreCase);
-    });
-  }
-
-  /**
-   * 比较单个值是否匹配（支持精确/模糊匹配）
-   * @private
-   * @param {*} itemValue - 列表项字段值
-   * @param {*} targetValue - 查询目标值
-   * @param {boolean} fuzzy - 是否模糊匹配
-   * @param {boolean} ignoreCase - 是否忽略大小写
-   * @returns {boolean} 是否匹配
-   */
-  _compareSingleValue(itemValue, targetValue, fuzzy, ignoreCase) {
-    // 类型不同时直接不匹配（避免隐式类型转换导致的问题）
-    if (typeof itemValue !== typeof targetValue) {
-      // 特殊处理：数字和字符串数字的匹配（如 123 和 '123'）
-      if (
-        (typeof itemValue === "number" && typeof targetValue === "string" && !isNaN(Number(targetValue))) ||
-        (typeof itemValue === "string" && typeof targetValue === "number" && !isNaN(Number(itemValue)))
-      ) {
-        return Number(itemValue) === targetValue;
-      }
-      return false;
-    }
-
-    // 字符串处理（支持模糊匹配和大小写忽略）
-    if (typeof itemValue === "string" && fuzzy) {
-      const itemStr = ignoreCase ? itemValue.toLowerCase() : itemValue;
-      const targetStr = ignoreCase ? String(targetValue).toLowerCase() : String(targetValue);
-      return itemStr.includes(targetStr);
-    }
-
-    // 其他类型（数字、布尔等）精确匹配
-    return itemValue === targetValue;
-  }
-
-  /**
-   * 处理范围查询（如 $gt/$lt/$gte/$lte）
-   * @private
-   * @param {number|string|Date} itemValue - 列表项字段值
-   * @param {Object} rangeConfig - 范围配置（{ $gt: 18, $lt: 30 }）
-   * @returns {boolean} 是否在范围内
-   */
-  _handleRangeQuery(itemValue, rangeConfig) {
-    const { $gt, $lt, $gte, $lte } = rangeConfig;
-    let isValid = true;
-
-    // 转换为可比较的类型（优先处理日期）
-    const compareValue = this._convertToComparableValue(itemValue);
-    const convertTarget = (val) => this._convertToComparableValue(val);
-
-    // 大于（>）
-    if ($gt !== undefined) {
-      isValid = isValid && compareValue > convertTarget($gt);
-    }
-    // 小于（<）
-    if ($lt !== undefined) {
-      isValid = isValid && compareValue < convertTarget($lt);
-    }
-    // 大于等于（>=）
-    if ($gte !== undefined) {
-      isValid = isValid && compareValue >= convertTarget($gte);
-    }
-    // 小于等于（<=）
-    if ($lte !== undefined) {
-      isValid = isValid && compareValue <= convertTarget($lte);
-    }
-
-    return isValid;
-  }
-
-  /**
-   * 将值转换为可比较的类型（统一数字、日期格式）
-   * @private
-   * @param {*} value - 待转换的值
-   * @returns {number|string} 可比较的值
-   */
-  _convertToComparableValue(value) {
-    // 日期转换为时间戳
-    if (value instanceof Date || dayjs(value).isValid()) {
-      return dayjs(value).valueOf();
-    }
-    // 字符串数字转换为数字
-    if (typeof value === "string" && !isNaN(Number(value))) {
-      return Number(value);
-    }
-    return value;
-  }
-
-  /**
-   * 过滤空查询条件（移除 undefined/null/空字符串/空数组/空对象）
-   * @private
-   * @param {Object} query - 原始查询条件
-   * @returns {Object} 过滤后的有效查询条件
-   */
-  _filterEmptyQuery(query) {
-    return Object.entries(query).reduce((acc, [key, value]) => {
-      // 保留非空值：
-      // 1. 不是 null/undefined
-      // 2. 不是空字符串
-      // 3. 不是空数组
-      // 4. 不是空对象
-      if (
-        !_.isNil(value) &&
-        value !== "" &&
-        !(Array.isArray(value) && value.length === 0) &&
-        !(typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)
-      ) {
-        acc[key] = value;
-      }
-      return acc;
-    }, {});
-  }
-
-  _hasId(id) {
-    return _.isNil(id) || id === "";
-  }
-
-  /**
-   * 子项没有 id 的时候自动添加
-   * @param {*} item
-   * @returns
-   */
-  _setId(item) {
-    if (_.isObject(item) && this._hasId(item[this._idKey])) {
-      item[this._idKey] = nanoid();
-    }
-    return item;
-  }
-
-  /**
-   * 设置创建时间
-   * @param {*} item
-   */
-  _setCreateTime(item) {
-    if (_.isObject(item) && this._hasId(item.createTime)) {
-      item.createTime = Date.now();
-    }
-  }
-
-  /**
-   * 设置更新时间
-   * @param {*} item
-   */
-  _setUpdateTime(item) {
-    item.createTime = Date.now();
-  }
-}
-
-export default ArrayUtils;
+import { nanoid } from "nanoid";
+import _ from "lodash";
+import dayjs from "dayjs";
+
+export const STATE_CODE = {
+  SUC: 200,
+  NOT_FOUNT: 404,
+  ERR: 500,
+  ERR_INPUT_ID: 501,
+};
+
+/**
+ * 数组模拟数据库存储
+ * TODO: FormData? 考虑到文件存储问题
+ */
+export class ArrayUtils {
+  _idKey = "id";
+  _list = [];
+  constructor(params) {
+    const { idKey = "id", list } = params;
+    /** 子项唯一标志字段 */
+    this._idKey = idKey || "id";
+    /** 列表数据 */
+    this._list = list || [];
+  }
+
+  /**
+   * 通过 id 获取子项
+   * @param {*} id
+   * @returns
+   */
+  findItemById(id) {
+    if (this._hasId(id)) {
+      return null;
+    }
+    const { _idKey } = this;
+    return _.cloneDeep(this._list.find((it) => it[_idKey] === id));
+  }
+
+  /**
+   * 通过 id 获取子项
+   * @param {*} id
+   * @returns
+   */
+  findItem(query = {}, options = {}) {
+    const { fuzzy = false, ignoreCase = false } = options;
+    const id = query[this._idKey];
+
+    if (!this._hasId(id)) {
+      return this.findItemById(id);
+    }
+
+    const validQuery = this._filterEmptyQuery(query);
+    if (_.isEmpty(validQuery)) {
+      return null;
+    }
+
+    const matchItem = this._list.find((item) => {
+      return this._isItemMatchQuery(item, validQuery, { fuzzy, ignoreCase });
+    });
+
+    return matchItem ? _.cloneDeep(matchItem) : null;
+  }
+
+  /**
+   * 通过 query 筛选列表（支持多条件筛选、分页、排序）
+   * @param {Object} query - 综合查询参数
+   * @param {number} [query.pageNum=1] - 页码（默认1）
+   * @param {number} [query.pageSize=10] - 每页条数（默认10）
+   * @param {string|string[]} [query.sortKey] - 排序字段（支持嵌套路径，如 'user.age'）
+   * @param {string} [query.sortType='desc'] - 排序方式（desc/asc）
+   * @param {string} [query.orderByColumn] - 兼容旧排序字段参数
+   * @param {string} [query.isAsc] - 兼容旧排序方式参数
+   * @param {Object} [options={}] - 查询选项
+   * @param {boolean} [options.fuzzy=false] - 字符串字段是否开启模糊匹配
+   * @param {boolean} [options.ignoreCase=true] - 模糊匹配时是否忽略大小写
+   * @returns {Object} 分页结果
+   * @returns {Object[]} result.list - 筛选后的列表（深拷贝）
+   * @returns {Object} result.pagination - 分页信息（current/total/pageSize）
+   */
+  findListByQuery(query = {}, options = {}) {
+    const {
+      pageNum = 1,
+      pageSize = 10,
+      sortKey,
+      sortType,
+      orderByColumn,
+      isAsc,
+      ...filterQuery // 提取筛选条件（排除分页排序参数）
+    } = query;
+
+    const { fuzzy = true, ignoreCase = false } = options;
+
+    // 数据筛选（基于 query 条件）
+    let filteredList = [...this._list];
+    const validFilterQuery = this._filterEmptyQuery(filterQuery);
+
+    if (!_.isEmpty(validFilterQuery)) {
+      filteredList = filteredList.filter((item) => {
+        return this._isItemMatchQuery(item, validFilterQuery, { fuzzy, ignoreCase });
+      });
+    }
+
+    // 数据排序（基于筛选后的数据）
+    const sortedList = this.getSortList(
+      sortKey || orderByColumn,
+      sortType || isAsc,
+      filteredList, // 传入筛选后列表，避免排序影响原数据
+    );
+
+    // 分页处理（边界校验）
+    const pagination = {
+      current: Math.max(1, pageNum), // 页码最小为1
+      pageSize: Math.max(1, pageSize), // 每页条数最小为1
+      total: filteredList.length,
+    };
+
+    // 计算分页截取范围
+    const startIndex = (pagination.current - 1) * pagination.pageSize;
+    const endIndex = startIndex + pagination.pageSize;
+    const paginatedList = sortedList.slice(startIndex, endIndex);
+
+    return {
+      list: _.cloneDeep(paginatedList),
+      pagination: { ...pagination },
+    };
+  }
+
+  /**
+   * 对目标数据进行多维度排序
+   * @param {string|string[]|Object[]} sortKey - 排序字段配置
+   * @param {string} sortType - 排序方式（desc/asc）
+   * @param {Object[]} [customList] - 自定义排序列表（默认使用内部 _list）
+   * @returns {Object[]} 排序后的列表
+   */
+  getSortList(sortKey, sortType, customList) {
+    const sourceList = customList || this._list;
+    const _list = _.cloneDeep(sourceList);
+
+    // 无排序条件时直接返回原列表
+    if (!sortKey && !sortType) {
+      return _list;
+    }
+
+    // 统一排序字段格式为数组
+    const paths = Array.isArray(sortKey) ? sortKey : [sortKey];
+
+    _list.sort((a, b) => {
+      return this.compareData(a, b, { paths, sortType, pathIdx: 0 });
+    });
+
+    return _list;
+  }
+
+  /**
+   * 比较两个数据对象的排序顺序（支持多字段优先级排序）
+   * @param {Object} dataA - 比较对象A
+   * @param {Object} dataB - 比较对象B
+   * @param {Object} opt - 比较配置
+   * @param {string[]|Object[]} opt.paths - 排序字段路径数组
+   * @param {number} opt.pathIdx - 当前比较的字段索引
+   * @param {string} opt.sortType - 排序方式（desc/asc）
+   * @returns {number} 排序结果（-1/0/1）
+   */
+  compareData(dataA, dataB, opt = {}) {
+    const { paths, pathIdx = 0, sortType = "desc" } = opt;
+    const currentPath = paths[pathIdx];
+
+    // 处理自定义比较逻辑
+    if (currentPath && typeof currentPath === "object" && typeof currentPath.customCompare === "function") {
+      const direction = sortType === "asc" ? -1 : 1;
+      return direction * currentPath.customCompare(dataA, dataB, opt);
+    }
+
+    // 提取实际字段路径（支持配置对象格式）
+    const path = typeof currentPath === "object" ? currentPath.path : currentPath;
+    if (!path) {
+      return 0;
+    }
+
+    // 确定排序方向（支持按字段单独配置排序方式）
+    let direction = 1;
+    let _sortType = sortType;
+    if (typeof _sortType === "object") {
+      _sortType = _sortType[path] || "desc";
+    }
+    if (_sortType === "asc") {
+      direction = -1;
+    }
+
+    // 获取并处理字段值（支持日期转换、自定义格式化）
+    const valueA = this.handleValByKey(dataA, currentPath);
+    const valueB = this.handleValByKey(dataB, currentPath);
+
+    // 数值比较
+    if (valueA < valueB) {
+      return -1 * direction;
+    }
+    if (valueA > valueB) {
+      return 1 * direction;
+    }
+
+    // 当前字段值相等时，使用下一个优先级字段排序
+    if (pathIdx + 1 < paths.length) {
+      return this.compareData(dataA, dataB, { ...opt, pathIdx: pathIdx + 1 });
+    }
+
+    // 所有字段都相等时，保持原有顺序
+    return 0;
+  }
+
+  /**
+   * 根据路径获取并处理字段值（支持嵌套路径、类型转换、自定义格式化）
+   * @param {Object} data - 数据源对象
+   * @param {string|Object} pathConfig - 字段配置
+   * @param {string} [pathConfig.path] - 字段路径（如 'user.address.city'）
+   * @param {string} [pathConfig.type] - 字段类型（支持 'date' 自动转时间戳）
+   * @param {Function} [pathConfig.customFormat] - 自定义值处理函数
+   * @returns {*} 处理后的字段值
+   */
+  handleValByKey(data, pathConfig) {
+    // 处理字符串路径
+    if (typeof pathConfig === "string") {
+      return _.get(data, pathConfig);
+    }
+
+    // 处理空配置
+    if (_.isNil(pathConfig)) {
+      return undefined;
+    }
+
+    // 处理对象配置
+    if (typeof pathConfig === "object") {
+      let val = _.get(data, pathConfig.path);
+
+      // 日期类型转换为时间戳（便于数值比较）
+      if (pathConfig.type === "date") {
+        val = dayjs(val).isValid() ? dayjs(val).valueOf() : 0;
+      }
+
+      // 自定义值格式化
+      if (typeof pathConfig.customFormat === "function") {
+        val = pathConfig.customFormat(val, data);
+      }
+
+      return val;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * 获取完整列表
+   */
+  findAllList() {
+    return _.cloneDeep(this._list);
+  }
+
+  /**
+   * 获取总数
+   * @returns
+   */
+  getCount() {
+    return this._list.length;
+  }
+
+  /**
+   * push 数据
+   * @param {*} data
+   */
+  pushItem(data) {
+    // TODO: id 去重
+    const items = Array.isArray(data) ? data : [data];
+    items.forEach((item) => {
+      const cloneItem = _.cloneDeep(item);
+      this._setId(cloneItem);
+      this._setCreateTime(cloneItem);
+      this._list.push(cloneItem);
+    });
+    return STATE_CODE.SUC;
+  }
+
+  /**
+   * unshift 数据
+   * @param {*} data
+   */
+  unshiftItem(data) {
+    // TODO: id 去重
+    const item = _.cloneDeep(data);
+    this._setId(item);
+    this._setCreateTime(item);
+    this._list.unshift(item);
+    return STATE_CODE.SUC;
+  }
+
+  /**
+   * 根据 id 更新子项——直接替换
+   * @param {Object} data
+   * @returns
+   */
+  replaceItem(data) {
+    const { _idKey, _list } = this;
+    const id = data[_idKey];
+    if (this._hasId(id)) {
+      return STATE_CODE.ERR_INPUT_ID;
+    }
+    const idx = _list.findIndex((it) => it[_idKey] === id);
+    if (idx < 0) {
+      return STATE_CODE.NOT_FOUNT;
+    }
+    _list.splice(idx, 1, data);
+    this._setUpdateTime(data);
+    return STATE_CODE.SUC;
+  }
+
+  /**
+   * 根据 id 更新子项——仅修改传入的数据
+   * @param {Object} data
+   * @returns
+   */
+  updateItemValue(data) {
+    const { _idKey, _list } = this;
+    const id = data[_idKey];
+    if (this._hasId(id)) {
+      return STATE_CODE.ERR_INPUT_ID;
+    }
+    const item = _list.find((it) => it[_idKey] === id);
+    if (!item) {
+      return STATE_CODE.NOT_FOUNT;
+    }
+    Object.keys(data).forEach((key) => {
+      item[key] = data[key];
+    });
+    this._setUpdateTime(data);
+    return STATE_CODE.SUC;
+  }
+
+  /**
+   * 删除子项
+   * @param {*} id
+   * @param {*} data
+   * @returns
+   */
+  delItem(id) {
+    const { _idKey, _list } = this;
+    if (this._hasId(id)) {
+      return STATE_CODE.ERR_INPUT_ID;
+    }
+    const idx = _list.findIndex((it) => it[_idKey] === id);
+    if (idx < 0) {
+      return STATE_CODE.NOT_FOUNT;
+    }
+    _list.splice(idx, 1);
+    return STATE_CODE.SUC;
+  }
+
+  /**
+   * 检查单个 item 是否匹配所有 query 条件
+   * @private
+   * @param {Object} item - 待检查的列表项
+   * @param {Object} query - 查询条件
+   * @param {Object} options - 匹配选项
+   * @param {boolean} options.fuzzy - 是否开启模糊匹配
+   * @param {boolean} options.ignoreCase - 模糊匹配是否忽略大小写
+   * @returns {boolean} 是否匹配所有条件
+   */
+  _isItemMatchQuery(item, query, { fuzzy, ignoreCase }) {
+    // 遍历所有查询条件，必须全部满足才返回 true
+    return Object.entries(query).every(([key, targetValue]) => {
+      // 获取 item 中对应字段的值（支持嵌套路径，如 'user.name'）
+      const itemValue = _.get(item, key);
+
+      // 处理空值情况（null/undefined 仅匹配 null/undefined）
+      if (_.isNil(itemValue)) {
+        return _.isNil(targetValue);
+      }
+
+      // 处理数组类型查询（支持 in 操作，如 { status: [1, 2] }）
+      if (Array.isArray(targetValue)) {
+        return targetValue.some((val) => this._compareSingleValue(itemValue, val, fuzzy, ignoreCase));
+      }
+
+      // 处理范围查询（如 { age: { $gt: 18, $lt: 30 } }）
+      if (typeof targetValue === "object" && !Array.isArray(targetValue)) {
+        return this._handleRangeQuery(itemValue, targetValue);
+      }
+
+      // 处理普通值匹配（精确/模糊）
+      return this._compareSingleValue(itemValue, targetValue, fuzzy, ignoreCase);
+    });
+  }
+
+  /**
+   * 比较单个值是否匹配（支持精确/模糊匹配）
+   * @private
+   * @param {*} itemValue - 列表项字段值
+   * @param {*} targetValue - 查询目标值
+   * @param {boolean} fuzzy - 是否模糊匹配
+   * @param {boolean} ignoreCase - 是否忽略大小写
+   * @returns {boolean} 是否匹配
+   */
+  _compareSingleValue(itemValue, targetValue, fuzzy, ignoreCase) {
+    // 类型不同时直接不匹配（避免隐式类型转换导致的问题）
+    if (typeof itemValue !== typeof targetValue) {
+      // 特殊处理：数字和字符串数字的匹配（如 123 和 '123'）
+      if (
+        (typeof itemValue === "number" && typeof targetValue === "string" && !isNaN(Number(targetValue))) ||
+        (typeof itemValue === "string" && typeof targetValue === "number" && !isNaN(Number(itemValue)))
+      ) {
+        return Number(itemValue) === targetValue;
+      }
+      return false;
+    }
+
+    // 字符串处理（支持模糊匹配和大小写忽略）
+    if (typeof itemValue === "string" && fuzzy) {
+      const itemStr = ignoreCase ? itemValue.toLowerCase() : itemValue;
+      const targetStr = ignoreCase ? String(targetValue).toLowerCase() : String(targetValue);
+      return itemStr.includes(targetStr);
+    }
+
+    // 其他类型（数字、布尔等）精确匹配
+    return itemValue === targetValue;
+  }
+
+  /**
+   * 处理范围查询（如 $gt/$lt/$gte/$lte）
+   * @private
+   * @param {number|string|Date} itemValue - 列表项字段值
+   * @param {Object} rangeConfig - 范围配置（{ $gt: 18, $lt: 30 }）
+   * @returns {boolean} 是否在范围内
+   */
+  _handleRangeQuery(itemValue, rangeConfig) {
+    const { $gt, $lt, $gte, $lte } = rangeConfig;
+    let isValid = true;
+
+    // 转换为可比较的类型（优先处理日期）
+    const compareValue = this._convertToComparableValue(itemValue);
+    const convertTarget = (val) => this._convertToComparableValue(val);
+
+    // 大于（>）
+    if ($gt !== undefined) {
+      isValid = isValid && compareValue > convertTarget($gt);
+    }
+    // 小于（<）
+    if ($lt !== undefined) {
+      isValid = isValid && compareValue < convertTarget($lt);
+    }
+    // 大于等于（>=）
+    if ($gte !== undefined) {
+      isValid = isValid && compareValue >= convertTarget($gte);
+    }
+    // 小于等于（<=）
+    if ($lte !== undefined) {
+      isValid = isValid && compareValue <= convertTarget($lte);
+    }
+
+    return isValid;
+  }
+
+  /**
+   * 将值转换为可比较的类型（统一数字、日期格式）
+   * @private
+   * @param {*} value - 待转换的值
+   * @returns {number|string} 可比较的值
+   */
+  _convertToComparableValue(value) {
+    // 日期转换为时间戳
+    if (value instanceof Date || dayjs(value).isValid()) {
+      return dayjs(value).valueOf();
+    }
+    // 字符串数字转换为数字
+    if (typeof value === "string" && !isNaN(Number(value))) {
+      return Number(value);
+    }
+    return value;
+  }
+
+  /**
+   * 过滤空查询条件（移除 undefined/null/空字符串/空数组/空对象）
+   * @private
+   * @param {Object} query - 原始查询条件
+   * @returns {Object} 过滤后的有效查询条件
+   */
+  _filterEmptyQuery(query) {
+    return Object.entries(query).reduce((acc, [key, value]) => {
+      // 保留非空值：
+      // 1. 不是 null/undefined
+      // 2. 不是空字符串
+      // 3. 不是空数组
+      // 4. 不是空对象
+      if (
+        !_.isNil(value) &&
+        value !== "" &&
+        !(Array.isArray(value) && value.length === 0) &&
+        !(typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)
+      ) {
+        acc[key] = value;
+      }
+      return acc;
+    }, {});
+  }
+
+  _hasId(id) {
+    return _.isNil(id) || id === "";
+  }
+
+  /**
+   * 子项没有 id 的时候自动添加
+   * @param {*} item
+   * @returns
+   */
+  _setId(item) {
+    if (_.isObject(item) && this._hasId(item[this._idKey])) {
+      item[this._idKey] = nanoid();
+    }
+    return item;
+  }
+
+  /**
+   * 设置创建时间
+   * @param {*} item
+   */
+  _setCreateTime(item) {
+    if (_.isObject(item) && this._hasId(item.createTime)) {
+      item.createTime = Date.now();
+    }
+  }
+
+  /**
+   * 设置更新时间
+   * @param {*} item
+   */
+  _setUpdateTime(item) {
+    item.createTime = Date.now();
+  }
+}
+
+export default ArrayUtils;