befly 3.9.37 → 3.9.39

package/types/roleApisCache.ts

@@ -0,0 +1,23 @@
+/**
+ * 角色接口权限缓存（Redis）元信息类型
+ *
+ * 说明：
+ * - active/ready 用于全局版本切换与就绪门槛
+ * - role meta 用于单角色增量刷新后的可观测性
+ */
+
+export type RoleApisCacheMeta = {
+    hash: string;
+    at: number;
+    roles: number;
+    members: number;
+    /** 可选：用于和 DB 侧的更新时间做一致性对比 */
+    updatedAt?: number;
+};
+
+export type RoleApisRoleMeta = {
+    roleCode: string;
+    at: number;
+    members: number;
+    hash: string;
+};

package/types/sync.d.ts

@@ -118,7 +118,7 @@ export interface IndexInfo {
  * 字段变更接口
  */
 export interface FieldChange {
-    type: 'length' | 'datatype' | 'comment' | 'default' | 'nullable';
+    type: "length" | "datatype" | "comment" | "default" | "nullable";
     current: any;
     expected: any;
 }
@@ -127,7 +127,7 @@ export interface FieldChange {
  * 索引操作接口
  */
 export interface IndexAction {
-    action: 'create' | 'drop';
+    action: "create" | "drop";
     indexName: string;
     fieldName: string;
 }
@@ -166,7 +166,7 @@ export interface GlobalStats {
  */
 export interface ParsedFieldRule {
     name: string;
-    type: 'string' | 'number' | 'text' | 'array_string' | 'array_text';
+    type: "string" | "number" | "text" | "array_string" | "array_text";
     min: number | null;
     max: number | null;
     default: any;
@@ -204,7 +204,7 @@ export interface SyncReportMeta {
     timestampStr: string;
     environment: string;
     totalTime: number;
-    status: 'success' | 'error';
+    status: "success" | "error";
     error?: string;
 }
 
@@ -229,9 +229,9 @@ export interface DatabaseReport {
  */
 export interface TableChangeDetail {
     name: string;
-    source: 'app' | 'addon';
+    source: "app" | "addon";
     addonName?: string;
-    action: 'create' | 'modify' | 'none';
+    action: "create" | "modify" | "none";
     fields: {
         added: FieldDetail[];
         modified: FieldModification[];
@@ -263,7 +263,7 @@ export interface FieldModification {
     name: string;
     before: FieldDetail;
     after: FieldDetail;
-    changeType: 'type' | 'length' | 'default' | 'nullable' | 'comment';
+    changeType: "type" | "length" | "default" | "nullable" | "comment";
 }
 
 /**
@@ -358,7 +358,7 @@ export interface MenuTreeNode {
     icon?: string;
     sort?: number;
     type?: number;
-    action?: 'created' | 'updated' | 'none';
+    action?: "created" | "updated" | "none";
     children?: MenuTreeNode[];
 }
 
@@ -391,7 +391,7 @@ export interface MenuDetailWithDiff extends MenuDetail {
  */
 export interface AdminDetail {
     username: string;
-    action: 'created' | 'updated' | 'exists';
+    action: "created" | "updated" | "exists";
 }
 
 /**
@@ -400,5 +400,5 @@ export interface AdminDetail {
 export interface RoleDetail {
     name: string;
     permissions: number;
-    action: 'created' | 'updated' | 'exists';
+    action: "created" | "updated" | "exists";
 }

package/types/table.d.ts

@@ -1,11 +1,52 @@
 /**
  * 表类型定义 - 用于增强 DbHelper 泛型推断
- *
- * 基础类型（SystemFields, BaseTable, InsertType, UpdateType, SelectType）
- * 请直接从 befly-shared/types 导入
  */
 
-import type { BaseTable, InsertType, UpdateType } from 'befly-shared/types';
+/**
+ * 保留字段（系统自动管理）
+ */
+export type ReservedFields = "id" | "created_at" | "updated_at" | "deleted_at" | "state";
+
+/**
+ * 系统字段（所有表都有的字段）
+ */
+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;
+
+/**
+ * 排除保留字段
+ */
+export type ExcludeReserved<T> = Omit<T, ReservedFields>;
 
 // ============================================
 // 数据库表映射接口
@@ -67,27 +108,27 @@ export type TableUpdateType<K extends TableName> = UpdateType<DatabaseTables[K]>
 /**
  * 比较操作符（值类型与字段类型相同）
  */
-type CompareOperators = 'gt' | 'gte' | 'lt' | 'lte' | 'ne' | 'not';
+type CompareOperators = "gt" | "gte" | "lt" | "lte" | "ne" | "not";
 
 /**
  * 数组操作符（值类型为字段类型的数组）
  */
-type ArrayOperators = 'in' | 'nin' | 'notIn';
+type ArrayOperators = "in" | "nin" | "notIn";
 
 /**
  * 字符串操作符（值类型为字符串）
  */
-type StringOperators = 'like' | 'notLike';
+type StringOperators = "like" | "notLike";
 
 /**
  * 范围操作符（值类型为 [min, max] 元组）
  */
-type RangeOperators = 'between' | 'notBetween';
+type RangeOperators = "between" | "notBetween";
 
 /**
  * 空值操作符（值类型为 boolean）
  */
-type NullOperators = 'null' | 'notNull';
+type NullOperators = "null" | "notNull";
 
 /**
  * 所有操作符联合类型

package/types/validate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 验证相关类型定义
+ */
+
+/**
+ * 字段类型
+ */
+export type FieldType = "string" | "number" | "text" | "array_string" | "array_text" | "array_number_string" | "array_number_text";
+
+/**
+ * 字段定义类型（对象格式）
+ */
+export interface FieldDefinition {
+    /** 字段标签/描述 */
+    name: string;
+    /** 字段详细说明 */
+    detail: string;
+    /** 字段类型 */
+    type: FieldType;
+    /** 最小值/最小长度 */
+    min: number | null;
+    /** 最大值/最大长度 */
+    max: number | null;
+    /** 默认值 */
+    default: any;
+    /** 是否创建索引 */
+    index: boolean;
+    /** 是否唯一 */
+    unique: boolean;
+    /** 是否允许为空 */
+    nullable: boolean;
+    /** 是否无符号（仅 number 类型） */
+    unsigned: boolean;
+    /** 正则验证 */
+    regexp: string | null;
+}
+
+/**
+ * 表定义类型（对象格式）
+ */
+export type TableDefinition = Record<string, FieldDefinition>;
+
+/**
+ * 验证结果类型
+ */
+export interface ValidateResult {
+    /** 状态码：0=通过，1=失败 */
+    code: 0 | 1;
+    /** 是否失败 */
+    failed: boolean;
+    /** 第一个错误 */
+    firstError: string | null;
+    /** 所有错误 */
+    errors: string[];
+    /** 错误字段列表 */
+    errorFields: string[];
+    /** 字段错误映射 */
+    fieldErrors: Record<string, string>;
+}
+
+/**
+ * 单值验证结果
+ */
+export interface SingleResult {
+    /** 转换后的值 */
+    value: any;
+    /** 错误信息（null 表示通过） */
+    error: string | null;
+}

package/utils/addonHelper.ts

@@ -0,0 +1,90 @@
+import fs from "node:fs";
+import { existsSync, statSync } from "node:fs";
+
+import { join } from "pathe";
+
+import { projectAddonsDir } from "../paths.js";
+
+/**
+ * 扫描所有可用的 addon
+ * 优先从本地 addons/ 目录加载，其次从 node_modules/@befly-addon/ 加载
+ * @param cwd - 项目根目录，默认为 process.cwd()
+ * @returns addon 名称数组
+ */
+export const scanAddons = (cwd: string = process.cwd()): string[] => {
+    const addons = new Set<string>();
+
+    // 1. 扫描本地 addons 目录（优先级高）
+    if (existsSync(projectAddonsDir)) {
+        try {
+            const localAddons = fs.readdirSync(projectAddonsDir).filter((name) => {
+                const fullPath = join(projectAddonsDir, name);
+                try {
+                    const stat = statSync(fullPath);
+                    return stat.isDirectory() && !name.startsWith("_");
+                } catch {
+                    return false;
+                }
+            });
+            localAddons.forEach((name) => addons.add(name));
+        } catch {
+            // 忽略本地目录读取错误
+        }
+    }
+
+    // 2. 扫描 node_modules/@befly-addon 目录
+    const beflyDir = join(cwd, "node_modules", "@befly-addon");
+    if (existsSync(beflyDir)) {
+        try {
+            const npmAddons = fs.readdirSync(beflyDir).filter((name) => {
+                // 如果本地已存在，跳过 npm 包版本
+                if (addons.has(name)) return false;
+
+                const fullPath = join(beflyDir, name);
+                try {
+                    const stat = statSync(fullPath);
+                    return stat.isDirectory();
+                } catch {
+                    return false;
+                }
+            });
+            npmAddons.forEach((name) => addons.add(name));
+        } catch {
+            // 忽略 npm 目录读取错误
+        }
+    }
+
+    return Array.from(addons).sort();
+};
+
+/**
+ * 获取 addon 的指定子目录路径
+ * 优先返回本地 addons 目录，其次返回 node_modules 目录
+ * @param name - addon 名称
+ * @param subDir - 子目录名称
+ * @param cwd - 项目根目录，默认为 process.cwd()
+ * @returns 完整路径
+ */
+export const getAddonDir = (name: string, subDir: string, cwd: string = process.cwd()): string => {
+    // 优先使用本地 addons 目录
+    // const projectAddonsDir = join(cwd, 'addons');
+    // const localPath = join(projectAddonsDir, name, subDir);
+    // if (existsSync(localPath)) {
+    //     return localPath;
+    // }
+
+    // 降级使用 node_modules 目录
+    return join(cwd, "node_modules", "@befly-addon", name, subDir);
+};
+
+/**
+ * 检查 addon 子目录是否存在
+ * @param name - addon 名称
+ * @param subDir - 子目录名称
+ * @param cwd - 项目根目录，默认为 process.cwd()
+ * @returns 是否存在
+ */
+export const addonDirExists = (name: string, subDir: string, cwd: string = process.cwd()): boolean => {
+    const dir = getAddonDir(name, subDir, cwd);
+    return existsSync(dir) && statSync(dir).isDirectory();
+};

package/utils/arrayKeysToCamel.ts

@@ -0,0 +1,18 @@
+import { keysToCamel } from "./keysToCamel.js";
+
+/**
+ * 数组对象字段名批量转小驼峰
+ * @param arr - 源数组
+ * @returns 字段名转为小驼峰格式的新数组
+ *
+ * @example
+ * arrayKeysToCamel([
+ *   { user_id: 1, user_name: 'John' },
+ *   { user_id: 2, user_name: 'Jane' }
+ * ])
+ * // [{ userId: 1, userName: 'John' }, { userId: 2, userName: 'Jane' }]
+ */
+export const arrayKeysToCamel = <T = any>(arr: Record<string, any>[]): T[] => {
+    if (!arr || !Array.isArray(arr)) return arr as T[];
+    return arr.map((item) => keysToCamel<T>(item));
+};

package/utils/calcPerfTime.ts

@@ -0,0 +1,13 @@
+/**
+ * 计算性能时间差
+ */
+export const calcPerfTime = (startTime: number, endTime: number = Bun.nanoseconds()): string => {
+    const elapsedMs = (endTime - startTime) / 1_000_000;
+
+    if (elapsedMs < 1000) {
+        return `${elapsedMs.toFixed(2)} 毫秒`;
+    } else {
+        const elapsedSeconds = elapsedMs / 1000;
+        return `${elapsedSeconds.toFixed(2)} 秒`;
+    }
+};

package/utils/configTypes.ts

@@ -0,0 +1,3 @@
+// 该类型已内联到 ./scanConfig.ts（减少文件分散）。
+// 这个文件保留为空模块，避免旧工具/缓存引用报错。
+export {};

package/utils/cors.ts

@@ -0,0 +1,19 @@
+import type { CorsConfig } from "../types/befly.js";
+
+/**
+ * 设置 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"
+    };
+}

package/utils/fieldClear.ts

@@ -0,0 +1,75 @@
+// fieldClear 工具函数实现
+// 支持 pick/omit/keepValues/excludeValues，处理对象和数组
+
+export interface FieldClearOptions {
+    pickKeys?: string[]; // 只保留这些字段
+    omitKeys?: string[]; // 排除这些字段
+    keepValues?: any[]; // 只保留这些值
+    excludeValues?: any[]; // 排除这些值
+    keepMap?: Record<string, any>; // 强制保留的键值对（优先级最高，忽略 excludeValues）
+}
+
+export type FieldClearResult<T> = T extends Array<infer U> ? Array<FieldClearResult<U>> : T extends object ? { [K in keyof T]?: T[K] } : T;
+
+function isObject(val: unknown): val is Record<string, any> {
+    return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+
+function isArray(val: unknown): val is any[] {
+    return Array.isArray(val);
+}
+
+export function fieldClear<T = any>(data: T | T[], options: FieldClearOptions = {}): FieldClearResult<T> {
+    const { pickKeys, omitKeys, keepValues, excludeValues, keepMap } = options;
+
+    const filterObj = (obj: Record<string, any>) => {
+        let result: Record<string, any> = {};
+        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;
+                }
+            }
+
+            // 2. 检查 keepValues (只保留指定值)
+            if (keepValues && keepValues.length && !keepValues.includes(value)) {
+                continue;
+            }
+
+            // 3. 检查 excludeValues (排除指定值)
+            if (excludeValues && excludeValues.length && excludeValues.includes(value)) {
+                continue;
+            }
+            result[key] = value;
+        }
+        return result;
+    };
+
+    if (isArray(data)) {
+        return (data as any[])
+            .map((item) => (isObject(item) ? filterObj(item) : item))
+            .filter((item) => {
+                if (isObject(item)) {
+                    // 只保留有内容的对象
+                    return Object.keys(item).length > 0;
+                }
+                // 原始值直接保留
+                return true;
+            }) as FieldClearResult<T>;
+    }
+    if (isObject(data)) {
+        return filterObj(data as Record<string, any>) as FieldClearResult<T>;
+    }
+    return data as FieldClearResult<T>;
+}

package/utils/genShortId.ts

@@ -0,0 +1,12 @@
+/**
+ * 生成短 ID
+ * 由时间戳（base36）+ 随机字符组成，约 13 位
+ * - 前 8 位：时间戳（可排序）
+ * - 后 5 位：随机字符（防冲突）
+ * @returns 短 ID 字符串
+ * @example
+ * genShortId() // "lxyz1a2b3c4"
+ */
+export function genShortId(): string {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+}

package/utils/getClientIp.ts

@@ -0,0 +1,45 @@
+/**
+ * 获取客户端 IP（优先代理头，其次 Bun server.requestIP 兜底）
+ *
+ * 注意：目前策略是“尽量取到 IP”，未做 trustProxy 防伪造控制。
+ */
+export function getClientIp(req: Request, server?: any): string {
+    // 1) 代理/网关常见头（优先取）
+    const xForwardedFor = req.headers.get("x-forwarded-for");
+    if (typeof xForwardedFor === "string" && xForwardedFor.trim()) {
+        const first = xForwardedFor.split(",")[0];
+        if (typeof first === "string" && first.trim()) {
+            return first.trim();
+        }
+    }
+
+    const xRealIp = req.headers.get("x-real-ip");
+    if (typeof xRealIp === "string" && xRealIp.trim()) {
+        return xRealIp.trim();
+    }
+
+    const cfConnectingIp = req.headers.get("cf-connecting-ip");
+    if (typeof cfConnectingIp === "string" && cfConnectingIp.trim()) {
+        return cfConnectingIp.trim();
+    }
+
+    const xClientIp = req.headers.get("x-client-ip");
+    if (typeof xClientIp === "string" && xClientIp.trim()) {
+        return xClientIp.trim();
+    }
+
+    const trueClientIp = req.headers.get("true-client-ip");
+    if (typeof trueClientIp === "string" && trueClientIp.trim()) {
+        return trueClientIp.trim();
+    }
+
+    // 2) 连接层兜底：Bun server.requestIP(req)
+    if (server && typeof server.requestIP === "function") {
+        const ipInfo = server.requestIP(req);
+        if (ipInfo && typeof ipInfo.address === "string" && ipInfo.address.trim()) {
+            return ipInfo.address.trim();
+        }
+    }
+
+    return "unknown";
+}

package/utils/keysToCamel.ts

@@ -0,0 +1,22 @@
+import { isPlainObject } from "es-toolkit/compat";
+import { camelCase } from "es-toolkit/string";
+
+/**
+ * 对象字段名转小驼峰
+ * @param obj - 源对象
+ * @returns 字段名转为小驼峰格式的新对象
+ *
+ * @example
+ * keysToCamel({ user_id: 123, user_name: 'John' }) // { userId: 123, userName: 'John' }
+ * keysToCamel({ created_at: 1697452800000 }) // { createdAt: 1697452800000 }
+ */
+export const keysToCamel = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = camelCase(key);
+        result[camelKey] = value;
+    }
+    return result;
+};

package/utils/keysToSnake.ts

@@ -0,0 +1,22 @@
+import { isPlainObject } from "es-toolkit/compat";
+import { snakeCase } from "es-toolkit/string";
+
+/**
+ * 对象字段名转下划线
+ * @param obj - 源对象
+ * @returns 字段名转为下划线格式的新对象
+ *
+ * @example
+ * keysToSnake({ userId: 123, userName: 'John' }) // { user_id: 123, user_name: 'John' }
+ * keysToSnake({ createdAt: 1697452800000 }) // { created_at: 1697452800000 }
+ */
+export const keysToSnake = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const snakeKey = snakeCase(key);
+        result[snakeKey] = value;
+    }
+    return result;
+};