befly 3.74.2 → 3.75.0

package/sync/api.js

@@ -1,6 +1,5 @@
-import { buildPathSyncLists } from "./syncUtil.js";
-
-const API_TABLE_NAME = "beflyApi";
+import { BEFLY_API_TABLE } from "../configs/constConfig.js";
+import { buildPathSyncLists, serializeAuth } from "./syncUtil.js";
 
 const getApiParentPath = (apiPath) => {
     const segments = apiPath
@@ -19,7 +18,7 @@ const getApiParentPath = (apiPath) => {
 
 export async function syncApi(ctx, apis) {
     const allDbApis = await ctx.mysql.getAll({
-        table: API_TABLE_NAME,
+        table: BEFLY_API_TABLE,
         fields: ["id", "path", "parentPath", "name", "auth", "state"],
         where: { state$gte: 0 }
     });
@@ -31,7 +30,7 @@ export async function syncApi(ctx, apis) {
             path: api.apiPath,
             method: api.method,
             parentPath: getApiParentPath(api.apiPath),
-            auth: api.auth === false ? "否" : Array.isArray(api.auth) ? api.auth.join(",") : "是"
+            auth: serializeAuth(api.auth)
         });
     }
 
@@ -55,14 +54,14 @@ export async function syncApi(ctx, apis) {
     );
 
     if (syncLists.updList.length > 0) {
-        await ctx.mysql.updBatch(API_TABLE_NAME, syncLists.updList);
+        await ctx.mysql.updBatch(BEFLY_API_TABLE, syncLists.updList);
     }
 
     if (syncLists.insList.length > 0) {
-        await ctx.mysql.insBatch(API_TABLE_NAME, syncLists.insList);
+        await ctx.mysql.insBatch(BEFLY_API_TABLE, syncLists.insList);
     }
 
     if (syncLists.delIds.length > 0) {
-        await ctx.mysql.delForceBatch(API_TABLE_NAME, syncLists.delIds);
+        await ctx.mysql.delForceBatch(BEFLY_API_TABLE, syncLists.delIds);
     }
 }

package/sync/cache.js

@@ -1,3 +1,5 @@
+import { createError } from "../utils/error.js";
+
 // 1
 export async function syncCache(ctx) {
     const tasks = [
@@ -22,7 +24,7 @@ export async function syncCache(ctx) {
     }
 
     if (failures.length > 0) {
-        throw new Error("缓存同步失败", {
+        throw createError("缓存同步失败", {
             cause: failures[0].error,
             code: "runtime",
             subsystem: "sync",

package/sync/dev.js

@@ -1,35 +1,39 @@
+import { BEFLY_ADMIN_TABLE, BEFLY_API_TABLE, BEFLY_MENU_TABLE, BEFLY_ROLE_TABLE } from "../configs/constConfig.js";
 import { hashPassword } from "../utils/crypto.js";
-import { isNumber } from "../utils/is.js";
-
-const MENU_TABLE_NAME = "beflyMenu";
-const API_TABLE_NAME = "beflyApi";
-const ROLE_TABLE_NAME = "beflyRole";
-const ADMIN_TABLE_NAME = "beflyAdmin";
+import { createError } from "../utils/error.js";
+import { isNonEmptyString, isNumber } from "../utils/is.js";
+import { authAllowsRole } from "./syncUtil.js";
 
 export async function syncDev(ctx) {
+    // devPassword 为必填项：dev 管理员拥有全部权限，未配置时阻断（不允许无密码/默认密码账号）。
+    // 校验放在 try 外，避免被下方统一包装掩盖具体原因。
+    if (!isNonEmptyString(ctx.config.devPassword)) {
+        throw createError("必须配置 devPassword（至少 6 位）以创建 dev 管理员账号", { code: "policy", subsystem: "sync", operation: "syncDev" });
+    }
+
     try {
         const allMenus = await ctx.mysql.getAll({
-            table: MENU_TABLE_NAME,
+            table: BEFLY_MENU_TABLE,
             fields: ["path"],
             where: { state$gte: 0 },
             orderBy: ["id#ASC"]
         });
 
         const allApis = await ctx.mysql.getAll({
-            table: API_TABLE_NAME,
+            table: BEFLY_API_TABLE,
             fields: ["path", "auth"],
             where: { state$gte: 0 },
             orderBy: ["id#ASC"]
         });
 
         const devRole = await ctx.mysql.getOne({
-            table: ROLE_TABLE_NAME,
+            table: BEFLY_ROLE_TABLE,
             fields: ["id"],
             where: { code: "dev", state$gte: 0 }
         });
 
         const devAdmin = await ctx.mysql.getOne({
-            table: ADMIN_TABLE_NAME,
+            table: BEFLY_ADMIN_TABLE,
             fields: ["id"],
             where: { username: "dev", state$gte: 0 }
         });
@@ -55,25 +59,20 @@ export async function syncDev(ctx) {
 
         if (isNumber(devRole.data.id)) {
             await ctx.mysql.updData({
-                table: ROLE_TABLE_NAME,
+                table: BEFLY_ROLE_TABLE,
                 where: { code: "dev", state$gte: 0 },
-                data: {
-                    name: devRoleData.name,
-                    description: devRoleData.description,
-                    menus: devRoleData.menus,
-                    apis: devRoleData.apis,
-                    sort: devRoleData.sort,
-                    state: 1
-                }
+                data: { ...devRoleData, state: 1 }
             });
         } else {
             await ctx.mysql.insData({
-                table: ROLE_TABLE_NAME,
+                table: BEFLY_ROLE_TABLE,
                 data: devRoleData
             });
         }
 
+        // devPassword 为必填项（校验见函数开头），此处直接使用
         const password = await hashPassword(ctx.config.devPassword);
+        // 【临时诊断】hashPassword 后连接预检
 
         const devAdminData = {
             nickname: "开发者",
@@ -86,29 +85,14 @@ export async function syncDev(ctx) {
 
         if (isNumber(devAdmin.data.id)) {
             await ctx.mysql.updData({
-                table: ADMIN_TABLE_NAME,
+                table: BEFLY_ADMIN_TABLE,
                 where: { username: "dev" },
-                data: {
-                    nickname: devAdminData.nickname,
-                    email: devAdminData.email,
-                    password: devAdminData.password,
-                    roleCode: devAdminData.roleCode,
-                    roleType: devAdminData.roleType,
-                    state: 1
-                }
+                data: { ...devAdminData, state: 1 }
             });
         } else {
             await ctx.mysql.insData({
-                table: ADMIN_TABLE_NAME,
-                data: {
-                    nickname: devAdminData.nickname,
-                    email: devAdminData.email,
-                    username: devAdminData.username,
-                    password: devAdminData.password,
-                    roleCode: devAdminData.roleCode,
-                    roleType: devAdminData.roleType,
-                    state: 1
-                }
+                table: BEFLY_ADMIN_TABLE,
+                data: { ...devAdminData, state: 1 }
             });
         }
 
@@ -135,7 +119,7 @@ export async function syncDev(ctx) {
 
         for (const roleConfig of roles) {
             const existingRole = await ctx.mysql.getOne({
-                table: ROLE_TABLE_NAME,
+                table: BEFLY_ROLE_TABLE,
                 fields: ["id", "apis"],
                 where: {
                     code: roleConfig.code,
@@ -150,24 +134,8 @@ export async function syncDev(ctx) {
                     continue;
                 }
 
-                const auth = api.auth;
-                if (auth === "否" || auth === false) {
+                if (authAllowsRole(api.auth, roleConfig.code)) {
                     defaultApis.push(apiPath);
-                    continue;
-                }
-
-                // 与 syncApi 的存储语义保持一致：
-                // - true -> "是"
-                // - false -> "否"
-                // - string[] -> "a,b,c"
-                if (typeof auth === "string" && auth !== "是") {
-                    const roleCodes = auth.split(",");
-                    for (const roleCode of roleCodes) {
-                        if (roleCode.trim() === roleConfig.code) {
-                            defaultApis.push(apiPath);
-                            break;
-                        }
-                    }
                 }
             }
 
@@ -200,7 +168,7 @@ export async function syncDev(ctx) {
             if (existingRole.data?.id) {
                 // 角色存在则强制更新（不做差异判断）
                 await ctx.mysql.updData({
-                    table: ROLE_TABLE_NAME,
+                    table: BEFLY_ROLE_TABLE,
                     where: { code: roleConfig.code, state$gte: 0 },
                     data: {
                         name: roleConfig.name,
@@ -212,7 +180,7 @@ export async function syncDev(ctx) {
                 });
             } else {
                 await ctx.mysql.insData({
-                    table: ROLE_TABLE_NAME,
+                    table: BEFLY_ROLE_TABLE,
                     data: {
                         code: roleConfig.code,
                         name: roleConfig.name,
@@ -225,11 +193,6 @@ export async function syncDev(ctx) {
             }
         }
     } catch (error) {
-        throw new Error("同步开发者数据失败", {
-            cause: error,
-            code: "runtime",
-            subsystem: "sync",
-            operation: "syncDev"
-        });
+        throw createError("同步开发者数据失败", { cause: error, code: "runtime", subsystem: "sync", operation: "syncDev" });
     }
 }

package/sync/menu.js

@@ -1,7 +1,6 @@
+import { BEFLY_MENU_TABLE } from "../configs/constConfig.js";
 import { buildPathSyncLists } from "./syncUtil.js";
 
-const MENU_TABLE_NAME = "beflyMenu";
-
 export function flattenMenusToDefMap(menus) {
     // 读取配置菜单：扁平化为 path => { name, sort, parentPath }
     // - 以 path 为唯一键：后出现的覆盖先出现的（与旧逻辑“同 path 多次同步同一条记录”一致）
@@ -44,7 +43,7 @@ export async function syncMenu(ctx, menus) {
     // 2) 批量同步（事务内）：按 path diff 执行批量 insert/update/delete
     // 读取全部菜单
     const allExistingMenus = await ctx.mysql.getAll({
-        table: MENU_TABLE_NAME,
+        table: BEFLY_MENU_TABLE,
         fields: ["id", "name", "path", "parentPath", "sort", "state"],
         where: { state$gte: 0 }
     });
@@ -67,15 +66,15 @@ export async function syncMenu(ctx, menus) {
     );
 
     if (syncLists.updList.length > 0) {
-        await ctx.mysql.updBatch(MENU_TABLE_NAME, syncLists.updList);
+        await ctx.mysql.updBatch(BEFLY_MENU_TABLE, syncLists.updList);
     }
 
     if (syncLists.insList.length > 0) {
-        await ctx.mysql.insBatch(MENU_TABLE_NAME, syncLists.insList);
+        await ctx.mysql.insBatch(BEFLY_MENU_TABLE, syncLists.insList);
     }
 
     // 3) 删除差集（DB - 配置）
     if (syncLists.delIds.length > 0) {
-        await ctx.mysql.delForceBatch(MENU_TABLE_NAME, syncLists.delIds);
+        await ctx.mysql.delForceBatch(BEFLY_MENU_TABLE, syncLists.delIds);
     }
 }

package/sync/syncUtil.js

@@ -1,3 +1,28 @@
+// 接口 auth 的存储协议（serializeAuth 与 authAllowsRole 配套使用）：
+// - true -> "是"
+// - false -> "否"
+// - string[] -> "a,b,c"
+export const AUTH_YES = "是";
+export const AUTH_NO = "否";
+
+/**
+ * 序列化 api.auth 为存储字符串
+ */
+export function serializeAuth(auth) {
+    return auth === false ? AUTH_NO : Array.isArray(auth) ? auth.join(",") : AUTH_YES;
+}
+
+/**
+ * 判断 auth 存储串是否授权给指定角色
+ */
+export function authAllowsRole(auth, roleCode) {
+    if (auth === AUTH_NO) return true;
+    if (typeof auth === "string" && auth !== AUTH_YES) {
+        return auth.split(",").some((code) => code.trim() === roleCode);
+    }
+    return false;
+}
+
 export function buildPathSyncLists(existingList, defList, buildUpdateData, buildInsertData) {
     const existingMap = new Map();
     const delIdSet = new Set();

package/utils/calcPerfTime.js

@@ -6,8 +6,7 @@ export const calcPerfTime = (startTime, endTime = Bun.nanoseconds()) => {
 
     if (elapsedMs < 1000) {
         return `${elapsedMs.toFixed(2)} 毫秒`;
-    } else {
-        const elapsedSeconds = elapsedMs / 1000;
-        return `${elapsedSeconds.toFixed(2)} 秒`;
     }
+    const elapsedSeconds = elapsedMs / 1000;
+    return `${elapsedSeconds.toFixed(2)} 秒`;
 };

package/utils/crypto.js

@@ -2,46 +2,6 @@
  * 通用加密/哈希工具
  */
 
-import { isString } from "./is.js";
-
-/**
- * 计算 md5（hex）
- * @param value 输入字符串
- * @returns md5 hex
- */
-export function md5(value) {
-    if (!isString(value) || value.length < 1) {
-        throw new Error("md5 输入必须是非空字符串", {
-            cause: null,
-            code: "validation",
-            subsystem: "crypto",
-            operation: "md5"
-        });
-    }
-    const hasher = new Bun.CryptoHasher("md5");
-    hasher.update(value);
-    return hasher.digest("hex");
-}
-
-/**
- * 计算 sha256（hex）
- * @param value 输入字符串
- * @returns sha256 hex
- */
-export function sha256(value) {
-    if (!isString(value) || value.length < 1) {
-        throw new Error("sha256 输入必须是非空字符串", {
-            cause: null,
-            code: "validation",
-            subsystem: "crypto",
-            operation: "sha256"
-        });
-    }
-    const hasher = new Bun.CryptoHasher("sha256");
-    hasher.update(value);
-    return hasher.digest("hex");
-}
-
 /**
  * 使用 bcrypt 对密码进行哈希
  * @param password 原始密码

package/utils/deepMerge.js

@@ -1,3 +1,4 @@
+import { createError } from "./error.js";
 import { isPlainObject } from "./is.js";
 
 function clone(value) {
@@ -69,10 +70,5 @@ export function deepMerge(source, target) {
         return mergeInto(base, incoming);
     }
 
-    throw new Error("deepMerge: source/target 必须同为数组或同为普通对象", {
-        cause: null,
-        code: "validation",
-        subsystem: "utils",
-        operation: "deepMerge"
-    });
+    throw createError("deepMerge: source/target 必须同为数组或同为普通对象", { code: "validation", subsystem: "utils", operation: "deepMerge" });
 }

package/utils/error.js

@@ -0,0 +1,64 @@
+/**
+ * 统一错误工厂
+ * 框架错误对象的唯一构造入口，统一字段约定：
+ * - code: "validation" | "runtime" | "policy"
+ * - subsystem: 子系统标识（sql/cache/redis/sync/config/start/...）
+ * - operation: 操作名
+ * - 其余字段原样透传（如 table、roleCode、runMode 等）
+ * - 不传 cause 时不设置（缺省为 undefined，避免 cause: null 噪音）
+ */
+export function createError(message, options = {}) {
+    const error = new Error(message, options.cause === undefined ? undefined : { cause: options.cause });
+
+    if (options.code) error.code = options.code;
+    if (options.subsystem) error.subsystem = options.subsystem;
+    if (options.operation) error.operation = options.operation;
+
+    for (const [key, value] of Object.entries(options)) {
+        if (key === "cause" || key === "code" || key === "subsystem" || key === "operation") {
+            continue;
+        }
+        error[key] = value;
+    }
+
+    return error;
+}
+
+/**
+ * 参数校验错误（code: "validation"）
+ */
+export function validationError(message) {
+    return createError(message, { code: "validation" });
+}
+
+/**
+ * 沿 cause 链取最底层错误（根因）
+ */
+export function getRootCause(error) {
+    let current = error;
+    while (current?.cause instanceof Error) {
+        current = current.cause;
+    }
+    return current;
+}
+
+/**
+ * 错误链摘要：沿 cause 展开为单行文本，根因在后
+ * 每层格式：message [code/subsystem/operation]（无元信息时仅 message）
+ * 例：SQL执行失败 [runtime/sql/execute] <- ER_DUP_ENTRY: 重复插入 [runtime]
+ */
+export function errorChainSummary(error) {
+    const parts = [];
+    const visited = new Set();
+    let current = error;
+
+    while (current instanceof Error && !visited.has(current)) {
+        visited.add(current);
+        const meta = [current.code, current.subsystem, current.operation].filter(Boolean).join("/");
+        const text = current.message || current.name || "Error";
+        parts.push(meta ? `${text} [${meta}]` : text);
+        current = current.cause;
+    }
+
+    return parts.join(" <- ");
+}

package/utils/fieldClear.js

@@ -1,65 +1,22 @@
 // fieldClear 工具函数实现
-// 支持 pick/omit/keepValues/excludeValues，处理对象和数组
+// 过滤对象中指定值（如 undefined）的字段，其余字段原样保留
 
-function isObject(val) {
-    return val !== null && typeof val === "object" && !Array.isArray(val);
-}
-
-function isArray(val) {
-    return Array.isArray(val);
-}
+import { isPlainObject } from "./is.js";
 
 export function fieldClear(data, options = {}) {
-    const { pickKeys, omitKeys, keepValues, excludeValues, keepMap } = options;
-
-    const filterObj = (obj) => {
-        const result = {};
-        let keys = Object.keys(obj);
-        if (pickKeys && pickKeys.length) {
-            keys = keys.filter((k) => pickKeys.includes(k));
-        }
-        if (omitKeys && omitKeys.length) {
-            keys = keys.filter((k) => !omitKeys.includes(k));
-        }
-        for (const key of keys) {
-            const value = obj[key];
-
-            // 1. 优先检查 keepMap
-            if (keepMap && key in keepMap) {
-                if (Object.is(keepMap[key], value)) {
-                    result[key] = value;
-                    continue;
-                }
-            }
+    if (!isPlainObject(data)) {
+        return data;
+    }
 
-            // 2. 检查 keepValues (只保留指定值)
-            if (keepValues && keepValues.length && !keepValues.includes(value)) {
-                continue;
-            }
+    const { excludeValues } = options;
+    const result = {};
 
-            // 3. 检查 excludeValues (排除指定值)
-            if (excludeValues && excludeValues.length && excludeValues.includes(value)) {
-                continue;
-            }
-            result[key] = value;
+    for (const [key, value] of Object.entries(data)) {
+        if (excludeValues && excludeValues.length && excludeValues.includes(value)) {
+            continue;
         }
-        return result;
-    };
-
-    if (isArray(data)) {
-        return data
-            .map((item) => (isObject(item) ? filterObj(item) : item))
-            .filter((item) => {
-                if (isObject(item)) {
-                    // 只保留有内容的对象
-                    return Object.keys(item).length > 0;
-                }
-                // 原始值直接保留
-                return true;
-            });
+        result[key] = value;
     }
-    if (isObject(data)) {
-        return filterObj(data);
-    }
-    return data;
+
+    return result;
 }

package/utils/importDefault.js

@@ -1,13 +1,14 @@
 /**
  * 动态导入模块并优先返回其 default 导出。
  *
- * - import() 报错：返回 defaultValue
- * - default 导出为 null/undefined：返回 defaultValue
+ * 仅限启动期使用（扫描 API/插件/钩子/表定义等静态资产），不要在运行期（请求处理中）调用：
+ * - import() 报错、default 导出类型与默认值不一致时，直接抛错中断启动（fail-fast），真实原因随 cause 带出
+ * - default 导出为空（null/undefined）时允许，回退默认值
  */
 import { isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { Logger } from "../lib/logger.js";
+import { createError } from "./error.js";
 import { isNullable } from "./is.js";
 import { getTypeTag } from "./util.js";
 
@@ -31,21 +32,19 @@ export async function importDefault(file, defaultValue) {
         // 为保证一致性：json 一律走 import assertion。
         const mod = isJson ? await import(toFileImportUrl(file), { with: { type: "json" } }) : await import(file);
         const value = mod?.default;
+
+        // default 导出为空：允许，回退默认值
         if (isNullable(value)) {
             return defaultValue;
         }
 
-        // 额外保护：如果导入值的运行时类型与 defaultValue 不一致，则回退 defaultValue。
-        // 这样调用方可以通过 defaultValue 的类型约束导入结果（例如 defaultValue 为 {} 时，数组/字符串等会被拒绝）。
-        const expectedType = getTypeTag(defaultValue);
-        const actualType = getTypeTag(value);
-        if (expectedType !== actualType) {
-            Logger.warn("importDefault 导入类型与默认值不一致，已回退到默认值", { file: file, expectedType: expectedType, actualType: actualType });
-            return defaultValue;
+        // 类型与默认值不一致：视为导入异常，中断启动
+        if (getTypeTag(value) !== getTypeTag(defaultValue)) {
+            throw new Error("导入内容类型与默认值不一致");
         }
+
         return value;
     } catch (err) {
-        Logger.warn("importDefault 导入失败，已回退到默认值", { err: err, file: file });
-        return defaultValue;
+        throw createError(`导入失败：${file}`, { cause: err, code: "runtime", subsystem: "scan", operation: "importDefault" });
     }
 }