@axewo/fin-micro 1.0.0 → 2.0.1

package/dist/watermark.mjs

@@ -0,0 +1,119 @@
+import { defineComponent as W, ref as j, onMounted as B, watch as $, onBeforeUnmount as N, openBlock as I, createElementBlock as P } from "vue";
+function h(s, e, f, m) {
+  return typeof s == "number" && Number.isFinite(s) ? Math.min(m, Math.max(f, s)) : e;
+}
+function C(s) {
+  var r, o;
+  const e = s && typeof s == "object" ? s : {}, m = (typeof e.text == "string" ? e.text.split(`
+`) : Array.isArray(e.text) ? e.text : ["内部资料"]).filter((l) => typeof l == "string").slice(0, 4).map((l) => l.slice(0, 120)), c = typeof e.fontFamily == "string" && e.fontFamily.length <= 160 && !/[;{}\\\n\r]/.test(e.fontFamily) ? e.fontFamily : "sans-serif";
+  return Object.freeze({
+    enabled: e.enabled !== !1,
+    text: Object.freeze(m),
+    color: typeof e.color == "string" && e.color.length <= 80 ? e.color : "#64748b",
+    opacity: h(e.opacity, 0.12, 0, 1),
+    rotate: h(e.rotate, -22, -180, 180),
+    fontSize: h(e.fontSize, 16, 10, 64),
+    fontFamily: c,
+    gap: Object.freeze([h((r = e.gap) == null ? void 0 : r[0], 100, 16, 600), h((o = e.gap) == null ? void 0 : o[1], 80, 16, 600)])
+  });
+}
+const H = /* @__PURE__ */ W({
+  __name: "FinWatermark",
+  props: {
+    config: {}
+  },
+  emits: ["error"],
+  setup(s, { emit: e }) {
+    const f = s, m = e, c = j();
+    let r = null, o, l, y = "", p = !1, v = !1;
+    function T() {
+      o == null || o.disconnect(), o = void 0, l !== void 0 && clearInterval(l), l = void 0;
+    }
+    function _(t) {
+      var S;
+      const a = C(f.config), i = t.ownerDocument.createElement("canvas"), n = i.getContext("2d");
+      if (!n) throw new Error("当前环境不支持 Canvas 2D，无法绘制水印。");
+      const g = `${a.fontSize}px ${a.fontFamily}`;
+      n.font = g;
+      const u = Math.min(1e3, Math.max(1, ...a.text.map((F) => n.measureText(F).width))), x = a.fontSize * 1.5, b = Math.max(1, a.text.length) * x, d = a.rotate * Math.PI / 180, k = Math.ceil(Math.abs(u * Math.cos(d)) + Math.abs(b * Math.sin(d)) + a.gap[0]), z = Math.ceil(Math.abs(u * Math.sin(d)) + Math.abs(b * Math.cos(d)) + a.gap[1]), w = Math.min(2, Math.max(1, ((S = t.ownerDocument.defaultView) == null ? void 0 : S.devicePixelRatio) ?? 1));
+      i.width = Math.ceil(k * w), i.height = Math.ceil(z * w), n.scale(w, w), n.translate(k / 2, z / 2), n.rotate(d), n.font = g, n.fillStyle = "#64748b", n.fillStyle = a.color, n.globalAlpha = a.opacity, n.textAlign = "center", n.textBaseline = "middle", a.text.forEach((F, O) => n.fillText(F, 0, (O - (a.text.length - 1) / 2) * x, 1e3));
+      const E = i.toDataURL("image/png");
+      if (!E.startsWith("data:image/png")) throw new Error("Canvas 未生成有效水印图像。");
+      return { url: E, width: k, height: z };
+    }
+    function D(t) {
+      o == null || o.observe(t, { attributes: !0 }), r && (o == null || o.observe(r, { childList: !0 }));
+    }
+    function M() {
+      var a;
+      const t = c.value;
+      if (!(!p || v || !t || !r)) {
+        v = !0, o == null || o.disconnect();
+        try {
+          t.parentNode !== r && r.appendChild(t), t.style.cssText !== y && (t.style.cssText = y), t.className && t.removeAttribute("class"), t.hasAttribute("hidden") && t.removeAttribute("hidden"), t.setAttribute("aria-hidden", "true");
+          const i = (a = t.ownerDocument.defaultView) == null ? void 0 : a.getComputedStyle(t);
+          i && (i.display === "none" || i.visibility !== "visible" || Number(i.opacity) === 0) && (t.style.cssText = y);
+        } finally {
+          v = !1, p && D(t);
+        }
+      }
+    }
+    function A() {
+      var i;
+      T();
+      const t = c.value;
+      if (!t || !p) return;
+      t.style.cssText = "display:none !important;";
+      const a = C(f.config);
+      if (!(!a.enabled || !a.text.some(Boolean)))
+        try {
+          const n = _(t), g = {
+            position: "absolute",
+            inset: "0",
+            width: "100%",
+            height: "100%",
+            margin: "0",
+            padding: "0",
+            border: "0",
+            display: "block",
+            visibility: "visible",
+            opacity: "1",
+            "pointer-events": "none",
+            "z-index": "2000",
+            transform: "none",
+            filter: "none",
+            "clip-path": "none",
+            "background-color": "transparent",
+            "background-image": `url("${n.url}")`,
+            "background-size": `${n.width}px ${n.height}px`,
+            "background-repeat": "repeat",
+            "background-position": "0 0",
+            "box-sizing": "border-box"
+          };
+          t.style.cssText = "";
+          for (const [x, b] of Object.entries(g)) t.style.setProperty(x, b, "important");
+          y = t.style.cssText;
+          const u = (i = t.ownerDocument.defaultView) == null ? void 0 : i.MutationObserver;
+          u && (o = new u(M)), M(), l = setInterval(M, 1e3);
+        } catch (n) {
+          t.style.cssText = "display:none !important;", m("error", n instanceof Error ? n : new Error("水印绘制失败。")), console.warn("[fin-micro/watermark] 水印绘制失败，本次检查已停止。", n);
+        }
+    }
+    return B(() => {
+      var t;
+      p = !0, r = ((t = c.value) == null ? void 0 : t.parentElement) ?? null, A();
+    }), $(() => f.config, A, { deep: !0 }), N(() => {
+      var t;
+      p = !1, T(), (t = c.value) == null || t.remove(), r = null;
+    }), (t, a) => (I(), P("div", {
+      ref_key: "layer",
+      ref: c,
+      "aria-hidden": "true",
+      "data-fin-watermark": ""
+    }, null, 512));
+  }
+});
+export {
+  H as FinWatermark,
+  C as normalizeWatermarkConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axewo/fin-micro",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -36,6 +36,17 @@
       "import": "./dist/vue.mjs",
       "require": "./dist/vue.cjs"
     },
+    "./layout": {
+      "types": "./dist/types/layout/index.d.ts",
+      "import": "./dist/layout.mjs",
+      "require": "./dist/layout.cjs"
+    },
+    "./layout/style.css": "./dist/layout.css",
+    "./watermark": {
+      "types": "./dist/types/watermark/index.d.ts",
+      "import": "./dist/watermark.mjs",
+      "require": "./dist/watermark.cjs"
+    },
     "./runtime": {
       "types": "./dist/types/runtime/index.d.ts",
       "import": "./dist/runtime.mjs",
@@ -46,6 +57,7 @@
     "fin-micro": "./cli/index.mjs"
   },
   "files": [
+    "dist/**/*.css",
     "dist/**/*.mjs",
     "dist/**/*.cjs",
     "dist/**/*.d.ts",
@@ -58,12 +70,22 @@
   "publishConfig": {
     "access": "public"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "peerDependencies": {
+    "element-plus": "^2.9.0",
+    "@element-plus/icons-vue": "^2.3.0",
     "vue": "^3.4.0",
     "vue-router": "^4.5.0"
   },
   "peerDependenciesMeta": {
+    "element-plus": {
+      "optional": true
+    },
+    "@element-plus/icons-vue": {
+      "optional": true
+    },
     "vue": {
       "optional": true
     },
@@ -75,6 +97,9 @@
     "wujie": "2.1.0"
   },
   "devDependencies": {
+    "@vitejs/plugin-vue": "^5.1.0",
+    "element-plus": "^2.9.0",
+    "@element-plus/icons-vue": "^2.3.0",
     "vue-router": "^4.5.0",
     "vue": "^3.5.0",
     "vite": "^5.4.0",
@@ -86,9 +111,9 @@
   "license": "MIT",
   "scripts": {
     "build": "vite build",
-    "test": "vitest run",
+    "test": "node ../../node_modules/vitest/vitest.mjs run",
     "typecheck": "vue-tsc --noEmit -p tsconfig.json",
-    "test:cli": "node --test cli/create.test.mjs cli/scaffold.test.mjs",
+    "test:cli": "node --test cli/create.test.mjs cli/scaffold.test.mjs cli/layout.test.mjs cli/startup.test.mjs",
     "check:package": "node scripts/check-package.mjs"
   }
 }

package/scaffold/base/index.html

@@ -6,7 +6,8 @@
     <title>__PROJECT_NAME__</title>
   </head>
   <body>
-    <div id="app"></div>
+    <!-- 启动前即显示；只占当前应用根区域，嵌入运行不会覆盖基座。Vue 挂载时替换。 -->
+    <div id="app"><div data-fin-startup="loading" role="status" aria-live="polite" style="min-height:240px;display:grid;place-content:center;gap:12px;text-align:center;color:#536079;background:#f4f6fa;font:14px/1.6 sans-serif"><strong>正在启动应用…</strong><span>正在加载配置与恢复会话，请稍候</span></div></div>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

package/scaffold/base/package.json.template

@@ -4,18 +4,22 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "check:runtime": "node scripts/check-runtime.mjs",
+    "predev": "npm run check:runtime",
+    "prebuild": "npm run check:runtime",
     "dev": "vite",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
-    "@axewo/fin-core": "2.1.0",
+    "@axewo/fin-core": "2.1.1",
     "@axewo/fin-micro": "__FIN_MICRO_VERSION__",
     "@axewo/fin-ui": "__FIN_UI_VERSION__",
     "@axewo/fin-editor": "2.0.1",
     "@element-plus/icons-vue": "2.3.2",
     "element-plus": "2.14.2",
+    "pinia": "2.3.1",
     "vue": "3.5.13",
     "vue-i18n": "^9.14.0",
     "vue-router": "4.5.0"

package/scaffold/base/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+# pnpm >=10.26（包含12.3.4）使用allowBuilds；旧版pnpm请按其审批机制单独配置。
+# 仅授权当前模板依赖的固定版本，升级依赖后须重新检查安装脚本。
+# esbuild准备平台构建二进制；vue-demi适配当前Vue版本。禁止全量放开依赖脚本。
+allowBuilds:
+  'esbuild@0.21.5': true
+  'vue-demi@0.14.10': true

package/scaffold/base/scripts/check-runtime.mjs

@@ -0,0 +1,43 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// 构建前检查安装包的实际导出，避免 Vite 链接失败被误认为登录或网络问题。
+const imports = new Map()
+let hostRouter = false
+async function scan(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const file = join(directory, entry.name)
+    if (entry.isDirectory()) await scan(file)
+    else if (/\.(ts|vue)$/.test(entry.name)) {
+      const source = await readFile(file, 'utf8')
+      if (source.includes('connectWorkspaceRouter')) hostRouter = true
+      for (const match of source.matchAll(/import\s*\{([^}]+)\}\s*from\s*['"](@axewo\/[^'"]+)['"]/g)) {
+        const names = imports.get(match[2]) ?? new Set()
+        for (const part of match[1].split(',')) {
+          const name = part.trim()
+          if (name && !name.startsWith('type ')) names.add(name.split(/\s+as\s+/)[0])
+        }
+        imports.set(match[2], names)
+      }
+    }
+  }
+}
+export async function checkRuntime() {
+  await scan(fileURLToPath(new URL('../src', import.meta.url)))
+  const problems = []
+  for (const [specifier, names] of imports) {
+    try {
+      const module = await import(specifier)
+      for (const name of names) if (!(name in module)) problems.push(`${specifier} 缺少导出 ${name}`)
+      if (specifier === '@axewo/fin-micro' && hostRouter && module.hostRouterProtocol !== 1) {
+        problems.push('@axewo/fin-micro 缺少 hostRouterProtocol=1（真实 host 路由、local 页面和 url:false 连接器能力）')
+      }
+    } catch { problems.push(`${specifier} 无法加载，请检查安装版本及其依赖（不输出原始异常）`) }
+  }
+  if (problems.length) {
+    console.error('启动依赖能力检查失败：\n' + problems.join('\n') + '\n请安装与生成器配套构建的包，并重新运行 npm run check:runtime；不会自动改依赖。')
+    process.exitCode = 1
+  } else console.log('启动依赖能力检查通过')
+}
+await checkRuntime()

package/scaffold/base/src/locales/en.ts

@@ -0,0 +1,12 @@
+// 与中文保持相同的业务词条结构。
+export default {
+  demo: {
+    title: 'Locale and state demo',
+    description: 'Switch language, increment or reset. State belongs only to this app.',
+    count: 'Count: {count}',
+    doubled: 'Double count: {count}',
+    increment: 'Increment',
+    reset: 'Reset',
+    switchLanguage: 'Switch language',
+  },
+}

package/scaffold/base/src/locales/index.ts

@@ -1,7 +1,13 @@
 import type { App } from 'vue'
 import { installFinI18n } from '@axewo/fin-ui'
+import zhCN from './zh-CN'
+import en from './en'
 
 /** 每次 createApp 后独立安装，不在模块级共享可变 i18n 实例。 */
 export function installAppLocale(app: App): void {
-  installFinI18n(app, { locale: 'zh-CN', fallbackLocale: 'zh-CN', legacy: false })
+  // 工厂递归合并业务词条，不覆盖 fin-ui 内置语言包。
+  installFinI18n(app, {
+    locale: 'zh-CN', fallbackLocale: 'zh-CN', legacy: false,
+    messages: { 'zh-CN': zhCN, en },
+  })
 }

package/scaffold/base/src/locales/zh-CN.ts

@@ -0,0 +1,12 @@
+// 业务词条使用独立命名空间，与 fin-ui 内置 fin.* 词条合并。
+export default {
+  demo: {
+    title: '国际化与状态示例',
+    description: '切换语言、增加计数或重置，状态仅属于当前应用。',
+    count: '当前计数：{count}',
+    doubled: '双倍计数：{count}',
+    increment: '增加',
+    reset: '重置',
+    switchLanguage: '切换语言',
+  },
+}

package/scaffold/base/src/main.ts

@@ -1,14 +1,22 @@
 import 'element-plus/dist/index.css'
 import '@axewo/fin-ui/style.css'
 import './styles/index.css'
-import { mount, unmount } from './bootstrap'
+import { createStartupLifecycle } from './utils/errorUtils'
+
+// 动态导入使配置解析等模块求值错误也进入脱敏启动边界。
+const { mount, unmount } = createStartupLifecycle(() => import('./bootstrap'))
 
 // 普通应用直接启动；Vue 子应用模板覆盖本入口，接入微前端生命周期。
 // fin-ui 公开根入口依赖 editor 与 icons，依赖已在公共 package.json 中显式声明。
 void mount()
-window.addEventListener('unload', unmount)
-if (import.meta.hot) import.meta.hot.dispose(() => {
+function onPageHide(event: PageTransitionEvent) {
+  // BFCache 返回时继续使用同一应用；保留监听以处理之后的普通离开。
+  if (!event.persisted) dispose()
+}
+function dispose() {
   // 基座只清理自身实例，不注册 Wujie 子应用全局回调。
-  window.removeEventListener('unload', unmount)
+  window.removeEventListener('pagehide', onPageHide)
   unmount()
-})
+}
+window.addEventListener('pagehide', onPageHide)
+if (import.meta.hot) import.meta.hot.dispose(dispose)

package/scaffold/base/src/router/demo.ts

@@ -0,0 +1,6 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+// 仅定义本地页面，不授予宿主菜单/页签权限；host 默认不自动安装。
+export const demoRoutes: RouteRecordRaw[] = [
+  { path: '/demo', name: 'demo', component: () => import('../views/demo/index.vue') },
+]

package/scaffold/base/src/router/index.ts

@@ -0,0 +1,13 @@
+import { createMemoryHistory, createRouter, type RouteRecordRaw, type Router } from 'vue-router'
+
+/**
+ * 每轮挂载创建独立路由，默认使用空路由表，业务可通过参数传入本地页面。
+ * 此通用工厂不拥有地址栏；host overlay 用真实 history 路由覆盖本文件，vue overlay 按嵌入模式选历史。
+ * 独立使用本工厂时须由调用方负责 URL 适配；本地路由不替代平台认证及 canOpen 检查。
+ * @param routes 本地页面路由表；省略时为空，不自动添加业务页面。
+ * @returns 独立 Router；调用方安装到 App，并在卸载时销毁 history。
+ * @throws 无效路由配置导致的 Vue Router 初始化异常原样抛出。
+ */
+export function createAppRouter(routes: RouteRecordRaw[] = []): Router {
+  return createRouter({ history: createMemoryHistory(), routes })
+}

package/scaffold/base/src/stores/demo.ts

@@ -0,0 +1,12 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+
+// 只定义 store，不在模块顶层实例化；状态由当前应用安装的 Pinia 隔离。
+export const useDemoStore = defineStore('demo', () => {
+  const count = ref(0)
+  const doubled = computed(() => count.value * 2)
+  function increment(): void { count.value++ }
+  // setup store 显式提供重置 action，不使用 options store 的默认 $reset。
+  function reset(): void { count.value = 0 }
+  return { count, doubled, increment, reset }
+})

package/scaffold/base/src/stores/index.ts

@@ -0,0 +1,11 @@
+import { createPinia, type Pinia } from 'pinia'
+
+/**
+ * 每个 Vue App、每轮挂载独立创建状态容器，禁止导出跨应用共享的模块级单例。
+ * @returns 未安装的独立 Pinia；调用方通过 app.use 安装，卸载时通过 disposePinia 释放。
+ * @throws 不额外包装底层初始化异常。
+ * @remarks 无参数；业务 store 需在安装后使用，组件外调用须显式传入所属 Pinia。
+ */
+export function createAppPinia(): Pinia {
+  return createPinia()
+}

package/scaffold/base/src/utils/appConfig.ts

@@ -0,0 +1,49 @@
+/** 构建时公开配置；VITE_* 均会进入前端产物，禁止放入任何密码或 Token。 */
+export interface AppConfig {
+  /** Axios API 目录；相对地址仅允许当前源的绝对路径。 */
+  readonly apiBase: string
+  /** 凭据允许发送的精确 API 目录，不从请求参数推断或扩大。 */
+  readonly trustedApiBase: string
+  /** 请求超时毫秒数，必须为正有限整数且不超过原生计时器上限。 */
+  readonly timeout: number
+  /** 是否允许跨源 Cookie；服务端仍须配置精确 CORS 与 CSRF 防护。 */
+  readonly withCredentials: boolean
+}
+
+/** 校验公开 HTTP(S) 地址；拒绝凭据、查询、片段、协议相对地址及编码路径歧义，不回显输入。 */
+export function validateAddress(value: string, directory = true): string {
+  if (typeof value !== 'string' || !value || value.trim() !== value || /[\\\s\u0000-\u001f\u007f]/.test(value) || /%(?:2f|5c|2e)/i.test(value) || /(?:^|\/)\.{1,2}(?:\/|$)/.test(value)) throw new Error('应用地址配置无效')
+  const relative = value.startsWith('/') && !value.startsWith('//')
+  if (!relative && !/^https?:\/\//i.test(value)) throw new Error('应用地址必须为 HTTP(S) 或同源绝对路径')
+  const url = new URL(value, 'https://config.invalid')
+  if (url.username || url.password || /[?#]/.test(value) || (directory && !url.pathname.endsWith('/'))) throw new Error('应用地址必须为无凭据、查询和片段的目录')
+  // 只有本机开发地址允许 HTTP；生产网关和代码入口必须使用 HTTPS。
+  if (!relative && url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('非本机应用地址必须使用 HTTPS')
+  return value
+}
+
+/** 将 Vite 环境转换成只读配置；非法值立即拒绝启动，默认值不扩大凭据目录。 */
+export function resolveAppConfig(env: Record<string, unknown> = {}): AppConfig {
+  const apiBase = validateAddress((env.VITE_API_BASE ?? '/api/') as string)
+  const trustedApiBase = validateAddress((env.VITE_TRUSTED_API_BASE ?? apiBase) as string)
+  if (apiBase !== trustedApiBase) throw new Error('API 与可信凭据目录必须一致')
+  const rawTimeout = env.VITE_API_TIMEOUT ?? 30000
+  if ((typeof rawTimeout !== 'string' && typeof rawTimeout !== 'number') || !/^\d+$/.test(String(rawTimeout))) throw new Error('API 超时配置无效')
+  const timeout = Number(rawTimeout)
+  if (!Number.isInteger(timeout) || timeout <= 0 || timeout > 2147483647) throw new Error('API 超时配置无效')
+  const credentials = env.VITE_API_CREDENTIALS ?? 'false'
+  if (credentials !== 'true' && credentials !== 'false') throw new Error('API credentials 配置必须为 true 或 false')
+  return Object.freeze({ apiBase, trustedApiBase, timeout, withCredentials: credentials === 'true' })
+}
+
+/** 解析部署者控制的可信代码入口；只读取构建环境，后台 appIds/menus 不得覆盖 entry。 */
+export function resolveTrustedApp(env: Record<string, unknown> = {}): { readonly appId: string; readonly entry: string } {
+  const appId = env.VITE_MICRO_APP_ID ?? 'business'
+  const entry = env.VITE_MICRO_APP_ENTRY ?? 'http://localhost:7101'
+  if (typeof appId !== 'string' || appId.length > 214 || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(appId)) throw new Error('可信应用 appId 配置无效')
+  if (typeof entry !== 'string' || !/^https?:\/\//i.test(entry)) throw new Error('可信应用 entry 必须为完整 HTTP(S) 地址')
+  return Object.freeze({ appId, entry: validateAddress(entry, false) })
+}
+
+/** 应用模块专属公开配置，不包含宿主认证状态；Node 测试环境使用相同默认值。 */
+export const appConfig = resolveAppConfig(import.meta.env)

package/scaffold/base/src/utils/errorUtils.ts

@@ -0,0 +1,109 @@
+/** 可直接展示/记录的错误分类，不附带原始异常、URL、请求头、响应体或堆栈。 */
+export interface SafeError {
+  readonly kind: 'cancelled' | 'unauthenticated' | 'forbidden' | 'timeout' | 'network' | 'unknown'
+  readonly message: string
+}
+
+/** 复用 Axios、HttpError 和 SDK 的公开判别字段；绝不采用外部 message/cause 作为用户文案。 */
+export function toSafeError(error: unknown): SafeError {
+  const value = error && typeof error === 'object' ? error as Record<string, unknown> : {}
+  const response = value.response && typeof value.response === 'object' ? value.response as Record<string, unknown> : {}
+  const code = value.code
+  const status = response.status ?? value.status
+  // 分段读取 Axios 旧版取消标识，避免被脚手架的大写双下划线占位符校验误识别。
+  if (code === 'ERR_CANCELED' || code === 'CANCELLED' || code === 'SESSION_CHANGED' || value.name === 'AbortError' || value['__CANCEL' + '__'] === true) return { kind: 'cancelled', message: '' }
+  if (status === 401 || code === 'UNAUTHENTICATED') return { kind: 'unauthenticated', message: '登录已失效，请重新登录' }
+  if (status === 403 || code === 'FORBIDDEN') return { kind: 'forbidden', message: '403：无权执行此操作，请联系管理员' }
+  if (code === 'ECONNABORTED' || code === 'ETIMEDOUT' || code === 'TIMEOUT') return { kind: 'timeout', message: '操作超时，请稍后重试' }
+  if (code === 'ERR_NETWORK' || value.name === 'TypeError') return { kind: 'network', message: '连接失败，请检查网络后重试' }
+  return { kind: 'unknown', message: '操作失败，请稍后重试或联系管理员' }
+}
+
+/** Vue/启动边界的保底接收器；只记录白名单分类与固定文案，不日志原始敏感对象。 */
+export function reportError(error: unknown): void {
+  const safe = toSafeError(error)
+  if (safe.kind !== 'cancelled') console.error(safe.message + devDiagnostic(error, 'runtime'))
+}
+
+/** DEV 仅输出固定阶段和标准错误名；不采用外部 name/message、请求、响应或栈。 */
+export function devDiagnostic(error: unknown, stage: 'load-bootstrap' | 'mount' | 'runtime'): string {
+  if (!import.meta.env?.DEV) return ''
+  const name = error && typeof error === 'object' && 'name' in error ? error.name : ''
+  const allowed = ['Error', 'TypeError', 'SyntaxError', 'ReferenceError', 'RangeError', 'URIError', 'AbortError']
+  const kind = typeof name === 'string' && allowed.includes(name) ? name : 'UnknownError'
+  return ` [阶段=${stage}; 错误=${kind}]${kind === 'SyntaxError' ? ' 请先执行 npm run check:runtime 检查模块导出及依赖能力' : ''}`
+}
+
+/**
+ * 在当前应用根节点显示启动占位；不使用全屏定位，不依赖 Vue 或 UI 插件。
+ * @returns 无返回值；无 DOM 或根节点时安全忽略，Vue 挂载后自然替换占位。
+ */
+export function showStartupLoading(): void {
+  if (typeof document === 'undefined') return
+  const container = document.getElementById('app')
+  if (!container) return
+  const text = document.createElement('p')
+  text.setAttribute('role', 'status')
+  text.setAttribute('aria-live', 'polite')
+  text.setAttribute('data-fin-startup', 'loading')
+  text.textContent = '正在启动应用，请稍候…'
+  container.replaceChildren(text)
+}
+
+/** 启动失败的纯文本可重试边界；不插入错误 HTML，不依赖尚未成功安装的 Vue/UI 插件。 */
+export function showStartupError(error: unknown, retry: () => Promise<void>, stage: 'load-bootstrap' | 'mount' = 'mount'): void {
+  if (typeof document === 'undefined') return
+  const container = document.getElementById('app')
+  if (!container) return
+  const text = document.createElement('p')
+  text.setAttribute('role', 'alert')
+  text.textContent = toSafeError(error).kind === 'cancelled' ? '应用启动已取消，可重试启动' : `应用启动失败：${toSafeError(error).message}${devDiagnostic(error, stage)}`
+  const button = document.createElement('button')
+  button.textContent = '重试启动'
+  button.onclick = () => { void retry().catch(reportError) }
+  container.replaceChildren(text, button)
+}
+
+/**
+ * 在入口动态加载 bootstrap，捕获其静态依赖中的配置解析/代码加载失败。
+ * 入口卸载立即推进代次；尚未完成的 import 不得在卸载或下一轮启动后挂载旧应用。
+ * 仅协调启动边界，不替代 bootstrap 内的 router、Pinia 和身份资源清理。
+ */
+export function createStartupLifecycle(load: () => Promise<{ mount(): Promise<void>; unmount(): void }>) {
+  let generation = 0
+  let current: { unmount(): void } | undefined
+  function unmount(): void {
+    generation++
+    const previous = current
+    current = undefined
+    previous?.unmount()
+  }
+  async function mount(): Promise<void> {
+    unmount()
+    const version = generation
+    showStartupLoading()
+    let stage: 'load-bootstrap' | 'mount' = 'load-bootstrap'
+    try {
+      const bootstrap = await load()
+      if (generation !== version) return
+      current = bootstrap
+      stage = 'mount'
+      await bootstrap.mount()
+    } catch (error) {
+      if (generation !== version) return
+      unmount()
+      reportError(error)
+      // 仅当前失败轮次可重试；卸载后遗留按钮或旧回调不得重启已释放的应用。
+      const failedVersion = generation
+      showStartupError(error, () => generation === failedVersion ? mount() : Promise.resolve(), stage)
+    }
+  }
+  return { mount, unmount }
+}
+
+/** 独立执行全部清理回调；一个回调失败不能阻断后续凭据撤销或资源释放。 */
+export function cleanupAll(callbacks: readonly (() => void)[]): void {
+  for (const callback of callbacks) {
+    try { callback() } catch (error) { reportError(error) }
+  }
+}