befly 3.8.30 → 3.8.32

package/types/befly.d.ts

@@ -124,6 +124,13 @@ export interface BeflyOptions {
     disableHooks?: string[];
     /** 禁用的插件列表 */
     disablePlugins?: string[];
+    /** 隐藏的菜单路径列表（不同步到数据库） */
+    hiddenMenus?: string[];
+    /**
+     * Addon 运行时配置
+     * 按 addon 名称分组，如 addons.admin.email
+     */
+    addons?: Record<string, Record<string, any>>;
     /** 其他插件配置 */
     [key: string]: any;
 }

package/types/cache.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 缓存助手类型定义
+ */
+
+import type { BeflyContext } from './befly.js';
+
+/**
+ * 缓存助手类
+ * 负责在服务器启动时缓存接口、菜单和角色权限到 Redis
+ */
+export interface CacheHelper {
+    /**
+     * 缓存所有接口到 Redis
+     */
+    cacheApis(): Promise<void>;
+
+    /**
+     * 缓存所有菜单到 Redis（从数据库读取）
+     */
+    cacheMenus(): Promise<void>;
+
+    /**
+     * 缓存所有角色的接口权限到 Redis
+     * 优化：使用 Promise.all 利用 Bun Redis 自动 pipeline 特性
+     */
+    cacheRolePermissions(): Promise<void>;
+
+    /**
+     * 缓存所有数据（接口、菜单、角色权限）
+     */
+    cacheAll(): Promise<void>;
+
+    /**
+     * 获取缓存的所有接口
+     * @returns 接口列表
+     */
+    getApis(): Promise<any[]>;
+
+    /**
+     * 获取缓存的所有菜单
+     * @returns 菜单列表
+     */
+    getMenus(): Promise<any[]>;
+
+    /**
+     * 获取角色的接口权限
+     * @param roleCode - 角色代码
+     * @returns 接口路径列表
+     */
+    getRolePermissions(roleCode: string): Promise<string[]>;
+
+    /**
+     * 检查角色是否有指定接口权限
+     * @param roleCode - 角色代码
+     * @param apiPath - 接口路径（格式：METHOD/path）
+     * @returns 是否有权限
+     */
+    checkRolePermission(roleCode: string, apiPath: string): Promise<boolean>;
+
+    /**
+     * 删除角色的接口权限缓存
+     * @param roleCode - 角色代码
+     * @returns 是否删除成功
+     */
+    deleteRolePermissions(roleCode: string): Promise<boolean>;
+}
+
+/**
+ * CacheHelper 构造函数类型
+ */
+export interface CacheHelperConstructor {
+    new (befly: BeflyContext): CacheHelper;
+}

package/types/common.d.ts

@@ -1,10 +1,8 @@
 /**
  * Befly 框架通用类型定义
- * Core 专用类型，befly-shared 的类型请直接从 befly-shared 导入
+ * Core 专用类型，通用类型请直接从 befly-shared/types 导入
  */
 
-import type { SqlValue } from 'befly-shared/types';
-
 // ============================================
 // Core 专用类型（不适合放在 shared 中的类型）
 // ============================================
@@ -45,22 +43,6 @@ export type ComparisonOperator = '=' | '>' | '<' | '>=' | '<=' | '!=' | '<>' | '
  */
 export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
 
-/**
- * 日志级别
- */
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-
-/**
- * 日志配置
- */
-export interface LoggerConfig {
-    level?: LogLevel;
-    transport?: {
-        target: string;
-        options?: Record<string, any>;
-    };
-}
-
 /**
  * 工具函数返回类型
  */
@@ -70,14 +52,6 @@ export interface ToolResponse<T = any> {
     error?: string;
 }
 
-/**
- * 分页参数
- */
-export interface PaginationParams {
-    page: number;
-    limit: number;
-}
-
 /**
  * 可选字段
  */
@@ -88,16 +62,6 @@ export type Optional<T> = T | null | undefined;
  */
 export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
 
-/**
- * 保留字段（系统自动管理）
- */
-export type ReservedFields = 'id' | 'created_at' | 'updated_at' | 'deleted_at' | 'state';
-
-/**
- * 排除保留字段
- */
-export type ExcludeReserved<T> = Omit<T, ReservedFields>;
-
 /**
  * 数据库记录基础类型
  */

package/types/database.d.ts

@@ -369,6 +369,11 @@ export interface DbHelper {
      * 查询单个字段值
      */
     getFieldValue<T = any>(options: Omit<QueryOptions, 'fields'> & { field: string }): Promise<T | null>;
+
+    /**
+     * 清理数据或 where 条件（默认排除 null 和 undefined）
+     */
+    cleanFields<T extends Record<string, any>>(data: T, excludeValues?: any[], keepValues?: Record<string, any>): Partial<T>;
 }
 
 /**

package/types/index.ts

@@ -1,19 +1,19 @@
 /**
  * 类型定义导出
+ *
+ * 注意：通用类型已迁移到 befly-shared/types
+ * - addon, crypto, jwt, logger, tool 等类型请从 befly-shared/types 导入
  */
 
-export * from './addon.js';
 export * from './api.js';
 export * from './befly.js';
+export * from './cache.js';
 export * from './common.js';
 export * from './context.js';
-export * from './crypto.js';
 export * from './database.js';
-export * from './jwt.js';
-export * from './logger.js';
+export * from './hook.js';
 export * from './plugin.js';
 export * from './redis.js';
 export * from './table.js';
-export * from './tool.js';
 export * from './validator.js';
 export * from './sync.js';

package/types/plugin.d.ts

@@ -28,14 +28,11 @@ export interface Plugin {
     after?: string[];
 
     /** 插件初始化函数 */
-    handler?: (context: BeflyContext, config?: Record<string, any>) => any | Promise<any>;
+    handler?: (context: BeflyContext) => any | Promise<any>;
 
     /** @deprecated use handler instead */
     onInit?: PluginInitFunction;
 
-    /** 插件配置 */
-    config?: Record<string, any>;
-
     /** 插件描述 */
     description?: string;
 

package/types/redis.d.ts

@@ -23,14 +23,13 @@ export type RedisTTL = number | null;
  * Redis 助手接口
  */
 export interface RedisHelper {
+    // ==================== 基础操作 ====================
     /** 设置对象到 Redis */
     setObject<T = any>(key: string, obj: T, ttl?: RedisTTL): Promise<string | null>;
     /** 从 Redis 获取对象 */
     getObject<T = any>(key: string): Promise<T | null>;
     /** 从 Redis 删除对象 */
     delObject(key: string): Promise<void>;
-    /** 生成基于时间的唯一 ID */
-    genTimeID(): Promise<number>;
     /** 设置字符串值 */
     setString(key: string, value: string, ttl?: RedisTTL): Promise<string | null>;
     /** 获取字符串值 */
@@ -41,6 +40,42 @@ export interface RedisHelper {
     expire(key: string, seconds: number): Promise<number>;
     /** 获取剩余过期时间 */
     ttl(key: string): Promise<number>;
+    /** 删除键 */
+    del(key: string): Promise<number>;
     /** 测试 Redis 连接 */
     ping(): Promise<string>;
+
+    // ==================== ID 生成 ====================
+    /** 生成基于时间的唯一 ID (14位纯数字) */
+    genTimeID(): Promise<number>;
+    /** 批量生成基于时间的唯一 ID */
+    genTimeIDBatch(count: number): Promise<number[]>;
+
+    // ==================== Set 操作 ====================
+    /** 向 Set 中添加一个或多个成员 */
+    sadd(key: string, members: string[]): Promise<number>;
+    /** 判断成员是否在 Set 中 */
+    sismember(key: string, member: string): Promise<number>;
+    /** 获取 Set 的成员数量 */
+    scard(key: string): Promise<number>;
+    /** 获取 Set 的所有成员 */
+    smembers(key: string): Promise<string[]>;
+
+    // ==================== 批量操作 ====================
+    /** 批量设置对象 */
+    setBatch<T = any>(items: Array<{ key: string; value: T; ttl?: number | null }>): Promise<number>;
+    /** 批量获取对象 */
+    getBatch<T = any>(keys: string[]): Promise<Array<T | null>>;
+    /** 批量删除键 */
+    delBatch(keys: string[]): Promise<number>;
+    /** 批量检查键是否存在 */
+    existsBatch(keys: string[]): Promise<boolean[]>;
+    /** 批量设置过期时间 */
+    expireBatch(items: Array<{ key: string; seconds: number }>): Promise<number>;
+    /** 批量获取剩余过期时间 */
+    ttlBatch(keys: string[]): Promise<number[]>;
+    /** 批量向多个 Set 添加成员 */
+    saddBatch(items: Array<{ key: string; members: string[] }>): Promise<number>;
+    /** 批量检查成员是否在 Set 中 */
+    sismemberBatch(items: Array<{ key: string; member: string }>): Promise<boolean[]>;
 }

package/types/table.d.ts

@@ -1,50 +1,11 @@
 /**
  * 表类型定义 - 用于增强 DbHelper 泛型推断
+ *
+ * 基础类型（SystemFields, BaseTable, InsertType, UpdateType, SelectType）
+ * 请直接从 befly-shared/types 导入
  */
 
-// ============================================
-// 基础表类型
-// ============================================
-
-/**
- * 系统字段（所有表都有的字段）
- */
-export interface SystemFields {
-    /** 主键 ID（雪花 ID） */
-    id: number;
-    /** 状态：0=已删除, 1=正常, 2=禁用 */
-    state: number;
-    /** 创建时间（毫秒时间戳） */
-    createdAt: number;
-    /** 更新时间（毫秒时间戳） */
-    updatedAt: number;
-    /** 删除时间（毫秒时间戳，软删除时设置） */
-    deletedAt: number | null;
-}
-
-/**
- * 基础表类型（包含系统字段）
- */
-export type BaseTable<T extends Record<string, any>> = T & SystemFields;
-
-// ============================================
-// 表操作类型工具
-// ============================================
-
-/**
- * 插入类型：排除系统自动生成的字段
- */
-export type InsertType<T> = Omit<T, keyof SystemFields>;
-
-/**
- * 更新类型：所有字段可选，排除不可修改的系统字段
- */
-export type UpdateType<T> = Partial<Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'deletedAt'>>;
-
-/**
- * 查询结果类型：完整的表记录
- */
-export type SelectType<T> = T;
+import type { BaseTable, InsertType, UpdateType } from 'befly-shared/types';
 
 // ============================================
 // 数据库表映射接口
@@ -205,7 +166,8 @@ export type TypedWhereConditions<T> = Partial<T> & // 精确匹配
     ArrayConditions<T> & // 数组操作符
     StringConditions<T> & // 字符串操作符
     RangeConditions<T> & // 范围操作符
-    NullConditions<T> & { // 空值操作符
+    NullConditions<T> & {
+        // 空值操作符
         /** OR 条件组 */
         $or?: TypedWhereConditions<T>[];
         /** AND 条件组 */

package/util.ts

@@ -0,0 +1,283 @@
+/**
+ * 核心工具函数
+ */
+
+// 内部依赖
+import { existsSync } from 'node:fs';
+
+/**
+ * 进程角色信息
+ */
+export interface ProcessRole {
+    /** 进程角色：primary（主进程）或 worker（工作进程） */
+    role: 'primary' | 'worker';
+    /** 实例 ID（PM2 或 Bun Worker） */
+    instanceId: string | null;
+    /** 运行环境：bun-cluster、pm2-cluster 或 standalone */
+    env: 'bun-cluster' | 'pm2-cluster' | 'standalone';
+}
+
+/**
+ * 获取当前进程角色信息
+ * @returns 进程角色、实例 ID 和运行环境
+ */
+export function getProcessRole(): ProcessRole {
+    const bunWorkerId = process.env.BUN_WORKER_ID;
+    const pm2InstanceId = process.env.PM2_INSTANCE_ID;
+
+    // Bun 集群模式
+    if (bunWorkerId !== undefined) {
+        return {
+            role: bunWorkerId === '' ? 'primary' : 'worker',
+            instanceId: bunWorkerId || '0',
+            env: 'bun-cluster'
+        };
+    }
+
+    // PM2 集群模式
+    if (pm2InstanceId !== undefined) {
+        return {
+            role: pm2InstanceId === '0' ? 'primary' : 'worker',
+            instanceId: pm2InstanceId,
+            env: 'pm2-cluster'
+        };
+    }
+
+    // 单进程模式
+    return {
+        role: 'primary',
+        instanceId: null,
+        env: 'standalone'
+    };
+}
+
+/**
+ * 检测当前进程是否为主进程
+ * 用于集群模式下避免重复执行同步任务
+ * - Bun 集群：BUN_WORKER_ID 为空时是主进程
+ * - PM2 集群：PM2_INSTANCE_ID 为 '0' 或不存在时是主进程
+ * @returns 是否为主进程
+ */
+export function isPrimaryProcess(): boolean {
+    return getProcessRole().role === 'primary';
+}
+
+// 外部依赖
+import { camelCase } from 'es-toolkit/string';
+import { scanFiles } from 'befly-shared/scanFiles';
+
+// 相对导入
+import { Logger } from './lib/logger.js';
+
+// 类型导入
+import type { Plugin } from './types/plugin.js';
+import type { Hook } from './types/hook.js';
+import type { CorsConfig, BeflyContext } from './types/befly.js';
+import type { RequestContext } from './types/context.js';
+import type { PluginRequestHook, Next } from './types/plugin.js';
+
+/**
+ * 创建错误响应（专用于 Hook 中间件）
+ * 在钩子中提前拦截请求时使用
+ * @param ctx - 请求上下文
+ * @param msg - 错误消息
+ * @param code - 错误码，默认 1
+ * @param data - 附加数据，默认 null
+ * @param detail - 详细信息，用于标记具体提示位置，默认 null
+ * @returns Response 对象
+ */
+export function ErrorResponse(ctx: RequestContext, msg: string, code: number = 1, data: any = null, detail: any = null): Response {
+    // 记录拦截日志
+    if (ctx.requestId) {
+        const duration = Date.now() - ctx.now;
+        const user = ctx.user?.id ? `[User:${ctx.user.id}]` : '[Guest]';
+        Logger.info(`[${ctx.requestId}] ${ctx.route} ${user} ${duration}ms [${msg}]`);
+    }
+
+    return Response.json(
+        {
+            code: code,
+            msg: msg,
+            data: data,
+            detail: detail
+        },
+        {
+            headers: ctx.corsHeaders
+        }
+    );
+}
+
+/**
+ * 创建最终响应（专用于 API 路由结尾）
+ * 自动处理 ctx.response/ctx.result，并记录请求日志
+ * @param ctx - 请求上下文
+ * @returns Response 对象
+ */
+export function FinalResponse(ctx: RequestContext): Response {
+    // 记录请求日志
+    if (ctx.api && ctx.requestId) {
+        const duration = Date.now() - ctx.now;
+        const user = ctx.user?.id ? `[User:${ctx.user.id}]` : '[Guest]';
+        Logger.info(`[${ctx.requestId}] ${ctx.route} ${user} ${duration}ms`);
+    }
+
+    // 1. 如果已经有 response，直接返回
+    if (ctx.response) {
+        return ctx.response;
+    }
+
+    // 2. 如果有 result，格式化为响应
+    if (ctx.result !== undefined) {
+        let result = ctx.result;
+
+        // 如果是字符串，自动包裹为成功响应
+        if (typeof result === 'string') {
+            result = {
+                code: 0,
+                msg: result
+            };
+        }
+        // 如果是对象，自动补充 code: 0
+        else if (result && typeof result === 'object') {
+            if (!('code' in result)) {
+                result = {
+                    code: 0,
+                    ...result
+                };
+            }
+        }
+
+        // 处理 BigInt 序列化问题
+        if (result && typeof result === 'object') {
+            const jsonString = JSON.stringify(result, (key, value) => (typeof value === 'bigint' ? value.toString() : value));
+            return new Response(jsonString, {
+                headers: {
+                    ...ctx.corsHeaders,
+                    'Content-Type': 'application/json'
+                }
+            });
+        } else {
+            return Response.json(result, {
+                headers: ctx.corsHeaders
+            });
+        }
+    }
+
+    // 3. 默认响应：没有生成响应
+    return Response.json(
+        {
+            code: 1,
+            msg: '未生成响应'
+        },
+        {
+            headers: ctx.corsHeaders
+        }
+    );
+}
+
+/**
+ * 设置 CORS 响应头
+ * @param req - 请求对象
+ * @param config - CORS 配置（可选）
+ * @returns CORS 响应头对象
+ */
+export function setCorsOptions(req: Request, config: CorsConfig = {}): Record<string, string> {
+    const origin = config.origin || '*';
+    return {
+        'Access-Control-Allow-Origin': origin === '*' ? req.headers.get('origin') || '*' : origin,
+        'Access-Control-Allow-Methods': config.methods || 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': config.allowedHeaders || 'Content-Type, Authorization, authorization, token',
+        'Access-Control-Expose-Headers': config.exposedHeaders || 'Content-Range, X-Content-Range, Authorization, authorization, token',
+        'Access-Control-Max-Age': String(config.maxAge || 86400),
+        'Access-Control-Allow-Credentials': config.credentials || 'true'
+    };
+}
+
+/**
+ * 扫描模块（插件或钩子）
+ * @param dir - 目录路径
+ * @param type - 模块类型（core/addon/app）
+ * @param moduleLabel - 模块标签（如"插件"、"钩子"）
+ * @param addonName - 组件名称（仅 type='addon' 时需要）
+ * @returns 模块列表
+ */
+export async function scanModules<T extends Plugin | Hook>(dir: string, type: 'core' | 'addon' | 'app', moduleLabel: string, addonName?: string): Promise<T[]> {
+    if (!existsSync(dir)) return [];
+
+    const items: T[] = [];
+    const files = await scanFiles(dir, '*.{ts,js}');
+
+    for (const { filePath, fileName } of files) {
+        // 生成模块名称
+        const name = camelCase(fileName);
+        const moduleName = type === 'core' ? name : type === 'addon' ? `addon_${camelCase(addonName!)}_${name}` : `app_${name}`;
+
+        try {
+            const normalizedFilePath = filePath.replace(/\\/g, '/');
+            const moduleImport = await import(normalizedFilePath);
+            const item = moduleImport.default;
+
+            item.name = moduleName;
+            // 为 addon 模块记录 addon 名称
+            if (type === 'addon' && addonName) {
+                item.addonName = addonName;
+            }
+            items.push(item);
+        } catch (err: any) {
+            const typeLabel = type === 'core' ? '核心' : type === 'addon' ? `组件${addonName}` : '项目';
+            Logger.error({ err: err, module: fileName }, `${typeLabel}${moduleLabel} 导入失败`);
+            process.exit(1);
+        }
+    }
+
+    return items;
+}
+
+/**
+ * 排序模块（根据依赖关系）
+ * @param modules - 待排序的模块列表
+ * @returns 排序后的模块列表，如果存在循环依赖或依赖不存在则返回 false
+ */
+export function sortModules<T extends { name?: string; after?: string[] }>(modules: T[]): T[] | false {
+    const result: T[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+    const moduleMap: Record<string, T> = Object.fromEntries(modules.map((m) => [m.name!, m]));
+    let isPass = true;
+
+    // 检查依赖是否存在
+    for (const module of modules) {
+        if (module.after) {
+            for (const dep of module.after) {
+                if (!moduleMap[dep]) {
+                    Logger.error({ module: module.name, dependency: dep }, '依赖的模块未找到');
+                    isPass = false;
+                }
+            }
+        }
+    }
+
+    if (!isPass) return false;
+
+    const visit = (name: string): void => {
+        if (visited.has(name)) return;
+        if (visiting.has(name)) {
+            Logger.error({ module: name }, '模块循环依赖');
+            isPass = false;
+            return;
+        }
+
+        const module = moduleMap[name];
+        if (!module) return;
+
+        visiting.add(name);
+        (module.after || []).forEach(visit);
+        visiting.delete(name);
+        visited.add(name);
+        result.push(module);
+    };
+
+    modules.forEach((m) => visit(m.name!));
+
+    return isPass ? result : false;
+}