befly 3.9.39 → 3.10.0

package/tests/syncTable-schema.test.ts

@@ -0,0 +1,99 @@
+/**
+ * syncTable 表结构查询模块测试（纯 mock，不连接真实数据库）
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { syncTable } from "../sync/syncTable.js";
+import { createMockSqliteDb } from "./_mocks/mockSqliteDb.js";
+
+describe("tableExistsRuntime", () => {
+    test("sql 执行器未初始化时抛出错误", async () => {
+        try {
+            await syncTable.TestKit.tableExistsRuntime(syncTable.TestKit.createRuntime("sqlite", null as any, ""), "user");
+            expect(true).toBe(false);
+        } catch (error: any) {
+            expect(error.message).toBe("SQL 执行器未初始化");
+        }
+    });
+
+    test("mock sqlite：表存在返回 true；表不存在返回 false", async () => {
+        const db = createMockSqliteDb({
+            executedSql: [],
+            tables: {
+                test_sync_table_exists: {
+                    columns: {},
+                    indexes: {}
+                }
+            }
+        });
+
+        const runtime = syncTable.TestKit.createRuntime("sqlite", db as any, "");
+        const exist = await syncTable.TestKit.tableExistsRuntime(runtime, "test_sync_table_exists");
+        expect(exist).toBe(true);
+
+        const notExist = await syncTable.TestKit.tableExistsRuntime(runtime, "test_sync_table_not_exist_12345");
+        expect(notExist).toBe(false);
+    });
+});
+
+describe("getTableColumnsRuntime", () => {
+    test("mock sqlite：返回列信息结构（至少包含我们定义的列）", async () => {
+        const db = createMockSqliteDb({
+            executedSql: [],
+            tables: {
+                test_sync_table_columns: {
+                    columns: {
+                        id: { name: "id", type: "INTEGER", notnull: 1, dflt_value: null },
+                        user_name: { name: "user_name", type: "TEXT", notnull: 1, dflt_value: "''" },
+                        user_id: { name: "user_id", type: "INTEGER", notnull: 1, dflt_value: "0" },
+                        age: { name: "age", type: "INTEGER", notnull: 0, dflt_value: "0" },
+                        created_at: { name: "created_at", type: "INTEGER", notnull: 1, dflt_value: "0" }
+                    },
+                    indexes: {}
+                }
+            }
+        });
+
+        const runtime = syncTable.TestKit.createRuntime("sqlite", db as any, "");
+        const columns = await syncTable.TestKit.getTableColumnsRuntime(runtime, "test_sync_table_columns");
+
+        expect(columns.id).toBeDefined();
+        expect(columns.user_name).toBeDefined();
+        expect(columns.user_id).toBeDefined();
+        expect(columns.age).toBeDefined();
+        expect(columns.created_at).toBeDefined();
+
+        expect(columns.user_name.nullable).toBe(false);
+    });
+});
+
+describe("getTableIndexesRuntime", () => {
+    test("mock sqlite：返回索引信息结构（仅单列索引；复合索引会被忽略）", async () => {
+        const db = createMockSqliteDb({
+            executedSql: [],
+            tables: {
+                test_sync_table_indexes: {
+                    columns: {},
+                    indexes: {
+                        idx_created_at: ["created_at"],
+                        idx_user_name: ["user_name"],
+                        idx_composite: ["user_id", "created_at"]
+                    }
+                }
+            }
+        });
+
+        const runtime = syncTable.TestKit.createRuntime("sqlite", db as any, "");
+        const indexes = await syncTable.TestKit.getTableIndexesRuntime(runtime, "test_sync_table_indexes");
+
+        expect(indexes.idx_created_at).toBeDefined();
+        expect(indexes.idx_created_at).toContain("created_at");
+
+        expect(indexes.idx_user_name).toBeDefined();
+        expect(indexes.idx_user_name).toContain("user_name");
+
+        // sqlite 路径下为了避免多列索引误判，仅收集单列索引
+        expect(indexes.idx_composite).toBeUndefined();
+    });
+});

package/tests/syncTable-testkit.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "bun:test";
+
+import { syncTable } from "../sync/syncTable.js";
+
+describe("syncTable - TestKit 挂载", () => {
+    it("should expose TestKit as a stable object", () => {
+        expect(typeof syncTable).toBe("function");
+        expect(syncTable.TestKit).toBeDefined();
+
+        const descriptor = Object.getOwnPropertyDescriptor(syncTable, "TestKit");
+        expect(descriptor).toBeDefined();
+        expect(descriptor?.writable).toBe(false);
+        expect(descriptor?.configurable).toBe(false);
+        expect(descriptor?.enumerable).toBe(true);
+
+        expect(typeof syncTable.TestKit.quoteIdentifier).toBe("function");
+        expect(typeof syncTable.TestKit.getTypeMapping).toBe("function");
+
+        expect(syncTable.TestKit.DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR).toBe(8);
+
+        const firstRef = syncTable.TestKit;
+        const secondRef = syncTable.TestKit;
+        expect(firstRef).toBe(secondRef);
+    });
+});

package/tests/syncTable-types.test.ts

@@ -0,0 +1,122 @@
+/**
+ * syncTable 类型处理模块测试
+ *
+ * 测试 types.ts 中的函数：
+ * - isStringOrArrayType
+ * - getSqlType
+ * - resolveDefaultValue
+ * - generateDefaultSql
+ */
+
+import { describe, test, expect } from "bun:test";
+
+import { syncTable } from "../sync/syncTable.js";
+
+describe("isStringOrArrayType", () => {
+    test("string 类型返回 true", () => {
+        expect(syncTable.TestKit.isStringOrArrayType("string")).toBe(true);
+    });
+
+    test("array_string 类型返回 true", () => {
+        expect(syncTable.TestKit.isStringOrArrayType("array_string")).toBe(true);
+    });
+
+    test("number 类型返回 false", () => {
+        expect(syncTable.TestKit.isStringOrArrayType("number")).toBe(false);
+    });
+
+    test("text 类型返回 false", () => {
+        expect(syncTable.TestKit.isStringOrArrayType("text")).toBe(false);
+    });
+
+    test("array_text 类型返回 false", () => {
+        expect(syncTable.TestKit.isStringOrArrayType("array_text")).toBe(false);
+    });
+});
+
+describe("resolveDefaultValue", () => {
+    test("null 值 + string 类型 => 空字符串", () => {
+        expect(syncTable.TestKit.resolveDefaultValue(null, "string")).toBe("");
+    });
+
+    test("null 值 + number 类型 => 0", () => {
+        expect(syncTable.TestKit.resolveDefaultValue(null, "number")).toBe(0);
+    });
+
+    test('"null" 字符串 + number 类型 => 0', () => {
+        expect(syncTable.TestKit.resolveDefaultValue("null", "number")).toBe(0);
+    });
+
+    test('null 值 + array_string 类型 => "[]"', () => {
+        expect(syncTable.TestKit.resolveDefaultValue(null, "array_string")).toBe("[]");
+    });
+
+    test('null 值 + text 类型 => "null"', () => {
+        expect(syncTable.TestKit.resolveDefaultValue(null, "text")).toBe("null");
+    });
+
+    test('null 值 + array_text 类型 => "null"（TEXT 不支持默认值）', () => {
+        expect(syncTable.TestKit.resolveDefaultValue(null, "array_text")).toBe("null");
+    });
+
+    test("有实际值时直接返回", () => {
+        expect(syncTable.TestKit.resolveDefaultValue("admin", "string")).toBe("admin");
+        expect(syncTable.TestKit.resolveDefaultValue(100, "number")).toBe(100);
+        expect(syncTable.TestKit.resolveDefaultValue(0, "number")).toBe(0);
+    });
+});
+
+describe("generateDefaultSql", () => {
+    test("number 类型生成数字默认值", () => {
+        expect(syncTable.TestKit.generateDefaultSql(0, "number")).toBe(" DEFAULT 0");
+        expect(syncTable.TestKit.generateDefaultSql(100, "number")).toBe(" DEFAULT 100");
+    });
+
+    test("string 类型生成带引号默认值", () => {
+        expect(syncTable.TestKit.generateDefaultSql("admin", "string")).toBe(" DEFAULT 'admin'");
+        expect(syncTable.TestKit.generateDefaultSql("", "string")).toBe(" DEFAULT ''");
+    });
+
+    test("text 类型不生成默认值", () => {
+        expect(syncTable.TestKit.generateDefaultSql("null", "text")).toBe("");
+    });
+
+    test("array_string 类型生成 JSON 数组默认值", () => {
+        expect(syncTable.TestKit.generateDefaultSql("[]", "array_string")).toBe(" DEFAULT '[]'");
+    });
+
+    test("array_text 类型不生成默认值（MySQL TEXT 不支持）", () => {
+        expect(syncTable.TestKit.generateDefaultSql("[]", "array_text")).toBe("");
+    });
+
+    test("单引号被正确转义", () => {
+        expect(syncTable.TestKit.generateDefaultSql("it's", "string")).toBe(" DEFAULT 'it''s'");
+    });
+});
+
+describe("getSqlType", () => {
+    test("string 类型带长度", () => {
+        const result = syncTable.TestKit.getSqlType("mysql", "string", 100);
+        expect(result).toBe("VARCHAR(100)");
+    });
+
+    test("array_string 类型带长度", () => {
+        const result = syncTable.TestKit.getSqlType("mysql", "array_string", 500);
+        expect(result).toBe("VARCHAR(500)");
+    });
+
+    test("number 类型无符号", () => {
+        const result = syncTable.TestKit.getSqlType("mysql", "number", null, true);
+        expect(result).toBe("BIGINT UNSIGNED");
+    });
+
+    test("number 类型有符号", () => {
+        const result = syncTable.TestKit.getSqlType("mysql", "number", null, false);
+        expect(result).toBe("BIGINT");
+    });
+
+    test("text 类型", () => {
+        const result = syncTable.TestKit.getSqlType("mysql", "text", null);
+        expect(result).toBe("MEDIUMTEXT");
+    });
+});

package/tests/tableRef-and-deserialize.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, mock } from "bun:test";
+
+import { MySqlDialect } from "../lib/dbDialect.js";
+import { DbHelper } from "../lib/dbHelper.js";
+import { DbUtils } from "../lib/dbUtils.js";
+import { SqlBuilder } from "../lib/sqlBuilder.js";
+
+describe("tableRef normalize + escape", () => {
+    it("DbUtils.normalizeTableRef: 保留 alias，仅 snakeCase 表名", () => {
+        expect(DbUtils.normalizeTableRef("UserProfile up")).toBe("user_profile up");
+        expect(DbUtils.normalizeTableRef("order o")).toBe("order o");
+    });
+
+    it("SqlBuilder.from: 支持 table alias", () => {
+        const sql = new SqlBuilder().select(["*"]).from("order o").toSelectSql().sql;
+        expect(sql).toContain("FROM `order` o");
+    });
+
+    it("SqlBuilder.from: 支持 schema.table alias", () => {
+        const sql = new SqlBuilder().select(["*"]).from("my_db.users u").toSelectSql().sql;
+        expect(sql).toContain("FROM `my_db`.`users` u");
+    });
+
+    it("SqlBuilder.from: 复杂表引用要求显式 fromRaw", () => {
+        expect(() => new SqlBuilder().select(["*"]).from("users u FORCE INDEX (idx_user)")).toThrow();
+    });
+});
+
+describe("DbHelper.getList deserialize", () => {
+    it("getList: 数组字段应被 DbUtils.deserializeArrayFields 反序列化", async () => {
+        const sqlMock = {
+            unsafe: mock(async (sql: string, _params?: any[]) => {
+                if (sql.includes("COUNT(*) as total")) {
+                    return [{ total: 1 }];
+                }
+                return [
+                    {
+                        id: "1",
+                        tags: '["a","b"]',
+                        state: 1,
+                        created_at: 0,
+                        updated_at: 0
+                    }
+                ];
+            })
+        };
+
+        const redisMock = {
+            getObject: mock(async () => null),
+            setObject: mock(async () => "OK"),
+            genTimeID: mock(async () => 1)
+        };
+
+        const dbHelper = new DbHelper({ redis: redisMock as any, sql: sqlMock as any, dialect: new MySqlDialect() });
+
+        const result = await dbHelper.getList<{ id: number; tags: string[] }>({
+            table: "users",
+            fields: ["id", "tags"],
+            where: {}
+        });
+
+        expect(result.total).toBe(1);
+        expect(result.lists.length).toBe(1);
+        expect(Array.isArray(result.lists[0].tags)).toBe(true);
+        expect(result.lists[0].tags).toEqual(["a", "b"]);
+    });
+});

package/tsconfig.json

@@ -50,5 +50,5 @@
         }
     },
     "include": ["**/*.ts"],
-    "exclude": ["node_modules", "dist", "logs", "temp", "tests", "main.single.ts"]
+    "exclude": ["node_modules", "dist", "logs", "temp", "tests"]
 }

package/types/api.d.ts

@@ -11,7 +11,7 @@ import type { TableDefinition } from "./validate.js";
  * HTTP 方法类型
  * 支持 GET、POST 或逗号分隔的组合
  */
-export type HttpMethod = "GET" | "POST" | "GET,POST" | "POST,GET";
+export type HttpMethod = "GET" | "POST" | "GET,POST";
 
 /**
  * 用户信息类型

package/types/befly.d.ts

@@ -93,8 +93,8 @@ export interface CorsConfig {
 export interface RateLimitRule {
     /**
      * 路由匹配串
-     * - 精确："POST/api/auth/login"
-     * - 前缀："POST/api/auth/*" 或 "/api/auth/*"
+    * - 精确："/api/auth/login"
+    * - 前缀："/api/auth/*"
      * - 全量："*"
      */
     route: string;
@@ -117,8 +117,8 @@ export interface RateLimitConfig {
     key?: "ip" | "user" | "ip_user";
     /**
      * 直接跳过限流的路由列表（优先级最高）
-     * - 精确："POST/api/health" 或 "/api/health"
-     * - 前缀："POST/api/health/*" 或 "/api/health/*"
+     * - 精确："/api/health"
+     * - 前缀："/api/health/*"
      */
     skipRoutes?: string[];
     /** 路由规则列表 */
@@ -165,14 +165,15 @@ export interface BeflyOptions {
     disableHooks?: string[];
     /** 禁用的插件列表 */
     disablePlugins?: string[];
-
-    /** 是否启用组件钩子扫描（默认 false，仅加载 core hooks） */
-    enableAddonHooks?: boolean;
-
-    /** 是否启用项目钩子扫描（默认 false，仅加载 core hooks） */
-    enableAppHooks?: boolean;
-    /** 隐藏的菜单路径列表（不同步到数据库） */
-    hiddenMenus?: string[];
+    /**
+        * 禁用的菜单 path 规则（用于菜单同步与加载前过滤）
+        *
+        * 仅支持 Bun.Glob 的 glob pattern 语法与 API（即把每条规则当作 glob 模式匹配菜单 path）。
+        * 示例：
+        * - 精确："/addon/admin/login"
+        * - 通配："/addon/admin/log/*"、"/addon/admin/**"、"**\/login"
+     */
+    disableMenus?: string[];
     /**
      * Addon 运行时配置
      * 按 addon 名称分组，如 addons.admin.email

package/types/cache.d.ts

@@ -27,7 +27,7 @@ export interface CacheHelper {
     /**
      * 增量刷新单个角色的接口权限缓存
      */
-    refreshRoleApiPermissions(roleCode: string, apiIds: number[]): Promise<void>;
+    refreshRoleApiPermissions(roleCode: string, apiPaths: string[]): Promise<void>;
 
     /**
      * 缓存所有数据（接口、菜单、角色权限）
@@ -56,7 +56,7 @@ export interface CacheHelper {
     /**
      * 检查角色是否有指定接口权限
      * @param roleCode - 角色代码
-     * @param apiPath - 接口路径（格式：METHOD/path）
+        * @param apiPath - 接口路径（url.pathname，例如 /api/user/login；与 method 无关）
      * @returns 是否有权限
      */
     checkRolePermission(roleCode: string, apiPath: string): Promise<boolean>;

package/types/context.d.ts

@@ -22,7 +22,7 @@ export interface RequestContext {
     ip: string;
     /** 请求头 */
     headers: Headers;
-    /** API 路由路径（如 POST/api/user/login） */
+    /** API 路由路径（url.pathname，例如 /api/user/login；与 method 无关） */
     route: string;
     /** 请求唯一 ID */
     requestId: string;

package/types/database.d.ts

@@ -400,11 +400,6 @@ 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/hook.d.ts

@@ -18,17 +18,8 @@ export interface Hook {
     name?: string;
 
     /** 依赖的钩子列表（在这些钩子之后执行） */
-    after?: string[];
-
-    /** 执行顺序（数字越小越先执行） */
-    order?: number;
+    deps: string[];
 
     /** 钩子处理函数 */
     handler: HookHandler;
-
-    /** 钩子配置 */
-    config?: Record<string, any>;
-
-    /** 钩子描述 */
-    description?: string;
 }

package/types/plugin.d.ts

@@ -3,22 +3,6 @@
  */
 
 import type { BeflyContext } from "./befly.js";
-import type { RequestContext } from "./context.js";
-
-/**
- * 插件初始化函数类型
- */
-export type PluginInitFunction = (befly: BeflyContext) => Promise<any> | any;
-
-/**
- * 插件请求处理钩子函数类型
- */
-export type Next = () => Promise<void>;
-
-/**
- * 插件请求钩子类型
- */
-export type PluginRequestHook = (ctx: RequestContext, next: Next) => Promise<void> | void;
 
 /**
  * 插件配置类型
@@ -26,88 +10,10 @@ export type PluginRequestHook = (ctx: RequestContext, next: Next) => Promise<voi
 export interface Plugin {
     /** 插件名称（运行时动态添加，由文件名生成） */
     name?: string;
-    /** @deprecated use name instead */
-    pluginName?: string;
 
     /** 依赖的插件列表（在这些插件之后执行） */
-    after?: string[];
+    deps: string[];
 
     /** 插件初始化函数 */
-    handler?: (context: BeflyContext) => any | Promise<any>;
-
-    /** @deprecated use handler instead */
-    onInit?: PluginInitFunction;
-
-    /** 插件描述 */
-    description?: string;
-
-    /** 插件版本 */
-    version?: string;
-
-    /** 插件作者 */
-    author?: string;
-}
-
-/**
- * 插件导出格式
- */
-export interface PluginExport {
-    default: Plugin;
-}
-
-/**
- * 插件加载选项
- */
-export interface PluginLoadOptions {
-    /** 插件目录路径 */
-    pluginDir: string;
-
-    /** 是否跳过错误 */
-    skipErrors?: boolean;
-
-    /** 插件过滤函数 */
-    filter?: (filename: string) => boolean;
-}
-
-/**
- * 插件执行上下文
- */
-export interface PluginContext {
-    /** 插件名称 */
-    name: string;
-
-    /** 执行开始时间 */
-    startTime: number;
-
-    /** 执行结束时间 */
-    endTime?: number;
-
-    /** 执行状态 */
-    status: "pending" | "running" | "success" | "error";
-
-    /** 错误信息 */
-    error?: Error;
-}
-
-/**
- * 插件管理器接口
- */
-export interface PluginManager {
-    /** 已加载的插件列表 */
-    plugins: Plugin[];
-
-    /** 注册插件 */
-    register(plugin: Plugin): void;
-
-    /** 加载插件目录 */
-    loadPlugins(options: PluginLoadOptions): Promise<void>;
-
-    /** 执行所有插件 */
-    executeAll(befly: BeflyContext): Promise<void>;
-
-    /** 获取插件 */
-    getPlugin(name: string): Plugin | undefined;
-
-    /** 移除插件 */
-    removePlugin(name: string): boolean;
+    handler: (context: BeflyContext) => any | Promise<any>;
 }

package/types/sync.d.ts

@@ -5,30 +5,10 @@
 
 // ==================== 命令选项类型 ====================
 
-/**
- * SyncDb 命令选项
- */
-export interface SyncDbOptions {
-    table?: string;
-    dryRun?: boolean;
-    force?: boolean;
-}
-
-/**
- * Sync 命令选项
- */
-export interface SyncOptions {
-    table?: string;
-    force?: boolean;
-    dryRun?: boolean;
-    drop?: boolean;
-}
-
 /**
  * SyncMenu 命令选项
  */
 export interface SyncMenuOptions {
-    plan?: boolean;
 }
 
 /**
@@ -42,27 +22,41 @@ export interface MenuConfig {
     children?: MenuConfig[];
 }
 
+/**
+ * 菜单配置来源（三值约束）
+ */
+export type MenuConfigSource = "core" | "app" | "addon";
+
 /**
  * SyncDev 命令选项
  */
 export interface SyncDevOptions {
-    plan?: boolean;
 }
 
 /**
  * SyncApi 命令选项
  */
 export interface SyncApiOptions {
-    plan?: boolean;
 }
 
+/**
+ * syncApi 入参条目（来自 scanFiles 扫描结果的最小子集）
+ * - addonName 必须为 string（app/core 为 ""，addon 为真实 addonName）
+ * - type 可选：历史/测试数据可能缺失；存在且不为 "api" 时在 syncApi 中会被跳过
+ */
+export type SyncApiItem = {
+    type?: string;
+    routePath: string;
+    name: string;
+    addonName: string;
+} & Record<string, any>;
+
 /**
  * API 信息
  */
 export interface ApiInfo {
     name: string;
     path: string;
-    method: string;
     description: string;
     addonName: string;
     addonTitle: string;
@@ -281,7 +275,7 @@ export interface IndexDetail {
 export interface ApiReport {
     stats: {
         totalApis: number;
-        projectApis: number;
+        appApis: number;
         addonApis: number;
         created: number;
         updated: number;
@@ -289,7 +283,7 @@ export interface ApiReport {
     };
     details: {
         bySource: {
-            project: ApiDetail[];
+            app: ApiDetail[];
             addons: Record<string, ApiDetail[]>;
         };
         byAction: {

package/utils/convertBigIntFields.ts

@@ -0,0 +1,38 @@
+/**
+ * 转换数据库 BIGINT 字段为数字类型
+ *
+ * 当 bigint: false 时，Bun SQL 会将大于 u32 的 BIGINT 返回为字符串，此方法将其转换为 number。
+ *
+ * 转换规则：
+ * 1. 白名单中的字段会被转换
+ * 2. 所有以 'Id' 或 '_id' 结尾的字段会被自动转换
+ * 3. 所有以 'At' 或 '_at' 结尾的字段会被自动转换（时间戳字段）
+ */
+export function convertBigIntFields<T = any>(arr: Record<string, any>[], fields: string[] = ["id", "pid", "sort"]): T[] {
+    if (!arr || !Array.isArray(arr)) {
+        return arr as T[];
+    }
+
+    return arr.map((item) => {
+        const converted: Record<string, any> = {};
+        for (const [key, value] of Object.entries(item)) {
+            converted[key] = value;
+        }
+
+        for (const [key, value] of Object.entries(converted)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+
+            const shouldConvert = fields.includes(key) || key.endsWith("Id") || key.endsWith("_id") || key.endsWith("At") || key.endsWith("_at");
+            if (shouldConvert && typeof value === "string") {
+                const num = Number(value);
+                if (!isNaN(num)) {
+                    converted[key] = num;
+                }
+            }
+        }
+
+        return converted as T;
+    }) as T[];
+}