befly 3.76.7 → 3.77.1

package/utils/scanFiles.js

@@ -12,6 +12,42 @@ const selectFields = {
     state: { name: "状态", paramType: "integer" }
 };
 
+/**
+ * 扫描接口目录下的 _meta.js 目录元数据（约定：_ 前缀文件不注册路由）。
+ * 返回 Map<目录 apiPath, 中文标题>，键与接口 apiPath 的目录部分对齐，供 scanSources 挂载 parentTitle。
+ */
+export async function scanApiMetaTitles(dir, source) {
+    const titles = new Map();
+    if (!existsSync(dir)) return titles;
+
+    const glob = new Bun.Glob("**/_meta.js");
+    const files = await Array.fromAsync(
+        glob.scan({
+            cwd: dir,
+            onlyFiles: true,
+            absolute: true,
+            followSymlinks: true
+        })
+    );
+
+    for (const file of files) {
+        const filePath = normalize(file);
+        const meta = await importDefault(filePath, {});
+        const record = isPlainObject(meta) ? meta : {};
+        const title = record.title;
+        if (typeof title !== "string" || title.trim().length === 0 || title.trim().length > 50) {
+            throw createError(`目录元数据无效：${filePath} 的 title 必须是 1-50 个字符`, { code: "policy", subsystem: "scan", operation: "scanApiMetaTitles" });
+        }
+
+        const parsedRelativePath = parse(relative(dir, filePath));
+        const relativeDir = parsedRelativePath.dir.replaceAll("\\", "/");
+        const dirApiPath = source === "core" ? `/api/core/${relativeDir}` : `/api/${relativeDir}`;
+        titles.set(dirApiPath, title.trim());
+    }
+
+    return titles;
+}
+
 /**
  * 扫描指定目录下的文件
  * @param dir 目录路径
@@ -24,58 +60,61 @@ export async function scanFiles(dir, source, type, pattern) {
         const glob = new Bun.Glob(pattern);
         if (!existsSync(dir)) return [];
 
-        const results = [];
+        const files = await Array.fromAsync(
+            glob.scan({
+                cwd: dir,
+                onlyFiles: true,
+                absolute: true,
+                followSymlinks: true
+            })
+        );
 
-        const files = await glob.scan({
-            cwd: dir,
-            onlyFiles: true,
-            absolute: true,
-            followSymlinks: true
-        });
+        // 并行导入源文件，Promise.all 保持与扫描顺序一致的结果顺序
+        const results = await Promise.all(
+            files.map(async (file) => {
+                const filePath = normalize(file);
+                const parsedFile = parse(filePath);
 
-        for await (const file of files) {
-            const filePath = normalize(file);
-            const parsedFile = parse(filePath);
+                // 获取文件名（去除扩展名）
+                const fileName = parsedFile.name;
 
-            // 获取文件名（去除扩展名）
-            const fileName = parsedFile.name;
+                // 计算相对路径（去除扩展名）
+                const parsedRelativePath = parse(relative(dir, filePath));
+                const relativePath = (parsedRelativePath.dir ? join(parsedRelativePath.dir, parsedRelativePath.name) : parsedRelativePath.name).replaceAll("\\", "/");
 
-            // 计算相对路径（去除扩展名）
-            const parsedRelativePath = parse(relative(dir, filePath));
-            const relativePath = (parsedRelativePath.dir ? join(parsedRelativePath.dir, parsedRelativePath.name) : parsedRelativePath.name).replaceAll("\\", "/");
+                // 固定默认过滤（不可关闭）：忽略下划线开头的文件/目录
+                if (relativePath.split("/").some((part) => part.startsWith("_"))) return null;
+                const content = await importDefault(filePath, {});
+                const contentObj = isPlainObject(content) ? content : {};
 
-            // 固定默认过滤（不可关闭）：忽略下划线开头的文件/目录
-            if (relativePath.split("/").some((part) => part.startsWith("_"))) continue;
-            const content = await importDefault(filePath, {});
-            const contentObj = isPlainObject(content) ? content : {};
-
-            const base = {
-                source: source,
-                type: type,
-                filePath: filePath,
-                relativePath: relativePath,
-                fileName: fileName,
-                apiPath: source === "core" ? `/api/${source}/${relativePath}` : `/api/${relativePath}`
-            };
-            if (type === "table") {
-                base["fieldsDef"] = contentObj;
-            }
-            if (type === "api") {
-                base["name"] = "";
-            }
-            if (type !== "table") {
-                for (const [key, value] of Object.entries(contentObj)) {
-                    if (base[key]) continue;
-                    base[key] = value;
+                const base = {
+                    source: source,
+                    type: type,
+                    filePath: filePath,
+                    relativePath: relativePath,
+                    fileName: fileName,
+                    apiPath: source === "core" ? `/api/${source}/${relativePath}` : `/api/${relativePath}`
+                };
+                if (type === "table") {
+                    base["fieldsDef"] = contentObj;
                 }
-            }
-            if (type === "api") {
-                base.category ||= "other";
-                if (base.category === "select") base.fields = { ...selectFields, ...base.fields };
-            }
-            results.push(base);
-        }
-        return results;
+                if (type === "api") {
+                    base["name"] = "";
+                }
+                if (type !== "table") {
+                    for (const [key, value] of Object.entries(contentObj)) {
+                        if (base[key]) continue;
+                        base[key] = value;
+                    }
+                }
+                if (type === "api") {
+                    base.category ||= "other";
+                    if (base.category === "select") base.fields = { ...selectFields, ...base.fields };
+                }
+                return base;
+            })
+        );
+        return results.filter((item) => item !== null);
     } catch (error) {
         throw createError(`扫描失败: source=${source} type=${type} dir=${dir} pattern=${pattern}`, { cause: error, code: "runtime" });
     }

package/utils/scanSources.js

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+
+import { Logger } from "../libs/logger/index.js";
 import { buildTableModel } from "../libs/tableModel.js";
 import {
     //
@@ -13,7 +16,42 @@ import {
     appCornDir
 } from "../paths.js";
 import { createError } from "./error.js";
-import { scanFiles } from "./scanFiles.js";
+import { scanApiMetaTitles, scanFiles } from "./scanFiles.js";
+
+// 逐级拼接目录显示标题：每级目录有 _meta.js 标题用标题，没有用目录名，以 / 连接
+// 例：/api/admin/product/insert + 标题映射 -> "后台管理/product"
+export function composeTitlePath(apiPath, metaTitles, missingCollector) {
+    const segments = apiPath.split("/").filter(Boolean);
+    const start = segments[1] === "core" ? 2 : 1;
+    const dirs = segments.slice(start, -1);
+    if (dirs.length === 0) return "";
+
+    const parts = [];
+    let current = `/${segments.slice(0, start).join("/")}`;
+    for (const dir of dirs) {
+        current = `${current}/${dir}`;
+        const title = metaTitles.get(current);
+        if (title) {
+            parts.push(title);
+        } else {
+            parts.push(dir);
+            if (missingCollector) missingCollector.add(current);
+        }
+    }
+    return parts.join("/");
+}
+
+function warnWhenAppSourcesMissing() {
+    // 全部 app 源码目录都不存在时显式告警，避免"项目源码静默消失、以纯 core 形态运行"的配置事故
+    const appDirs = [appApiDir, appTableDir, appPluginDir, appHookDir, appCornDir];
+    if (appDirs.every((dir) => !existsSync(dir))) {
+        Logger.warn("项目源码目录（apis/tables/plugins/hooks/corns）均不存在，请检查启动目录是否为项目根目录", {
+            subsystem: "scan",
+            operation: "scanSources",
+            appDir: appDirs[0]
+        });
+    }
+}
 
 export function assertUnique(items, key, label) {
     const values = new Map();
@@ -72,6 +110,8 @@ export const scanSources = async ({ beflyMode = "auto" } = {}) => {
     const tables = await scanTables({ beflyMode: beflyMode });
     const corns = [];
 
+    warnWhenAppSourcesMissing();
+
     // 处理插件
     const allCorePlugins = await scanFiles(corePluginDir, "core", "plugin", "*.js");
     for (const item of allCorePlugins) {
@@ -102,17 +142,29 @@ export const scanSources = async ({ beflyMode = "auto" } = {}) => {
         corns.push(item);
     }
 
-    // 处理接口
-    const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
+    // 处理接口（读取目录 _meta.js 标题挂载 parentTitle）；
+    // 每一级接口目录都必须有中文标题，缺失即启动失败并列出清单
+    const [allCoreApis, coreMetaTitles, allAppApis, appMetaTitles] = await Promise.all([scanFiles(coreApiDir, "core", "api", "**/*.js"), scanApiMetaTitles(coreApiDir, "core"), scanFiles(appApiDir, "app", "api", "**/*.js"), scanApiMetaTitles(appApiDir, "app")]);
+
+    const missingTitleDirs = new Set();
     for (const item of allCoreApis) {
+        item.parentTitle = composeTitlePath(item.apiPath, coreMetaTitles, missingTitleDirs);
         apis.push(item);
     }
-    const allAppApis = await scanFiles(appApiDir, "app", "api", "**/*.js");
     for (const item of allAppApis) {
         assertAppApiNamespace(item);
+        item.parentTitle = composeTitlePath(item.apiPath, appMetaTitles, missingTitleDirs);
         apis.push(item);
     }
 
+    if (missingTitleDirs.size > 0) {
+        throw createError(`以下接口目录缺少 _meta.js 中文标题：${Array.from(missingTitleDirs).toSorted().join("、")}`, {
+            code: "policy",
+            subsystem: "scan",
+            operation: "scanSources"
+        });
+    }
+
     assertUnique(plugins, "fileName", "Plugin 文件名");
     assertUnique(hooks, "fileName", "Hook 文件名");
     assertUnique(corns, "fileName", "Cron 文件名");

package/utils/util.js

@@ -37,7 +37,11 @@ export function getRunMode() {
 }
 
 export function toSessionTtlSeconds(ttlDays) {
-    return ttlDays * 24 * 60 * 60;
+    const parsed = typeof ttlDays === "number" ? ttlDays : Number(String(ttlDays ?? "").trim());
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return Math.floor(parsed * 24 * 60 * 60);
+    }
+    return 7 * 24 * 60 * 60;
 }
 
 export function genShortId() {