cloud-web-corejs 1.0.54-dev.762 → 1.0.54-dev.764

package/src/microRouter/index.js

@@ -1,521 +1,393 @@
-/**
- * qiankun 主应用侧：应用注册表驱动的子应用注册。
- * 注册表载体为逻辑参数 micro_app_registry（JSON 数组），
- * 协议见 docs/qiankun微前端改造-实现方案.md 3.2 / 3.4。
- * 由 permission store 在登录后菜单生成流程中调用（settings.microMainEnabled 门控）。
- */
-import { loadMicroApp } from "qiankun";
-import { getLogicParamValue } from "@base/api/user";
-import {
-  getAccessPath,
-  validateRegistry,
-  resolveEntry,
-} from "@base/utils/menuAdapter";
-import { getToken } from "@base/utils/auth";
-import router from "@base/router";
-import settings from "@/settings";
-
-export const REGISTRY_PARAM_CODE = "micro_app_registry";
-export const DEBUG_STORAGE_KEY = "micro_app_debug";
-
-const REGISTRY_TIMEOUT = 8000;
-const CONTAINER_WRAPPER_ID = "Appmicro";
-const DEBUG_APP_CODE_REG = /^[A-Za-z][A-Za-z0-9_-]*$/;
-
-// 本机调试的约定默认值：包内兜底，各应用 settings.js 无需声明。
-// 需要偏离约定（改端口 / 调真实 appCode 的菜单派发）才在应用 settings.js 里覆盖，
-// 或用 ?microDebug=appB=http://... 单次指定。
-const DEBUG_DEFAULT_APP_CODE = "debugApp";
-const DEBUG_DEFAULT_ENTRY = "http://localhost:17527/";
-
-// 保活管理：appCode → { instance, el }；离开子应用路由只隐藏容器不卸载，
-// 切回直接显示并经 update 生命周期同步路由，页面状态（页签/表格/表单）得以保留
-let microAppConfigs = {};
-let aliveApps = {};
-let routeHookInstalled = false;
-
-/**
- * 读应用注册表（第一阶段载体：逻辑参数）。
- * 非法条目由 validateRegistry 跳过并在控制台显式报错；
- * 参数缺失 / 请求失败 / 超时一律回落空数组，不阻塞登录流程。
- */
-export function getAppRegistry() {
-  const fetchPromise = new Promise((resolve) => {
-    getLogicParamValue({
-      data: { paramCode: REGISTRY_PARAM_CODE },
-      failMsg: false,
-      errorMsg: false,
-      modal: false,
-      success: (res) => {
-        const raw = res && res.objx;
-        if (!raw) {
-          resolve([]);
-          return;
-        }
-        const { apps, errors } = validateRegistry(raw);
-        if (errors.length) {
-          console.error(
-            "[microRouter] 应用注册表存在非法条目（已跳过）：",
-            errors
-          );
-        }
-        resolve(apps);
-      },
-    }).catch(() => resolve([]));
-  });
-  const timeoutPromise = new Promise((resolve) => {
-    setTimeout(() => {
-      resolve([]);
-    }, REGISTRY_TIMEOUT);
-  });
-  return Promise.race([fetchPromise, timeoutPromise]).then((apps) =>
-    applyDebugOverrides(apps)
-  );
-}
-
-const DEBUG_URL_PARAMS = ["microDebug", "microDebugAppCode", "microDebugEntry"];
-
-/** 取 URL 上某个查询参数（hash 前后都找），非法转义按原文处理 */
-function readUrlParam(href, name) {
-  const matched = href.match(new RegExp("[?&]" + name + "=([^&#]*)"));
-  if (!matched) return null;
-  const raw = matched[1] || "";
-  let value = raw;
-  try {
-    value = decodeURIComponent(raw);
-  } catch (e) {
-    // 非法转义（如值里有裸 %）会抛 URIError，按原文处理，不能让它中断注册表加载
-    value = raw;
-  }
-  return value.trim();
-}
-
-/**
- * 从 URL 读调试开关并落盘 localStorage，读到后即从地址栏抹掉（避免被收藏/分享扩散）。
- * 支持 hash 前后两种位置：?microDebug=xx#/... 与 #/...?microDebug=xx。
- * 两种写法：
- *   ?microDebug=xx                                取值同 localStorage 四档写法；off/0 清除
- *   ?microDebugAppCode=mkweb&microDebugEntry=17527  拆成两个参数，值里不含 "="
- * 后者存在的原因：部分网关/WAF 对查询串里出现第二个裸 "=" 直接返 500（整页打不开），
- * 拆成两个参数后每个值都没有 "="，无需编码即可通过。entry 可写端口号简写。
- * 存在意义：settings.microDebugEnabled 是构建期常量、全体用户共用，生产构建里必须失效；
- * 生产环境主应用要装本机子应用，只能靠这种"按浏览器生效"的通道。
- */
-function readDebugFromUrl() {
-  const href = window.location.href || "";
-  const single = readUrlParam(href, "microDebug");
-  const appCode = readUrlParam(href, "microDebugAppCode");
-  const entry = readUrlParam(href, "microDebugEntry");
-  let value = null;
-  if (appCode) {
-    // 双参数写法：entry 缺省时落到默认入口（由 getDebugOverrides 补）
-    value = entry ? appCode + "=" + entry : appCode;
-  } else if (single !== null) {
-    value = single;
-  }
-  if (value === null) return;
-  try {
-    if (!value || value === "off" || value === "0") {
-      window.localStorage.removeItem(DEBUG_STORAGE_KEY);
-    } else {
-      window.localStorage.setItem(DEBUG_STORAGE_KEY, value);
-    }
-  } catch (e) {
-    console.error("[microRouter] 调试开关写入 localStorage 失败：", e.message);
-    return;
-  }
-  try {
-    let cleaned = href;
-    DEBUG_URL_PARAMS.forEach((name) => {
-      cleaned = cleaned.replace(
-        new RegExp("([?&])" + name + "=[^&#]*&?"),
-        "$1"
-      );
-    });
-    cleaned = cleaned.replace(/[?&](?=#|$)/, ""); // 抹掉可能残留的空查询串
-    window.history.replaceState(null, "", cleaned);
-  } catch (e) {
-    // replaceState 失败不影响开关本身，忽略
-  }
-}
-
-/**
- * entry 规范化：允许只写端口号（如 "17527"）代替完整地址。
- * 完整地址里的 ":" 与 "//" 放在 URL 查询串上容易被地址栏或服务端重定向吃掉，
- * 端口简写让 ?microDebug=mkweb=17527 这种最省事的写法可用。
- */
-function normalizeDebugEntry(entry) {
-  const value = (entry == null ? "" : String(entry)).trim();
-  if (/^\d{2,5}$/.test(value)) {
-    return "http://localhost:" + value + "/";
-  }
-  return value;
-}
-
-/**
- * 本机调试覆盖，三种触发方式（localStorage 优先于 settings 开关）：
- * 1) URL 参数 ?microDebug=xx —— 任何环境（含生产构建）都生效，值写入 localStorage
- *    后自动从地址栏抹掉；?microDebug=off 清除。生产环境主应用只能用这种。
- * 2) localStorage.micro_app_debug —— 仅当前浏览器生效，不影响其他用户。四档写法：
- *   "1"                          → settings.microDebugAppCode + microDebugEntry
- *   "appB"                       → appB + 默认调试入口
- *   "appB=http://localhost:17528/" → 指定入口；多个用逗号分隔，可混写
- *   '[{"appCode":"..","entry":".."}]' → 完整条目数组
- * 3) settings.microDebugEnabled = true —— 本地起主应用时免设 localStorage；
- *    仅非 production 构建生效，防误留 true 发版后所有用户被指向 localhost。
- * 与注册表按 appCode 合并：已存在的条目覆盖 entry 并强制 enabled，不存在的追加。
- */
-function getDebugOverrides() {
-  readDebugFromUrl();
-  let raw = null;
-  try {
-    raw = window.localStorage.getItem(DEBUG_STORAGE_KEY);
-  } catch (e) {
-    raw = null;
-  }
-  raw = raw ? raw.trim() : "";
-  // off / 0 一律视为关闭：与 URL 形态语义一致，
-  // 否则会被当成一个名叫 off 的 appCode 注册出去
-  if (raw === "off" || raw === "0" || raw === "false") {
-    raw = "";
-  }
-  const defaults = {
-    appCode: settings.microDebugAppCode || DEBUG_DEFAULT_APP_CODE,
-    entry: settings.microDebugEntry || DEBUG_DEFAULT_ENTRY,
-  };
-  let restoreHint
-    = "删除 localStorage." + DEBUG_STORAGE_KEY + " 后刷新恢复";
-  let items = [];
-  if (!raw) {
-    if (
-      settings.microDebugEnabled
-      && process.env.NODE_ENV !== "production"
-    ) {
-      items = [defaults];
-      restoreHint = "settings.microDebugEnabled 置 false 恢复";
-    } else {
-      return { items: [], restoreHint };
-    }
-  } else if (raw.charAt(0) === "[") {
-    try {
-      const list = JSON.parse(raw);
-      items = (Array.isArray(list) ? list : []).map((item) => ({
-        appCode: (item && item.appCode) || "",
-        entry: (item && item.entry) || defaults.entry,
-      }));
-    } catch (e) {
-      console.error(
-        "[microRouter] micro_app_debug JSON 解析失败，已忽略：",
-        e.message
-      );
-      return { items: [], restoreHint };
-    }
-  } else if (raw === "1" || raw === "true") {
-    items = [defaults];
-  } else {
-    items = raw.split(",").map((part) => {
-      const idx = part.indexOf("=");
-      const code = (idx > -1 ? part.slice(0, idx) : part).trim();
-      const entry = idx > -1 ? part.slice(idx + 1).trim() : defaults.entry;
-      return { appCode: code, entry };
-    });
-  }
-  items = items.map((item) => ({
-    appCode: item.appCode,
-    entry: normalizeDebugEntry(item.entry),
-  }));
-  items = items.filter((item) => {
-    if (!DEBUG_APP_CODE_REG.test(item.appCode || "") || !item.entry) {
-      console.error(
-        "[microRouter] micro_app_debug 非法条目已跳过：",
-        JSON.stringify(item)
-      );
-      return false;
-    }
-    return true;
-  });
-  return { items, restoreHint };
-}
-
-function applyDebugOverrides(apps) {
-  const { items: overrides, restoreHint } = getDebugOverrides();
-  if (!overrides.length) return apps || [];
-  const result = (apps || []).slice();
-  overrides.forEach((override) => {
-    const existing = result.find((app) => app.appCode === override.appCode);
-    if (existing) {
-      existing.entry = override.entry;
-      existing.enabled = true;
-      // 打标记：子应用据此启用"URL 直达未配菜单页面"的调试兜底路由
-      existing.debugOverride = true;
-    } else {
-      result.push({
-        appCode: override.appCode,
-        appName: override.appCode + "(本地调试)",
-        entry: override.entry,
-        hasCorejs: true,
-        enabled: true,
-        debugOverride: true,
-      });
-    }
-    console.warn(
-      "[microRouter] ⚠ 本地调试覆盖生效："
-        + override.appCode
-        + " → "
-        + override.entry
-        + "（"
-        + restoreHint
-        + "）"
-    );
-  });
-  return result;
-}
-
-/**
- * activeRule 由 appCode 推导：hash 首段即归属首段，与菜单访问路径天然一致。
- */
-export function buildActiveRule(appCode) {
-  const prefix = "#/" + appCode;
-  return (location) => {
-    const hash = location.hash || "";
-    return (
-      hash === prefix
-      || hash.indexOf(prefix + "/") === 0
-      || hash.indexOf(prefix + "?") === 0
-    );
-  };
-}
-
-/**
- * 登记子应用（保活模式）：不再走 registerMicroApps/start 的 activeRule 自动装卸，
- * 改为路由钩子驱动的 loadMicroApp 手动装载——首次进入装载，离开只隐藏，切回显示并同步路由。
- * options.subAppMenus 为 menuAdapter.dispatchMenus 的切分结果。
- */
-export function registerSubApps(apps, options = {}) {
-  const env = process.env.NODE_ENV || "development";
-  const subAppMenus = options.subAppMenus || {};
-  const mainAdapter = options.mainAdapter || createDefaultMainAdapter();
-  const userInfo = options.userInfo || null;
-  microAppConfigs = {};
-  (apps || []).forEach((app) => {
-    const entry = resolveEntry(app.entry, env);
-    if (!entry) {
-      console.error(
-        "[microRouter] 子应用缺少当前环境 entry，已跳过：" + app.appCode
-      );
-      return;
-    }
-    microAppConfigs[app.appCode] = {
-      name: app.appCode,
-      entry,
-      props: {
-        appCode: app.appCode,
-        menus: subAppMenus[app.appCode] || [],
-        token: getToken(),
-        lang: localStorage.getItem("i18n-lang") || "",
-        userInfo,
-        mainAdapter,
-        // 本地调试覆盖装载的应用：允许 URL 直达未配菜单的页面（见 permission.js 调试兜底路由）
-        microDebug: !!app.debugOverride,
-      },
-    };
-  });
-  installRouteHook();
-  return Object.keys(microAppConfigs);
-}
-
-// 当前应处于激活态的子应用（等待容器期间用户可能又切走，异步续体据此丢弃过期操作）
-let currentActiveAppCode = null;
-
-function installRouteHook() {
-  if (routeHookInstalled) return;
-  routeHookInstalled = true;
-  router.afterEach((to) => {
-    const appCode
-      = to.meta && to.meta.isMicroApp && microAppConfigs[to.meta.appCode]
-        ? to.meta.appCode
-        : null;
-    currentActiveAppCode = appCode;
-    Object.keys(aliveApps).forEach((code) => {
-      if (code !== appCode) {
-        deactivateMicroApp(code);
-      }
-    });
-    if (appCode) {
-      activateMicroApp(appCode);
-    }
-  });
-}
-
-// 刷新直接落在子应用路由时，afterEach 早于布局渲染（AppMain 懒加载 + showAppMain 延迟），
-// 容器尚未进 DOM——轮询等待，超时显式报错
-const WRAPPER_WAIT_INTERVAL = 100;
-const WRAPPER_WAIT_MAX_TRIES = 100;
-
-function waitForWrapper(tryCount = 0) {
-  const wrapper = document.getElementById(CONTAINER_WRAPPER_ID);
-  if (wrapper) return Promise.resolve(wrapper);
-  if (tryCount >= WRAPPER_WAIT_MAX_TRIES) {
-    console.error(
-      "[microRouter] 等待子应用容器 #" + CONTAINER_WRAPPER_ID + " 超时"
-    );
-    return Promise.resolve(null);
-  }
-  return new Promise((resolve) => {
-    setTimeout(() => {
-      resolve(waitForWrapper(tryCount + 1));
-    }, WRAPPER_WAIT_INTERVAL);
-  });
-}
-
-function getContainerEl(wrapper, appCode) {
-  const id = CONTAINER_WRAPPER_ID + "-" + appCode;
-  let el = document.getElementById(id);
-  if (!el) {
-    el = document.createElement("div");
-    el.id = id;
-    el.style.height = "100%";
-    wrapper.appendChild(el);
-  }
-  return el;
-}
-
-function activateMicroApp(appCode) {
-  const config = microAppConfigs[appCode];
-  if (!config) return;
-  waitForWrapper().then((wrapper) => {
-    if (!wrapper) return;
-    if (currentActiveAppCode !== appCode) return; // 等待期间已切走
-    const el = getContainerEl(wrapper, appCode);
-    el.style.display = "";
-    const alive = aliveApps[appCode];
-    if (!alive) {
-      aliveApps[appCode] = {
-        el,
-        instance: loadMicroApp({
-          name: config.name,
-          entry: config.entry,
-          container: el,
-          props: config.props,
-        }),
-      };
-      return;
-    }
-    // 已保活：显示容器并通知子应用恢复路由监听、同步当前 hash（含"切到本应用另一菜单"的深导航）
-    notifyMicroApp(alive.instance, { microActive: true });
-  });
-}
-
-function deactivateMicroApp(appCode) {
-  const alive = aliveApps[appCode];
-  if (!alive) return;
-  alive.el.style.display = "none";
-  // 暂停子应用路由监听，防止隐藏期间对主应用的 URL 变化做出反应（回写 URL 互相打架）
-  notifyMicroApp(alive.instance, { microActive: false });
-}
-
-function notifyMicroApp(instance, props) {
-  if (!instance || typeof instance.update !== "function") return;
-  const mountPromise = instance.mountPromise || Promise.resolve();
-  mountPromise
-    .then(() => instance.update(props))
-    .catch((e) => {
-      console.error("[microRouter] 子应用 update 通知失败：", e);
-    });
-}
-
-/**
- * 转发"刷新当前页"给子应用。
- * 保活模式下主应用那套 delCachedView + /redirect 重建只作用于自己的 router-view，
- * 子应用内容由 qiankun 挂在独立容器里，走一圈只是容器隐藏再显示、实例毫发无损，
- * 表现为点刷新没反应——必须由子应用在自身路由内重建组件。
- * 返回是否已转发（false 表示该应用未装载，调用方回落自身刷新逻辑）。
- */
-export function refreshMicroApp(appCode) {
-  const alive = aliveApps[appCode];
-  if (!alive) return false;
-  // 带时间戳：qiankun 对相同 props 也会调用 update，但时间戳能让子应用区分每次点击
-  notifyMicroApp(alive.instance, { microRefresh: Date.now() });
-  return true;
-}
-
-/** 真正卸载全部子应用（登出等场景按需调用；常规页签切换不卸载） */
-export function unmountAllMicroApps() {
-  Object.keys(aliveApps).forEach((code) => {
-    const alive = aliveApps[code];
-    if (alive && alive.instance) {
-      alive.instance.unmount().catch(() => {});
-    }
-    if (alive && alive.el && alive.el.parentNode) {
-      alive.el.parentNode.removeChild(alive.el);
-    }
-  });
-  aliveApps = {};
-}
-
-/**
- * 每个子应用先按菜单生成精确路由以携带菜单标题等元数据，再追加通配兜底。
- * 路由均不挂组件，内容由 qiankun 挂进 AppMain 的 #Appmicro 容器。
- */
-export function buildSubAppRoutes(apps, subAppMenus = {}) {
-  const routes = [];
-  (apps || []).forEach((app) => {
-    const seenPaths = {};
-    (subAppMenus[app.appCode] || []).forEach((menu, index) => {
-      let path = getAccessPath(menu).split("?")[0];
-      if (!path) return;
-      if (!path.startsWith("/")) {
-        path = "/" + path;
-      }
-      if (seenPaths[path]) return;
-      seenPaths[path] = true;
-      routes.push({
-        path,
-        name: `micro-${app.appCode}-menu-${menu.id || menu.menuCode || index}`,
-        meta: {
-          title: menu.menuName || app.appName,
-          enTitle: menu.menuEnName || null,
-          treePathName: menu.treePathName,
-          repeatOpen: menu.repeatOpen,
-          isMicroApp: true,
-          appCode: app.appCode,
-        },
-      });
-    });
-    routes.push({
-      path: "/" + app.appCode + "/*",
-      name: "micro-" + app.appCode,
-      meta: {
-        title: app.appName,
-        isMicroApp: true,
-        appCode: app.appCode,
-      },
-    });
-  });
-  return routes;
-}
-
-// 子应用表单脚本跳主应用路由必须走该回调，不得直接摸主应用 router
-function createDefaultMainAdapter() {
-  return {
-    navigate(path) {
-      const vueRoot = window.$vueRoot;
-      if (vueRoot && vueRoot.$router) {
-        vueRoot.$router.push(path).catch(() => {});
-      }
-    },
-    openTab(path) {
-      this.navigate(path);
-    },
-    closeTab(view) {
-      const vueRoot = window.$vueRoot;
-      if (vueRoot && vueRoot.$store) {
-        return vueRoot.$store.dispatch(
-          "tagsView/delView",
-          view || vueRoot.$route
-        );
-      }
-      return Promise.resolve();
-    },
-  };
-}
+/**
+ * qiankun 主应用侧：应用注册表驱动的子应用注册。
+ * 注册表载体为逻辑参数 micro_app_registry（JSON 数组），
+ * 协议见 docs/qiankun微前端改造-实现方案.md 3.2 / 3.4。
+ * 由 permission store 在登录后菜单生成流程中调用（settings.microMainEnabled 门控）。
+ */
+import { loadMicroApp } from "qiankun";
+import { getLogicParamValue } from "@base/api/user";
+import {
+  getAccessPath,
+  validateRegistry,
+  resolveEntry,
+  swapMenuNamespace,
+  parseDebugEnabled,
+  isDebugAllowed,
+  MICRO_SEGMENT,
+  MICRO_DEBUG_SEGMENT,
+} from "@base/utils/menuAdapter";
+import { getToken } from "@base/utils/auth";
+import router from "@base/router";
+
+const REGISTRY_PARAM_CODE = "micro_app_registry";
+// 调试开关单独一条逻辑参数：与注册表生命周期不同，运维开关调试不必改注册表 JSON
+const DEBUG_PARAM_CODE = "micro_debug_enabled";
+
+const REGISTRY_TIMEOUT = 8000;
+const CONTAINER_WRAPPER_ID = "Appmicro";
+
+/**
+ * 调试命名空间（/micro_debug/<appCode>/...）的约定入口。
+ * 调试态不落任何存储、不读 URL 查询参数——路径本身就是开关，因此入口只能是约定值。
+ * 各子应用把 devServer 端口固定为 17527 即可零配置被主应用装载。
+ */
+const DEBUG_ENTRY = "http://localhost:17527/";
+
+// 保活管理：appCode → { instance, el }；离开子应用路由只隐藏容器不卸载，
+// 切回直接显示并经 update 生命周期同步路由，页面状态（页签/表格/表单）得以保留
+let microAppConfigs = {};
+let aliveApps = {};
+let routeHookInstalled = false;
+
+/**
+ * 读一条逻辑参数的原始值；缺失 / 请求失败 / 超时一律回落空串，不阻塞登录流程。
+ */
+function readLogicParam(paramCode) {
+  const fetchPromise = new Promise((resolve) => {
+    getLogicParamValue({
+      data: { paramCode },
+      failMsg: false,
+      errorMsg: false,
+      modal: false,
+      success: (res) => resolve((res && res.objx) || ""),
+    }).catch(() => resolve(""));
+  });
+  const timeoutPromise = new Promise((resolve) => {
+    setTimeout(() => resolve(""), REGISTRY_TIMEOUT);
+  });
+  return Promise.race([fetchPromise, timeoutPromise]);
+}
+
+/**
+ * 读应用注册表 + 调试开关（两条逻辑参数并行取，互不依赖）。
+ * 注册表非法条目由 validateRegistry 跳过并在控制台显式报错；
+ * 调试开关取不到即视为关闭，标注在各 app 的 debugEnabled 上供下游使用。
+ */
+export function getAppRegistry() {
+  return Promise.all([
+    readLogicParam(REGISTRY_PARAM_CODE),
+    readLogicParam(DEBUG_PARAM_CODE),
+  ]).then(([registryRaw, debugRaw]) => {
+    if (!registryRaw) return [];
+    const { apps, errors } = validateRegistry(registryRaw);
+    if (errors.length) {
+      console.error("[microRouter] 应用注册表存在非法条目（已跳过）：", errors);
+    }
+    const debugSetting = parseDebugEnabled(debugRaw);
+    return apps.map((app) =>
+      Object.assign({}, app, {
+        debugEnabled: isDebugAllowed(debugSetting, app.appCode),
+      })
+    );
+  });
+}
+
+/** 装载实例键：同一个 appCode 的正式态与调试态各自保活，可同时开着对比 */
+function instanceKey(appCode, debug) {
+  return debug ? appCode + "@" + MICRO_DEBUG_SEGMENT : appCode;
+}
+
+/**
+ * 登记子应用（保活模式）：不再走 registerMicroApps/start 的 activeRule 自动装卸，
+ * 改为路由钩子驱动的 loadMicroApp 手动装载——首次进入装载，离开只隐藏，切回显示并同步路由。
+ * options.subAppMenus 为 menuAdapter.dispatchMenus 的切分结果。
+ */
+export function registerSubApps(apps, options = {}) {
+  const subAppMenus = options.subAppMenus || {};
+  const mainAdapter = options.mainAdapter || createDefaultMainAdapter();
+  const userInfo = options.userInfo || null;
+  microAppConfigs = {};
+  (apps || []).forEach((app) => {
+    const menus = subAppMenus[app.appCode] || [];
+    const baseProps = {
+      appCode: app.appCode,
+      token: getToken(),
+      lang: localStorage.getItem("i18n-lang") || "",
+      userInfo,
+      mainAdapter,
+    };
+    const entry = resolveEntry(app.entry);
+    if (entry) {
+      microAppConfigs[instanceKey(app.appCode, false)] = {
+        name: app.appCode,
+        entry,
+        props: Object.assign({}, baseProps, { menus, microDebug: false }),
+      };
+    } else {
+      console.error(
+        "[microRouter] 子应用缺少当前环境 entry，正式态已跳过：" + app.appCode
+      );
+    }
+    // 调试态：入口固定为约定端口，菜单路径一并换到 /micro_debug/ 命名空间——
+    // 子应用据此生成的路由才与浏览器 hash 对得上（主子路径始终一致）。
+    // 注册表未显式 debugEnabled 的应用不建调试实例，其 /micro_debug/ 地址打不开
+    if (app.debugEnabled) {
+      microAppConfigs[instanceKey(app.appCode, true)] = {
+        name: instanceKey(app.appCode, true),
+        entry: DEBUG_ENTRY,
+        props: Object.assign({}, baseProps, {
+          menus: menus.map((menu) => swapMenuNamespace(menu, true)),
+          // 调试态才允许 URL 直达未配菜单的页面（见 permission.js 调试兜底路由）
+          microDebug: true,
+        }),
+      };
+    }
+  });
+  installRouteHook();
+  return Object.keys(microAppConfigs);
+}
+
+// 当前应处于激活态的实例键（等待容器期间用户可能又切走，异步续体据此丢弃过期操作）
+let currentActiveKey = null;
+
+/**
+ * 由路由推导装载实例：正式路由 meta 直接带 microKey；
+ * 调试通配路由只带 appCode 参数，在此拼出实例键。
+ */
+function resolveMicroKey(to) {
+  const meta = (to && to.meta) || {};
+  if (!meta.isMicroApp) return null;
+  if (meta.microDebugCatchAll) {
+    const appCode = (to.params && to.params.appCode) || "";
+    const key = appCode ? instanceKey(appCode, true) : "";
+    if (!microAppConfigs[key]) {
+      console.error(
+        "[microRouter] 无法装载调试实例："
+          + (appCode || "(空 appCode)")
+          + "。请检查该 appCode 是否在应用注册表 "
+          + REGISTRY_PARAM_CODE
+          + " 里，以及逻辑参数 "
+          + DEBUG_PARAM_CODE
+          + " 是否为该应用放开了调试（默认关闭）"
+      );
+      return null;
+    }
+    return key;
+  }
+  return microAppConfigs[meta.microKey] ? meta.microKey : null;
+}
+
+function installRouteHook() {
+  if (routeHookInstalled) return;
+  routeHookInstalled = true;
+  router.afterEach((to) => {
+    const key = resolveMicroKey(to);
+    currentActiveKey = key;
+    Object.keys(aliveApps).forEach((code) => {
+      if (code !== key) {
+        deactivateMicroApp(code);
+      }
+    });
+    if (key) {
+      activateMicroApp(key);
+    }
+  });
+}
+
+// 刷新直接落在子应用路由时，afterEach 早于布局渲染（AppMain 懒加载 + showAppMain 延迟），
+// 容器尚未进 DOM——轮询等待，超时显式报错
+const WRAPPER_WAIT_INTERVAL = 100;
+const WRAPPER_WAIT_MAX_TRIES = 100;
+
+function waitForWrapper(tryCount = 0) {
+  const wrapper = document.getElementById(CONTAINER_WRAPPER_ID);
+  if (wrapper) return Promise.resolve(wrapper);
+  if (tryCount >= WRAPPER_WAIT_MAX_TRIES) {
+    console.error(
+      "[microRouter] 等待子应用容器 #" + CONTAINER_WRAPPER_ID + " 超时"
+    );
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(waitForWrapper(tryCount + 1));
+    }, WRAPPER_WAIT_INTERVAL);
+  });
+}
+
+function getContainerEl(wrapper, key) {
+  const id = CONTAINER_WRAPPER_ID + "-" + key.replace("@", "_");
+  let el = document.getElementById(id);
+  if (!el) {
+    el = document.createElement("div");
+    el.id = id;
+    el.style.height = "100%";
+    wrapper.appendChild(el);
+  }
+  return el;
+}
+
+function activateMicroApp(key) {
+  const config = microAppConfigs[key];
+  if (!config) return;
+  waitForWrapper().then((wrapper) => {
+    if (!wrapper) return;
+    if (currentActiveKey !== key) return; // 等待期间已切走
+    const el = getContainerEl(wrapper, key);
+    el.style.display = "";
+    const alive = aliveApps[key];
+    if (!alive) {
+      if (config.props.microDebug) {
+        console.warn(
+          "[microRouter] ⚠ 调试命名空间装载："
+            + config.name
+            + " → "
+            + config.entry
+            + "（把地址里的 /"
+            + MICRO_DEBUG_SEGMENT
+            + "/ 改回 /"
+            + MICRO_SEGMENT
+            + "/ 即回到正式环境）"
+        );
+      }
+      aliveApps[key] = {
+        el,
+        instance: loadMicroApp({
+          name: config.name,
+          entry: config.entry,
+          container: el,
+          props: config.props,
+        }),
+      };
+      return;
+    }
+    // 已保活：显示容器并通知子应用恢复路由监听、同步当前 hash（含"切到本应用另一菜单"的深导航）
+    notifyMicroApp(alive.instance, { microActive: true });
+  });
+}
+
+function deactivateMicroApp(key) {
+  const alive = aliveApps[key];
+  if (!alive) return;
+  alive.el.style.display = "none";
+  // 暂停子应用路由监听，防止隐藏期间对主应用的 URL 变化做出反应（回写 URL 互相打架）
+  notifyMicroApp(alive.instance, { microActive: false });
+}
+
+function notifyMicroApp(instance, props) {
+  if (!instance || typeof instance.update !== "function") return;
+  const mountPromise = instance.mountPromise || Promise.resolve();
+  mountPromise
+    .then(() => instance.update(props))
+    .catch((e) => {
+      console.error("[microRouter] 子应用 update 通知失败：", e);
+    });
+}
+
+/**
+ * 转发"刷新当前页"给子应用。
+ * 保活模式下主应用那套 delCachedView + /redirect 重建只作用于自己的 router-view，
+ * 子应用内容由 qiankun 挂在独立容器里，走一圈只是容器隐藏再显示、实例毫发无损，
+ * 表现为点刷新没反应——必须由子应用在自身路由内重建组件。
+ * 入参是当前路由（调试通配路由的实例键要从路由参数推导，不在 meta 里）。
+ * 返回是否已转发（false 表示该应用未装载，调用方回落自身刷新逻辑）。
+ */
+export function refreshMicroApp(route) {
+  const alive = aliveApps[resolveMicroKey(route)];
+  if (!alive) return false;
+  // 带时间戳：qiankun 对相同 props 也会调用 update，但时间戳能让子应用区分每次点击
+  notifyMicroApp(alive.instance, { microRefresh: Date.now() });
+  return true;
+}
+
+/** 真正卸载全部子应用（登出等场景按需调用；常规页签切换不卸载） */
+export function unmountAllMicroApps() {
+  Object.keys(aliveApps).forEach((code) => {
+    const alive = aliveApps[code];
+    if (alive && alive.instance) {
+      alive.instance.unmount().catch(() => {});
+    }
+    if (alive && alive.el && alive.el.parentNode) {
+      alive.el.parentNode.removeChild(alive.el);
+    }
+  });
+  aliveApps = {};
+}
+
+/**
+ * 每个子应用先按菜单生成精确路由以携带菜单标题等元数据，再追加通配兜底。
+ * 路由均不挂组件，内容由 qiankun 挂进 AppMain 的 #Appmicro 容器。
+ *
+ * 调试命名空间不按应用展开：精确路由只为菜单元数据（标题/树路径/重复打开）而生，
+ * 装载哪个实例只取决于 appCode——做成一条参数化通配即可，
+ * 子应用再多也还是一条，代价仅是调试页签标题不显示具体菜单名。
+ */
+export function buildSubAppRoutes(apps, subAppMenus = {}) {
+  const routes = [];
+  (apps || []).forEach((app) => {
+    const key = instanceKey(app.appCode, false);
+    const seenPaths = {};
+    (subAppMenus[app.appCode] || []).forEach((menu, index) => {
+      let path = getAccessPath(menu).split("?")[0];
+      if (!path) return;
+      if (!path.startsWith("/")) {
+        path = "/" + path;
+      }
+      if (seenPaths[path]) return;
+      seenPaths[path] = true;
+      routes.push({
+        path,
+        name: `micro-${app.appCode}-menu-${menu.id || menu.menuCode || index}`,
+        meta: {
+          title: menu.menuName || app.appName,
+          enTitle: menu.menuEnName || null,
+          treePathName: menu.treePathName,
+          repeatOpen: menu.repeatOpen,
+          isMicroApp: true,
+          appCode: app.appCode,
+          microKey: key,
+        },
+      });
+    });
+    routes.push({
+      path: "/" + MICRO_SEGMENT + "/" + app.appCode + "/*",
+      name: "micro-" + app.appCode,
+      meta: {
+        title: app.appName,
+        isMicroApp: true,
+        appCode: app.appCode,
+        microKey: key,
+      },
+    });
+  });
+  // 没有任何应用开启调试时连路由都不注册——/micro_debug/ 直接落 404，
+  // 而不是进到一个装载不了任何东西的空白页
+  if ((apps || []).some((app) => app.debugEnabled)) {
+    // 整个调试命名空间共用这一条；appCode 由路由参数带出，装载实例在 afterEach 里推导
+    routes.push({
+      path: "/" + MICRO_DEBUG_SEGMENT + "/:appCode/*",
+      name: "micro-" + MICRO_DEBUG_SEGMENT,
+      meta: {
+        title: "微前端调试",
+        isMicroApp: true,
+        microDebugCatchAll: true,
+      },
+    });
+  }
+  return routes;
+}
+
+// 子应用表单脚本跳主应用路由必须走该回调，不得直接摸主应用 router
+function createDefaultMainAdapter() {
+  return {
+    navigate(path) {
+      const vueRoot = window.$vueRoot;
+      if (vueRoot && vueRoot.$router) {
+        vueRoot.$router.push(path).catch(() => {});
+      }
+    },
+    openTab(path) {
+      this.navigate(path);
+    },
+    closeTab(view) {
+      const vueRoot = window.$vueRoot;
+      if (vueRoot && vueRoot.$store) {
+        return vueRoot.$store.dispatch(
+          "tagsView/delView",
+          view || vueRoot.$route
+        );
+      }
+      return Promise.resolve();
+    },
+  };
+}