@sisin/egg-client 1.0.0

package/README.md

@@ -0,0 +1,267 @@
+# @niceguy/egg-client
+
+Egg.js 核心框架包 — 将 egg-example 中沉淀的通用基础设施封装为可复用的 Egg 框架，新建项目只需依赖此包即可直接使用中间件、数据层、认证、日志、Redis 等能力，业务项目只需关注业务层面。
+
+## 核心特性
+
+- **即拉即用**：安装依赖 + 配置框架名，所有封装自动生效
+- **独立迭代**：框架包可独立发版更新，业务项目同步升级即可
+- **多项目复用**：一套核心逻辑应用于多个业务项目
+- **Egg 原生集成**：基于 Egg.js Framework 机制，完美继承 loadUnit 加载顺序
+
+## 安装
+
+`ash
+npm install @niceguy/egg-client
+`
+
+## 使用方式
+
+### 1. 新建 Egg.js 项目
+
+创建标准 Egg.js 项目结构后，在 package.json 中指定框架：
+
+`json
+{
+  "name": "my-business-project",
+  "egg": {
+    "framework": "@niceguy/egg-client"
+  },
+  "dependencies": {
+    "@niceguy/egg-client": "^1.0.0",
+    "egg": "^3.17.5"
+  }
+}
+`
+
+### 2. 项目结构
+
+`
+my-business-project/
+├── package.json                # egg.framework: '@niceguy/egg-client'
+├── app.js                      # （可选）业务项目初始化逻辑
+├── config/
+│   ├── config.default.js       # 覆盖框架默认配置（数据库、Redis 等）
+│   └── plugin.js               # 追加业务插件
+├── app/
+│   ├── controller/             # 业务控制器
+│   ├── router/                 # 业务路由
+│   ├── service/                # 业务服务
+│   └── model/                  # 业务 Prisma 模型
+├── prisma/
+│   ├── schema.prisma           # 数据表定义
+│   └── generated/              # prisma generate 产物
+│       ├── fx/                 # 数据库名称（与 config.Dbs key 对应）
+│       └── business/
+└── package.json
+`
+
+### 3. 配置数据库 & Redis
+
+在你的项目 config/config.default.js 中覆盖连接信息：
+
+`js
+module.exports = (appInfo) => {
+  return {
+    Dbs: {
+      fx: {
+        type: 'mysql',
+        host: '127.0.0.1',
+        port: 3306,
+        user: 'root',
+        password: '123456',
+        database: 'db_base',
+        connectionLimit: 5,
+      },
+      business: {
+        type: 'mysql',
+        host: '127.0.0.1',
+        port: 3306,
+        user: 'root',
+        password: '123456',
+        database: 'db_business',
+        connectionLimit: 5,
+      },
+    },
+    redis: {
+      fx: { host: '127.0.0.1', port: 6379, password: '123456', db: 0 },
+      business: { host: '127.0.0.1', port: 6379, password: '123456', db: 1 },
+    },
+  };
+};
+`
+
+### 4. 编写路由和控制器
+
+`js
+// app/router/user.js
+module.exports = (app) => {
+  const { router, controller } = app;
+  router.get('/api/user/info', controller.user.info);
+};
+
+// app/controller/user.js
+const Controller = require('egg').Controller;
+class UserController extends Controller {
+  async info() {
+    const { ctx } = this;
+    const user = await ctx.service.authSystem.auth.findByUser({ username: 'admin' });
+    ctx.api.success(user);
+  }
+}
+module.exports = UserController;
+`
+
+## 框架包目录结构
+
+`
+packages/egg-client/
+├── package.json              # 框架声明（egg.framework: true）
+├── app.js                    # 框架生命周期：初始化数据库、Redis、日志、认证
+├── config/
+│   ├── config.default.js     # 默认配置（合并策略：项目配置优先）
+│   └── plugin.default.js     # 默认插件
+├── app/
+│   ├── constants/            # 状态码、错误码、密码常量、Redis key
+│   ├── core/                 # 数据库客户端管理、Repository、事务封装
+│   ├── extend/               # ctx.api / ctx.payload / ctx.repository / helper
+│   ├── middleware/           # jwt_auth / error_handler / check_ready / etc.
+│   ├── model/redis/          # RedisAuth 模型（Session CRUD）
+│   ├── redis/                # Redis 客户端工厂 & 管理器
+│   ├── service/authSystem/   # 认证服务（登录/登出/刷新Token/改密）
+│   ├── utils/                # JWT / 加密 / 日志 / 通用工具
+│   └── validate/             # 参数校验规则
+└── init/                     # 初始化编排脚本（挂载日志→数据库→Redis→认证）
+`
+
+## 框架提供的能力清单
+
+| 模块 | 提供能力 | 使用方式 |
+|------|---------|---------|
+| **中间件** | checkReady / errorHandler / requestLog / jwtAuth / auth / uploadLimit / loginLimit / permission | 自动注册 checkReady, errorHandler, requestLog, jwtAuth |
+| **Context 扩展** | ctx.api.success/fail/page / ctx.payload / ctx.repository / ctx.encrypt | 直接使用 |
+| **Helper** | ormatTime / ormDateExp / 	imeUtil / snakeToCamel / camelToSnake | ctx.helper.* |
+| **认证服务** | login / logout / erifyAccessToken / 
+| **Redis 管理** | 多实例客户端 / get/set/hset/hget/del | pp.redis.getClient(name) |
+| **数据库** | Prisma 多库管理 / 事务 / 通用 CRUD Repository | ctx.repository.fx.Raw('table') |
+| **日志** | 文件按日切割 / 终端彩显 / 请求日志 / Prisma SQL 日志 | pp.logger.* / ctx.logger.* |
+| **WebSocket** | 可选启用 | pp.config.websocket.enable = true |
+
+## 本地开发
+
+### 安装依赖
+
+```bash
+# 在 monorepo 根目录
+cd niceguy-core-web
+npm install
+```
+
+### 测试
+
+单元测试（不依赖外部服务）：
+
+```bash
+# 在 packages/egg-client 目录
+cd packages/egg-client
+npm run test:unit
+
+# 带覆盖率
+npx c8 --reporter=text --reporter=html mocha test/unit/**/*.test.js --timeout 10000
+```
+
+集成测试（依赖 egg-mock，无需真实数据库）：
+
+```bash
+npm test
+```
+
+### 发布流程
+
+```bash
+# 1. 构建检查：确保测试通过
+npm run test:unit
+
+# 2. 发布 patch 版本（0.0.1 → 0.0.2）
+npm run publish:patch
+
+# 3. 发布 minor 版本（0.0.1 → 0.1.0）
+npm run publish:minor
+
+# 4. 发布 major 版本（0.0.1 → 1.0.0）
+npm run publish:major
+```
+
+## 使用本地开发版本（link 模式）
+
+在业务项目中直接使用本地的 egg-client：
+
+```bash
+# 在 egg-client 目录注册全局 link
+cd niceguy-core-web/packages/egg-client
+npm link
+
+# 在业务项目（如 egg-example）中使用本地版本
+cd egg-example
+npm link @niceguy/egg-client
+
+# 恢复为 npm 版本
+npm unlink @niceguy/egg-client && npm install @niceguy/egg-client
+```
+
+或者使用 npm workspaces（推荐）：
+
+```json
+{
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+然后在业务项目的 package.json 中：
+
+```json
+{
+  "egg": {
+    "framework": "@niceguy/egg-client"
+  },
+  "dependencies": {
+    "@niceguy/egg-client": "^1.0.0"
+  }
+}
+```
+
+## 框架目录结构
+
+```
+packages/egg-client/
+├── index.js                  # 框架入口，导出工具函数
+├── app.js                    # 框架生命周期：初始化数据库、Redis、日志、认证
+├── package.json              # 框架声明（egg.framework: true）
+├── .npmignore                # npm 发布排除文件
+├── .mocharc.yml              # 测试配置
+├── config/
+│   ├── config.default.js     # 默认配置（合并策略：项目配置优先）
+│   └── plugin.default.js     # 默认插件
+├── app/
+│   ├── constants/            # 状态码、错误码、密码常量、Redis key
+│   ├── core/                 # 数据库客户端管理、Repository、事务封装
+│   ├── extend/               # ctx.api / ctx.payload / ctx.repository / helper
+│   ├── middleware/           # jwt_auth / error_handler / check_ready 等
+│   ├── model/redis/          # RedisAuth 模型（Session CRUD）
+│   ├── redis/                # Redis 客户端工厂 & 管理器
+│   ├── service/authSystem/   # 认证服务（登录/登出/刷新Token/改密）
+│   ├── utils/                # JWT / 加密 / 日志 / 通用 / PrismaManager
+│   └── validate/             # 参数校验规则
+├── init/                     # 初始化编排脚本
+└── test/                     # 测试
+    ├── config/
+    │   └── config.default.js # 测试环境配置
+    ├── app/controller/       # 集成测试
+    └── unit/                 # 单元测试
+```
+
+## License
+
+MIT

package/app/constants/code.js

@@ -0,0 +1,9 @@
+module.exports = {
+  SUCCESS: 0,         // 成功
+  BAD_REQUEST: 400,   // 请求错误
+  UNAUTHORIZED: 401,  // 未授权，无权限
+  NOT_ALLOWED: 405,   // 不允许的请求方法
+  FORBIDDEN: 403,     // 禁止访问
+  NOT_FOUND: 404,     // 未找到
+  SERVER_ERROR: 500,  // 服务器错误
+};

package/app/constants/crypt.js

@@ -0,0 +1,10 @@
+// JWT 配置
+module.exports = {
+  ALG: 'HS256',
+  ACCESS_SECRET: 'niceguy328597wndvhefn8935nx',
+  REFRESH_SECRET: 'niceguyondgnos0sdfodf0ssfs34',
+  SESSION_EXPIRES_IN: 7 * 24 * 60,              // 会话最长有效时长 7天，单位 分钟
+  TOKEN_EXPIRES_IN: 1,                           // jwt过期时长 1小时，单位 分钟
+  REFRESH_TOKEN_EXPIRES_IN: 7 * 24 * 60,        // 刷新token过期时长 7天，单位 分钟
+  SESSION_COOKIE_NAME: 'sessionId',
+};

package/app/constants/error.js

@@ -0,0 +1,20 @@
+// 错误状态码
+module.exports = {
+  200:   { code: 200,   parent: null,  msg: '请求成功' },
+  400:   { code: 200,   parent: 400,   msg: '请求错误/操作失败' },
+  401:   { code: 401,   parent: null,  msg: '用户未登录或登录过期' },
+  40101: { code: 40101, parent: 401,   msg: 'access登录已过期' },
+  40102: { code: 40102, parent: 401,   msg: 'refresh登录已过期' },
+  40103: { code: 40103, parent: 401,   msg: '非法TOKEN登录' },
+  40104: { code: 40104, parent: 401,   msg: '登录已失效，请重新登录' },
+  40105: { code: 40105, parent: 401,   msg: '用户不存在' },
+  40106: { code: 40106, parent: 401,   msg: '密码错误' },
+  40107: { code: 40107, parent: 401,   msg: '暂不支持当前平台登录' },
+  403:   { code: 403,   parent: null,  msg: '权限不足，禁止访问' },
+  40301: { code: 40301, parent: 403,   msg: '账号禁用' },
+  40302: { code: 40302, parent: 403,   msg: '权限不足' },
+  404:   { code: 404,   parent: null,  msg: '未找到资源' },
+  405:   { code: 405,   parent: null,  msg: '非法请求' },
+  422:   { code: 422,   parent: null,  msg: '数据校验不通过' },
+  500:   { code: 500,   parent: null,  msg: '服务器错误' },
+};

package/app/constants/redis.js

@@ -0,0 +1,17 @@
+// 各模块的 redis key 常量
+module.exports = {
+  USER_LOGIN: 'user:login',
+  USER_LOGIN_TOKEN: 'login:token',
+  USER_LOGIN_REFRESH_TOKEN: 'login:refresh',
+  USER_LOGIN_SESSION: 'login:session',
+  USER_SESSION: 'user:session',
+  AUTH_SESSION: 'auth:session',
+  AUTH_USER_SESSIONS: 'auth:user:sessions',
+  AUTH_REFRESH_LOCK: 'auth:refresh:lock',
+
+  DEVICE_OPTION: {
+    PC: 'pc', APP: 'app', MINIAPP: 'miniapp',
+    WXAPP: 'wxapp', ALIPAY: 'alipay', BAIDU: 'baidu',
+    TIKTOK: 'tiktok', QQ: 'qq', DOUYIN: 'douyin', H5: 'h5',
+  },
+};

package/app/controller/authSystem/auth.js

@@ -0,0 +1,119 @@
+const Controller = require("egg").Controller;
+const errorCode = require("../../constants/error");
+const {
+  REFRESH_TOKEN_EXPIRES_IN,
+  SESSION_COOKIE_NAME,
+} = require("../../constants/crypt");
+
+class AuthController extends Controller {
+  /**
+   * 登录：校验 → 调用 service → 返回 accessToken + 设置 refreshToken cookie
+   */
+  async login() {
+    const { ctx } = this;
+    ctx.validate(
+      {
+        username: { type: "string", required: true, min: 3, max: 20 },
+        password: { type: "string", required: true, min: 6, max: 20 },
+      },
+      ctx.payload,
+    );
+
+    const result = await ctx.service.authSystem.auth.login(ctx.payload);
+    if (!result.ok) {
+      return ctx.api.fail(errorCode[result.code]?.msg, result.code, null);
+    }
+
+    // 设置 refreshToken 为 HTTP-only cookie
+    const maxAge = REFRESH_TOKEN_EXPIRES_IN * 60 * 1000;
+    ctx.cookies.set(SESSION_COOKIE_NAME, result.data.refreshToken, {
+      httpOnly: true,
+      sameSite: "Strict",
+      path: "/",
+      maxAge,
+      signed: false,
+    });
+
+    return ctx.api.success({ accessToken: result.data.accessToken });
+  }
+
+  /**
+   * 刷新 accessToken：从 cookie 获取 refreshToken → 调用 service → 返回新 token
+   */
+  async refresh() {
+    const { ctx } = this;
+    const token = ctx.cookies.get(SESSION_COOKIE_NAME, { signed: false });
+    if (!token) {
+      return ctx.api.fail(errorCode[401]?.msg, 401, null);
+    }
+
+    const result = await ctx.service.authSystem.auth.refreshToken({ token });
+    if (!result.ok) {
+      ctx.cookies.set(SESSION_COOKIE_NAME, null, { maxAge: 0, path: "/" });
+      return ctx.api.fail(errorCode[result.code]?.msg, result.code, null);
+    }
+
+    // 设置新 refreshToken cookie
+    const maxAge = REFRESH_TOKEN_EXPIRES_IN * 60 * 1000;
+    ctx.cookies.set(SESSION_COOKIE_NAME, result.data.refreshToken, {
+      httpOnly: true,
+      sameSite: "Strict",
+      path: "/",
+      maxAge,
+      signed: false,
+    });
+
+    return ctx.api.success({ accessToken: result.data.accessToken });
+  }
+
+  /**
+   * 登出：调用 service → 清除 cookie
+   */
+  async logout() {
+    const { ctx } = this;
+    const { uid, sid } = ctx.user;
+    await ctx.service.authSystem.auth.logout({ uid, sid });
+    ctx.cookies.set(SESSION_COOKIE_NAME, null, { maxAge: 0, path: "/" });
+    return ctx.api.success(null);
+  }
+
+  /**
+   * 用户信息查询（保留，仅做代理）
+   */
+  async getUserInfo() {
+    const { ctx } = this;
+    const { username } = ctx.payload;
+    const data = await ctx.service.authSystem.auth.findByUser({ username });
+    return ctx.api.success(data);
+  }
+
+  /**
+   * 修改密码：校验 → 调用 service → 清除 cookie
+   */
+  async changePassword() {
+    const { ctx } = this;
+    ctx.validate(
+      {
+        oldPassword: { type: "string", required: true, min: 6, max: 20 },
+        newPassword: { type: "string", required: true, min: 6, max: 20 },
+      },
+      ctx.payload,
+    );
+
+    const { uid } = ctx.user;
+    const result = await ctx.service.authSystem.auth.changePassword({
+      uid,
+      oldPassword: ctx.payload.oldPassword,
+      newPassword: ctx.payload.newPassword,
+    });
+    if (!result.ok) {
+      return ctx.api.fail(errorCode[result.code]?.msg, result.code, null);
+    }
+
+    // 密码已改，全端已登出 → 清除 cookie
+    ctx.cookies.set(SESSION_COOKIE_NAME, null, { maxAge: 0, path: "/" });
+    return ctx.api.success(null);
+  }
+}
+
+module.exports = AuthController;

package/app/controller/common/health.js

@@ -0,0 +1,15 @@
+const Controller = require('egg').Controller;
+
+class HealthController extends Controller {
+  async index() {
+    const { ctx } = this;
+
+    return ctx.api.success({
+      ready: this.app.initStatus.ready,
+      tasks: this.app.initStatus.tasks,
+      uptime: process.uptime(),
+    });
+  }
+}
+
+module.exports = HealthController;

package/app/controller/home.js

@@ -0,0 +1,10 @@
+const { Controller } = require('egg');
+
+class HomeController extends Controller {
+  async index() {
+    const { ctx } = this;
+    ctx.body = 'hi, egg';
+  }
+}
+
+module.exports = HomeController;

package/app/core/database/database-health.js

@@ -0,0 +1,39 @@
+// 数据库健康检查
+const { initDatabases } = require('./index');
+
+async function checkClient(name, prisma, query) {
+  const startedAt = Date.now();
+  try {
+    await prisma.\();
+    const result = await query(prisma);
+    return { name, ok: true, duration: Date.now() - startedAt, detail: result };
+  } catch (error) {
+    return { name, ok: false, duration: Date.now() - startedAt, detail: error instanceof Error ? error.message : String(error) };
+  } finally {
+    await prisma.\();
+  }
+}
+
+function formatResult(result) {
+  const status = result.ok ? 'PASS' : 'FAIL';
+  return '[' + status + '] ' + result.name + ' (' + result.duration + 'ms) ' + result.detail;
+}
+
+async function runDbChecks(app) {
+  const clients = initDatabases(app);
+  const checks = [];
+  for (const key in clients) {
+    if (!clients[key]) continue;
+    checks.push(
+      checkClient(key + ':connect-and-query', clients[key], async (prisma) => {
+        await prisma.\\SELECT 1 AS ok\;
+        return 'connected';
+      })
+    );
+  }
+  const results = await Promise.all(checks);
+  const failed = results.filter((r) => !r.ok);
+  return { ok: failed.length === 0, results };
+}
+
+module.exports = { formatResult, runDbChecks };

package/app/core/database/database-manager.js

@@ -0,0 +1,43 @@
+// 数据库实例管理器
+// 根据 app.config.Dbs 动态创建 PrismaClient 实例
+// Prisma 生成客户端从业务项目的 prisma/generated/{key} 加载
+const path = require('path');
+const { PrismaMariaDb } = require('@prisma/adapter-mariadb');
+const { buildPrismaLogDefinitions } = require('./prisma-logging');
+const { buildDataBaseUrl } = require('../../utils/prisma');
+
+/**
+ * 创建所有配置的数据库客户端实例
+ * @param {Egg.Application} app
+ * @returns {Object} { dbName: PrismaClient }
+ */
+function createDatabaseClients(app) {
+  const dbConfig = app.config.Dbs || {};
+  const loggingConfig = app.config.logging;
+  const clients = {};
+
+  for (const key in dbConfig) {
+    if (!dbConfig[key]) continue;
+
+    let PrismaClient;
+    // 优先从业务项目的 prisma/generated/{key} 加载
+    const projectPrismaPath = path.join(app.baseDir, 'prisma', 'generated', key);
+    try {
+      const mod = require(projectPrismaPath);
+      PrismaClient = mod.PrismaClient;
+    } catch (_) {
+      app.logger && app.logger.warn('[数据库] ' + key + ' PrismaClient 未在项目 prisma/generated 中找到: ' + projectPrismaPath);
+      continue;
+    }
+
+    const adapter = new PrismaMariaDb(dbConfig[key]);
+    clients[key] = new PrismaClient({
+      adapter,
+      log: buildPrismaLogDefinitions(loggingConfig),
+    });
+  }
+
+  return clients;
+}
+
+module.exports = createDatabaseClients;

package/app/core/database/index.js

@@ -0,0 +1,19 @@
+// 数据库模块入口
+const createDatabaseClients = require('./database-manager');
+const { setupPrismaLogging } = require('./prisma-logging');
+
+/**
+ * 初始化所有数据库客户端
+ * @param {Egg.Application} app
+ * @returns {Object} { dbName: PrismaClient }
+ */
+function initDatabases(app) {
+  const clients = createDatabaseClients(app);
+  const loggingConfig = app.config.logging;
+  for (const key in clients) {
+    if (clients[key]) setupPrismaLogging(key, clients[key], loggingConfig);
+  }
+  return clients;
+}
+
+module.exports = { initDatabases };

package/app/core/database/prisma-logging.js

@@ -0,0 +1,38 @@
+// Prisma 日志定义 & 事件监听
+const path = require('path');
+const { createLogger } = require('../../utils/logger');
+
+const prismaLevelRank = { query: 10, info: 20, warn: 30, error: 40 };
+
+function shouldEnablePrismaLevel(level, config) {
+  const configuredRank = prismaLevelRank[config.prisma.level] || prismaLevelRank.warn;
+  const currentRank = prismaLevelRank[level];
+  return currentRank >= configuredRank;
+}
+
+function buildPrismaLogDefinitions(config) {
+  const log = [];
+  for (const level of ['info', 'warn', 'error']) {
+    if (shouldEnablePrismaLevel(level, config)) log.push({ level, emit: 'event' });
+  }
+  if (config.prisma.sqlTerminal || config.prisma.slowQueryMs >= 0) {
+    log.push({ level: 'query', emit: 'event' });
+  }
+  return log;
+}
+
+function setupPrismaLogging(name, prisma, config) {
+  const elog = createLogger({ level: config.prisma.level || 'info', filePath: config.prisma.filePath, terminal: config.prisma.sqlTerminal, pretty: config.prisma.sqlTerminal });
+  const slog = createLogger({ level: config.prisma.sqlLogLevel, filePath: config.prisma.filePath, terminal: config.prisma.sqlTerminal, pretty: config.prisma.sqlTerminal });
+
+  prisma.$on('query', (event) => {
+    const payload = { component: 'prisma', database: name, query: event.query, params: event.params, duration: event.duration };
+    if (typeof slog.debug === 'function') slog.debug('Prisma SQL [' + name + ']', payload);
+    if (event.duration > config.prisma.slowQueryMs) elog.warn('Prisma Slow Query [' + name + ']', payload);
+  });
+  prisma.$on('info', (event) => elog.info('Prisma Info [' + name + ']', { component: 'prisma', database: name, target: event.target, message: event.message }));
+  prisma.$on('warn', (event) => elog.warn('Prisma Warn [' + name + ']', { component: 'prisma', database: name, target: event.target, message: event.message }));
+  prisma.$on('error', (event) => elog.error('Prisma Error [' + name + ']', { component: 'prisma', database: name, target: event.target, message: event.message }));
+}
+
+module.exports = { buildPrismaLogDefinitions, setupPrismaLogging };

package/app/core/database/transaction-manager.js

@@ -0,0 +1,9 @@
+// 事务封装
+class TransactionManager {
+  static async execute(db, callback) {
+    return db.$transaction(async (tx) => {
+      try { return await callback(tx); } catch (error) { throw error; }
+    });
+  }
+}
+module.exports = TransactionManager;

package/app/core/repository/auth/user_repository.js

@@ -0,0 +1,14 @@
+const BaseRepository = require('../base-repository');
+
+class UserRepository extends BaseRepository {
+  constructor(ctx) { super(ctx.Dbs.fx.user_info); this.ctx = ctx; }
+
+  async findOneUser({ userId, enName, password }) {
+    const where = {};
+    if (userId) where.id = userId;
+    if (enName) where.en_name = enName;
+    return await this.findOne({ where });
+  }
+}
+
+module.exports = UserRepository;

package/app/core/repository/base-repository.js

@@ -0,0 +1,26 @@
+// 通用 CRUD 封装
+class BaseRepository {
+  constructor(model) { this.model = model; }
+
+  async create(data) { return this.model.create({ data }); }
+  async createMany(data) { return this.model.createMany({ data }); }
+  async findById(args) { return this.model.findUnique(args); }
+  async findOne(args) { return this.model.findFirst(args); }
+  async findMany(args) { return this.model.findMany(args); }
+
+  async paginate(pageIndex = 1, pageSize = 10, args = {}) {
+    const skip = (pageIndex - 1) * pageSize;
+    const [list, total] = await Promise.all([
+      this.model.findMany({ ...args, skip, take: pageSize }),
+      this.model.count(args.where ? { where: args.where } : {}),
+    ]);
+    return { list, total, totalPages: Math.ceil(total / pageSize) };
+  }
+
+  async updateByFilter(args) { return this.model.update(args); }
+  async deleteByFilter(args) { return this.model.delete(args); }
+  async exists(where = {}) { const count = await this.model.count({ where }); return count > 0; }
+  async count(where = {}) { return this.model.count({ where }); }
+}
+
+module.exports = BaseRepository;