befly 3.75.3 → 3.76.1

package/apis/admin/insert.js

@@ -51,7 +51,8 @@ export default {
                 username: ctx.body.username,
                 password: hashedPassword,
                 nickname: ctx.body.nickname,
-                roleCode: ctx.body.roleCode
+                roleCode: ctx.body.roleCode,
+                roleType: "admin"
             }
         });
 

package/apis/admin/update.js

@@ -16,8 +16,7 @@ export default {
         lastLoginIp: adminTable.lastLoginIp,
         lastLoginTime: adminTable.lastLoginTime,
         password: adminTable.password,
-        phone: adminTable.phone,
-        roleType: adminTable.roleType
+        phone: adminTable.phone
     },
     required: ["id"],
     handler: async (befly, ctx) => {
@@ -79,7 +78,7 @@ export default {
             updateData.password = await hashPassword(ctx.body.password);
         }
         if (ctx.body.phone !== undefined) updateData.phone = ctx.body.phone;
-        if (ctx.body.roleType !== undefined) updateData.roleType = ctx.body.roleType;
+        // 管理员表类型固定为 admin，roleType 不允许通过更新接口修改
         if (ctx.body.username !== undefined) updateData.username = ctx.body.username;
         if (ctx.body.nickname !== undefined) updateData.nickname = ctx.body.nickname;
         if (ctx.body.roleCode !== undefined) updateData.roleCode = ctx.body.roleCode;

package/checks/corns.js

@@ -0,0 +1,54 @@
+import { Logger } from "../lib/logger.js";
+import { formatValidationIssues } from "../utils/formatValidationIssues.js";
+import { isFunction, isPlainObject, isValidCronSchedule } from "../utils/is.js";
+
+// scanFiles 基础字段 + 定时器业务字段（schedule/handler；时区统一走 config.tz）
+const cornKeys = new Set(["source", "type", "filePath", "relativePath", "fileName", "apiPath", "schedule", "handler"]);
+
+export const checkCorn = (corns) => {
+    if (!Array.isArray(corns)) {
+        const errors = formatValidationIssues([{ path: [], message: "必须是数组" }], { item: corns, itemLabel: "corn" });
+        Logger.warn(`定时器校验失败`, { errors: errors });
+        return errors;
+    }
+
+    const errors = [];
+
+    // 任务名唯一性：文件名即任务名（core + app 合并后全局唯一，防止同名任务被 register 静默去重）
+    const nameMap = new Map();
+    for (const corn of corns) {
+        if (!corn?.fileName) continue;
+        nameMap.set(corn.fileName, (nameMap.get(corn.fileName) || 0) + 1);
+    }
+    const duplicateNames = [...nameMap].filter(([, count]) => count > 1).map(([name]) => name);
+    if (duplicateNames.length > 0) {
+        const duplicateCorns = corns.filter((corn) => duplicateNames.includes(corn.fileName));
+        errors.push(
+            ...formatValidationIssues(
+                duplicateCorns.map((corn, index) => ({ path: [index], message: `任务名 ${corn.fileName} 重复，请显式区分` })),
+                { items: duplicateCorns, itemLabel: "corn" }
+            )
+        );
+    }
+
+    for (const [index, corn] of corns.entries()) {
+        if (!isPlainObject(corn)) {
+            errors.push(...formatValidationIssues([{ path: [index], message: "必须是对象格式" }], { items: corns, itemLabel: "corn" }));
+            continue;
+        }
+
+        const issues = [];
+        for (const key of Object.keys(corn)) {
+            if (!cornKeys.has(key)) issues.push({ path: [key], message: "不允许出现" });
+        }
+        if (!isFunction(corn.handler)) issues.push({ path: ["handler"], message: "必须是函数" });
+        if (!isValidCronSchedule(corn.schedule)) issues.push({ path: ["schedule"], message: "必须是可注册的 cron 表达式" });
+        if (issues.length === 0) continue;
+        errors.push(...formatValidationIssues(issues, { items: corns, itemLabel: "corn" }));
+    }
+
+    if (errors.length > 0) {
+        Logger.warn(`定时器校验失败`, { errors: errors });
+    }
+    return errors;
+};

package/hooks/permission.js

@@ -6,9 +6,11 @@ import { ErrorResponse } from "../utils/response.js";
 /**
  * 权限检查钩子
  * - 接口无需权限（auth=false）：直接通过
- * - auth 为 ctx.roleType 白名单（string[]）：登录后按 ctx.roleType 放行
+ * - auth 为角色类型白名单（string[]，如 ["admin"] / ["user"]）：按 ctx.roleType 校验。
+ *   类型与角色解耦：管理员表（beflyAdmin）roleType 固定 "admin"，用户表固定 "user"，
+ *   任意角色 code 的管理员共享 "admin" 类型门槛，细粒度授权由下方集合检查（roleCode）负责
  * - 用户未登录：返回 401
- * - 开发者角色（dev）：最高权限，直接通过
+ * - 开发者角色（dev）：最高权限，直接通过（唯一内置角色，不可创建）
  * - 其他角色：检查 Redis 中的角色权限集合
  */
 export default {

package/index.js

@@ -6,6 +6,7 @@
 // 检查
 import { checkApi } from "#befly/checks/api.js";
 import { checkConfig } from "#befly/checks/config.js";
+import { checkCorn } from "#befly/checks/corns.js";
 import { checkHook, checkPlugin } from "#befly/checks/items.js";
 import { checkMenu } from "#befly/checks/menu.js";
 import { checkTable } from "#befly/checks/table.js";
@@ -18,6 +19,8 @@ import { BEFLY_ADMIN_TABLE, BEFLY_API_TABLE, BEFLY_MENU_TABLE, BEFLY_ROLE_TABLE
 import { Connect } from "#befly/lib/connect.js";
 // oxlint-disable-next-line unicorn/prefer-export-from -- Logger 同时被本文件大量使用，不能合并为 re-export
 import { Logger } from "#befly/lib/logger.js";
+// 定时任务
+import { registerCorns } from "#befly/plugins/cron.js";
 // 路由处理
 import { apiHandler } from "#befly/router/api.js";
 import { staticHandler } from "#befly/router/static.js";
@@ -108,7 +111,7 @@ export async function createBefly(config = {}, menus = []) {
     Logger.info(`启动 检查配置 耗时 ${calcPerfTime(stageStartTime)}`);
 
     stageStartTime = Bun.nanoseconds();
-    const { apis, tables, plugins, hooks } = await scanSources();
+    const { apis, tables, plugins, hooks, corns } = await scanSources();
     Logger.info(`启动 扫描源码 耗时 ${calcPerfTime(stageStartTime)}`);
 
     stageStartTime = Bun.nanoseconds();
@@ -127,6 +130,10 @@ export async function createBefly(config = {}, menus = []) {
     const hookErrors = await checkHook(hooks);
     Logger.info(`启动 检查钩子 耗时 ${calcPerfTime(stageStartTime)}`);
 
+    stageStartTime = Bun.nanoseconds();
+    const cornErrors = await checkCorn(corns);
+    Logger.info(`启动 检查定时器 耗时 ${calcPerfTime(stageStartTime)}`);
+
     stageStartTime = Bun.nanoseconds();
     const menuErrors = await checkMenu(mergedMenus);
     Logger.info(`启动 检查菜单 耗时 ${calcPerfTime(stageStartTime)}`);
@@ -138,6 +145,7 @@ export async function createBefly(config = {}, menus = []) {
         { check: "表结构", errors: tableErrors },
         { check: "插件", errors: pluginErrors },
         { check: "钩子", errors: hookErrors },
+        { check: "定时器", errors: cornErrors },
         { check: "菜单", errors: menuErrors }
     ].filter((entry) => entry.errors.length > 0);
 
@@ -161,6 +169,7 @@ export async function createBefly(config = {}, menus = []) {
         apis: apis,
         hooks: hooks,
         plugins: plugins,
+        corns: corns,
         createdByFactory: true
     });
 }
@@ -179,6 +188,7 @@ export class Befly {
         this.hooks = Array.isArray(init.hooks) ? init.hooks : [];
         this.apis = Array.isArray(init.apis) ? init.apis : [];
         this.plugins = Array.isArray(init.plugins) ? init.plugins : [];
+        this.corns = Array.isArray(init.corns) ? init.corns : [];
         this.createdByFactory = init.createdByFactory === true;
     }
 
@@ -217,6 +227,11 @@ export class Befly {
                 Logger.info(`启动 插件 ${item.fileName} 耗时 ${calcPerfTime(pluginStartTime)}`);
             }
 
+            // 注册定时器（依赖插件加载完成的 ctx.cron，非主进程自动跳过）
+            stageStartTime = Bun.nanoseconds();
+            registerCorns(this.context, this.corns);
+            Logger.info(`启动 注册定时器 耗时 ${calcPerfTime(stageStartTime)}`);
+
             stageStartTime = Bun.nanoseconds();
             await syncReady(this.context);
             Logger.info(`启动 同步就绪 耗时 ${calcPerfTime(stageStartTime)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.75.3",
+    "version": "3.76.1",
     "gitHead": "49c39d36695036e85fc64083cc43c1652fff96cb",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",

package/paths.js

@@ -46,6 +46,13 @@ export const coreCheckDir = join(moduleDir, "checks");
  */
 export const corePluginDir = join(moduleDir, "plugins");
 
+/**
+ * Core 框架定时器目录
+ * @description packages/core/corns/
+ * @usage 存放框架内置定时任务（每文件一个定时器）
+ */
+export const coreCornDir = join(moduleDir, "corns");
+
 /**
  * Core 框架钩子目录
  * @description packages/core/hooks/
@@ -90,6 +97,13 @@ export const appCheckDir = join(appDir, "checks");
  */
 export const appPluginDir = join(appDir, "plugins");
 
+/**
+ * 项目定时器目录
+ * @description {appDir}/corns/
+ * @usage 存放用户业务定时任务（每文件一个定时器）
+ */
+export const appCornDir = join(appDir, "corns");
+
 /**
  * 项目钩子目录
  * @description {appDir}/hooks/

package/plugins/cron.js

@@ -4,7 +4,8 @@ import { PLUGIN_ORDER } from "../configs/constConfig.js";
  * 基于 Bun.cron 提供进程内定时任务能力。
  */
 import { Logger } from "../lib/logger.js";
-import { isPrimaryProcess } from "../utils/is.js";
+import { createError } from "../utils/error.js";
+import { isPrimaryProcess, isValidCronSchedule } from "../utils/is.js";
 
 const jobs = new Map();
 
@@ -24,15 +25,26 @@ function register(context, name, schedule, task) {
         return jobs.get(name);
     }
 
-    const job = Bun.cron(schedule, async function () {
-        Logger.info(`[定时任务] ${name} 开始执行`);
-        try {
-            await task(context);
-            Logger.info(`[定时任务] ${name} 执行完成`);
-        } catch (error) {
-            Logger.error(`[定时任务] ${name} 执行失败`, error);
-        }
-    });
+    // 前置校验：表达式非法时启动即报错，避免 Bun.cron 注册时抛裸错
+    if (!isValidCronSchedule(schedule)) {
+        throw createError(`定时任务 ${name} 的 schedule 不是合法的 cron 表达式`, { code: "validation", subsystem: "cron", operation: "register" });
+    }
+
+    // 时区统一走 config.tz（checkConfig 已校验 IANA 合法性），未配置时使用系统时区
+    const tz = context.config?.tz;
+    const job = Bun.cron(
+        schedule,
+        async function () {
+            Logger.info(`[定时任务] ${name} 开始执行`);
+            try {
+                await task(context);
+                Logger.info(`[定时任务] ${name} 执行完成`);
+            } catch (error) {
+                Logger.error(`[定时任务] ${name} 执行失败`, error);
+            }
+        },
+        tz ? { tz: tz } : undefined
+    );
 
     jobs.set(name, job);
     return job;
@@ -73,6 +85,15 @@ function second(context, name, seconds, task) {
     return job;
 }
 
+/**
+ * 批量注册扫描到的定时器（corns/*.js），任务名取文件名
+ */
+export function registerCorns(context, corns) {
+    for (const corn of corns) {
+        register(context, corn.fileName, corn.schedule, corn.handler);
+    }
+}
+
 /**
  * 停止所有已注册的定时任务
  */

package/sync/syncUtil.js

@@ -1,23 +1,17 @@
 // 接口 auth 的存储协议（serializeAuth 与 authAllowsRole 配套使用）：
-// - true -> "是"
-// - false -> "否"
-// - string[] -> "a,b,c"
-export const AUTH_YES = "是";
-export const AUTH_NO = "否";
-
-/**
- * 序列化 api.auth 为存储字符串
- */
+// - true -> 1（需登录）
+// - false -> 0（免登录）
+// - string[] -> "a,b,c"（角色类型白名单，如 admin/user）
 export function serializeAuth(auth) {
-    return auth === false ? AUTH_NO : Array.isArray(auth) ? auth.join(",") : AUTH_YES;
+    return auth === false ? 0 : Array.isArray(auth) ? auth.join(",") : 1;
 }
 
 /**
- * 判断 auth 存储串是否授权给指定角色
+ * 判断 auth 存储值是否授权给指定角色
  */
 export function authAllowsRole(auth, roleCode) {
-    if (auth === AUTH_NO) return true;
-    if (typeof auth === "string" && auth !== AUTH_YES) {
+    if (Number(auth) === 0) return true;
+    if (typeof auth === "string" && Number(auth) !== 1) {
         return auth.split(",").some((code) => code.trim() === roleCode);
     }
     return false;

package/tables/api.json

@@ -1,4 +1,4 @@
-{
+{
     "id": {
         "name": "ID",
         "input": "integer",
@@ -12,7 +12,7 @@
         "max": 100
     },
     "auth": {
-        "name": "是否需要登录",
+        "name": "登录与权限（0=免登录，1=需登录，其他=角色类型白名单）",
         "input": "string",
         "min": 1,
         "max": 200

package/utils/is.js

@@ -187,6 +187,20 @@ export function isValidTimeZone(value) {
     }
 }
 
+/**
+ * 判断值是否为可注册的 cron 表达式（与 Bun.cron 注册行为一致：
+ * parse 抛异常或 8 年内无匹配都视为非法，避免启动后才报错）。
+ */
+export function isValidCronSchedule(value) {
+    if (!isString(value)) return false;
+
+    try {
+        return Bun.cron.parse(value) !== null;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * 判断值是否为有限整数。
  */

package/utils/scanSources.js

@@ -7,7 +7,9 @@ import {
     coreHookDir,
     appHookDir,
     coreApiDir,
-    appApiDir
+    appApiDir,
+    coreCornDir,
+    appCornDir
 } from "../paths.js";
 import { createError } from "./error.js";
 import { scanFiles } from "./scanFiles.js";
@@ -17,6 +19,7 @@ export const scanSources = async () => {
     const plugins = [];
     const hooks = [];
     const tables = {};
+    const corns = [];
 
     // 处理表格
     const allCoreTables = await scanFiles(coreTableDir, "core", "table", "*.json");
@@ -48,6 +51,16 @@ export const scanSources = async () => {
         hooks.push(item);
     }
 
+    // 处理定时器
+    const allCoreCorns = await scanFiles(coreCornDir, "core", "corn", "*.js");
+    for (const item of allCoreCorns) {
+        corns.push(item);
+    }
+    const allAppCorns = await scanFiles(appCornDir, "app", "corn", "*.js");
+    for (const item of allAppCorns) {
+        corns.push(item);
+    }
+
     // 处理接口
     const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
     for (const item of allCoreApis) {
@@ -70,6 +83,7 @@ export const scanSources = async () => {
         hooks: hooks,
         plugins: plugins,
         apis: apis,
-        tables: tables
+        tables: tables,
+        corns: corns
     };
 };

package/apis/role/delete.js

@@ -1,41 +0,0 @@
-import { getRoleById, systemRoleCodes } from "./_role.js";
-
-export default {
-    name: "删除角色",
-    method: "POST",
-    body: "none",
-    auth: true,
-    fields: {
-        id: { name: "ID", input: "integer", min: 1, max: null }
-    },
-    required: ["id"],
-    handler: async (befly, ctx) => {
-        const role = await getRoleById(befly, ctx.body.id, ["code"]);
-
-        if (!role.data?.code) {
-            return befly.tool.No("角色不存在");
-        }
-
-        if (systemRoleCodes.includes(role.data.code)) {
-            return befly.tool.No(`系统角色 [${role.data.code}] 不允许删除`);
-        }
-
-        const adminList = await befly.mysql.getList({
-            table: "beflyAdmin",
-            where: { roleCode: role.data.code }
-        });
-
-        if (adminList.data.total > 0) {
-            return befly.tool.No("该角色已分配给用户，无法删除");
-        }
-
-        await befly.mysql.delData({
-            table: "beflyRole",
-            where: { id: ctx.body.id }
-        });
-
-        await befly.cache.deleteRoleApis(role.data.code);
-
-        return befly.tool.Yes("操作成功");
-    }
-};

package/apis/role/insert.js

@@ -1,45 +0,0 @@
-import roleTable from "#befly/tables/role.json";
-
-export default {
-    name: "创建角色",
-    method: "POST",
-    body: "none",
-    auth: true,
-    fields: {
-        name: roleTable.name,
-        code: roleTable.code,
-        description: roleTable.description,
-        menus: roleTable.menus,
-        apis: roleTable.apis,
-        sort: roleTable.sort
-    },
-    required: [],
-    handler: async (befly, ctx) => {
-        const menuPaths = ctx.body.menus || [];
-        const apiPaths = ctx.body.apis || [];
-        const existing = await befly.mysql.getOne({
-            table: "beflyRole",
-            where: { code: ctx.body.code }
-        });
-
-        if (existing.data?.id) {
-            return befly.tool.No("角色代码已存在");
-        }
-
-        const roleId = await befly.mysql.insData({
-            table: "beflyRole",
-            data: {
-                name: ctx.body.name,
-                code: ctx.body.code,
-                description: ctx.body.description,
-                menus: menuPaths,
-                apis: apiPaths,
-                sort: ctx.body.sort
-            }
-        });
-
-        await befly.cache.refreshRoleApis(ctx.body.code, apiPaths);
-
-        return befly.tool.Yes("操作成功", { id: roleId.data });
-    }
-};

package/apis/role/save.js

@@ -1,36 +0,0 @@
-import adminTable from "#befly/tables/admin.json";
-import roleTable from "#befly/tables/role.json";
-
-import { getRoleByCode } from "./_role.js";
-
-export default {
-    name: "角色保存",
-    method: "POST",
-    body: "none",
-    auth: true,
-    fields: {
-        adminId: adminTable.id,
-        roleCode: roleTable.code
-    },
-    required: ["adminId", "roleCode"],
-    handler: async (befly, ctx) => {
-        const role = await getRoleByCode(befly, ctx.body.roleCode);
-
-        if (!role.data?.id) {
-            return befly.tool.No("角色不存在");
-        }
-
-        const roleType = role.data.code === "dev" || role.data.code === "admin" ? "admin" : "user";
-
-        await befly.mysql.updData({
-            table: "beflyAdmin",
-            where: { id: ctx.body.adminId },
-            data: {
-                roleCode: role.data.code,
-                roleType: roleType
-            }
-        });
-
-        return befly.tool.Yes("操作成功");
-    }
-};

package/apis/role/update.js

@@ -1,66 +0,0 @@
-import roleTable from "#befly/tables/role.json";
-
-import { getRoleById } from "./_role.js";
-
-export default {
-    name: "更新角色",
-    method: "POST",
-    body: "none",
-    auth: true,
-    fields: {
-        id: roleTable.id,
-        name: roleTable.name,
-        code: roleTable.code,
-        description: roleTable.description,
-        menus: roleTable.menus,
-        apis: roleTable.apis,
-        sort: roleTable.sort
-    },
-    required: ["id"],
-    handler: async (befly, ctx) => {
-        const role = await getRoleById(befly, ctx.body.id);
-
-        if (!role.data?.id) {
-            return befly.tool.No("角色不存在");
-        }
-
-        if (ctx.body.code !== undefined) {
-            const existing = await befly.mysql.getOne({
-                table: "beflyRole",
-                where: {
-                    code: ctx.body.code,
-                    id$not: ctx.body.id
-                }
-            });
-
-            if (existing.data?.id) {
-                return befly.tool.No("角色代码已被其他角色使用");
-            }
-        }
-
-        const roleCode = ctx.body.code === undefined ? role.data.code : ctx.body.code;
-        const apiPaths = ctx.body.apis === undefined ? role.data.apis || [] : ctx.body.apis;
-        const menuPaths = ctx.body.menus === undefined ? role.data.menus || [] : ctx.body.menus;
-
-        await befly.mysql.updData({
-            table: "beflyRole",
-            where: { id: ctx.body.id },
-            data: {
-                name: ctx.body.name,
-                code: roleCode,
-                description: ctx.body.description,
-                menus: menuPaths,
-                apis: apiPaths,
-                sort: ctx.body.sort
-            }
-        });
-
-        if (role.data.code !== roleCode) {
-            await befly.cache.deleteRoleApis(role.data.code);
-        }
-
-        await befly.cache.refreshRoleApis(roleCode, apiPaths);
-
-        return befly.tool.Yes("操作成功");
-    }
-};