befly 3.8.29 → 3.8.31

package/types/befly.d.ts

@@ -5,6 +5,7 @@
 import type { Plugin } from './plugin.js';
 import type { ApiRoute, HttpMethod } from './api.js';
 import type { KeyValue } from './common.js';
+import type { LoggerConfig } from './logger.js';
 import type { Logger } from '../lib/logger.js';
 import type { Jwt } from '../lib/jwt.js';
 import type { Validator } from '../lib/validator.js';
@@ -14,21 +15,7 @@ import type { RedisHelper } from '../lib/redisHelper.js';
 import type { Cipher } from '../lib/cipher.js';
 import type { CacheHelper } from '../lib/cacheHelper.js';
 
-/**
- * 日志配置
- */
-export interface LoggerConfig {
-    /** 是否开启调试模式 (0: 关闭, 1: 开启) @default 1 */
-    debug?: number;
-    /** 日志排除字段 (逗号分隔) @default 'password,token,secret' */
-    excludeFields?: string;
-    /** 日志目录 @default './logs' */
-    dir?: string;
-    /** 是否输出到控制台 (0: 关闭, 1: 开启) @default 1 */
-    console?: number;
-    /** 单个日志文件最大大小 (字节) @default 10485760 (10MB) */
-    maxSize?: number;
-}
+export type { LoggerConfig };
 
 /**
  * 数据库配置
@@ -137,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,47 +1,11 @@
 /**
  * Befly 框架通用类型定义
+ * Core 专用类型，通用类型请直接从 befly-shared/types 导入
  */
 
-/**
- * 响应结果类型
- */
-export interface ResponseResult<T = any> {
-    code: number;
-    msg: string;
-    data?: T;
-    error?: any;
-}
-
-/**
- * 验证结果类型
- */
-export interface ValidationResult {
-    code: 0 | 1;
-    fields: Record<string, any>;
-}
-
-/**
- * 字段定义类型（对象格式）
- */
-export interface FieldDefinition {
-    name: string; // 字段标签/描述
-    detail: string; // 字段详细说明
-    type: 'string' | 'number' | 'text' | 'array_string' | 'array_text';
-    min: number | null; // 最小值/最小长度
-    max: number | null; // 最大值/最大长度
-    default: any; // 默认值
-    index: boolean; // 是否创建索引
-    unique: boolean; // 是否唯一
-    comment: string; // 字段注释
-    nullable: boolean; // 是否允许为空
-    unsigned: boolean; // 是否无符号（仅number类型）
-    regexp: string | null; // 正则验证
-}
-
-/**
- * 表定义类型（对象格式）
- */
-export type TableDefinition = Record<string, FieldDefinition>;
+// ============================================
+// Core 专用类型（不适合放在 shared 中的类型）
+// ============================================
 
 /**
  * 字段规则字符串（已废弃，保留用于兼容）
@@ -60,26 +24,15 @@ export type FieldRule = string;
  * @deprecated 请使用 FieldDefinition 对象格式
  */
 export interface ParsedFieldRule {
-    name: string; // 字段名称
+    name: string;
     type: 'string' | 'number' | 'text' | 'array_string' | 'array_text';
-    min: number | null; // 最小值
-    max: number | null; // 最大值
-    default: any; // 默认值
-    index: 0 | 1; // 是否索引
-    regex: string | null; // 正则约束
+    min: number | null;
+    max: number | null;
+    default: any;
+    index: 0 | 1;
+    regex: string | null;
 }
 
-/**
- * SQL 查询参数类型
- */
-export type SqlValue = string | number | boolean | null | Date;
-export type SqlParams = SqlValue[];
-
-/**
- * 排序方向
- */
-export type OrderDirection = 'ASC' | 'DESC' | 'asc' | 'desc';
-
 /**
  * 比较运算符
  */
@@ -90,44 +43,6 @@ export type ComparisonOperator = '=' | '>' | '<' | '>=' | '<=' | '!=' | '<>' | '
  */
 export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
 
-/**
- * 数据库配置类型
- */
-export interface DatabaseConfig {
-    host: string;
-    port: number;
-    user: string;
-    password: string;
-    database: string;
-    connectionLimit?: number;
-}
-
-/**
- * Redis 配置类型
- */
-export interface RedisConfig {
-    host: string;
-    port: number;
-    password?: string;
-    db?: number;
-}
-
-/**
- * 日志级别
- */
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-
-/**
- * 日志配置
- */
-export interface LoggerConfig {
-    level?: LogLevel;
-    transport?: {
-        target: string;
-        options?: Record<string, any>;
-    };
-}
-
 /**
  * 工具函数返回类型
  */
@@ -137,29 +52,6 @@ export interface ToolResponse<T = any> {
     error?: string;
 }
 
-/**
- * 分页参数
- */
-export interface PaginationParams {
-    page: number;
-    limit: number;
-}
-
-/**
- * 分页结果
- */
-export interface PaginatedResult<T = any> {
-    total: number;
-    page: number;
-    limit: number;
-    data: T[];
-}
-
-/**
- * 通用键值对
- */
-export type KeyValue<T = any> = Record<string, T>;
-
 /**
  * 可选字段
  */
@@ -170,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

@@ -2,13 +2,80 @@
  * 数据库相关类型定义
  */
 
-import type { SqlValue, WhereConditions } from './common';
+import type { SqlValue } from 'befly-shared/types';
+import type { WhereConditions } from './common';
+import type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, TypedWhereConditions } from './table';
 
 // 重新导出 WhereOperator 和 WhereConditions，供其他模块使用
 export type { WhereOperator, WhereConditions } from './index';
 
+// 重新导出表类型工具
+export type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, SystemFields, BaseTable, InsertType, UpdateType, SelectType, TypedWhereConditions } from './table';
+
+// ============================================
+// 泛型查询选项（类型安全版本）
+// ============================================
+
+/**
+ * 泛型查询选项 - 支持类型推断
+ * @template K - 表名类型
+ */
+export interface TypedQueryOptions<K extends TableName> {
+    /** 表名 */
+    table: K;
+    /** 查询字段（表字段的子集） */
+    fields?: (keyof TableType<K>)[] | string[];
+    /** WHERE 条件（类型安全） */
+    where?: TypedWhereConditions<TableType<K>> | WhereConditions;
+    /** 排序（格式：["字段#ASC", "字段#DESC"]） */
+    orderBy?: string[];
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    limit?: number;
+}
+
 /**
- * 查询选项
+ * 泛型插入选项 - 支持类型推断
+ * @template K - 表名类型
+ */
+export interface TypedInsertOptions<K extends TableName> {
+    /** 表名 */
+    table: K;
+    /** 插入数据（ID、时间戳、state 会自动生成） */
+    data: TableInsertType<K> | Record<string, any>;
+}
+
+/**
+ * 泛型更新选项 - 支持类型推断
+ * @template K - 表名类型
+ */
+export interface TypedUpdateOptions<K extends TableName> {
+    /** 表名 */
+    table: K;
+    /** 更新数据（updated_at 会自动更新） */
+    data: TableUpdateType<K> | Record<string, any>;
+    /** WHERE 条件 */
+    where: TypedWhereConditions<TableType<K>> | WhereConditions;
+}
+
+/**
+ * 泛型删除选项 - 支持类型推断
+ * @template K - 表名类型
+ */
+export interface TypedDeleteOptions<K extends TableName> {
+    /** 表名 */
+    table: K;
+    /** WHERE 条件 */
+    where: TypedWhereConditions<TableType<K>> | WhereConditions;
+}
+
+// ============================================
+// 兼容旧版查询选项（非类型安全版本）
+// ============================================
+
+/**
+ * 查询选项（兼容旧版，不进行类型检查）
  */
 export interface QueryOptions {
     /** 表名 */
@@ -26,7 +93,7 @@ export interface QueryOptions {
 }
 
 /**
- * 插入选项
+ * 插入选项（兼容旧版）
  */
 export interface InsertOptions {
     /** 表名 */
@@ -36,7 +103,7 @@ export interface InsertOptions {
 }
 
 /**
- * 更新选项
+ * 更新选项（兼容旧版）
  */
 export interface UpdateOptions {
     /** 表名 */
@@ -48,7 +115,7 @@ export interface UpdateOptions {
 }
 
 /**
- * 删除选项
+ * 删除选项（兼容旧版）
  */
 export interface DeleteOptions {
     /** 表名 */
@@ -147,17 +214,166 @@ export interface SyncStats {
 
 /**
  * DbHelper 接口（前向声明）
+ * 支持两种使用方式：
+ * 1. 类型安全模式：使用 TypedQueryOptions 等泛型接口，获得完整类型推断
+ * 2. 兼容模式：使用 QueryOptions 等非泛型接口，行为与之前一致
  */
 export interface DbHelper {
+    // ============================================
+    // 类型安全方法（推荐）
+    // ============================================
+
+    /**
+     * 查询记录数（类型安全版本）
+     * @template K - 表名类型
+     */
+    getCount<K extends TableName>(options: Omit<TypedQueryOptions<K>, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number>;
+
+    /**
+     * 查询单条数据（类型安全版本）
+     * @template K - 表名类型
+     * @returns 返回类型自动推断为对应表的记录类型
+     */
+    getOne<K extends TableName>(options: TypedQueryOptions<K>): Promise<TableType<K> | null>;
+
+    /**
+     * 查询列表（类型安全版本）
+     * @template K - 表名类型
+     * @returns 返回类型自动推断为对应表的记录列表
+     */
+    getList<K extends TableName>(options: TypedQueryOptions<K>): Promise<ListResult<TableType<K>>>;
+
+    /**
+     * 查询所有数据（类型安全版本）
+     * @template K - 表名类型
+     * @returns 返回类型自动推断为对应表的记录数组
+     */
+    getAll<K extends TableName>(options: Omit<TypedQueryOptions<K>, 'page' | 'limit'>): Promise<TableType<K>[]>;
+
+    /**
+     * 插入数据（类型安全版本）
+     * @template K - 表名类型
+     */
+    insData<K extends TableName>(options: TypedInsertOptions<K>): Promise<number>;
+
+    /**
+     * 更新数据（类型安全版本）
+     * @template K - 表名类型
+     */
+    updData<K extends TableName>(options: TypedUpdateOptions<K>): Promise<number>;
+
+    /**
+     * 删除数据（类型安全版本）
+     * @template K - 表名类型
+     */
+    delData<K extends TableName>(options: TypedDeleteOptions<K>): Promise<number>;
+
+    // ============================================
+    // 兼容旧版方法（手动指定返回类型）
+    // ============================================
+
+    /**
+     * 查询记录数（兼容版本）
+     */
     getCount(options: Omit<QueryOptions, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number>;
+
+    /**
+     * 查询单条数据（兼容版本，需手动指定泛型）
+     * @template T - 返回类型
+     */
     getOne<T = any>(options: QueryOptions): Promise<T | null>;
+
+    /**
+     * 查询列表（兼容版本，需手动指定泛型）
+     * @template T - 列表项类型
+     */
     getList<T = any>(options: QueryOptions): Promise<ListResult<T>>;
+
+    /**
+     * 查询所有数据（兼容版本，需手动指定泛型）
+     * @template T - 返回类型
+     */
     getAll<T = any>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<T[]>;
+
+    /**
+     * 插入数据（兼容版本）
+     */
     insData(options: InsertOptions): Promise<number>;
+
+    /**
+     * 更新数据（兼容版本）
+     */
     updData(options: UpdateOptions): Promise<number>;
+
+    /**
+     * 删除数据（兼容版本）
+     */
     delData(options: DeleteOptions): Promise<number>;
+
+    // ============================================
+    // 通用方法
+    // ============================================
+
+    /**
+     * 执行事务
+     * @template T - 事务返回类型
+     */
     trans<T = any>(callback: TransactionCallback<T>): Promise<T>;
+
+    /**
+     * 执行原始 SQL
+     */
     query(sql: string, params?: any[]): Promise<any>;
+
+    /**
+     * 检查数据是否存在
+     */
+    exists(options: Omit<QueryOptions, 'fields' | 'orderBy' | 'page' | 'limit'>): Promise<boolean>;
+
+    /**
+     * 检查表是否存在
+     */
+    tableExists(tableName: string): Promise<boolean>;
+
+    /**
+     * 批量插入数据
+     */
+    insBatch(table: string, dataList: Record<string, any>[]): Promise<number[]>;
+
+    /**
+     * 禁用数据（设置 state=2）
+     */
+    disableData(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+
+    /**
+     * 启用数据（设置 state=1）
+     */
+    enableData(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+
+    /**
+     * 硬删除数据（物理删除）
+     */
+    delForce(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+
+    /**
+     * 自增字段
+     */
+    increment(table: string, field: string, where: WhereConditions, value?: number): Promise<number>;
+
+    /**
+     * 自减字段
+     */
+    decrement(table: string, field: string, where: WhereConditions, value?: number): Promise<number>;
+
+    /**
+     * 查询单个字段值
+     */
+    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,18 +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 './tool.js';
+export * from './table.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[]>;
 }