chanjs 2.7.2 → 2.7.4

package/base/{Service.js → Repository.js}

@@ -1,539 +1,644 @@
-/**
- * 数据库服务基类
- * 提供常用的数据库操作方法，包括增删改查、分页查询、事务等
- */
-import { formatDateFields } from "../helper/time.js";
-import Container from "./Container.js";
-
-class Service extends Container {
-  /**
-   * 构造函数
-   * @param {string} tableName - 表名
-   * @param {string} dbName - 数据库名称，默认使用默认数据库
-   */
-  constructor(tableName = null, dbName = null) {
-    super('service');
-
-    // 根据数据库名称获取，否则使用默认数据库
-    if (dbName) {
-      this.db = Chan.dbManager.get(dbName);
-    } else {
-      this.db = Chan.db;
-    }
-
-    if (tableName) {
-      this.tableName = tableName;
-    }
-
-    this._dateFields = [
-      'created_at', 
-      'updated_at', 
-      'deleted_at', 
-      'publish_time', 
-      'start_time', 
-      'end_time', 
-      'login_time', 
-      'created_date', 
-      'updated_date', 
-      'createdAt', 
-      'updatedAt', 
-      'deletedAt', 
-      'publishTime', 
-      'startTime', 
-      'endTime', 
-      'loginTime', 
-      'createdDate', 
-      'updatedDate'
-    ]; 
-    
-    // 自动注册事件监听器（如果子类定义了 on 方法）
-    if (typeof this.on === 'function') {
-      this.on();
-    }
-  }
-
-  /**
-   * 获取每页大小配置
-   * @returns {number} 每页记录数，默认20
-   */
-  get pageSize() {
-    return Chan.config.PAGE_SIZE || 20;
-  }
-
-  /**
-   * 获取最大限制配置
-   * @returns {number} 最大记录数，默认300
-   */
-  get limit() {
-    return Chan.config.LIMIT_MAX || 300;
-  }
-
-  /**
-   * 检查数据库连接是否可用
-   * @private
-   * @throws {Error} 数据库连接不可用时抛出异常
-   */
-  _checkDB() {
-    if (!this.db) {
-      throw new Error("Database connection not available");
-    }
-  }
-
-  /**
-   * 格式化日期字段
-   * @private
-   * @param {Object} data - 要格式化的数据对象
-   * @returns {Object} 格式化后的数据
-   * @description 自动将日期字符串转换为数据库可识别的格式
-   */
-  _formatDateFields(data) {
-    if (!data || typeof data !== 'object') return data;
-    
-    const result = { ...data };
-    for (const field of this._dateFields) {
-      if (result[field] && typeof result[field] === 'string') {
-        try {
-          const date = new Date(result[field]);
-          if (!isNaN(date.getTime())) {
-            result[field] = date;
-          }
-        } catch (error) {
-          console.error(`[Service._formatDateFields] 日期字段 ${field} 格式化失败:`, {
-            value: result[field],
-            error: error.message
-          });
-        }
-      }
-    }
-    return result;
-  }
-
-  /**
-   * 构建基础查询
-   * @private
-   * @param {Object} options - 查询选项
-   * @param {Object} options.query - 查询条件
-   * @param {Object} options.sort - 排序条件
-   * @param {Array} options.fields - 查询字段
-   * @returns {Object} Knex查询构建器
-   */
-  _buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) {
-    this._checkDB();
-    
-    let dbQuery = this.db(this.tableName);
-    
-    if (Object.keys(query).length) dbQuery = dbQuery.where(query);
-    if (fields.length) dbQuery = dbQuery.select(fields);
-    
-    if (sort && typeof sort === 'object') {
-      for (const [field, dir] of Object.entries(sort)) {
-        const direction = ['asc', 'desc'].includes(dir.toLowerCase()) ? dir.toLowerCase() : 'asc';
-        dbQuery = dbQuery.orderBy(field, direction);
-      }
-    }
-    
-    return dbQuery;
-  }
-
-  /**
-   * 查询所有记录
-   * @param {Object} options - 查询选项
-   * @param {Object} options.query - 查询条件
-   * @param {Object} options.sort - 排序条件
-   * @param {Array} options.fields - 查询字段
-   * @returns {Promise<Array>} 查询结果数组
-   */
-  async all({ query = {}, sort = {}, fields = [] } = {}) {
-    const _query = this._buildBaseQuery({ query, sort, fields });
-    const res = await _query.select();
-    return formatDateFields(res, this._dateFields);
-  }
-
-  /**
-   * 分页查询记录
-   * @param {Object} options - 查询选项
-   * @param {Object} options.query - 查询条件
-   * @param {Object} options.sort - 排序条件
-   * @param {Array} options.fields - 查询字段
-   * @param {number} options.limit - 限制条数
-   * @param {number} options.offset - 偏移量
-   * @returns {Promise<Object>} 查询结果，包含data字段
-   */
-  async find({ query = {}, sort = {}, fields = [], limit, offset } = {}) {
-    let _query = this._buildBaseQuery({ query, sort, fields });
-
-    if (typeof offset === 'number') {
-      _query = _query.offset(offset);
-    }
-    if (typeof limit === 'number') {
-      _query = _query.limit(limit);
-    }
-
-    const res = await _query.select();
-    return { success: true, code: 200, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
-  }
-
-  /**
-   * 查询单条记录
-   * @param {Object} options - 查询选项
-   * @param {Object} options.query - 查询条件
-   * @param {Array} options.fields - 查询字段
-   * @returns {Promise<Object>} 查询结果，包含data字段
-   */
-  async findOne({ query = {}, fields = [] } = {}) {
-    this._checkDB();
-    
-    let dbQuery = this.db(this.tableName);
-    if (Object.keys(query).length) dbQuery = dbQuery.where(query);
-    if (fields.length) dbQuery = dbQuery.select(fields);
-    const res = await dbQuery.first();
-    
-    if (!res) {
-      return { success: false, code: 404, msg: '记录不存在', data: null };
-    }
-    
-    return { success: true, code: 200, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
-  }
-
-  /**
-   * 根据ID查询单条记录
-   * @param {number|string} id - 记录ID
-   * @param {Object} options - 查询选项
-   * @param {Array} options.fields - 查询字段
-   * @returns {Promise<Object>} 查询结果，包含data字段
-   */
-  async findById(id, { fields = [] } = {}) {
-    this._checkDB();
-    
-    let _query = this.db(this.tableName).where({ id });
-    if (fields.length) _query = _query.select(fields);
-    const res = await _query.first();
-    
-    if (!res) {
-      return { success: false, code: 404, msg: '记录不存在', data: null };
-    }
-    
-    return { success: true, code: 200, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
-  }
-
-  /**
-   * 插入单条记录
-   * @param {Object} data - 要插入的数据
-   * @returns {Promise<Object>} 插入结果，包含insertId和affectedRows
-   */
-  async insert(data = {}) {
-    this._checkDB();
-    
-    if (!Object.keys(data).length) return { success: false, code: 400, msg: '参数缺失', data: {} };
-    const formattedData = this._formatDateFields(data);
-    const result = await this.db(this.tableName).insert(formattedData);
-    return { success: true, code: 200, msg: '插入成功', data: { insertId: result[0], affectedRows: result.length } };
-  }
-
-  /**
-   * 批量插入记录
-   * @param {Array} records - 要插入的记录数组
-   * @returns {Promise<Object>} 插入结果，包含insertIds和affectedRows
-   */
-  async insertMany(records = []) {
-    this._checkDB();
-    
-    if (!records.length) return { success: false, code: 400, msg: '参数缺失', data: {} };
-    const formattedRecords = records.map(record => this._formatDateFields(record));
-    const result = await this.db(this.tableName).insert(formattedRecords);
-    return { success: true, code: 200, msg: '批量插入成功', data: { insertIds: result, affectedRows: result.length } };
-  }
-
-  /**
-   * 根据条件删除记录
-   * @param {Object} query - 删除条件
-   * @returns {Promise<Object>} 删除结果，包含affectedRows
-   */
-  async delete(query = {}) {
-    this._checkDB();
-    
-    if (!Object.keys(query).length) return { success: false, code: 400, msg: '参数缺失', data: {} };
-    const affectedRows = await this.db(this.tableName).where(query).del();
-    return { success: true, code: 200, msg: '删除成功', data: { affectedRows } };
-  }
-
-  /**
-   * 根据ID删除记录
-   * @param {number|string} id - 记录ID
-   * @returns {Promise<Object>} 删除结果，包含affectedRows
-   */
-  async deleteById(id) {
-    this._checkDB();
-    
-    if (!id) return { success: false, code: 400, msg: '参数缺失', data: {} };
-    const affectedRows = await this.db(this.tableName).where({ id }).del();
-    return { success: true, code: 200, msg: '删除成功', data: { affectedRows } };
-  }
-
-  /**
-   * 根据条件更新记录
-   * @param {Object} options - 更新选项
-   * @param {Object} options.query - 更新条件
-   * @param {Object} options.data - 更新数据
-   * @returns {Promise<Object>} 更新结果，包含affectedRows
-   */
-  async updateByQuery({ query, data } = {}) {
-    this._checkDB();
-    
-    if (!query || !data || !Object.keys(query).length || !Object.keys(data).length) {
-      return { success: false, code: 400, msg: '参数无效', data: {} };
-    }
-    const formattedData = this._formatDateFields(data);
-    const affectedRows = await this.db(this.tableName).where(query).update(formattedData);
-    return { success: true, code: 200, msg: '更新成功', data: { affectedRows } };
-  }
-
-  /**
-   * 根据ID更新记录
-   * @param {number|string} id - 记录ID
-   * @param {Object} data - 更新数据
-   * @returns {Promise<Object>} 更新结果，包含affectedRows
-   */
-  async updateById(id, data = {}) {
-    this._checkDB();
-    
-    if (!id || !Object.keys(data).length) {
-      return { success: false, code: 400, msg: '参数无效', data: {} };
-    }
-    const formattedData = this._formatDateFields(data);
-    const affectedRows = await this.db(this.tableName).where({ id }).update(formattedData);
-    const updatedRecord = await this.findById(id);
-    return { success: true, code: 200, msg: '更新成功', data: updatedRecord.data };
-  }
-
-  /**
-   * 批量更新记录（事务）
-   * @param {Array} updates - 更新数组，每项包含query和data
-   * @returns {Promise<Object>} 更新结果，包含affectedRows
-   */
-  async updateMany(updates = []) {
-    this._checkDB();
-    
-    if (!Array.isArray(updates) || !updates.length) {
-      return { success: false, code: 400, msg: '参数缺失', data: {} };
-    }
-
-    const trx = await this.db.transaction();
-    let totalAffected = 0;
-    for (const { query, data } of updates) {
-      if (!query || !Object.keys(query).length) {
-        await trx.rollback().catch(rollbackErr => {
-          console.error('[updateMany] 回滚失败:', rollbackErr.message);
-        });
-        return { success: false, code: 400, msg: '参数无效：批量更新不允许空条件', data: {} };
-      }
-      const result = await trx(this.tableName).where(query).update(data);
-      if (result === 0) {
-        console.log('[updateMany] 未匹配到行, query=%j', query);
-      }
-      totalAffected += result;
-    }
-    await trx.commit();
-    return { success: true, code: 200, msg: '批量更新成功', data: { affectedRows: totalAffected } };
-  }
-
-  /**
-   * 分页查询
-   * @param {Object} options - 查询选项
-   * @param {number} options.current - 当前页码，默认1
-   * @param {number} options.pageSize - 每页大小，默认10
-   * @param {Object} options.query - 查询条件
-   * @param {Object} options.sort - 排序条件
-   * @param {Array} options.field - 查询字段
-   * @returns {Promise<Object>} 分页结果，包含list、total、current、pageSize、totalPages
-   */
-  async query({ current = 1, pageSize = 10, query = {}, sort = {}, field = [] }) {
-    this._checkDB();
-    
-    const size = Math.min(Math.max(pageSize, 1), this.limit);
-    const offset = (current - 1) * size;
-
-    let countQuery = this.db(this.tableName).count("* as total");
-    let dataQuery = this._buildBaseQuery({ query, sort, fields: field });
-
-    const [totalResult, list] = await Promise.all([
-      countQuery.first(),
-      dataQuery.offset(offset).limit(size),
-    ]);
-
-    const total = Number(totalResult?.total ?? 0);
-    const totalPages = Math.ceil(total / size);
-
-    return { success: true, code: 200, msg: '查询成功', data: { list: formatDateFields(list, this._dateFields), total, current, pageSize: size, totalPages } };
-  }
-
-  /**
-   * 统计记录数
-   * @param {Object} query - 查询条件
-   * @returns {Promise<Object>} 统计结果，包含count
-   */
-  async count(query = {}) {
-    this._checkDB();
-    
-    let dataQuery = this.db(this.tableName);
-    if (Object.keys(query).length) dataQuery = dataQuery.where(query);
-    const result = await dataQuery.count("* as total").first();
-    return { success: true, code: 200, msg: '统计成功', data: { count: Number(result?.total ?? 0) } };
-  }
-
-  /**
-   * 检查记录是否存在
-   * @param {Object} query - 查询条件
-   * @returns {Promise<Object>} 存在性结果，包含exists布尔值
-   */
-  async exists(query = {}) {
-    this._checkDB();
-    
-    let dataQuery = this.db(this.tableName);
-    if (Object.keys(query).length) dataQuery = dataQuery.where(query);
-    const result = await dataQuery.first();
-    return { success: true, code: 200, msg: '检查成功', data: { exists: !!result } };
-  }
-
-  /**
-   * 关联查询
-   * @param {Object} options - 查询选项
-   * @param {string} options.joinTable - 关联表名
-   * @param {string} options.localField - 本地表字段
-   * @param {string} options.foreignField - 关联表字段
-   * @param {Array} options.fields - 查询字段，默认["*"]
-   * @param {Object} options.query - 查询条件
-   * @param {Object} options.sort - 排序条件
-   * @returns {Promise<Array>} 查询结果数组
-   */
-  async join({ joinTable, localField, foreignField, fields = ["*"], query = {}, sort = {} }) {
-    this._checkDB();
-    
-    let _query = this.db(this.tableName)
-      .join(
-        joinTable,
-        `${this.tableName}.${localField}`,
-        "=",
-        `${joinTable}.${foreignField}`
-      )
-      .select(fields);
-
-    if (Object.keys(query).length) _query = _query.where(query);
-    if (sort && typeof sort === 'object') {
-      for (const [field, dir] of Object.entries(sort)) {
-        const direction = ['asc', 'desc'].includes(dir.toLowerCase()) ? dir.toLowerCase() : 'asc';
-        _query = _query.orderBy(field, direction);
-      }
-    }
-
-    const res = await _query;
-    return { success: true, code: 200, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
-  }
-
-  /**
-   * 批量删除记录（根据ID数组）
-   * @param {Array} ids - ID数组
-   * @returns {Promise<Object>} 删除结果，包含affectedRows
-   */
-  async deleteMany(ids = []) {
-    this._checkDB();
-    
-    if (!ids.length) return { success: false, code: 400, msg: '参数缺失', data: {} };
-    const affectedRows = await this.db(this.tableName).whereIn('id', ids).del();
-    return { success: true, code: 200, msg: '删除成功', data: { affectedRows } };
-  }
-
-  /**
-   * 软删除（设置deleted_at字段）
-   * @param {number|string} id - 记录ID
-   * @returns {Promise<Object>} 删除结果，包含affectedRows
-   */
-  async softDelete(id) {
-    this._checkDB();
-    
-    if (!id) return { msg: '参数缺失' };
-    const affectedRows = await this.db(this.tableName)
-      .where({ id })
-      .update({ deleted_at: new Date() });
-    return { affectedRows };
-  }
-
-  /**
-   * 恢复软删除的记录
-   * @param {number|string} id - 记录ID
-   * @returns {Promise<Object>} 恢复结果，包含affectedRows
-   */
-  async restore(id) {
-    this._checkDB();
-    
-    if (!id) return { msg: '参数缺失' };
-    const affectedRows = await this.db(this.tableName)
-      .where({ id })
-      .update({ deleted_at: null });
-    return { affectedRows };
-  }
-
-  /**
-   * 查询已软删除的记录
-   * @param {Object} options - 查询选项
-   * @param {Object} options.query - 查询条件
-   * @param {Array} options.fields - 查询字段
-   * @param {number} options.limit - 限制条数，默认20
-   * @param {number} options.offset - 偏移量，默认0
-   * @returns {Promise<Array>} 查询结果数组
-   */
-  async findTrashed({ query = {}, fields = [], limit = 20, offset = 0 } = {}) {
-    this._checkDB();
-    
-    let _query = this.db(this.tableName).whereNotNull('deleted_at');
-    
-    if (Object.keys(query).length) _query = _query.where(query);
-    if (fields.length) _query = _query.select(fields);
-    
-    const res = await _query.limit(limit).offset(offset).orderBy('deleted_at', 'desc');
-    return res;
-  }
-
-  /**
-   * 强制删除指定天数前的软删除记录
-   * @param {number} days - 天数，默认30天
-   * @returns {Promise<Object>} 删除结果，包含affectedRows
-   */
-  async forceDelete(days = 30) {
-    this._checkDB();
-    
-    const date = new Date();
-    date.setDate(date.getDate() - days);
-    
-    const affectedRows = await this.db(this.tableName)
-      .whereNotNull('deleted_at')
-      .where('deleted_at', '<', date)
-      .del();
-    
-    return { affectedRows };
-  }
-
-  /**
-   * 统计数据（总数和今日新增）
-   * @returns {Promise<Object>} 统计结果，包含total和today
-   */
-  async stats() {
-    this._checkDB();
-    
-    const total = await this.db(this.tableName).count('* as count').first();
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-    
-    const todayCount = await this.db(this.tableName)
-      .where('created_at', '>=', today)
-      .count('* as count')
-      .first();
-    
-    return {
-      total: Number(total?.count || 0),
-      today: Number(todayCount?.count || 0)
-    };
-  }
-}
-
-export default Service;
+/**
+ * 数据访问基类（Repository / DAO 层）
+ *
+ * ============================================================
+ * 设计说明
+ * ============================================================
+ * 本类是真正的 DAO/Repository 层，负责数据访问（CRUD/分页/事务/软删除）。
+ * 业务侧的 Service 层应继承本类，专注于业务编排，数据访问委托给 Repository。
+ *
+ * 三层架构：
+ *   Controller（路由）→ Service（业务编排）→ Repository（数据访问）
+ *
+ * ============================================================
+ * 依赖注入（DI）
+ * ============================================================
+ * 不再依赖 global.Chan，通过 Container 基类的 DI 获取应用资源：
+ * - this.db      → 数据库连接（动态读取 Chan.db）
+ * - this.config  → 应用配置（动态读取 Chan.config）
+ * - this.app     → Chan 类引用（可访问 app.dbManager 等）
+ * - this.paths   → 路径配置（动态读取 Chan.paths）
+ *
+ * ============================================================
+ * 响应码体系（与 Controller 对齐）
+ * ============================================================
+ * 所有返回值遵循：{ success, code, msg, data }
+ * - code: 0 成功 / 1xxx 业务 / 5xxx 系统 / 6xxx 数据库
+ */
+import { formatDateFields } from "../utils/time.js";
+import Container from "./Container.js";
+import {
+  CODE_OK,
+  CODE_NOT_FOUND,
+  CODE_PARAM_INVALID,
+  CODE_PARAM_MISSING,
+} from "../config/code.js";
+
+// 业务 code 语义化常量（本文件内部使用，避免硬编码数字）
+const OK = CODE_OK;                  // 0 成功
+const NOT_FOUND = CODE_NOT_FOUND;    // 1004 资源不存在
+const PARAM_INVALID = CODE_PARAM_INVALID;  // 1006 参数无效
+const PARAM_MISSING = CODE_PARAM_MISSING;  // 1007 参数缺失
+
+// 排序字段白名单正则：仅允许字母开头、字母数字下划线组合，拒绝任意 SQL 注入字符
+const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+class Repository extends Container {
+  /**
+   * 构造函数
+   * @param {string} tableName - 表名
+   * @param {string} dbName - 数据库名称，默认使用默认数据库
+   */
+  constructor(tableName = null, dbName = null) {
+    super('service');
+
+    // 通过 DI 获取数据库连接（dbName 指定则从 dbManager 取，否则用默认 db）
+    // 注意：延迟到首次访问时读取，避免构造时 Chan.db 尚未初始化
+    this._dbName = dbName;
+    if (dbName) {
+      // 指定库名：覆盖父类 getter，从 dbManager 取
+      this._customDb = null;  // 延迟初始化
+    }
+    // 默认库名：用父类 getter this.db（动态读取 Chan.db）
+
+    if (tableName) {
+      this.tableName = tableName;
+    }
+
+    this._dateFields = [
+      'created_at',
+      'updated_at',
+      'deleted_at',
+      'publish_time',
+      'start_time',
+      'end_time',
+      'login_time',
+      'created_date',
+      'updated_date',
+      'createdAt',
+      'updatedAt',
+      'deletedAt',
+      'publishTime',
+      'startTime',
+      'endTime',
+      'loginTime',
+      'createdDate',
+      'updatedDate'
+    ];
+
+    // 自动注册事件监听器（如果子类定义了 on 方法）
+    if (typeof this.on === 'function') {
+      this.on();
+    }
+  }
+
+  /**
+   * 数据库连接（DI 动态读取）
+   * 指定 dbName 时从 dbManager 获取，否则用默认 Chan.db
+   */
+  get db() {
+    if (this._dbName) {
+      // 指定库名：从 dbManager 获取（延迟初始化 + 缓存）
+      if (!this._customDb) {
+        this._customDb = this.app.dbManager.get(this._dbName);
+      }
+      return this._customDb;
+    }
+    // 默认库：动态读取（避免构造时快照）
+    return this.app.db;
+  }
+
+  /**
+   * 获取每页大小配置
+   * @returns {number} 每页记录数，默认20
+   */
+  get pageSize() {
+    return this.config?.PAGE_SIZE || 20;
+  }
+
+  /**
+   * 获取最大限制配置
+   * @returns {number} 最大记录数，默认300
+   */
+  get limit() {
+    return this.config?.LIMIT_MAX || 300;
+  }
+
+  /**
+   * 检查数据库连接是否可用
+   * @private
+   * @throws {Error} 数据库连接不可用时抛出异常
+   */
+  _checkDB() {
+    if (!this.db) {
+      throw new Error("Database connection not available");
+    }
+  }
+
+  /**
+   * 格式化日期字段
+   * @private
+   * @param {Object} data - 要格式化的数据对象
+   * @returns {Object} 格式化后的数据
+   * @description 自动将日期字符串转换为数据库可识别的格式
+   */
+  _formatDateFields(data) {
+    if (!data || typeof data !== 'object') return data;
+
+    const result = { ...data };
+    for (const field of this._dateFields) {
+      if (result[field] && typeof result[field] === 'string') {
+        try {
+          const date = new Date(result[field]);
+          if (!isNaN(date.getTime())) {
+            result[field] = date;
+          }
+        } catch (error) {
+          console.error(`[Repository._formatDateFields] 日期字段 ${field} 格式化失败:`, {
+            value: result[field],
+            error: error.message
+          });
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 构建基础查询
+   * @private
+   * @param {Object} options - 查询选项
+   * @param {Object} options.query - 查询条件
+   * @param {Object} options.sort - 排序条件
+   * @param {Array} options.fields - 查询字段
+   * @returns {Object} Knex查询构建器
+   */
+  _buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) {
+    this._checkDB();
+
+    let dbQuery = this.db(this.tableName);
+
+    if (Object.keys(query).length) dbQuery = dbQuery.where(query);
+    if (fields.length) dbQuery = dbQuery.select(fields);
+
+    if (sort && typeof sort === 'object') {
+      for (const [field, dir] of Object.entries(sort)) {
+        // 排序字段白名单校验，拒绝 SQL 注入字符
+        if (!SORT_FIELD_REGEX.test(field)) {
+          console.warn(`[Repository] 非法排序字段被拒绝: ${field}`);
+          continue;
+        }
+        const direction = ['asc', 'desc'].includes(String(dir).toLowerCase()) ? String(dir).toLowerCase() : 'asc';
+        dbQuery = dbQuery.orderBy(field, direction);
+      }
+    }
+
+    return dbQuery;
+  }
+
+  /**
+   * 查询所有记录
+   *
+   * 安全说明：
+   *   - 默认 limit 1000，防止全表返回导致 OOM
+   *   - 业务侧如需更多结果，可显式传 limit 参数覆盖
+   *   - 如需分页，请使用 find()/query() 而非 all()
+   *
+   * @param {Object} options - 查询选项
+   * @param {Object} options.query - 查询条件
+   * @param {Object} options.sort - 排序条件
+   * @param {Array} options.fields - 查询字段（推荐显式指定，避免 SELECT * 拉回 longtext content 放大 IO）
+   * @param {number} [options.limit=1000] - 返回条数上限，默认 1000
+   * @returns {Promise<Object>} 查询结果，包含 data 字段（数组）
+   */
+  async all({ query = {}, sort = {}, fields = [], limit = 1000 } = {}) {
+    const _query = this._buildBaseQuery({ query, sort, fields });
+    const res = await _query.limit(limit).select();
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 分页查询记录
+   * @param {Object} options - 查询选项
+   * @param {Object} options.query - 查询条件
+   * @param {Object} options.sort - 排序条件
+   * @param {Array} options.fields - 查询字段
+   * @param {number} options.limit - 限制条数
+   * @param {number} options.offset - 偏移量
+   * @returns {Promise<Object>} 查询结果，包含data字段
+   */
+  async find({ query = {}, sort = {}, fields = [], limit, offset } = {}) {
+    let _query = this._buildBaseQuery({ query, sort, fields });
+
+    if (typeof offset === 'number') {
+      _query = _query.offset(offset);
+    }
+    if (typeof limit === 'number') {
+      _query = _query.limit(limit);
+    }
+
+    const res = await _query.select();
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 查询单条记录
+   * @param {Object} options - 查询选项
+   * @param {Object} options.query - 查询条件
+   * @param {Array} options.fields - 查询字段
+   * @returns {Promise<Object>} 查询结果，包含data字段
+   */
+  async findOne({ query = {}, fields = [] } = {}) {
+    this._checkDB();
+
+    let dbQuery = this.db(this.tableName);
+    if (Object.keys(query).length) dbQuery = dbQuery.where(query);
+    if (fields.length) dbQuery = dbQuery.select(fields);
+    const res = await dbQuery.first();
+
+    if (!res) {
+      return { success: false, code: NOT_FOUND, msg: '记录不存在', data: null };
+    }
+
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 根据ID查询单条记录
+   * @param {number|string} id - 记录ID
+   * @param {Object} options - 查询选项
+   * @param {Array} options.fields - 查询字段
+   * @returns {Promise<Object>} 查询结果，包含data字段
+   */
+  async findById(id, { fields = [] } = {}) {
+    this._checkDB();
+
+    let _query = this.db(this.tableName).where({ id });
+    if (fields.length) _query = _query.select(fields);
+    const res = await _query.first();
+
+    if (!res) {
+      return { success: false, code: NOT_FOUND, msg: '记录不存在', data: null };
+    }
+
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 插入单条记录
+   * @param {Object} data - 要插入的数据
+   * @returns {Promise<Object>} 插入结果，包含insertId和affectedRows
+   */
+  async insert(data = {}) {
+    this._checkDB();
+
+    if (!Object.keys(data).length) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const formattedData = this._formatDateFields(data);
+    const result = await this.db(this.tableName).insert(formattedData);
+    return { success: true, code: OK, msg: '插入成功', data: { insertId: result[0], affectedRows: result.length } };
+  }
+
+  /**
+   * 批量插入记录
+   * @param {Array} records - 要插入的记录数组
+   * @returns {Promise<Object>} 插入结果，包含insertIds和affectedRows
+   */
+  async insertMany(records = []) {
+    this._checkDB();
+
+    if (!records.length) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const formattedRecords = records.map(record => this._formatDateFields(record));
+    const result = await this.db(this.tableName).insert(formattedRecords);
+    return { success: true, code: OK, msg: '批量插入成功', data: { insertIds: result, affectedRows: result.length } };
+  }
+
+  /**
+   * 根据条件删除记录
+   * @param {Object} query - 删除条件
+   * @returns {Promise<Object>} 删除结果，包含affectedRows
+   */
+  async delete(query = {}) {
+    this._checkDB();
+
+    if (!Object.keys(query).length) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const affectedRows = await this.db(this.tableName).where(query).del();
+    return { success: true, code: OK, msg: '删除成功', data: { affectedRows } };
+  }
+
+  /**
+   * 根据ID删除记录
+   * @param {number|string} id - 记录ID
+   * @returns {Promise<Object>} 删除结果，包含affectedRows
+   */
+  async deleteById(id) {
+    this._checkDB();
+
+    if (!id) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const affectedRows = await this.db(this.tableName).where({ id }).del();
+    return { success: true, code: OK, msg: '删除成功', data: { affectedRows } };
+  }
+
+  /**
+   * 根据条件更新记录
+   * @param {Object} options - 更新选项
+   * @param {Object} options.query - 更新条件
+   * @param {Object} options.data - 更新数据
+   * @returns {Promise<Object>} 更新结果，包含affectedRows
+   */
+  async updateByQuery({ query, data } = {}) {
+    this._checkDB();
+
+    if (!query || !data || !Object.keys(query).length || !Object.keys(data).length) {
+      return { success: false, code: PARAM_INVALID, msg: '参数无效', data: {} };
+    }
+    const formattedData = this._formatDateFields(data);
+    const affectedRows = await this.db(this.tableName).where(query).update(formattedData);
+    return { success: true, code: OK, msg: '更新成功', data: { affectedRows } };
+  }
+
+  /**
+   * 根据ID更新记录
+   * @param {number|string} id - 记录ID
+   * @param {Object} data - 更新数据
+   * @returns {Promise<Object>} 更新结果，包含affectedRows
+   */
+  async updateById(id, data = {}) {
+    this._checkDB();
+
+    if (!id || !Object.keys(data).length) {
+      return { success: false, code: PARAM_INVALID, msg: '参数无效', data: {} };
+    }
+    const formattedData = this._formatDateFields(data);
+    const affectedRows = await this.db(this.tableName).where({ id }).update(formattedData);
+    const updatedRecord = await this.findById(id);
+    return { success: true, code: OK, msg: '更新成功', data: updatedRecord.data };
+  }
+
+  /**
+   * 批量更新记录（事务）
+   * @param {Array} updates - 更新数组，每项包含query和data
+   * @returns {Promise<Object>} 更新结果，包含affectedRows
+   * @description
+   * 在事务内执行批量更新，任一更新失败会回滚整个事务
+   *
+   * 安全改进：
+   * - 整体 try/catch 包裹，确保异常时事务一定 rollback
+   * - rollback 自身失败也不影响错误抛出（只记日志）
+   * - 参数校验提前到事务外，避免无谓事务开销
+   */
+  async updateMany(updates = []) {
+    this._checkDB();
+
+    if (!Array.isArray(updates) || !updates.length) {
+      return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    }
+
+    // 参数预校验：在事务外检查，避免开启事务后才发现参数无效
+    for (const { query } of updates) {
+      if (!query || !Object.keys(query).length) {
+        return { success: false, code: PARAM_INVALID, msg: '参数无效：批量更新不允许空条件', data: {} };
+      }
+    }
+
+    const trx = await this.db.transaction();
+    try {
+      let totalAffected = 0;
+      for (const { query, data } of updates) {
+        const result = await trx(this.tableName).where(query).update(data);
+        if (result === 0) {
+          console.log('[updateMany] 未匹配到行, query=%j', query);
+        }
+        totalAffected += result;
+      }
+      await trx.commit();
+      return { success: true, code: OK, msg: '批量更新成功', data: { affectedRows: totalAffected } };
+    } catch (error) {
+      // 异常时一定 rollback，且 rollback 自身失败也不影响错误抛出
+      await trx.rollback().catch(rollbackErr => {
+        console.error('[updateMany] 回滚失败:', rollbackErr.message);
+      });
+      console.error('[updateMany] 批量更新失败:', error.message);
+      throw error;  // 重新抛出，由上层处理
+    }
+  }
+
+  /**
+   * 分页查询
+   * @param {Object} options - 查询选项
+   * @param {number} options.current - 当前页码，默认1
+   * @param {number} options.pageSize - 每页大小，默认10
+   * @param {Object} options.query - 查询条件
+   * @param {Object} options.sort - 排序条件
+   * @param {Array} options.field - 查询字段
+   * @returns {Promise<Object>} 分页结果，包含list、total、current、pageSize、totalPages
+   */
+  async query({ current = 1, pageSize = 10, query = {}, sort = {}, field = [] }) {
+    this._checkDB();
+
+    const size = Math.min(Math.max(pageSize, 1), this.limit);
+    const offset = (current - 1) * size;
+
+    let countQuery = this.db(this.tableName).count("* as total");
+    let dataQuery = this._buildBaseQuery({ query, sort, fields: field });
+
+    const [totalResult, list] = await Promise.all([
+      countQuery.first(),
+      dataQuery.offset(offset).limit(size),
+    ]);
+
+    const total = Number(totalResult?.total ?? 0);
+    const totalPages = Math.ceil(total / size);
+
+    return { success: true, code: OK, msg: '查询成功', data: { list: formatDateFields(list, this._dateFields), total, current, pageSize: size, totalPages } };
+  }
+
+  /**
+   * 统计记录数
+   * @param {Object} query - 查询条件
+   * @returns {Promise<Object>} 统计结果，包含count
+   */
+  async count(query = {}) {
+    this._checkDB();
+
+    let dataQuery = this.db(this.tableName);
+    if (Object.keys(query).length) dataQuery = dataQuery.where(query);
+    const result = await dataQuery.count("* as total").first();
+    return { success: true, code: OK, msg: '统计成功', data: { count: Number(result?.total ?? 0) } };
+  }
+
+  /**
+   * 检查记录是否存在
+   * @param {Object} query - 查询条件
+   * @returns {Promise<Object>} 存在性结果，包含exists布尔值
+   */
+  async exists(query = {}) {
+    this._checkDB();
+
+    let dataQuery = this.db(this.tableName);
+    if (Object.keys(query).length) dataQuery = dataQuery.where(query);
+    const result = await dataQuery.first();
+    return { success: true, code: OK, msg: '检查成功', data: { exists: !!result } };
+  }
+
+  /**
+   * 关联查询
+   *
+   * IO 提醒：
+   *   默认 fields=["*"] 会 SELECT 所有列，若主表含 longtext（如 cms_article.content）
+   *   或大字段，会显著放大查询 IO。业务侧请显式传入 fields 白名单，仅取必要列。
+   *
+   * @param {Object} options - 查询选项
+   * @param {string} options.joinTable - 关联表名
+   * @param {string} options.localField - 本地表字段
+   * @param {string} options.foreignField - 关联表字段
+   * @param {Array} options.fields - 查询字段，默认["*"]（推荐显式指定，避免拉回 longtext content）
+   * @param {Object} options.query - 查询条件
+   * @param {Object} options.sort - 排序条件
+   * @returns {Promise<Array>} 查询结果数组
+   */
+  async join({ joinTable, localField, foreignField, fields = ["*"], query = {}, sort = {} }) {
+    this._checkDB();
+
+    let _query = this.db(this.tableName)
+      .join(
+        joinTable,
+        `${this.tableName}.${localField}`,
+        "=",
+        `${joinTable}.${foreignField}`
+      )
+      .select(fields);
+
+    if (Object.keys(query).length) _query = _query.where(query);
+    if (sort && typeof sort === 'object') {
+      for (const [field, dir] of Object.entries(sort)) {
+        // 排序字段白名单校验，拒绝 SQL 注入字符
+        if (!SORT_FIELD_REGEX.test(field)) {
+          console.warn(`[Repository] 非法排序字段被拒绝: ${field}`);
+          continue;
+        }
+        const direction = ['asc', 'desc'].includes(String(dir).toLowerCase()) ? String(dir).toLowerCase() : 'asc';
+        _query = _query.orderBy(field, direction);
+      }
+    }
+
+    const res = await _query;
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 批量删除记录（根据ID数组）
+   * @param {Array} ids - ID数组
+   * @returns {Promise<Object>} 删除结果，包含affectedRows
+   */
+  async deleteMany(ids = []) {
+    this._checkDB();
+
+    if (!ids.length) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const affectedRows = await this.db(this.tableName).whereIn('id', ids).del();
+    return { success: true, code: OK, msg: '删除成功', data: { affectedRows } };
+  }
+
+  /**
+   * 软删除（设置deleted_at字段）
+   * @param {number|string} id - 记录ID
+   * @returns {Promise<Object>} 删除结果，包含 affectedRows
+   */
+  async softDelete(id) {
+    this._checkDB();
+
+    if (!id) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const affectedRows = await this.db(this.tableName)
+      .where({ id })
+      .update({ deleted_at: new Date() });
+    return { success: true, code: OK, msg: '软删除成功', data: { affectedRows } };
+  }
+
+  /**
+   * 恢复软删除的记录
+   * @param {number|string} id - 记录ID
+   * @returns {Promise<Object>} 恢复结果，包含 affectedRows
+   */
+  async restore(id) {
+    this._checkDB();
+
+    if (!id) return { success: false, code: PARAM_MISSING, msg: '参数缺失', data: {} };
+    const affectedRows = await this.db(this.tableName)
+      .where({ id })
+      .update({ deleted_at: null });
+    return { success: true, code: OK, msg: '恢复成功', data: { affectedRows } };
+  }
+
+  /**
+   * 查询已软删除的记录
+   * @param {Object} options - 查询选项
+   * @param {Object} options.query - 查询条件
+   * @param {Array} options.fields - 查询字段
+   * @param {number} options.limit - 限制条数，默认20
+   * @param {number} options.offset - 偏移量，默认0
+   * @returns {Promise<Object>} 查询结果，包含 data 字段（数组）
+   */
+  async findTrashed({ query = {}, fields = [], limit = 20, offset = 0 } = {}) {
+    this._checkDB();
+
+    let _query = this.db(this.tableName).whereNotNull('deleted_at');
+
+    if (Object.keys(query).length) _query = _query.where(query);
+    if (fields.length) _query = _query.select(fields);
+
+    const res = await _query.limit(limit).offset(offset).orderBy('deleted_at', 'desc');
+    return { success: true, code: OK, msg: '查询成功', data: formatDateFields(res, this._dateFields) };
+  }
+
+  /**
+   * 强制删除指定天数前的软删除记录
+   * @param {number} days - 天数，默认30天
+   * @returns {Promise<Object>} 删除结果，包含 affectedRows
+   */
+  async forceDelete(days = 30) {
+    this._checkDB();
+
+    const date = new Date();
+    date.setDate(date.getDate() - days);
+
+    const affectedRows = await this.db(this.tableName)
+      .whereNotNull('deleted_at')
+      .where('deleted_at', '<', date)
+      .del();
+
+    return { success: true, code: OK, msg: '强制删除成功', data: { affectedRows } };
+  }
+
+  /**
+   * 统计数据（总数和今日新增）
+   *
+   * 列名说明：
+   *   业务表统一使用驼峰 createdAt（与 cms_article / member 等表 DDL 一致）。
+   *   若子类对应的表为蛇形 created_at（如 sys_oper_log），请在子类中覆盖 stats()。
+   *
+   * @returns {Promise<Object>} 统计结果，包含 data: { total, today }
+   */
+  async stats() {
+    this._checkDB();
+
+    const total = await this.db(this.tableName).count('* as count').first();
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+
+    const todayCount = await this.db(this.tableName)
+      .where('createdAt', '>=', today)
+      .count('* as count')
+      .first();
+
+    return {
+      success: true,
+      code: OK,
+      msg: '统计成功',
+      data: {
+        total: Number(total?.count || 0),
+        today: Number(todayCount?.count || 0)
+      }
+    };
+  }
+}
+
+export default Repository;