chanjs 2.7.3 → 2.7.5

package/core/App.js

@@ -0,0 +1,166 @@
+import express from "express";
+import DatabaseManager from "./Database.js";
+import { setApp } from "./registry.js";
+import { Paths } from "../utils/paths.js";
+import { loadConfig } from "./loader.js";
+import { store } from "../storage/index.js";
+import logger from "../utils/logger.js";
+import { AppError, describeError, errorExtraProps } from "./errors.js";
+import { register as registerShutdown, shutdown as runShutdown } from "../utils/signal.js";
+import { registerCoreMiddleware } from "./bootstrap/middleware.js";
+import { loadModuleRouter, loadCommonRouter } from "./bootstrap/router-loader.js";
+import { registerErrorHandler } from "./bootstrap/error-handler.js";
+import { runHooks } from "./bootstrap/hook-runner.js";
+import { loadDotEnv } from "../config/index.js";
+
+// 初始化环境变量
+loadDotEnv();
+
+/**
+ * Chan 应用核心类
+ */
+export default class Chan {
+  constructor() {
+    this.app = express();
+    this.router = express.Router();
+    this.dbManager = new DatabaseManager();
+
+    this.config = null;
+    this.paths = Paths;
+    this.db = null;
+    this.hooks = [];
+    this.server = null;
+  }
+
+  /** 完整启动流程 */
+  async start() {
+    await this.#loadConfig();
+    logger.info("[Chan] 配置加载完成");
+
+    await this.#initStore();
+    logger.info("[Chan] 缓存初始化完成");
+
+    await this.#loadDb();
+    logger.info("[Chan] 数据库加载完成");
+
+    setApp(this);
+    logger.info("[Chan] 全局应用实例注册完成");
+
+    await this.#regCoreMiddleware();
+    logger.info("[Chan] 核心中间件注册完成");
+
+    this.#setupApp();
+    await this.#loadRoutes();
+    this.#mountRouter();
+    logger.info("[Chan] 路由加载挂载完成");
+
+    this.#regErrHandler();
+    logger.info("[Chan] 全局错误中间件注册完成");
+
+    await this.#runHooks();
+    logger.info("[Chan] 启动钩子全部执行完毕");
+  }
+
+  /** 注册启动前置钩子 */
+  beforeStart(fn) {
+    if (typeof fn !== "function") {
+      throw new AppError("PARAM_INVALID", "beforeStart 参数必须为函数", 400);
+    }
+    this.hooks.push(fn);
+  }
+
+  /** 执行优雅停机流程 */
+  async shutdown() {
+    await runShutdown(this);
+  }
+
+  /**
+   * 启动 HTTP 监听服务
+   * @param {(port: number) => void} cb 启动成功回调
+   */
+  run(cb) {
+    const port = Number(this.config.PORT) || 3000;
+    this.server = this.app.listen(port, () => {
+      logger.info(`[Chan] HTTP服务启动，监听端口：${port}`);
+      cb?.(port);
+    });
+    this.server.on("error", (err) => {
+      logger.error(`[Chan] HTTP服务启动失败: ${err.message}`, err);
+    });
+    registerShutdown(this);
+  }
+
+  async #loadConfig() {
+    this.config = await loadConfig();
+  }
+
+  async #initStore() {
+    const cfg = this.config;
+    try {
+      await store.init({
+        REDIS_ENABLED: !!cfg?.REDIS_ENABLED,
+        REDIS: cfg?.REDIS ?? {}
+      });
+      if (!cfg?.REDIS_ENABLED) logger.info("[Store] Redis未开启，使用内存缓存");
+    } catch (err) {
+      logger.warn("[Store] Redis连接失败，自动降级内存缓存");
+      logger.error(`[Store] 异常信息：${describeError(err)}${errorExtraProps(err)}`, err);
+    }
+  }
+
+  async #loadDb() {
+    const dbList = this.config?.db ?? [];
+    if (!Array.isArray(dbList) || dbList.length === 0) return;
+
+    for (const [idx, dbCfg] of dbList.entries()) {
+      const dbKey = dbCfg.key ?? String(idx);
+      let conn;
+      try {
+        conn = this.dbManager.add(dbKey, dbCfg, { isDefault: idx === 0 });
+        // 首个成功连接即作为默认 this.db，避免 idx===0 失败时 this.db 恒为 null
+        if (!this.db) this.db = conn;
+      } catch (err) {
+        logger.error(`[DB] 数据库[${dbKey}]初始化失败：${describeError(err)}${errorExtraProps(err)}`, err);
+        continue;
+      }
+
+      const ok = await this.dbManager.ping(dbKey);
+      ok
+        ? logger.info(`[DB] 数据库[${dbKey}]连接正常`)
+        : logger.error(`[DB] ⚠️ 数据库[${dbKey}]连通性校验失败，请检查库服务、账号配置`);
+    }
+    logger.info(`[DB] 数据库初始化结束，共配置${dbList.length}个连接`);
+  }
+
+  async #regCoreMiddleware() {
+    await registerCoreMiddleware(this);
+  }
+
+  /**
+   * 配置 Express trust proxy
+   * 默认只信任本机回环；生产环境通过 TRUSTED_PROXIES 注入真实上游代理
+   * 切勿使用 true（信任任意来源）
+   */
+  #setupApp() {
+    const env = process.env.TRUSTED_PROXIES;
+    const trustedProxies = env ? env.split(",").map(s => s.trim()).filter(Boolean) : ["loopback"];
+    this.app.set("trust proxy", trustedProxies);
+  }
+
+  async #loadRoutes() {
+    await loadModuleRouter(this);
+    await loadCommonRouter(this);
+  }
+
+  #mountRouter() {
+    this.app.use(this.router);
+  }
+
+  #regErrHandler() {
+    registerErrorHandler(this);
+  }
+
+  async #runHooks() {
+    await runHooks(this);
+  }
+}

package/core/Container.js

@@ -0,0 +1,77 @@
+import fs from 'fs';
+import path from 'path';
+import { Paths } from '../utils/paths.js';
+import { getApp } from './registry.js';
+import logger from "../utils/logger.js";
+
+const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+/**
+ * 组件容器：统一加载 controller/service
+ */
+export class Container {
+  constructor(type = 'service') {
+    this.cache = new Map();
+    this.type = type;
+    this.baseDir = Paths.modulesPath;
+  }
+
+  get app() { return getApp(); }
+
+  /**
+   * 全局配置快捷访问
+   * 业务 Controller/Service/Repository 大量使用 `this.config.xxx` 读取配置项
+   * 统一从 app.config 取，未初始化时返回空对象避免 undefined.xxx 报错
+   */
+  get config() {
+    return this.app?.config ?? {};
+  }
+
+  /**
+   * 获取组件，自动缓存
+   * @param {string} moduleName
+   * @param {string} fileName
+   */
+  async get(moduleName, fileName) {
+    const cacheKey = `${moduleName}.${fileName}`;
+    if (this.cache.has(cacheKey)) return this.cache.get(cacheKey);
+
+    try {
+      const instance = await this.loadFile(moduleName, fileName);
+      if (!instance) logger.info(`[Container] ${moduleName}/${this.type}/${fileName}.js 导出实例为空`);
+      return instance;
+    } catch (err) {
+      logger.error(`[Container] 加载组件失败 ${moduleName}/${fileName}：${err.message}`);
+      return null;
+    }
+  }
+
+  /** 物理加载文件、导入模块、安全校验 */
+  async loadFile(moduleName, fileName) {
+    const cacheKey = `${moduleName}.${fileName}`;
+
+    if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName)) {
+      throw new Error(`非法名称 ${moduleName}/${fileName}`);
+    }
+
+    const filePath = path.resolve(this.baseDir, moduleName, this.type, `${fileName}.js`);
+    const relativePath = path.relative(this.baseDir, filePath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      throw new Error(`路径越界拦截：${filePath}`);
+    }
+
+    try {
+      await fs.promises.access(filePath, fs.constants.R_OK);
+    } catch {
+      logger.info(`[Container] 文件不存在：${moduleName}/${this.type}/${fileName}.js`);
+      return null;
+    }
+
+    const mod = await import(`file://${filePath}`);
+    const instance = mod.default;
+    this.cache.set(cacheKey, instance);
+    return instance;
+  }
+}
+
+export default Container;

package/core/Controller.js

@@ -0,0 +1,29 @@
+import { success, fail } from "../response/response.js";
+import Container from "./Container.js";
+
+/**
+ * 控制器基类，继承组件容器，内置统一成功/失败响应封装
+ * 响应结构 { success, code, msg, data }
+ * 错误码规范：0成功 / 1xxx业务 / 5xxx系统 / 6xxx数据库
+ */
+export default class Controller extends Container {
+  constructor() {
+    super("controller");
+  }
+
+  /**
+   * 成功返回，默认code=0
+   * @param {{data?: any, msg?: string}} opts
+   */
+  success({ data, msg = "操作成功" } = {}) {
+    return success({ data: data ?? {}, msg });
+  }
+
+  /**
+   * 失败返回，传字符串直接作为提示文案，默认code=1008
+   * @param {string | {msg?: string, code?: number}} opts
+   */
+  fail(opts = {}) {
+    return typeof opts === "string" ? fail({ msg: opts }) : fail(opts);
+  }
+}

package/core/Database.js

@@ -0,0 +1,93 @@
+import knex from "knex";
+import logger from "../utils/logger.js";
+
+const DEFAULT_NAME = "default";
+
+/**
+ * 多Knex连接管理器，统一管理连接、心跳、批量销毁
+ */
+class DatabaseManager {
+  constructor() {
+    this._connections = new Map();
+    this._defaultName = DEFAULT_NAME;
+    // 健康缓存：运行时由 error-handler 实时更新，用于鉴权层廉价区分「用户未登录」与「库挂了」
+    this._health = new Map();
+  }
+
+  /**
+   * 添加数据库连接，首个连接 / isDefault=true 自动设为默认
+   * @param {string} name 连接标识
+   * @param {object} config Knex配置
+   * @param {{isDefault?: boolean}} opts
+   * @returns {knex.Knex}
+   */
+  add(name, config, { isDefault = false } = {}) {
+    const conn = knex(config);
+    this._connections.set(name, conn);
+    if (isDefault || this._connections.size === 1) this._defaultName = name;
+    return conn;
+  }
+
+  /**
+   * 获取指定连接，不存在抛异常
+   * @param {string} [name=this._defaultName]
+   * @returns {knex.Knex}
+   */
+  get(name = this._defaultName) {
+    const conn = this._connections.get(name);
+    if (!conn) throw new Error(`Database connection "${name}" not found`);
+    return conn;
+  }
+
+  /** 批量关闭全部连接，单个失败不阻断其他 */
+  async closeAll() {
+    const results = [];
+    for (const [name, conn] of this._connections) {
+      try {
+        await conn.destroy();
+        results.push({ name, success: true });
+      } catch (err) {
+        results.push({ name, success: false, error: err.message });
+        logger.error(`[Database] 关闭连接 ${name} 失败`, err);
+      }
+    }
+    this._connections.clear();
+    logger.info(`[Database] 全部连接关闭完成，总计 ${results.length} 个`);
+    return results;
+  }
+
+  /**
+   * 心跳探测，SELECT 1 校验连通性（启动时 + 运行时按需调用）
+   * @param {string} [name=this._defaultName]
+   * @returns {boolean}
+   */
+  async ping(name = this._defaultName) {
+    const conn = this._connections.get(name);
+    if (!conn) {
+      this._health.set(name, false);
+      return false;
+    }
+    try {
+      await conn.raw("SELECT 1");
+      this._health.set(name, true);
+      return true;
+    } catch (err) {
+      this._health.set(name, false);
+      logger.error(`[Database] ping ${name} 连通校验失败`, err);
+      return false;
+    }
+  }
+
+  /** 运行时主动标记连接不可用（error-handler 捕获 DB 异常时调用） */
+  markDown(name = this._defaultName) {
+    this._health.set(name, false);
+  }
+
+  /** 运行时标记连接恢复可用（error-handler 捕获业务成功响应时调用） */
+  markUp(name = this._defaultName) {
+    this._health.set(name, true);
+  }
+}
+
+export default DatabaseManager;
+

package/core/Repository.js

@@ -0,0 +1,327 @@
+import Container from "./Container.js";
+import logger from "../utils/logger.js";
+import {
+  CODE_OK,
+  CODE_NOT_FOUND,
+  CODE_PARAM_INVALID,
+  CODE_PARAM_MISSING,
+} from "../response/code.js";
+
+const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>', $in:'in' };
+
+/**
+ * 拼接查询条件，支持操作符/等值/数组in
+ * @param {import('knex').Knex.QueryBuilder} dbQuery
+ * @param {object} query
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+function applyQuery(dbQuery, query) {
+  for (const [field, val] of Object.entries(query)) {
+    if (!SORT_FIELD_REGEX.test(field)) {
+      logger.warn(`[Repository] 非法查询字段：${field}`);
+      continue;
+    }
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      const ops = Object.keys(val);
+      if (ops.length && ops.every(k => k in OPERATORS || k === '$null' || k === '$notNull')) {
+        for (const [op, operand] of Object.entries(val)) {
+          if (OPERATORS[op]) {
+            dbQuery = dbQuery.where(field, OPERATORS[op], operand);
+          } else if (op === '$in') {
+            dbQuery = dbQuery.whereIn(field, Array.isArray(operand) ? operand : [operand]);
+          } else if (op === '$null') {
+            operand ? dbQuery.whereNull(field) : dbQuery.whereNotNull(field);
+          } else if (op === '$notNull') {
+            dbQuery.whereNotNull(field);
+          }
+        }
+        continue;
+      }
+    }
+    Array.isArray(val) ? dbQuery.whereIn(field, val) : dbQuery.where(field, val);
+  }
+  return dbQuery;
+}
+
+/**
+ * 应用字段白名单 + 排序白名单到 query
+ * @param {import('knex').Knex.QueryBuilder} q
+ * @param {string[]} fields
+ * @param {object} sort
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+function applySelectAndSort(q, fields, sort) {
+  if (fields.length) {
+    const safeFields = fields.filter(f => SORT_FIELD_REGEX.test(f) || f === '*');
+    if (safeFields.length) q = q.select(safeFields);
+  }
+  if (sort && typeof sort === 'object') {
+    for (const [field, dir] of Object.entries(sort)) {
+      if (!SORT_FIELD_REGEX.test(field)) {
+        logger.warn(`[Repository] 非法排序字段：${field}`);
+        continue;
+      }
+      const d = ['asc','desc'].includes(String(dir).toLowerCase()) ? dir.toLowerCase() : 'asc';
+      q = q.orderBy(field, d);
+    }
+  }
+  return q;
+}
+
+/**
+ * 数据访问基类，封装通用CRUD操作
+ */
+class Repository extends Container {
+  constructor(table=null, dbName=null, opts={}) {
+    super('service');
+    this.tableName = table;
+    this._dbName = dbName;
+    this._customDb = null;
+    this._dateFields = Array.isArray(opts.dateFields) ? opts.dateFields : [];
+    typeof this.on === 'function' && this.on();
+  }
+
+  /** 动态获取数据库连接 */
+  get db() {
+    if (this._dbName) {
+      this._customDb ??= this.app.dbManager.get(this._dbName);
+      return this._customDb;
+    }
+    return this.app.db;
+  }
+
+  /** 分页配置快捷读取 */
+  get limit() { return this.config?.LIMIT_MAX || 300; }
+
+  /** 前置数据库校验 */
+  _checkDB() {
+    if (!this.db) throw new Error("Database connection not available");
+  }
+
+  /** 统一构建查询实例（子类可重写以扩展过滤逻辑） */
+  _buildBaseQuery({ query = {}, sort = {}, fields = [] } = {}) {
+    this._checkDB();
+    let q = this.db(this.tableName);
+    if (Object.keys(query).length) q = applyQuery(q, query);
+    return applySelectAndSort(q, fields, sort);
+  }
+
+  /** 工具：日期字段自动转Date */
+  #formatDate(data) {
+    if (!data || typeof data !== 'object' || !this._dateFields.length) return data;
+    const row = {...data};
+    for (const k of this._dateFields) {
+      if (typeof row[k] === 'string') {
+        const dt = new Date(row[k]);
+        !isNaN(dt.getTime()) && (row[k] = dt);
+      }
+    }
+    return row;
+  }
+
+  /** 查询全部，默认上限1000条 */
+  async all({ query={}, sort={}, fields=[], limit=1000 }={}) {
+    const list = await this._buildBaseQuery({query,sort,fields}).limit(limit);
+    return { success:true, code:CODE_OK, msg:"查询成功", data: list };
+  }
+
+  /** 分页偏移查询 */
+  async find({ query={}, sort={}, fields=[], limit, offset }={}) {
+    let q = this._buildBaseQuery({query,sort,fields});
+    typeof offset === 'number' && (q = q.offset(offset));
+    typeof limit === 'number' && (q = q.limit(limit));
+    return { success:true, code:CODE_OK, msg:"查询成功", data: await q };
+  }
+
+  /** 查询单条记录 */
+  async findOne({ query={}, fields=[] }={}) {
+    const row = await this._buildBaseQuery({query,fields}).first();
+    if (!row) return { success:false, code:CODE_NOT_FOUND, msg:"记录不存在", data:null };
+    return { success:true, code:CODE_OK, msg:"查询成功", data: row };
+  }
+
+  /** 根据ID查询单条 */
+  async findById(id, { fields=[] }={}) {
+    return this.findOne({ query:{id}, fields });
+  }
+
+  /** 单条插入 */
+  async insert(data={}) {
+    this._checkDB();
+    if (!Object.keys(data).length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
+    const res = await this.db(this.tableName).insert(this.#formatDate(data));
+    return { success:true, code:CODE_OK, msg:"插入成功", data:{ insertId:res[0], affectedRows:res.length } };
+  }
+
+  /** 批量插入 */
+  async insertMany(records=[]) {
+    this._checkDB();
+    if (!records.length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
+    const list = records.map(r => this.#formatDate(r));
+    const res = await this.db(this.tableName).insert(list);
+    return { success:true, code:CODE_OK, msg:"批量插入成功", data:{ insertId:res[0], affectedRows:res.length } };
+  }
+
+  /** 条件删除 */
+  async del(query={}) {
+    this._checkDB();
+    if (!Object.keys(query).length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
+    const rows = await applyQuery(this.db(this.tableName), query).del();
+    return { success:true, code:CODE_OK, msg:"删除成功", data:{ affectedRows:rows } };
+  }
+
+  /** 根据ID删除单条 */
+  async delById(id) {
+    return this.del({ id });
+  }
+
+  /** ID数组批量删除 */
+  async delMany(ids=[]) {
+    this._checkDB();
+    if (!ids.length) return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
+    const rows = await this.db(this.tableName).whereIn('id', ids).del();
+    return { success:true, code:CODE_OK, msg:"删除成功", data:{ affectedRows:rows } };
+  }
+
+  /** 按条件更新记录 */
+  async update({ query, data }={}) {
+    this._checkDB();
+    if (!query || !data || !Object.keys(query).length || !Object.keys(data).length) {
+      return { success:false, code:CODE_PARAM_INVALID, msg:"参数无效", data:{} };
+    }
+    const rows = await applyQuery(this.db(this.tableName), query).update(this.#formatDate(data));
+    return { success:true, code:CODE_OK, msg:"更新成功", data:{ affectedRows:rows } };
+  }
+
+  /** 根据ID更新，返回更新后完整数据 */
+  async updateById(id, data={}) {
+    this._checkDB();
+    if (!id || !Object.keys(data).length) return { success:false, code:CODE_PARAM_INVALID, msg:"参数无效", data:{} };
+    await this.db(this.tableName).where({id}).update(this.#formatDate(data));
+    return this.findById(id);
+  }
+
+  /** 事务批量更新，失败自动回滚 */
+  async updateMany(updates=[]) {
+    this._checkDB();
+    if (!Array.isArray(updates) || !updates.length) {
+      return { success:false, code:CODE_PARAM_MISSING, msg:"参数缺失", data:{} };
+    }
+    for (const item of updates) {
+      if (!item.query || !Object.keys(item.query).length) {
+        return { success:false, code:CODE_PARAM_INVALID, msg:"批量更新条件不能为空", data:{} };
+      }
+    }
+    const trx = await this.db.transaction();
+    let total = 0;
+    try {
+      for (const { query, data } of updates) {
+        const row = await trx(this.tableName).where(query).update(this.#formatDate(data));
+        row === 0 && logger.info("[Repository] updateMany无匹配行", query);
+        total += row;
+      }
+      await trx.commit();
+      return { success:true, code:CODE_OK, msg:"批量更新成功", data:{ affectedRows:total } };
+    } catch (err) {
+      await trx.rollback().catch(e => logger.error("[Repository] 事务回滚失败", e.message));
+      logger.error("[Repository] 批量更新异常", err.message);
+      throw err;
+    }
+  }
+
+  /**
+   * 分页查询核心实现
+   * 私有方法，避免 query/list 子类重写时发生互相递归
+   * @param {object} params 分页参数
+   * @returns {Promise<{success:boolean,code:number,msg:string,data:object}>}
+   */
+  async _doPaginate({ current=1, pageSize=10, query={}, sort={}, field=[] }={}) {
+    this._checkDB();
+    const size = Math.min(Math.max(pageSize, 1), this.limit);
+    const offset = (current - 1) * size;
+    const countQ = applyQuery(this.db(this.tableName), query);
+    const [totalRow, list] = await Promise.all([
+      countQ.count("* as total").first(),
+      this._buildBaseQuery({query,sort,fields:field}).offset(offset).limit(size)
+    ]);
+    const total = Number(totalRow?.total ?? 0);
+    return {
+      success:true,
+      code:CODE_OK,
+      msg:"查询成功",
+      data: {
+        list,
+        total,
+        current,
+        pageSize: size,
+        totalPages: Math.ceil(total / size)
+      }
+    };
+  }
+
+  /** 标准分页查询（业务侧常用别名） */
+  async query(params={}) {
+    return this._doPaginate(params);
+  }
+
+  /** 标准分页查询（list 别名，向后兼容） */
+  async list(params={}) {
+    return this._doPaginate(params);
+  }
+
+  /** 统计符合条件记录行数 */
+  async count(query={}) {
+    this._checkDB();
+    const res = await applyQuery(this.db(this.tableName), query).count("* as total").first();
+    return { success:true, code:CODE_OK, msg:"统计成功", data:{ count: Number(res?.total ?? 0) } };
+  }
+
+  /** 判断查询条件下记录是否存在 */
+  async exists(query={}) {
+    this._checkDB();
+    const row = await applyQuery(this.db(this.tableName), query).first();
+    return { success:true, code:CODE_OK, msg:"检查成功", data:{ exists: !!row } };
+  }
+
+  /** 联表join查询 */
+  async join({ joinTable, localField, foreignField, fields=[], query={}, sort={} }) {
+    this._checkDB();
+    if (!SORT_FIELD_REGEX.test(joinTable) || !SORT_FIELD_REGEX.test(localField) || !SORT_FIELD_REGEX.test(foreignField)) {
+      logger.warn(`[Repository] 非法联表/字段：${joinTable}/${localField}/${foreignField}`);
+      return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表或字段", data: null };
+    }
+    const select = fields.length
+      ? fields.filter(f => SORT_FIELD_REGEX.test(f) || f === '*')
+      : [`${this.tableName}.*`];
+    let q = this.db(this.tableName)
+      .join(joinTable, `${this.tableName}.${localField}`, '=', `${joinTable}.${foreignField}`)
+      .select(select);
+    q = applyQuery(q, query);
+    q = applySelectAndSort(q, [], sort);
+    return { success:true, code:CODE_OK, msg:"查询成功", data: await q };
+  }
+
+  /** 统计表总数量 + 今日新增数量 */
+  async stats() {
+    this._checkDB();
+    const createKey = this._dateFields.find(f => /created_at|createdAt/.test(f)) || "created_at";
+    const today = new Date();
+    today.setHours(0,0,0,0);
+    const [totalRes, todayRes] = await Promise.all([
+      this.db(this.tableName).count('* as count').first(),
+      this.db(this.tableName).where(createKey, '>=', today).count('* as count').first()
+    ]);
+    return {
+      success:true,
+      code:CODE_OK,
+      msg:"统计成功",
+      data: {
+        total: Number(totalRes?.count || 0),
+        today: Number(todayRes?.count || 0)
+      }
+    };
+  }
+}
+
+export default Repository;

package/core/Service.js

@@ -0,0 +1,11 @@
+/**
+ * Service 基类 - 纯业务逻辑层（无表绑定、无 CRUD 方法）
+ * 业务子类注入多个 Repository 做跨表事务编排
+ */
+import { Container } from "./Container.js";
+
+export class Service extends Container {
+  constructor() {
+    super('service');
+  }
+}