@layoutkit/bree-core 1.0.10 → 1.1.0

package/dist/index.js

@@ -5,13 +5,15 @@ import nodemailer from 'nodemailer';
 import { createClient } from 'redis';
 import Bree from 'bree';
 import fs$1 from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import winston from 'winston';
 import 'winston-daily-rotate-file';
 import knex from 'knex';
-import dotenv from 'dotenv';
 import crypto from 'node:crypto';
-import { parentPort, workerData } from 'node:worker_threads';
+import express from 'express';
+import { readdir } from 'fs/promises';
+import path$1 from 'path';
+import { pathToFileURL } from 'url';
+import { parentPort } from 'node:worker_threads';
 
 let baseFolder = null;
 
@@ -137,7 +139,7 @@ var excelUtil = {
 
 let transporter = null;
 let from = '';
-const init$2 = () => {
+const init = () => {
     from = `"${process.env.MAIL_USERNAME}" <${process.env.MAIL_ACCOUNT}>`;
     transporter = nodemailer.createTransport({
         host: process.env.MAIL_HOST, // 或公司邮箱 SMTP
@@ -168,7 +170,7 @@ const send = async (subject, toUser = '', copyUser = '', content = '', filePath
 };
 
 var mailUtil = {
-    init: init$2,
+    init,
     send
 };
 
@@ -374,57 +376,131 @@ class RedisHelper {
 
 var redis = new RedisHelper();
 
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-
-const { combine: combine$2, timestamp: timestamp$2, printf: printf$2 } = winston.format;
-const logFormat$2 = printf$2(({ timestamp, level, message }) => {
-    return `[${timestamp}] [${level.toUpperCase()}] ${message}`
-});
+const { combine, timestamp, printf } = winston.format;
 
-const breeLogger = winston.createLogger({
-    level: 'info',
-    format: combine$2(
-        timestamp$2({ format: 'YYYY-MM-DD HH:mm:ss' }),
-        logFormat$2
-    ),
-    transports: [
-        new winston.transports.Console(),
-        new winston.transports.DailyRotateFile({
-            dirname: 'logs',
-            filename: 'worker-%DATE%.log',
-            datePattern: 'YYYY-MM-DD',
-            maxSize: '20m',
-            maxFiles: '30d'
-        })
-    ]
+/**
+ * 默认日志格式：可被 format 参数覆盖
+ */
+const defaultLogFormat = printf(({ timestamp, level, message }) => {
+    return `[${timestamp}] [${level.toUpperCase()}] ${message}`
 });
 
 /**
- * worker日志
+ * 单级别文件过滤器（用于 split 按级别拆文件）
  */
-const worker = (jobName, message) => {
-    breeLogger.info(`[${jobName}] ${message}`);
+const levelFilter = (level) => {
+    return winston.format((info) => {
+        return info.level === level ? info : false
+    })()
 };
 
 /**
- * error日志
+ * split=true 时默认按全部级别拆分
  */
-const error$1 = (jobName, err) => {
-    breeLogger.error(`[${jobName}] ${err?.stack || err?.message || err}`);
-};
-var blogger = { worker, error: error$1 };
+const defaultSplitLevels = ['debug', 'info', 'warn', 'error'];
+
+/**
+ * 统一 logger 工厂
+ * @param {object} options
+ * @param {string} [options.name='app']        日志文件名前缀，如 'worker' -> worker-%DATE%.log；不传 dirname 时同时作为子目录名
+ * @param {string} [options.dirname]           日志子目录（相对 logs 根）；不传则用 name 作为子目录名，
+ *                                             显式传 '' 则直接写在 logs 根下。如 'weixinapi' -> logs/weixinapi/
+ * @param {string} [options.level='info']      日志级别：error | warn | info | debug
+ * @param {function} [options.format]          自定义日志格式（printf 函数），默认 [时间] [级别] 消息
+ * @param {boolean} [options.console=true]     是否输出到控制台
+ * @param {boolean} [options.file=true]        是否输出到文件
+ * @param {string} [options.datePattern='YYYY-MM-DD']  日志文件名日期格式
+ * @param {string} [options.maxSize='20m']     单个日志文件大小上限，超过即滚动，如 '20m' | '100k'
+ * @param {string|number} [options.maxFiles='30d']  日志保留时长/份数，如 '30d' | 14
+ * @param {boolean|string[]} [options.split=false]
+ *        false：不拆分，全部写到 <name>-%DATE%.log
+ *        true：按 debug/info/warn/error 各写一个文件
+ *        数组：按传入级别拆分，如 ['info', 'warn', 'error']
+ * @returns {import('winston').Logger}
+ */
+function createLogger(options = {}) {
+    const {
+        name = 'app',
+        dirname,
+        level = 'info',
+        format = defaultLogFormat,
+        console = true,
+        file = true,
+        datePattern = 'YYYY-MM-DD',
+        maxSize = '10m',
+        maxFiles = '10d',
+        split = false
+    } = options;
+
+    // 目录解析：设置 LOG_DIR 环境变量即自动以其为日志根目录，否则以 logs 为根目录
+    // dirname 为其下子目录；不传 dirname 时自动用 name 作为子目录；显式传 '' 则直接写根
+    const subDir = dirname ?? name;
+    const root = process.env.LOG_DIR ? path.join(process.env.LOG_DIR, 'logs') : 'logs';
+    const logDir = path.join(root, subDir);
+
+    /**
+     * 内部：创建文件滚动 transport
+     * @param {string} filename
+     * @param {string} [fileLevel] 指定级别时配合 levelFilter 精确过滤，仅写该级别日志
+     */
+    const createFileTransport = (filename, fileLevel) => {
+        const formatParts = [
+            timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+            format
+        ];
+        if (fileLevel) formatParts.unshift(levelFilter(fileLevel));
+
+        return new winston.transports.DailyRotateFile({
+            dirname: logDir,
+            filename,
+            ...(fileLevel ? { level: fileLevel } : {}),
+            datePattern,
+            maxSize,
+            maxFiles,
+            format: combine(...formatParts)
+        })
+    };
+
+    const transports = [];
+
+    if (console) {
+        transports.push(new winston.transports.Console());
+    }
+
+    if (file) {
+        const splitLevels = Array.isArray(split)
+            ? split
+            : (split ? defaultSplitLevels : null);
+
+        if (splitLevels) {
+            for (const splitLevel of splitLevels) {
+                transports.push(createFileTransport(`${name}-${splitLevel}-%DATE%.log`, splitLevel));
+            }
+        } else {
+            transports.push(createFileTransport(`${name}-%DATE%.log`));
+        }
+    }
+
+    return winston.createLogger({
+        level,
+        format: combine(
+            timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+            format
+        ),
+        transports
+    })
+}
 
-const ALGORITHM_MAP$1 = {
+const ALGORITHM_MAP = {
     16: 'aes-128-ecb',
     24: 'aes-192-ecb',
     32: 'aes-256-ecb'
 };
 
-const encrypt$1 = (data, key) => {
+const encrypt = (data, key) => {
     // key 必须 16 / 24 / 32 字节
     const keyBuf = Buffer.from(key, 'utf8');
-    const cipher = crypto.createCipheriv(ALGORITHM_MAP$1[keyBuf.length], keyBuf, null);
+    const cipher = crypto.createCipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
     cipher.setAutoPadding(true); // PKCS7
     const encrypted = Buffer.concat([
         cipher.update(data),
@@ -433,9 +509,9 @@ const encrypt$1 = (data, key) => {
     return encrypted
 };
 
-const decrypt$1 = (data, key) => {
+const decrypt = (data, key) => {
     const keyBuf = Buffer.from(key, 'utf8');
-    const decipher = crypto.createDecipheriv(ALGORITHM_MAP$1[keyBuf.length], keyBuf, null);
+    const decipher = crypto.createDecipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
     decipher.setAutoPadding(true);
     const decrypted = Buffer.concat([
         decipher.update(data),
@@ -453,9 +529,9 @@ const decrypt$1 = (data, key) => {
  * @param {string} key AES密钥(16/24/32字节)
  * @returns {string} 明文
  */
-const decryptString$1 = (data, key) => {
+const decryptString = (data, key) => {
     const keyBuf = Buffer.from(key, 'utf8');
-    const decipher = crypto.createDecipheriv(ALGORITHM_MAP$1[keyBuf.length], keyBuf, null);
+    const decipher = crypto.createDecipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
     decipher.setAutoPadding(true);
     const decrypted = Buffer.concat([
         decipher.update(Buffer.from(data, 'base64')),
@@ -464,73 +540,131 @@ const decryptString$1 = (data, key) => {
     return decrypted.toString('utf8')
 };
 
-var aes$1 = { encrypt: encrypt$1, decrypt: decrypt$1, decryptString: decryptString$1 };
+var aes = { encrypt, decrypt, decryptString };
 
-dotenv.config();
-
-function useDatabase() {
-    let db = null;
-
-    const init = async (connectionString) => {
-        const aesKey = process.env.DB_AES_KEY;
+let db$1 = null;
+
+/** 解析 `key=value;key=value` 形式的连接串（值允许包含 `=`） */
+const parseConnectionString = (str) =>
+    str.split(';').reduce((acc, param) => {
+        const idx = param.indexOf('=');
+        if (idx === -1) return acc
+        const key = param.slice(0, idx).trim();
+        const value = param.slice(idx + 1).trim();
+        if (key) acc[key] = value;
+        return acc
+    }, {});
+
+/** 配置了 DB_AES_KEY 时尝试解密；非密文（解密失败）则原样使用 */
+const resolveConnectionString = (connectionString) => {
+    const aesKey = process.env.DB_AES_KEY;
+    if (aesKey) {
         try {
-            const decryptedConnectionString = aes$1.decryptString(connectionString, aesKey);
-            const connectionParams = decryptedConnectionString.split(';').reduce((acc, param) => {
-                const [key, value] = param.split('=');
-                acc[key] = value;
-                return acc
-            }, {});
-            db = knex({
-                client: 'mssql',
-                connection: {
-                    user: connectionParams.user,
-                    password: connectionParams.password,
-                    server: connectionParams.server,
-                    database: connectionParams.database,
-                    options: {
-                        encrypt: false
-                    }
-                }
-            });
+            return aes.decryptString(connectionString, aesKey)
+        } catch {
+            // 明文连接串，直接使用
+        }
+    }
+    return connectionString
+};
 
-            // 等待数据库真实连接
-            await db.raw('SELECT 1');
-            console.log('database initialized');
-            return db
-        } catch (error) {
-            await close();
+class DatabaseHelper {
+    /**
+     * 初始化数据库连接（自动读取 DB_CONNECTION_STRING，可传参覆盖）
+     * @param {string} [connectionString=process.env.DB_CONNECTION_STRING] 连接串（明文或 AES 密文）
+     * @returns {Promise<object>} knex 实例
+     * @example
+     * const db = await database.init()
+     * const rows = await db('users').select('*')
+     */
+    async init(connectionString = process.env.DB_CONNECTION_STRING) {
+        if (!connectionString) {
+            throw new Error(
+                'DB connection string required: pass it to database.init(str) or set DB_CONNECTION_STRING'
+            )
+        }
+        await this.close(); // 重复初始化前先释放旧连接
+
+        const params = parseConnectionString(resolveConnectionString(connectionString));
+        db$1 = knex({
+            client: 'mssql',
+            connection: {
+                user: params.user,
+                password: params.password,
+                server: params.server,
+                database: params.database,
+                options: {
+                    encrypt: false
+                }
+            }
+        });
 
-            throw error
+        try {
+            await db$1.raw('SELECT 1'); // 验证真实连接
+        } catch (err) {
+            await this.close();
+            throw err
         }
-    };
+        return db$1
+    }
+
+    /**
+     * 获取 knex 实例（未初始化时给出明确提示）
+     * @returns {object} knex 实例
+     */
+    get() {
+        if (!db$1) throw new Error('Database not initialized, call await database.init() first')
+        return db$1
+    }
 
-    const close = async () => {
-        if (db) {
-            await db.destroy();
-            db = null;
+    /** 关闭数据库连接 */
+    async close() {
+        if (db$1) {
+            await db$1.destroy();
+            db$1 = null;
         }
-    };
+    }
+}
 
-    return { init, close }
-}
+var database = new DatabaseHelper();
 
-dotenv.config();
-
-const db$1 = useDatabase();
-const init$1 = async () => await db$1.init(process.env.DB_CONNECTION_STRING);
-const close = async () => await db$1.close();
+let registerError = null;
+let registerComplete = null;
+let registerLoader = null;
+
+/** 每个钩子未注册时只提示一次，避免刷屏 */
+const warnOnce = (() => {
+    const warned = new Set();
+    return (name) => {
+        if (warned.has(name)) return
+        warned.add(name);
+        console.warn(
+            `[bree-core] hooks.${name} 未注册，任务状态不会回写数据库。` +
+            `可直接赋值 hooks.${name} = async (db, obj) => { /* 回写逻辑 */ } 注册。`
+        );
+    }
+})();
+
+// 默认空实现：不注册不崩溃，只提示一次
+registerError = async () => warnOnce('registerError');
+registerComplete = async () => warnOnce('registerComplete');
+registerLoader = async () => {
+    warnOnce('registerLoader');
+    return []
+};
 
-var database = {
-    init: init$1,
-    close
+var hooks = {
+    registerLoader,
+    registerError,
+    registerComplete
 };
 
-path.resolve(__dirname$1, '../../');
-
 let bree = null;
 let db = null;
 let jobsRoot = null;
 
+const logger = createLogger({ name: 'scheduler', split: true });
+
 // 让使用者通过环境变量或配置指定 jobs 目录
 const getJobsRoot = () => {
     if (jobsRoot) return jobsRoot
@@ -573,47 +707,51 @@ const createBree = () => {
     const instance = new Bree({
         hasSeconds: true,
         root: jobsPath,
+        doRootCheck: false, // 任务列表由 hooks.registerLoader / 数据库提供，无需 root/index.js
         errorHandler: async (error, workerMetadata) => {
-            if (workerMetadata?.threadId) {
-                blogger.worker(workerMetadata.name,
-                    `There was an error while running a worker ${workerMetadata.name} with thread ID: ${workerMetadata.threadId}`);
-            } else {
-                blogger.worker(workerMetadata.name,
-                    `There was an error while running a worker ${workerMetadata.name}`);
-            }
-
-            blogger.error(workerMetadata?.name, error);
             if (error?.message?.indexOf('exited with code') > -1) return
-            const job = instance.config.jobs.find(x => x.name === workerMetadata?.name);
-            const workerData = job?.worker?.workerData;
+            const name = workerMetadata?.name;
+            logger.info(`[${name}] There was an error while running a worker ${name} with thread ID: ${workerMetadata?.threadId}`);
+            logger.error(`[${name}] ${error?.stack || error?.message || error}`);
+            const worker = instance.workers.get(name);
+            const workerData = worker?.workerData;
             if (workerData) {
-                await db('Sys_BreeJobs')
-                    .where('ID', workerData.id)
-                    .update({
-                        'ResultStatus': 1,
-                        'ErrorMessage': error?.stack
-                    });
+                await hooks.registerError(db, { id: workerData.id, error: error?.stack });
             }
         }
     });
 
     instance.on('worker created', (name) => {
-        console.log('worker created', name);
-        blogger.worker(name, 'worker created');
+        console.log(`[${name}] worker created`);
+        logger.info(`[${name}] worker created`);
     });
 
-    instance.on('worker deleted', (name) => {
-        console.log('worker deleted', name);
-        blogger.worker(name, 'worker deleted');
+    instance.on('worker deleted', async (name) => {
+        console.log(`[${name}] worker deleted`);
+        logger.info(`[${name}] worker deleted`);
     });
 
-    return instance
-};
+    instance.on('worker message', async (name, message) => {
+        console.log(`[${name}] worker message:`, message);
 
-const getBree = () => {
-    return bree
+        if (message.type === 'done') {
+            try {
+                const worker = instance.workers.get(name);
+                const workerData = worker?.workerData;
+                await hooks.registerComplete(db, {
+                    id: workerData?.id,
+                    result: message.data
+                });
+            } catch (error) {
+                logger.error(`[${name}] registerComplete failed`, error);
+            }
+        }
+    });
+
+    return instance
 };
 
+const getBree = () => bree;
 const reset = async (job, startStatus) => {
     await bree.stop(job.name);
     const index = bree.config.jobs.findIndex(x => x.name === job.name);
@@ -624,10 +762,8 @@ const reset = async (job, startStatus) => {
 
 const remove = async (name) => {
     await bree.stop(name);
-
     // 删除运行中的 worker 貌似不需要
     // delete bree.workers.get(name)
-
     const index = bree.config.jobs.findIndex(x => x.name === name);
     if (index !== -1) bree.config.jobs.splice(index, 1);
 };
@@ -640,66 +776,20 @@ const create = async (job) => {
 };
 
 // 启动任务
-const start = async (name) => {
-    await bree.start(name);
-};
+const start = async (name) => await bree.start(name);
 // 停止任务
-const stop = async (name) => {
-    await bree.stop(name);
-};
+const stop = async (name) => await bree.stop(name);
 // 执行一次任务
-const run = async (name) => {
-    await bree.run(name);
-};
-
+const run = async (name) => await bree.run(name);
 // 任务初始化
-const init = async () => {
-    // 1. 从数据库读取任务列表
+const register$1 = async () => {
     db = await database.init();
-    // 2. 创建 Bree 实例（在数据库初始化之后）
     bree = createBree();
-    // 3. 从数据库读取任务列表
-    const jobs = await db('Sys_BreeJobs'); //.where('Status', 1)
-    // 4. 批量注册到调度器
-    for (const job of jobs) {
-        const id = job['ID'];
-        const name = job['Name'];
-        const cron = job['Cron'];
-        const path = job['Path'];
-        const status = job['Status']; // status 状态为0：已停止 1：执行中 2：
-        const createStatus = job['CreateStatus'];
-
-        try {
-            await create({
-                name,
-                cron,
-                path: path || undefined,
-                worker: { workerData: { id } }
-            });
-
-            if (status === 1) await bree.start(name);
-            if (createStatus === 0) {
-                await db('Sys_BreeJobs')
-                    .where('ID', id)
-                    .update({
-                        'CreateStatus': 1
-                    });
-            }
-        }
-        catch (error) {
-            blogger.error(name, error);
-            await db('Sys_BreeJobs')
-                .where('ID', id)
-                .update({
-                    'ResultStatus': 1,
-                    'ErrorMessage': error?.stack
-                });
-        }
-    }
+    await hooks.registerLoader(db, logger);
 };
 
 var scheduler = {
-    init,
+    register: register$1,
     create,
     reset,
     start,
@@ -709,149 +799,168 @@ var scheduler = {
     remove
 };
 
-const { combine: combine$1, timestamp: timestamp$1, printf: printf$1 } = winston.format;
-const logFormat$1 = printf$1(({ timestamp, level, message }) => {
-    return `[${timestamp}] [${level.toUpperCase()}] ${message}`
-});
-
 /**
- * 日志级别过滤器
+ * 单函数接口风格路由（近似 `@Route('/path')` 装饰器，纯 JS 用函数包装实现）
+ *
+ * 用法（业务模块中定义即自动注册，无需手动传给 useServer）：
+ *   route.post('/test', (body) => {
+ *       const { name, age } = body
+ *       return { code: 0, message: 'success', data: null }  // 完整响应体原样返回
+ *   })
+ *   route.get('/user/:id', async ({ id }) => ({ id }))
+ *
+ * 分组前缀（减少重复路径）：
+ *   const api = route.parentRoute('/task')
+ *   api.post('/upload', upload.single('file'), async (body, req) => {
+ *       // 注册为 POST /task/upload
+ *       if (!req.file) return { code: -1, message: '文件不能为空' }
+ *       return { code: 0, message: '上传成功', data: { filename: req.file.filename } }
+ *   })
+ *   api.get('/list', async () => [])   // GET /task/list
+ *   api.parentRoute('/:id').get('/info', async ({ id }) => ({}))  // 支持嵌套，GET /task/:id/info
+ *
+ * 支持中间件（Express 风格，如 multer 文件上传）：
+ *   route.post('/upload', upload.single('file'), async (body, req, res) => {
+ *       // req.file 由 multer 解析后注入（body 不含文件，文件在 req.file）
+ *       return { code: 0, message: '上传成功', data: { filename: req.file.filename } }
+ *   })
+ *   route.post('/upload', [auth, upload.array('files', 5)], async (body, req, res) => { ... })
+ *
+ * handler 签名：async (body, req, res) => result
+ *   - body：自动合并 { params, query, body }，解构即用
+ *   - req / res：原始对象（需要时可用 req.file、req.ip、res.setHeader 等）
+ *   - 返回 { code, ... } 对象时原样 res.json 输出；返回普通数据自动包装为 res.success
+ *   - 抛错自动进入全局错误处理
+ *
+ * 方法类型：route.get / route.post / route.put / route.delete / route.patch
+ *   也可 route(path, handler, method)，默认 POST
  */
-const levelFilter = (level) => {
-    return winston.format((info) => {
-        return info.level === level ? info : false
-    })()
+
+/** 自动注册路由注册表（模块加载时定义即注册，useServer 启动时自动收集） */
+const registeredRoutes = [];
+
+const register = (route) => {
+    const idx = registeredRoutes.findIndex((r) => r.method === route.method && r.path === route.path);
+    if (idx >= 0) registeredRoutes[idx] = route;
+    else registeredRoutes.push(route);
+    return route
 };
 
-const logger = winston.createLogger({
-    level: 'info',
-    format: combine$1(
-        timestamp$1({ format: 'YYYY-MM-DD HH:mm:ss' }),
-        logFormat$1
-    ),
-    transports: [
-        new winston.transports.Console(),
-        new winston.transports.DailyRotateFile({
-            dirname: 'logs',
-            filename: 'info-%DATE%.log',
-            datePattern: 'YYYY-MM-DD',
-            maxSize: '20m',
-            maxFiles: '30d',
-            format: combine$1(
-                levelFilter('info'),
-                timestamp$1({ format: 'YYYY-MM-DD HH:mm:ss' }),
-                logFormat$1
-            )
-        }),
-        new winston.transports.DailyRotateFile({
-            dirname: 'logs',
-            filename: 'error-%DATE%.log',
-            level: 'error',
-            datePattern: 'YYYY-MM-DD',
-            maxSize: '20m',
-            maxFiles: '30d',
-            format: combine$1(
-                levelFilter('error'),
-                timestamp$1({ format: 'YYYY-MM-DD HH:mm:ss' }),
-                logFormat$1
-            )
-        })
-    ]
-});
-
-function useHandler() {
-    let isCancelled = false;
-    let db = null;
+/** 获取所有已注册路由（内部使用，供 useServer 启动时收集） */
+const getRegisteredRoutes = () => [...registeredRoutes];
 
-    const getIsCancelled = () => isCancelled;
-    const updateTask = async (obj) => {
-        await db('Sys_BreeJobs')
-            .where('ID', workerData.id)
-            .update(obj);
-    };
-    const run = async (worker) => {
-        if (parentPort)
-            parentPort.once('message', (message) => {
-                console.log(message);
-                if (message === 'cancel') isCancelled = true;
-            });
+/** 拼接路径：joinPath('/task', '/upload') => '/task/upload'；joinPath('/task', '') => '/task' */
+const joinPath = (prefix, path) => {
+    const p = String(prefix ?? '').replace(/\/+$/, '');
+    const h = String(path ?? '').replace(/^\/+/, '');
+    return h ? `${p}/${h}` : p
+};
 
-        db = await database.init();
+/**
+ * 解析参数：route(path, [middlewares...,] handler[, method])
+ * 兼容：route(path, handler, method)
+ */
+const resolveArgs = (...args) => {
+    let method = null;
+    // 末尾若为合法方法字符串，视为 method（兼容 route(path, handler, method)）
+    if (typeof args[args.length - 1] === 'string' && ['get', 'post', 'put', 'delete', 'patch'].includes(args[args.length - 1].toLowerCase())) {
+        method = args.pop();
+    }
+    const handler = args.pop();
+    // 中间件：单个函数或数组（数组展开），handler 之前的参数
+    const middlewares = Array.isArray(args[0]) ? args[0] : args;
+    return { middlewares, handler, method }
+};
 
-        try {
-            const result = await worker({ logger, redis, db });
-            await updateTask({ 'ResultStatus': 0, 'ExecuteResult': result });
-        } catch (err) {
-            await updateTask({ 'ResultStatus': 1, 'ErrorMessage': err.message });
-            logger.error(`${err?.stack || err?.message || err}`);
-        } finally {
-            await redis.close();
-            await database.close(); // 关闭连接池
-            if (parentPort) {
-                parentPort.postMessage("done");
-            } else {
-                process.exit(0);
+const createRoute = (path, middlewares, handler, method) => {
+    const item = {
+        method,
+        path,
+        handler: async (req, res, next) => {
+            try {
+                // 先执行引用者中间件（Express 风格 (req, res, next)，如 multer 的 upload.single('file')）
+                for (const mw of middlewares) {
+                    await new Promise((resolve, reject) => {
+                        mw(req, res, (err) => (err ? reject(err) : resolve()));
+                    });
+                }
+                const body = { ...req.params, ...req.query, ...req.body };
+                const result = await handler(body, req, res);
+                if (!res.headersSent) {
+                    if (result && typeof result === 'object' && 'code' in result) {
+                        res.json(result);
+                    } else {
+                        res.success(result === undefined ? null : result);
+                    }
+                }
+            } catch (err) {
+                next(err);
             }
         }
     };
-
-    return { run, getIsCancelled }
-}
-
-const ALGORITHM_MAP = {
-    16: 'aes-128-ecb',
-    24: 'aes-192-ecb',
-    32: 'aes-256-ecb'
+    return register(item)
 };
 
-const encrypt = (data, key) => {
-    // key 必须 16 / 24 / 32 字节
-    const keyBuf = Buffer.from(key, 'utf8');
-    const cipher = crypto.createCipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
-    cipher.setAutoPadding(true); // PKCS7
-    const encrypted = Buffer.concat([
-        cipher.update(data),
-        cipher.final()
-    ]);
-    return encrypted
+/**
+ * 定义并自动注册一个路由
+ * @param {string} path 路由路径，如 '/test'
+ * @param {function|function[]} handlerOrMws 处理函数 async (body, req, res) => result；
+ *        也可先传中间件（单个或数组，如 multer 的 upload.single('file')），最后一个参数为处理函数
+ * @param {string} [method='post'] HTTP 方法：get | post | put | delete | patch
+ * @returns {{method:string,path:string,handler:function}} 路由配置
+ */
+const route = (path, ...args) => {
+    const { middlewares, handler, method } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, method || 'post')
 };
 
-const decrypt = (data, key) => {
-    const keyBuf = Buffer.from(key, 'utf8');
-    const decipher = crypto.createDecipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
-    decipher.setAutoPadding(true);
-    const decrypted = Buffer.concat([
-        decipher.update(data),
-        decipher.final()
-    ]);
-    return decrypted
+// 方法类型便捷写法（IDE 自动补全友好）
+route.get = (path, ...args) => {
+    const { middlewares, handler } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, 'get')
+};
+route.post = (path, ...args) => {
+    const { middlewares, handler } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, 'post')
+};
+route.put = (path, ...args) => {
+    const { middlewares, handler } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, 'put')
+};
+route.delete = (path, ...args) => {
+    const { middlewares, handler } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, 'delete')
+};
+route.patch = (path, ...args) => {
+    const { middlewares, handler } = resolveArgs(...args);
+    return createRoute(path, middlewares, handler, 'patch')
 };
 
 /**
- * AES解密
- * 对应 Java:
- * AesUtil.decrypt(String data, String key)
- *
- * @param {string} data Base64密文
- * @param {string} key AES密钥(16/24/32字节)
- * @returns {string} 明文
+ * 分组前缀路由：返回带 get/post/put/delete/patch 的子路由，路径自动拼接前缀
+ * 用法：
+ *   const api = route.parentRoute('/task')
+ *   api.post('/upload', upload.single('file'), handler)   // POST /task/upload
+ *   api.get('/list', handler)                              // GET /task/list
+ *   api.parentRoute('/:id').get('/info', handler)          // 支持嵌套，GET /task/:id/info
+ * @param {string} [prefix=''] 路径前缀，如 '/task'
+ * @returns {{get:function,post:function,put:function,delete:function,patch:function,parentRoute:function}}
  */
-const decryptString = (data, key) => {
-    const keyBuf = Buffer.from(key, 'utf8');
-    const decipher = crypto.createDecipheriv(ALGORITHM_MAP[keyBuf.length], keyBuf, null);
-    decipher.setAutoPadding(true);
-    const decrypted = Buffer.concat([
-        decipher.update(Buffer.from(data, 'base64')),
-        decipher.final()
-    ]);
-    return decrypted.toString('utf8')
-};
-
-var aes = { encrypt, decrypt, decryptString };
+route.parentRoute = (prefix = '') => {
+    const api = {};
+    for (const method of ['get', 'post', 'put', 'delete', 'patch']) {
+        api[method] = (path, ...args) => {
+            const { middlewares, handler } = resolveArgs(...args);
+            return createRoute(joinPath(prefix, path), middlewares, handler, method)
+        };
+    }
+    // 嵌套分组：api.parentRoute('/:id').get(...)
+    api.parentRoute = (sub = '') => route.parentRoute(joinPath(prefix, sub));
+    return api
+};
 
 function auth(req, res, next) {
-    const apiKey = req.headers['x-api-key'];
-
+    const apiKey = req.headers[process.env.API_SECRET_KEY_NAME];
     if (!apiKey) {
         return res.status(200).json({
             code: -1,
@@ -885,43 +994,272 @@ function auth(req, res, next) {
     next();
 }
 
-const { combine, timestamp, printf } = winston.format;
-const logFormat = printf(({ timestamp, level, message }) => {
-    return `[${timestamp}] [${level.toUpperCase()}] ${message}`
-});
+/**
+ * 递归扫描目录下所有 JS 文件并动态加载（触发 route() 自动注册）
+ * 跳过以 . / _ 开头的文件（如 .DS_Store、_private.js）
+ */
+const loadRouteFiles = async (dirs, logger) => {
+    const list = Array.isArray(dirs) ? dirs : [dirs];
+    let total = 0;
 
-const weixinLogger = winston.createLogger({
-    level: 'info',
-    format: combine(
-        timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
-        logFormat
-    ),
-    transports: [
-        new winston.transports.Console(),
-        new winston.transports.DailyRotateFile({
-            dirname: 'logs',
-            filename: 'weixinapi-%DATE%.log',
-            datePattern: 'YYYY-MM-DD',
-            maxSize: '20m',
-            maxFiles: '30d'
-        })
-    ]
-});
+    for (const dir of list) {
+        const abs = path$1.resolve(dir);
+        let entries;
+        try {
+            entries = await readdir(abs, { withFileTypes: true });
+        } catch {
+            // 目录不存在则跳过，但给出提示便于诊断路由未加载
+            logger?.warn?.(`routes dir not found, skipped: ${abs}`);
+            continue
+        }
+
+        const walk = async (items, base) => {
+            for (const item of items) {
+                if (item.name.startsWith('.') || item.name.startsWith('_')) continue
+                const full = path$1.join(base, item.name);
+                if (item.isDirectory()) {
+                    await walk(await readdir(full, { withFileTypes: true }), full);
+                } else if (/\.(mjs|cjs|js)$/i.test(item.name)) {
+                    try {
+                        await import(pathToFileURL(full).href);
+                        total += 1;
+                    } catch (err) {
+                        logger?.error?.(`load routes file failed: ${full} - ${err?.message || err}`);
+                    }
+                }
+            }
+        };
+        await walk(entries, abs);
+    }
+
+    if (total > 0) logger?.info?.(`auto-loaded ${total} routes file(s)`);
+};
 
 /**
- * worker日志
+ * CORS 中间件（不引入额外依赖）
  */
-const info = (apiName, message) => {
-    weixinLogger.info(`[${apiName}] ${message}`);
+const createCors = (options = {}) => {
+    const opts = typeof options === 'string' ? { origin: options } : options;
+    const origin = opts.origin ?? '*';
+    const methods = opts.methods || 'GET,POST,PUT,DELETE,PATCH,OPTIONS';
+    const headers = opts.headers || 'Content-Type,Authorization,x-api-key';
+
+    return (req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Access-Control-Allow-Methods', methods);
+        res.setHeader('Access-Control-Allow-Headers', headers);
+        if (req.method === 'OPTIONS') return res.sendStatus(204)
+        next();
+    }
 };
 
 /**
- * error日志
+ * Express 服务封装
+ * @param {object} options
+ * @param {number} [options.port=3000]        监听端口
+ * @param {string} [options.host='0.0.0.0']   监听地址
+ * @param {object} [options.logger]           自定义 logger（默认 createLogger({ name: 'server', split: true })）
+ * @param {string} [options.jsonLimit='10mb']  JSON body 大小限制
+ * @param {string} [options.urlencodedLimit='10mb']  urlencoded body 大小限制
+ * @param {boolean|string|object} [options.cors=true] 是否启用 CORS；可传 origin 字符串或 { origin, methods, headers }
+ * @param {string|string[]} [options.staticDir=null]  静态资源目录（可传数组），相对 cwd 或绝对路径
+ * @param {boolean|function|function[]} [options.auth=false]  认证中间件：
+ *        true 使用内置 auth（依赖 API_SECRET_KEY/API_TOKEN/ALLOW_IPS 环境变量）；
+ *        传函数或函数数组则使用外部自定义中间件（如 (req, res, next) => {...}）；false 不启用
+ * @param {boolean} [options.health=true]     是否启用 GET /health 健康检查
+ * @param {boolean} [options.trustProxy=true] 是否信任代理（影响 req.ip）
+ * @param {function|Array<{method:string,path:string,handler:function|function[]}>} [options.routes=null]
+ *        路由注册：函数 (app) => {...} 或路由配置数组；也可省略，用 route() 定义即自动注册
+ * @param {string|string[]|false} [options.routesDir=['routes','src/routes']] 路由文件目录（相对 cwd 或绝对路径），
+ *        start() 时自动递归扫描并加载其中所有 JS 文件（触发 route() 自动注册），无需手动 import；
+ *        默认同时扫描 'routes' 与 'src/routes' 两个候选目录（存在哪个扫哪个）；
+ *        传 false 关闭扫描；传数组可自定义多个目录
+ * @returns {{ app, start, stop, getServer }}
  */
-const error = (apiName, err) => {
-    weixinLogger.error(`[${apiName}] ${err?.stack || err?.message || err}`);
-};
-var weixinLogger_default = { info, error };
+function useServer(options = {}) {
+    const {
+        port = 3000,
+        host = '0.0.0.0',
+        logger = createLogger({ name: 'server', split: true }),
+        jsonLimit = '10mb',
+        urlencodedLimit = '10mb',
+        cors = true,
+        staticDir = null,
+        auth: enableAuth = false,
+        health = true,
+        trustProxy = true,
+        routes = null,
+        routesDir = ['routes', 'src/routes']
+    } = options;
+
+    const app = express();
+
+    if (trustProxy) app.set('trust proxy', true);
+
+    // body 解析
+    app.use(express.json({ limit: jsonLimit }));
+    app.use(express.urlencoded({ extended: true, limit: urlencodedLimit }));
+
+    // 请求日志（含耗时/状态码/IP）
+    app.use((req, res, next) => {
+        const start = Date.now();
+        res.on('finish', () => {
+            const duration = Date.now() - start;
+            logger.info(`${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms ${req.ip || ''}`);
+        });
+        next();
+    });
+
+    // CORS
+    if (cors) app.use(createCors(cors));
+
+    // 统一响应格式 res.success / res.fail
+    app.use((req, res, next) => {
+        res.success = (data = null, message = 'ok') => {
+            res.json({ code: 0, message, data });
+        };
+        res.fail = (message = 'error', code = -1) => {
+            res.json({ code, message, data: null });
+        };
+        next();
+    });
+
+    // 静态资源
+    if (staticDir) {
+        const dirs = Array.isArray(staticDir) ? staticDir : [staticDir];
+        for (const dir of dirs) {
+            app.use(express.static(dir));
+        }
+    }
+
+    // 认证（true 用内置 auth；函数/数组用外部自定义中间件）
+    if (enableAuth) {
+        if (typeof enableAuth === 'function') {
+            app.use(enableAuth);
+        } else if (Array.isArray(enableAuth)) {
+            app.use(...enableAuth);
+        } else {
+            app.use(auth);
+        }
+    }
+
+    // 健康检查
+    if (health) {
+        app.get('/health', (req, res) => {
+            res.success({ status: 'ok', uptime: process.uptime() });
+        });
+    }
+
+    // 路由注册 + 404 + 错误处理
+    // 需在 routesDir 扫描加载（触发 route() 自动注册）之后执行，故封装为函数由 start() 调用
+    const setupRoutes = () => {
+        // 业务路由（routes 为函数时保留原逻辑：完全自控注册顺序）
+        if (typeof routes === 'function') {
+            routes(app);
+        }
+
+        // 路由配置：手动传入的 routes + route() 自动注册的路由
+        // 定义即自动注册，无需在 app.js 中重复传递
+        const allRoutes = [
+            ...(Array.isArray(routes) ? routes : []),
+            ...getRegisteredRoutes()
+        ];
+
+        // 静态路径优先注册，避免被动态参数路由（如 /:id）吞掉
+        allRoutes.sort((a, b) => {
+            const dynamic = (r) => (r.path || '').split('/').filter((s) => s.startsWith(':')).length;
+            return dynamic(a) - dynamic(b)
+        });
+
+        for (const route of allRoutes) {
+            const { method, path: routePath, handler } = route;
+            const fn = app[method?.toLowerCase()];
+            if (typeof fn === 'function' && routePath && handler) {
+                fn.call(app, routePath, handler);
+            }
+        }
+
+        // 404
+        app.use((req, res) => {
+            res.status(404).fail('Not Found', 404);
+        });
+
+        // 全局错误处理（express 5 自动捕获 async 异常）
+        app.use((err, req, res, next) => {
+            logger.error(`${req.method} ${req.originalUrl} - ${err?.stack || err?.message || err}`);
+            if (res.headersSent) return next(err)
+
+            const status = err?.status || err?.statusCode || 500;
+            res.status(status).fail(err?.message || 'Internal Server Error', status);
+        });
+    };
+
+    // 启动/停止控制
+    let server = null;
+
+    const start = async () => {
+        // 自动扫描加载路由文件（触发 route() 自动注册）
+        if (routesDir) await loadRouteFiles(routesDir, logger);
+
+        // 路由注册 + 404 + 错误处理（在扫描之后执行）
+        setupRoutes();
+
+        return new Promise((resolve, reject) => {
+            server = app.listen(port, host, () => {
+                logger.info(`Server listening on http://${host}:${port}`);
+                resolve(server);
+            });
+            server.on('error', (err) => {
+                logger.error(`Server error: ${err?.message}`);
+                reject(err);
+            });
+        })
+    };
+
+    const stop = () => {
+        return new Promise((resolve) => {
+            if (!server) return resolve()
+            server.close(() => resolve());
+        })
+    };
+
+    return {
+        app,
+        start,
+        stop,
+        getServer: () => server
+    }
+}
+
+function useHandler() {
+    let isCancelled = false;
+    let db = null;
+    const logger = createLogger({ name: 'worker' });
+
+    if (parentPort)
+        parentPort.once('message', (message) => {
+            if (message !== 'cancel') return
+
+            isCancelled = true;
+            if (parentPort) parentPort.postMessage('cancelled');
+            else process.exit(0);
+        });
+
+    const getIsCancelled = () => isCancelled;
+    const run = async (worker) => {
+        db = await database.init();
+        const result = await worker({ logger, redis, db });
+        if (parentPort) {
+            parentPort.postMessage({
+                type: 'done',
+                data: result
+            });
+        }
+        else process.exit(0);
+    };
+
+    return { run, getIsCancelled }
+}
 
-export { aes$1 as aes, auth, database, excelUtil as excel, mailUtil as mail, redis, scheduler, useDatabase, useHandler, weixinLogger_default as weixinLogger };
+export { aes, auth, createLogger, database, excelUtil as excel, hooks, mailUtil as mail, redis, route, scheduler, useHandler, useServer };
 //# sourceMappingURL=index.js.map