befly 3.9.40 → 3.10.0

package/sync/syncMenu.ts

@@ -1,521 +1,307 @@
-/**
- * SyncMenu 命令 - 同步菜单数据到数据库
- * 说明：扫描 addon 的 views 目录和项目的 menus.json，同步菜单数据
- *
- * 流程：
- * 1. 扫描所有 addon 的 views 目录下的 index.vue，并从 definePage({ meta }) 解析菜单元信息
- * 2. 根据目录层级构建菜单树（无层级限制）
- * 3. 读取项目的 menus.json 文件（手动配置的菜单）
- * 4. 根据菜单的 path 字段检查是否存在
- * 5. 存在则更新其他字段（name、sort、pid）
- * 6. 不存在则新增菜单记录
- * 7. 强制删除配置中不存在的菜单记录
- * 注：state 字段由框架自动管理（1=正常，2=禁用，0=删除）
- */
-
-import type { SyncMenuOptions, MenuConfig } from "../types/sync.js";
-
-import { existsSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
-
-import { join } from "pathe";
-
-import { beflyConfig } from "../befly.config.js";
-import { CacheKeys } from "../lib/cacheKeys.js";
-import { Connect } from "../lib/connect.js";
-import { DbHelper } from "../lib/dbHelper.js";
-import { Logger } from "../lib/logger.js";
-import { RedisHelper } from "../lib/redisHelper.js";
-import { projectDir } from "../paths.js";
-import { scanAddons, getAddonDir } from "../utils/addonHelper.js";
-
-/**
- * 清理目录名中的数字后缀
- * 如：login_1 → login, index_2 → index
- */
-function cleanDirName(name: string): string {
-    return name.replace(/_\d+$/, "");
-}
+import type { BeflyContext } from "../types/befly.js";
+import type { MenuConfig } from "../types/sync.js";
 
-type ViewDirMeta = {
-    title: string;
-    order?: number;
+import { Logger } from "../lib/logger.js";
+import { compileDisableMenuGlobRules, isMenuPathDisabledByGlobRules } from "../utils/disableMenusGlob.js";
+import { getParentPath } from "../utils/loadMenuConfigs.js";
+
+type MenuDef = {
+    path: string;
+    name: string;
+    sort: number;
+    parentPath: string;
 };
 
-function normalizeMenuPath(path: string): string {
-    // 约束：统一 path 形态，避免隐藏菜单匹配、DB 同步出现重复
-    // - 必须以 / 开头
-    // - 折叠多个 /
-    // - 去掉尾随 /（根 / 除外）
-    let result = path;
-
-    if (!result) {
-        return "/";
+function flattenMenusToDefMap(mergedMenus: MenuConfig[]): Map<string, MenuDef> {
+    // 读取配置菜单：扁平化为 path => { name, sort, parentPath }
+    // - 以 path 为唯一键：后出现的覆盖先出现的（与旧逻辑“同 path 多次同步同一条记录”一致）
+    // parentPath 规则：
+    // 1) 若 menu 显式携带 parentPath（包括空字符串），以其为准
+    // 2) 否则使用“树结构”推导的父级（由 children 嵌套关系决定；根级为 ""）
+    // 3) 保底：若无法推导（极端情况），回退到 getParentPath(path)
+    const menuDefMap = new Map<string, MenuDef>();
+
+    const stack: Array<{ menu: MenuConfig; parentPathFromTree: string }> = [];
+    for (const m of mergedMenus) {
+        stack.push({ menu: m, parentPathFromTree: "" });
     }
 
-    if (!result.startsWith("/")) {
-        result = `/${result}`;
-    }
-
-    result = result.replace(/\/+/g, "/");
-
-    if (result.length > 1) {
-        result = result.replace(/\/+$/, "");
-    }
-
-    return result;
-}
-
-function normalizeMenuTree(menus: MenuConfig[]): MenuConfig[] {
-    // 递归规范化并按 path 去重（同 path 的 children 合并）
-    const map = new Map<string, MenuConfig>();
+    while (stack.length > 0) {
+        const item = stack.pop();
+        const menu = item ? item.menu : null;
+        if (!menu) {
+            continue;
+        }
 
-    for (const menu of menus) {
-        const menuPath = menu.path ? normalizeMenuPath(menu.path) : "";
-        const cloned: MenuConfig = {
-            name: menu.name,
-            path: menuPath,
-            sort: menu.sort
-        };
+        const path = typeof (menu as any).path === "string" ? (menu as any).path : "";
 
-        if (menu.children && menu.children.length > 0) {
-            cloned.children = normalizeMenuTree(menu.children);
+        const rawChildren = (menu as any).children;
+        if (rawChildren && Array.isArray(rawChildren) && rawChildren.length > 0) {
+            const nextParentPathFromTree = typeof path === "string" ? path : "";
+            for (const child of rawChildren) {
+                stack.push({ menu: child, parentPathFromTree: nextParentPathFromTree });
+            }
         }
 
-        if (!menuPath) {
-            // path 缺失的菜单无法参与同步/去重，直接丢弃
+        if (!path) {
             continue;
         }
 
-        const existing = map.get(menuPath);
-        if (existing) {
-            if (cloned.children && cloned.children.length > 0) {
-                existing.children = existing.children || [];
-                existing.children.push(...cloned.children);
-                existing.children = normalizeMenuTree(existing.children);
-            }
-            if (typeof cloned.sort === "number") {
-                existing.sort = cloned.sort;
-            }
-            if (cloned.name) {
-                existing.name = cloned.name;
-            }
-        } else {
-            map.set(menuPath, cloned);
+        const name = typeof (menu as any).name === "string" ? (menu as any).name : "";
+        if (!name) {
+            continue;
         }
-    }
 
-    const result = Array.from(map.values());
-    result.sort((a, b) => (a.sort || 1) - (b.sort || 1));
-    return result;
-}
+        const sort = typeof (menu as any).sort === "number" ? (menu as any).sort : 999999;
 
-function extractScriptSetupBlock(vueContent: string): string | null {
-    // 只取第一个 <script ... setup ...> 块
-    const openTag = /<script\b[^>]*\bsetup\b[^>]*>/i.exec(vueContent);
-    if (!openTag) {
-        return null;
-    }
+        const hasExplicitParentPath = typeof (menu as any).parentPath === "string";
+        const parentPath = hasExplicitParentPath ? ((menu as any).parentPath as string) : typeof item?.parentPathFromTree === "string" ? item.parentPathFromTree : getParentPath(path);
 
-    const start = openTag.index + openTag[0].length;
-    const closeIndex = vueContent.indexOf("</script>", start);
-    if (closeIndex < 0) {
-        return null;
+        menuDefMap.set(path, {
+            path: path,
+            name: name,
+            sort: sort,
+            parentPath: parentPath
+        });
     }
 
-    return vueContent.slice(start, closeIndex);
+    return menuDefMap;
 }
 
-function extractDefinePageMetaFromScriptSetup(scriptSetup: string): ViewDirMeta | null {
-    // 简化约束：
-    // - 每个页面只有一个 definePage
-    // - title 是纯字符串字面量
-    // - order 是数字字面量（可选）
-    // - 不考虑变量/表达式/多段 meta 组合
+export async function syncMenu(ctx: BeflyContext, mergedMenus: MenuConfig[]): Promise<void> {
+    if (!ctx.db) {
+        throw new Error("syncMenu: ctx.db 未初始化（Db 插件未加载或注入失败）");
+    }
 
-    const titleMatch = scriptSetup.match(/definePage\s*\([\s\S]*?meta\s*:\s*\{[\s\S]*?title\s*:\s*(["'`])([^"'`]+)\1/);
-    if (!titleMatch) {
-        return null;
+    if (!ctx.cache) {
+        throw new Error("syncMenu: ctx.cache 未初始化（cache 插件未加载或注入失败）");
     }
 
-    const orderMatch = scriptSetup.match(/definePage\s*\([\s\S]*?meta\s*:\s*\{[\s\S]*?order\s*:\s*(\d+)/);
+    if (!ctx.config) {
+        throw new Error("syncMenu: ctx.config 未初始化（config 插件未加载或注入失败）");
+    }
 
-    return {
-        title: titleMatch[2],
-        order: orderMatch ? Number(orderMatch[1]) : undefined
-    };
-}
+    if (!(await ctx.db.tableExists("addon_admin_menu"))) {
+        Logger.debug(`addon_admin_menu 表不存在`);
+        return;
+    }
 
-/**
- * 扫描 views 目录，构建菜单树
- * @param viewsDir views 目录路径
- * @param prefix 路径前缀（addon 前缀）
- * @param parentPath 父级路径
- * @returns 菜单数组
- */
-async function scanViewsDir(viewsDir: string, prefix: string, parentPath: string = ""): Promise<MenuConfig[]> {
-    if (!existsSync(viewsDir)) {
-        return [];
+    // 防御性过滤：保证禁用菜单不会进入 DB（即使上游遗漏了 checkMenu 的过滤）
+    const disableRules = compileDisableMenuGlobRules(ctx.config?.disableMenus);
+    const filteredMergedMenus: MenuConfig[] =
+        disableRules.length === 0
+            ? mergedMenus
+            : (() => {
+                  const filterMenusByDisableRules = (menus: MenuConfig[]): MenuConfig[] => {
+                      const filtered: MenuConfig[] = [];
+
+                      for (const menu of menus) {
+                          const menuPath = typeof (menu as any)?.path === "string" ? String((menu as any).path).trim() : "";
+                          if (menuPath && isMenuPathDisabledByGlobRules(menuPath, disableRules)) {
+                              continue;
+                          }
+
+                          const children = Array.isArray((menu as any)?.children) ? ((menu as any).children as MenuConfig[]) : null;
+                          if (children && children.length > 0) {
+                              const nextChildren = filterMenusByDisableRules(children);
+                              if (nextChildren.length > 0) {
+                                  (menu as any).children = nextChildren;
+                              } else {
+                                  delete (menu as any).children;
+                              }
+                          }
+
+                          filtered.push(menu);
+                      }
+
+                      return filtered;
+                  };
+
+                  return filterMenusByDisableRules(mergedMenus);
+              })();
+
+    const menuDefMap = flattenMenusToDefMap(filteredMergedMenus);
+
+    const configPaths = new Set<string>();
+    for (const p of menuDefMap.keys()) {
+        configPaths.add(p);
     }
 
-    const menus: MenuConfig[] = [];
-    const entries = await readdir(viewsDir, { withFileTypes: true });
+    const tableName = "addon_admin_menu";
 
-    for (const entry of entries) {
-        // 只处理目录，忽略 components 目录
-        if (!entry.isDirectory() || entry.name === "components") {
-            continue;
-        }
+    // 2) 批量同步（事务内）：按 path diff 执行批量 insert/update/delete
+    await ctx.db.trans(async (trans: any) => {
+        // 读取全部菜单（用于清理禁用菜单：不分 state）
+        const allExistingMenusAllState = await trans.getAll({
+            table: tableName,
+            fields: ["id", "name", "path", "parentPath", "sort", "state"]
+        } as any);
 
-        const dirPath = join(viewsDir, entry.name);
-        const indexVuePath = join(dirPath, "index.vue");
+        const existingListAllState = allExistingMenusAllState.lists || [];
+        const existingList = existingListAllState.filter((m: any) => typeof m?.state === "number" && m.state >= 0);
 
-        // 没有 index.vue 的目录不处理
-        if (!existsSync(indexVuePath)) {
-            continue;
-        }
+        const existingMenuMap = new Map<string, any>();
+        const duplicateIdSet = new Set<number>();
+        const duplicatePathInfoMap = new Map<string, { keptId: number; removedIds: number[] }>();
 
-        // 从 index.vue 中解析 definePage({ meta })
-        let meta: ViewDirMeta | null = null;
-        try {
-            const content = await readFile(indexVuePath, "utf-8");
-
-            const scriptSetup = extractScriptSetupBlock(content);
-            if (!scriptSetup) {
-                Logger.warn({ path: indexVuePath }, "index.vue 缺少 <script setup>，已跳过该目录菜单同步");
+        for (const record of existingList) {
+            if (typeof record?.path !== "string" || !record.path) {
+                continue;
+            }
+            if (typeof record?.id !== "number") {
                 continue;
             }
 
-            meta = extractDefinePageMetaFromScriptSetup(scriptSetup);
-            if (!meta?.title) {
-                Logger.warn({ path: indexVuePath }, "index.vue 未声明 definePage({ meta: { title, order? } })，已跳过该目录菜单同步");
+            const existing = existingMenuMap.get(record.path);
+            if (!existing) {
+                existingMenuMap.set(record.path, record);
                 continue;
             }
-        } catch (error: any) {
-            Logger.warn({ err: error, path: indexVuePath }, "读取 index.vue 失败");
-            continue;
-        }
 
-        // 没有 definePage meta 的目录不处理
-        if (!meta?.title) {
-            continue;
-        }
+            const existingId = typeof existing?.id === "number" ? existing.id : 0;
+            const recordId = record.id;
 
-        // 计算路径：清理数字后缀，index 目录特殊处理
-        const cleanName = cleanDirName(entry.name);
-        let menuPath: string;
-        if (cleanName === "index") {
-            // index 目录路径为父级路径；根级别用空字符串（避免 addon prefix 拼出尾随 /）
-            menuPath = parentPath;
-        } else {
-            menuPath = parentPath ? `${parentPath}/${cleanName}` : `/${cleanName}`;
-        }
+            // 保留 id 最大的一条（genTimeID 越大通常越新），其余标记为重复并清理
+            if (recordId > existingId) {
+                existingMenuMap.set(record.path, record);
 
-        // 添加 addon 前缀
-        const fullPath = prefix ? (menuPath ? `${prefix}${menuPath}` : prefix) : menuPath || "/";
+                if (existingId > 0) {
+                    duplicateIdSet.add(existingId);
+                }
 
-        const menu: MenuConfig = {
-            name: meta.title,
-            path: fullPath,
-            sort: meta.order || 1
-        };
+                const info = duplicatePathInfoMap.get(record.path) || { keptId: recordId, removedIds: [] as number[] };
+                info.keptId = recordId;
+                if (existingId > 0) {
+                    info.removedIds.push(existingId);
+                }
+                duplicatePathInfoMap.set(record.path, info);
+            } else {
+                if (recordId > 0) {
+                    duplicateIdSet.add(recordId);
+                }
 
-        // 递归扫描子目录
-        const children = await scanViewsDir(dirPath, prefix, menuPath);
-        if (children.length > 0) {
-            menu.children = children;
+                const info = duplicatePathInfoMap.get(record.path) || { keptId: existingId, removedIds: [] as number[] };
+                info.keptId = existingId;
+                if (recordId > 0) {
+                    info.removedIds.push(recordId);
+                }
+                duplicatePathInfoMap.set(record.path, info);
+            }
         }
 
-        menus.push(menu);
-    }
-
-    // 按 sort 排序
-    menus.sort((a, b) => (a.sort || 1) - (b.sort || 1));
-
-    return menus;
-}
+        if (duplicatePathInfoMap.size > 0) {
+            const examples: Array<{ path: string; keptId: number; removedIds: number[] }> = [];
+            for (const entry of duplicatePathInfoMap.entries()) {
+                const path = entry[0];
+                const info = entry[1];
+                examples.push({ path: path, keptId: info.keptId, removedIds: info.removedIds });
+                if (examples.length >= 10) {
+                    break;
+                }
+            }
 
-/**
- * 合并菜单配置
- * 支持无限层级菜单结构
- */
-function mergeMenuConfigs(allMenus: Array<{ menus: MenuConfig[]; source: string }>): MenuConfig[] {
-    const menuMap = new Map<string, MenuConfig>();
+            Logger.warn(
+                {
+                    table: tableName,
+                    duplicatePaths: duplicatePathInfoMap.size,
+                    duplicateIds: duplicateIdSet.size,
+                    examples: examples
+                },
+                "addon_admin_menu 检测到重复 path 记录：已保留 id 最大的一条并删除其余记录"
+            );
+        }
 
-    for (const { menus } of allMenus) {
-        for (const menu of menus) {
-            if (!menu.path) continue;
+        // 2) 一次性算出 insert/update（仅依赖 path diff，不使用 pid，不预生成 id）
+        const updList: Array<{ id: number; data: Record<string, any> }> = [];
+        const insList: Array<Record<string, any>> = [];
 
-            const existing = menuMap.get(menu.path);
+        for (const def of menuDefMap.values()) {
+            const existing = existingMenuMap.get(def.path);
             if (existing) {
-                // 合并子菜单
-                if (menu.children && menu.children.length > 0) {
-                    existing.children = existing.children || [];
-                    existing.children.push(...menu.children);
+                const existingParentPath = typeof existing.parentPath === "string" ? existing.parentPath : "";
+                const needUpdate = existing.name !== def.name || existing.sort !== def.sort || existingParentPath !== def.parentPath;
+                if (needUpdate) {
+                    updList.push({
+                        id: existing.id,
+                        data: {
+                            name: def.name,
+                            path: def.path,
+                            parentPath: def.parentPath,
+                            sort: def.sort
+                        }
+                    });
                 }
             } else {
-                menuMap.set(menu.path, { ...menu });
+                insList.push({
+                    name: def.name,
+                    path: def.path,
+                    parentPath: def.parentPath,
+                    sort: def.sort
+                });
             }
         }
-    }
-
-    return Array.from(menuMap.values());
-}
 
-/**
- * 过滤隐藏的菜单（递归处理子菜单）
- */
-function filterHiddenMenus(menus: MenuConfig[], hiddenSet: Set<string>): MenuConfig[] {
-    const result: MenuConfig[] = [];
-
-    for (const menu of menus) {
-        // 如果菜单在隐藏列表中，跳过
-        if (menu.path && hiddenSet.has(menu.path)) {
-            continue;
+        if (updList.length > 0) {
+            await trans.updBatch(tableName, updList);
         }
 
-        const filtered = { ...menu };
-
-        // 递归过滤子菜单
-        if (filtered.children && filtered.children.length > 0) {
-            filtered.children = filterHiddenMenus(filtered.children, hiddenSet);
+        if (insList.length > 0) {
+            await trans.insBatch(tableName, insList);
         }
 
-        result.push(filtered);
-    }
-
-    return result;
-}
-
-/**
- * 收集所有菜单的 path（递归收集所有层级）
- */
-function collectPaths(menus: MenuConfig[]): Set<string> {
-    const paths = new Set<string>();
+        // 3) 删除差集（DB - 配置，仅 state>=0） + 删除重复 path 的多余记录 + 删除禁用菜单（不分 state）
+        const delIdSet = new Set<number>();
 
-    function collect(items: MenuConfig[]): void {
-        for (const menu of items) {
-            if (menu.path) {
-                paths.add(menu.path);
-            }
-            if (menu.children && menu.children.length > 0) {
-                collect(menu.children);
-            }
-        }
-    }
-
-    collect(menus);
-    return paths;
-}
+        // 3.1) 清理禁用菜单：只要命中 disableMenus，就强制删除（避免 menu/list 之类接口还能查到）
+        if (disableRules.length > 0) {
+            for (const record of existingListAllState) {
+                const recordPath = typeof record?.path === "string" ? String(record.path).trim() : "";
+                if (!recordPath) {
+                    continue;
+                }
 
-/**
- * 递归同步单个菜单（无层级限制）
- */
-async function syncMenuRecursive(helper: any, menu: MenuConfig, pid: number, existingMenuMap: Map<string, any>): Promise<number> {
-    const existing = existingMenuMap.get(menu.path || "");
-    let menuId: number;
-
-    if (existing) {
-        menuId = existing.id;
-
-        const needUpdate = existing.pid !== pid || existing.name !== menu.name || existing.sort !== (menu.sort || 1);
-
-        if (needUpdate) {
-            await helper.updData({
-                table: "addon_admin_menu",
-                where: { id: existing.id },
-                data: {
-                    pid: pid,
-                    name: menu.name,
-                    sort: menu.sort || 1
+                if (isMenuPathDisabledByGlobRules(recordPath, disableRules)) {
+                    if (typeof record?.id === "number" && record.id > 0) {
+                        delIdSet.add(record.id);
+                    }
                 }
-            });
-        }
-    } else {
-        menuId = await helper.insData({
-            table: "addon_admin_menu",
-            data: {
-                pid: pid,
-                name: menu.name,
-                path: menu.path || "",
-                sort: menu.sort || 1
             }
-        });
-    }
-
-    if (menu.children && menu.children.length > 0) {
-        for (const child of menu.children) {
-            await syncMenuRecursive(helper, child, menuId, existingMenuMap);
-        }
-    }
-
-    return menuId;
-}
-
-/**
- * 同步菜单到数据库
- */
-async function syncMenus(helper: any, menus: MenuConfig[]): Promise<void> {
-    const allExistingMenus = await helper.getAll({
-        table: "addon_admin_menu"
-    });
-    const existingMenuMap = new Map<string, any>();
-    for (const menu of allExistingMenus.lists) {
-        if (menu.path) {
-            existingMenuMap.set(menu.path, menu);
-        }
-    }
-
-    for (const menu of menus) {
-        try {
-            await syncMenuRecursive(helper, menu, 0, existingMenuMap);
-        } catch (error: any) {
-            Logger.error({ err: error, menu: menu.name }, "同步菜单失败");
-            throw error;
-        }
-    }
-}
-
-/**
- * 删除配置中不存在的菜单（强制删除）
- */
-async function deleteObsoleteRecords(helper: any, configPaths: Set<string>): Promise<void> {
-    const allRecords = await helper.getAll({
-        table: "addon_admin_menu",
-        fields: ["id", "path"],
-        where: { state$gte: 0 }
-    });
-
-    for (const record of allRecords.lists) {
-        if (record.path && !configPaths.has(record.path)) {
-            await helper.delForce({
-                table: "addon_admin_menu",
-                where: { id: record.id }
-            });
         }
-    }
-}
 
-/**
- * 加载所有菜单配置（addon views + 项目 menus.json）
- */
-async function loadMenuConfigs(): Promise<Array<{ menus: MenuConfig[]; source: string }>> {
-    const allMenus: Array<{ menus: MenuConfig[]; source: string }> = [];
-
-    // 1. 扫描所有 addon 的 views 目录
-    const addonNames = scanAddons();
-
-    for (const addonName of addonNames) {
-        try {
-            const addonDir = getAddonDir(addonName, "");
-            const viewsDir = join(addonDir, "views");
-
-            if (existsSync(viewsDir)) {
-                const prefix = `/addon/${addonName}`;
-                const menus = await scanViewsDir(viewsDir, prefix);
-                if (menus.length > 0) {
-                    allMenus.push({
-                        menus: menus,
-                        source: `addon:${addonName}`
-                    });
+        for (const record of existingList) {
+            if (typeof record?.path !== "string" || !record.path) {
+                continue;
+            }
+            if (!configPaths.has(record.path)) {
+                if (typeof record?.id === "number") {
+                    delIdSet.add(record.id);
                 }
             }
-        } catch (error: any) {
-            Logger.warn({ err: error, addon: addonName }, "扫描 addon views 目录失败");
         }
-    }
 
-    // 2. 读取项目的 menus.json
-    const menusJsonPath = join(projectDir, "menus.json");
-    if (existsSync(menusJsonPath)) {
-        try {
-            const content = await readFile(menusJsonPath, "utf-8");
-            const projectMenus = JSON.parse(content);
-            if (Array.isArray(projectMenus) && projectMenus.length > 0) {
-                allMenus.push({
-                    menus: projectMenus,
-                    source: "project"
-                });
+        for (const id of duplicateIdSet) {
+            if (typeof id === "number" && id > 0) {
+                delIdSet.add(id);
             }
-        } catch (error: any) {
-            Logger.warn({ err: error }, "读取项目 menus.json 失败");
         }
-    }
-
-    return allMenus;
-}
-
-/**
- * SyncMenu 命令主函数
- */
-export async function syncMenuCommand(options: SyncMenuOptions = {}): Promise<void> {
-    try {
-        if (options.plan) {
-            Logger.debug("[计划] 同步菜单配置到数据库（plan 模式不执行）");
-            return;
-        }
-
-        // 1. 加载所有菜单配置
-        const allMenus = await loadMenuConfigs();
-
-        // 2. 合并菜单配置
-        let mergedMenus = mergeMenuConfigs(allMenus);
 
-        // 2.1 规范化并去重（防止尾随 / 或多 / 导致隐藏菜单与 DB 同步异常）
-        mergedMenus = normalizeMenuTree(mergedMenus);
+        const delIds = Array.from(delIdSet);
 
-        // 3. 过滤隐藏菜单（根据 hiddenMenus 配置）
-        const hiddenMenus = (beflyConfig as any).hiddenMenus || [];
-        if (Array.isArray(hiddenMenus) && hiddenMenus.length > 0) {
-            const hiddenSet = new Set(hiddenMenus.map((item: string) => normalizeMenuPath(item)));
-            mergedMenus = filterHiddenMenus(mergedMenus, hiddenSet);
-            mergedMenus = normalizeMenuTree(mergedMenus);
+        if (delIds.length > 0) {
+            await trans.delForceBatch(tableName, delIds);
         }
+    });
 
-        // 连接数据库
-        await Connect.connect();
-
-        const helper = new DbHelper({ redis: new RedisHelper() } as any, Connect.getSql());
-
-        // 3. 检查表是否存在
-        const exists = await helper.tableExists("addon_admin_menu");
-
-        if (!exists) {
-            Logger.debug("表 addon_admin_menu 不存在，跳过菜单同步");
-            return;
-        }
-
-        // 4. 收集所有菜单的 path
-        const configPaths = collectPaths(mergedMenus);
-
-        // 5. 同步菜单
-        await syncMenus(helper, mergedMenus);
-
-        // 6. 删除不存在的菜单
-        await deleteObsoleteRecords(helper, configPaths);
-
-        // 7. 获取最终菜单数据（用于缓存）
-        const allMenusData = await helper.getAll({
-            table: "addon_admin_menu"
-        });
-
-        // 8. 缓存菜单数据到 Redis
-        try {
-            const redisHelper = new RedisHelper();
-            await redisHelper.setObject(CacheKeys.menusAll(), allMenusData.lists);
-        } catch (error: any) {
-            Logger.warn({ err: error }, "Redis 缓存菜单数据失败");
-        }
-    } catch (error: any) {
-        Logger.error({ err: error }, "菜单同步失败");
-        throw error;
-    } finally {
-        await Connect.disconnect();
-    }
+    // 缓存同步职责已收敛到 syncCache（启动流程单点调用），此处只负责 DB 同步。
 }
 
 // 仅测试用（避免将内部扫描逻辑变成稳定 API）
 export const __test__ = {
-    scanViewsDir: scanViewsDir,
-    normalizeMenuPath: normalizeMenuPath
+    scanViewsDir: async (viewsDir: string, prefix: string, parentPath: string = "") => {
+        const mod = await import("../utils/loadMenuConfigs.js");
+        return await mod.scanViewsDirToMenuConfigs(viewsDir, prefix, parentPath);
+    },
+    flattenMenusToDefMap: (mergedMenus: MenuConfig[]) => {
+        return flattenMenusToDefMap(mergedMenus);
+    }
 };