@axewo/fin-micro 1.0.0 → 2.0.0

package/dist/types/sdk/index.d.ts

@@ -20,16 +20,26 @@ export interface MicroMenuRoute {
     /** 该应用内可导航叶节点的 menuId。 */
     menuId: string;
 }
-/** 宿主登记的应用元信息；entry 必须为 HTTP(S) 地址，菜单配置在创建宿主时递归复制冻结。 */
-export interface MicroApp {
+/** 应用公共元信息；菜单配置在创建宿主时递归复制冻结。 */
+interface MicroAppMetadata {
     appId: string;
     name: string;
-    entry: string;
     /** 可选多级菜单；不配置时保持原有无菜单导航行为。 */
     menus?: readonly MicroMenu[];
     /** 隐藏页面的菜单归属规则；入口 target 路径也自动参与匹配。 */
     menuRoutes?: readonly MicroMenuRoute[];
 }
+/**
+ * 明确区分远端与宿主本地应用；省略 kind 保持原有远端协议，entry 必须为 HTTP(S)。
+ * local 只登记导航身份，不具有执行地址；由宿主自己的 SFC 容器渲染，不能交给 Wujie。
+ */
+export type MicroApp = MicroAppMetadata & ({
+    kind?: 'remote';
+    entry: string;
+} | {
+    kind: 'local';
+    entry?: never;
+});
 /** 打开页面的导航元信息；tabId 在宿主内唯一，route 为应用内绝对路径，不应存放敏感信息。 */
 export interface OpenTab {
     appId: string;
@@ -154,8 +164,12 @@ export type NavigationOperation =
     type: 'open';
     input: OpenTab;
 } | {
-    type: 'activate' | 'refresh' | 'close';
+    type: 'activate' | 'refresh';
     target: TabRef;
+} | {
+    type: 'close';
+    target: TabRef;
+    closeFallback?: TabRef;
 } | {
     type: 'closeMany';
     scope: 'all' | 'others' | 'left' | 'right';
@@ -166,6 +180,8 @@ export type NavigationOperation =
      * 排除项不参与关闭确认，不会扩大页面 SDK 的应用权限；省略时完全保持原有范围选择行为。
      */
     exclude?: readonly TabRef[];
+    /** 活动页被关闭时优先激活仍存活的指定生命周期；不存在时沿用相邻页回落，不创建页面。 */
+    closeFallback?: TabRef;
 } | {
     type: 'back';
     target?: TabRef;
@@ -326,6 +342,48 @@ export declare function createTokenCapability(options: {
     apps: readonly string[];
     handler(context: HostCallContext): Promise<TokenResult>;
 };
+/** 单窗口宿主签发的不透明请求票据；只作内存关联，不含 Token，不得序列化或持久化。 */
+export interface AuthRequestTicket {
+    readonly request: string;
+}
+/** 正式登录失效能力契约；与 getToken 同样必须显式注册并配置可信应用白名单。 */
+export interface AuthCapabilities extends TokenCapabilities {
+    /** 请求发送前签发原对象票据；只关联宿主私有版本，不接受子应用自报版本或身份。 */
+    beginAuthRequest(): AuthRequestTicket;
+    /**
+     * 上报该请求的认证失效；首次有效上报同步撤销会话并返回 true。
+     * 伪造、复制、跨应用、已消费或旧版本票据返回 false；能力越权及生命周期释放仍由 callHost 拒绝。
+     * 本返回值不是业务请求结果，不得据此自动重发请求或恢复身份。
+     */
+    reportAuthFailure(ticket: AuthRequestTicket): boolean;
+}
+/**
+ * 创建会话失效协调能力，复用现有 callHost 白名单与生命周期，不建立事件总线。
+ * @param options apps 是可信应用白名单；getRevision 必须读取宿主私有版本，每次身份/凭据变化递增。
+ * invalidate 必须同步撤销身份并推进版本，不能等待 beforeLeave 或远程注销；抛错仍由 core 隔离。
+ * @returns 两个正式能力配置；票据同时绑定可信 context.appId、对象身份和私有版本，不接受子应用自报 revision。
+ * @remarks 仅支持同窗口对象桥，白名单不是 XSS 沙箱；后台仍须鉴权，不自动刷新 Token 或重放请求。
+ */
+export declare function createAuthFailureCapabilities(options: {
+    apps: readonly string[];
+    getRevision(): number;
+    invalidate(): void;
+}): {
+    beginAuthRequest: {
+        apps: readonly string[];
+        handler(context: HostCallContext): AuthRequestTicket;
+    };
+    reportAuthFailure: {
+        apps: readonly string[];
+        handler(context: HostCallContext, ticket: AuthRequestTicket): boolean;
+    };
+};
+/** 未登录或空权限输入一律拒绝；权限名区分大小写，不进行通配符或隐式角色映射。 */
+export declare function hasPermission(session: SessionInput | null | undefined, permission: string): boolean;
+/** 至少一个明确权限匹配才允许；空数组拒绝，不将空条件解释成公共访问。 */
+export declare function hasAny(session: SessionInput | null | undefined, permissions: readonly string[]): boolean;
+/** 所有明确权限均匹配才允许；空数组或包含空权限名均拒绝。 */
+export declare function hasAll(session: SessionInput | null | undefined, permissions: readonly string[]): boolean;
 /** Wujie 注入约定；可显式传入测试窗口，SDK 本身不导入 Wujie。 */
 export interface MicroWindow extends Window {
     $wujie?: {
@@ -336,3 +394,4 @@ export interface MicroWindow extends Window {
 }
 /** 获取 target 上的桥；默认浏览器 window，独立运行或 Node/SSR 无 window 时返回 undefined，不创建宿主。 */
 export declare function getMicroBridge<C extends CapabilityContract<C> = HostCapabilities>(target?: MicroWindow): AppBridge<C> | undefined;
+export {};

package/dist/types/vue/index.d.ts

@@ -1,7 +1,18 @@
-import { PropType } from 'vue';
+import { PropType, MaybeRefOrGetter } from 'vue';
+import { SessionSnapshot, AppBridge, MicroTab, PageSDK, CapabilityContract } from '../sdk';
 import { MicroHost } from '../core';
 import { MicroRuntime } from '../runtime';
-import { AppBridge, MicroTab, PageSDK, CapabilityContract } from '../sdk';
+/**
+ * 根据响应式公开会话消费权限；不读取 Token、不绕过核心准入或后台鉴权。
+ * @param session 当前 SessionSnapshot 的 ref/getter，未连接或未登录安全拒绝。
+ * @returns 三种判断函数；在 computed/模板中调用会追踪最新权限，can 用于直接生成权限计算值。
+ */
+export declare function usePermission(session: MaybeRefOrGetter<SessionSnapshot | null | undefined>): {
+    hasPermission: (permission: string) => boolean;
+    hasAny: (permissions: readonly string[]) => boolean;
+    hasAll: (permissions: readonly string[]) => boolean;
+    can: (permission: MaybeRefOrGetter<string>) => import('vue').ComputedRef<boolean>;
+};
 export { useMicroTab } from './tab-context';
 export { MicroRouteView, type MicroRouteErrorCode } from './router-view';
 /** 应用共享容器：appId 对应一个 runtime 实例；挂载失败显示错误，组件卸载触发异步 unmount。不是页级缓存组件，不应在每次切 tab 时销毁。 */

package/dist/types/vue/router-view-impl.d.ts

@@ -8,7 +8,7 @@ import { MicroRouteErrorCode } from './router-view';
  *
  * 这里只解析与加载页面，不启动导航事务、不执行 Vue Router 导航守卫、不修改宿主页签和权限。
  * redirect 不替代宿主 canOpen；业务必须保证重定向目标属于该应用已授权页面，鉴权仍由宿主/core 负责。
- * 页面定位等价于从 START_LOCATION 发起解析：相对 redirect 以应用根为基准，函数 redirect 的 from 为 START_LOCATION。
+ * 页面定位等价于从 START_LOCATION 发起解析：相对 redirect 以应用根为基准，函数 redirect 按公开契约只接收目标 route。
  * 建议 redirect 使用绝对 path 或 name；不会把其他页签的全局 currentRoute 当作本页的导航来源。
  * 页面跳转和离页确认应使用页面 SDK；不要通过 RouterLink/router.push 把全局路由当作宿主页签导航。
  * 懒加载无法取消网络请求；卸载后忽略迟到结果，不再写入组件状态。模块加载后的组件 setup/render 异常由 Vue 错误边界处理。

package/dist/vue.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("vue"),s=Symbol("micro-tab");function d(){const t=e.inject(s);if(!t)throw new Error("useMicroTab 必须在 MicroTabCache 内调用");return t}const m=e.defineComponent({name:"MicroRouteView",props:{name:{type:String,default:"default"}},slots:Object,setup(t,{slots:n}){const i=d(),a=e.shallowRef(),r=e.shallowRef(!1);let u=!1,c=!1;async function o(){if(!(u||c)){c=!0,r.value=!1;try{const l=await Promise.resolve().then(()=>require("./router-view-impl-CgLEalx4.cjs"));u||(a.value=l.MicroRouteViewImpl)}catch{u||(r.value=!0)}finally{c=!1}}}return e.onBeforeUnmount(()=>{u=!0}),o(),()=>{var l,f;return a.value?e.h(a.value,{name:t.name},n):r.value?((l=n.error)==null?void 0:l.call(n,{tab:i,code:"LOAD_FAILED",retry:o}))??e.h("div",{role:"alert","data-micro-route-error":"LOAD_FAILED"},[e.h("p","页面加载失败（LOAD_FAILED）"),e.h("button",{type:"button",onClick:o},"重新加载")]):((f=n.loading)==null?void 0:f.call(n,{tab:i}))??e.h("p",{role:"status"},"页面加载中…")}}}),h=e.defineComponent({name:"MicroAppContainer",props:{appId:{type:String,required:!0},runtime:{type:Object,required:!0},retryDisabled:Boolean},setup(t){const n=e.shallowRef(),i=e.shallowRef(""),a=e.shallowRef(!1);let r=!1;async function u(c=!1){if(!(r||a.value||!c&&t.retryDisabled)){a.value=!0,i.value="";try{await t.runtime.mount(t.appId,n.value)}catch(o){r||(i.value=String(o))}finally{r||(a.value=!1)}}}return e.onMounted(()=>{u(!0)}),e.onBeforeUnmount(()=>{r=!0,t.runtime.unmount(t.appId).catch(console.error)}),()=>e.h("section",{style:{height:"100%",minHeight:"420px"},"aria-busy":a.value},[i.value?e.h("div",{role:"alert"},[e.h("p",i.value),e.h("button",{type:"button",disabled:t.retryDisabled||a.value,onClick:()=>{u()}},"重新加载")]):null,a.value?e.h("p",{role:"status"},"子应用加载中…"):null,e.h("div",{ref:n,style:{height:"100%",minHeight:"420px"}})])}});function v(t){const n=e.shallowRef(t.getState()),i=t.subscribe(a=>{n.value=a});return e.onBeforeUnmount(i),n}const b=e.defineComponent({name:"MicroTabBoundary",props:{tab:{type:Object,required:!0},active:Boolean},setup(t,{slots:n}){const i=Object.freeze({...t.tab});e.provide(s,i);const a=e.defineComponent({name:"MicroTabContent",setup:()=>()=>{var r;return(r=n.default)==null?void 0:r.call(n,{tab:i})}});return()=>e.h("section",{hidden:!t.active,"data-micro-tab":i.key},[e.h(e.KeepAlive,null,{default:()=>t.active?e.h(a):null})])}}),p=e.defineComponent({name:"MicroTabCache",props:{tabs:{type:Array,required:!0},activeKey:String,max:{type:Number,default:20}},setup(t,{slots:n}){const i=e.shallowRef([]);return e.watch(()=>[t.tabs,t.activeKey,t.max],()=>{const a=new Set(t.tabs.map(o=>o.key));let r=i.value.filter(o=>a.has(o.key));const u=t.tabs.find(o=>o.key===t.activeKey);u&&(r=[...r.filter(o=>o.key!==u.key),u]);const c=Number.isFinite(t.max)?Math.max(1,Math.floor(t.max)):20;for(;r.length>c;){const o=r.findIndex(l=>l.key!==t.activeKey);if(o<0)break;r.splice(o,1)}i.value=r},{immediate:!0,flush:"sync"}),()=>i.value.map(a=>e.h(b,{key:a.key,tab:a,active:a.key===t.activeKey},n))}});function M(t,n,i=console.error){let a=!1,r,u=!1,c=0;async function o(){if(!u){u=!0;try{let f=-1;for(;!a&&r&&f!==c;){f=c;try{await n.replace(r.route,r)}catch(y){i(y)}}}finally{u=!1}}}const l=t.ready(f=>{r=f,c++,o()});return()=>{a=!0,l()}}function w(t,n){const i=t.page(n.key);return e.onBeforeUnmount(i.dispose),i}exports.MicroAppContainer=h;exports.MicroRouteView=m;exports.MicroTabCache=p;exports.connectMicroRouter=M;exports.useMicroHost=v;exports.useMicroPage=w;exports.useMicroTab=d;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("vue"),f=require("./sdk.cjs"),d=Symbol("micro-tab");function m(){const t=e.inject(d);if(!t)throw new Error("useMicroTab 必须在 MicroTabCache 内调用");return t}const y=e.defineComponent({name:"MicroRouteView",props:{name:{type:String,default:"default"}},slots:Object,setup(t,{slots:n}){const i=m(),a=e.shallowRef(),r=e.shallowRef(!1);let u=!1,c=!1;async function o(){if(!(u||c)){c=!0,r.value=!1;try{const l=await Promise.resolve().then(()=>require("./router-view-impl-BvOToV_Z.cjs"));u||(a.value=l.MicroRouteViewImpl)}catch{u||(r.value=!0)}finally{c=!1}}}return e.onBeforeUnmount(()=>{u=!0}),o(),()=>{var l,s;return a.value?e.h(a.value,{name:t.name},n):r.value?((l=n.error)==null?void 0:l.call(n,{tab:i,code:"LOAD_FAILED",retry:o}))??e.h("div",{role:"alert","data-micro-route-error":"LOAD_FAILED"},[e.h("p","页面加载失败（LOAD_FAILED）"),e.h("button",{type:"button",onClick:o},"重新加载")]):((s=n.loading)==null?void 0:s.call(n,{tab:i}))??e.h("p",{role:"status"},"页面加载中…")}}});function v(t){return{hasPermission:n=>f.hasPermission(e.toValue(t),n),hasAny:n=>f.hasAny(e.toValue(t),n),hasAll:n=>f.hasAll(e.toValue(t),n),can:n=>e.computed(()=>f.hasPermission(e.toValue(t),e.toValue(n)))}}const b=e.defineComponent({name:"MicroAppContainer",props:{appId:{type:String,required:!0},runtime:{type:Object,required:!0},retryDisabled:Boolean},setup(t){const n=e.shallowRef(),i=e.shallowRef(""),a=e.shallowRef(!1);let r=!1;async function u(c=!1){if(!(r||a.value||!c&&t.retryDisabled)){a.value=!0,i.value="";try{await t.runtime.mount(t.appId,n.value)}catch{r||(i.value="子应用加载失败，请重试或联系管理员")}finally{r||(a.value=!1)}}}return e.onMounted(()=>{u(!0)}),e.onBeforeUnmount(()=>{r=!0,t.runtime.unmount(t.appId).catch(()=>console.error("[fin-micro] 子应用资源释放失败"))}),()=>e.h("section",{style:{height:"100%",minHeight:"420px"},"aria-busy":a.value},[i.value?e.h("div",{role:"alert"},[e.h("p",i.value),e.h("button",{type:"button",disabled:t.retryDisabled||a.value,onClick:()=>{u()}},"重新加载")]):null,a.value?e.h("p",{role:"status"},"子应用加载中…"):null,e.h("div",{ref:n,style:{height:"100%",minHeight:"420px"}})])}});function p(t){const n=e.shallowRef(t.getState()),i=t.subscribe(a=>{n.value=a});return e.onBeforeUnmount(i),n}const M=e.defineComponent({name:"MicroTabBoundary",props:{tab:{type:Object,required:!0},active:Boolean},setup(t,{slots:n}){const i=Object.freeze({...t.tab});e.provide(d,i);const a=e.defineComponent({name:"MicroTabContent",setup:()=>()=>{var r;return(r=n.default)==null?void 0:r.call(n,{tab:i})}});return()=>e.h("section",{hidden:!t.active,"data-micro-tab":i.key},[e.h(e.KeepAlive,null,{default:()=>t.active?e.h(a):null})])}}),w=e.defineComponent({name:"MicroTabCache",props:{tabs:{type:Array,required:!0},activeKey:String,max:{type:Number,default:20}},setup(t,{slots:n}){const i=e.shallowRef([]);return e.watch(()=>[t.tabs,t.activeKey,t.max],()=>{const a=new Set(t.tabs.map(o=>o.key));let r=i.value.filter(o=>a.has(o.key));const u=t.tabs.find(o=>o.key===t.activeKey);u&&(r=[...r.filter(o=>o.key!==u.key),u]);const c=Number.isFinite(t.max)?Math.max(1,Math.floor(t.max)):20;for(;r.length>c;){const o=r.findIndex(l=>l.key!==t.activeKey);if(o<0)break;r.splice(o,1)}i.value=r},{immediate:!0,flush:"sync"}),()=>i.value.map(a=>e.h(M,{key:a.key,tab:a,active:a.key===t.activeKey},n))}});function g(t,n,i=()=>console.error("[fin-micro] 路由同步失败")){let a=!1,r,u=!1,c=0;async function o(){if(!u){u=!0;try{let s=-1;for(;!a&&r&&s!==c;){s=c;try{await n.replace(r.route,r)}catch(h){try{i(h)}catch{}}}}finally{u=!1}}}const l=t.ready(s=>{r=s,c++,o()});return()=>{a=!0,l()}}function k(t,n){const i=t.page(n.key);return e.onBeforeUnmount(i.dispose),i}exports.MicroAppContainer=b;exports.MicroRouteView=y;exports.MicroTabCache=w;exports.connectMicroRouter=g;exports.useMicroHost=p;exports.useMicroPage=k;exports.useMicroTab=m;exports.usePermission=v;

package/dist/vue.mjs

@@ -1,22 +1,23 @@
-import { inject as b, defineComponent as s, shallowRef as d, onBeforeUnmount as y, h as u, onMounted as p, provide as h, KeepAlive as M, watch as g } from "vue";
-const m = Symbol("micro-tab");
-function k() {
-  const e = b(m);
+import { inject as p, defineComponent as y, shallowRef as d, onBeforeUnmount as m, h as u, onMounted as M, provide as g, KeepAlive as k, watch as A, computed as w, toValue as s } from "vue";
+import { hasPermission as v, hasAll as x, hasAny as C } from "./sdk.mjs";
+const b = Symbol("micro-tab");
+function D() {
+  const e = p(b);
   if (!e) throw new Error("useMicroTab 必须在 MicroTabCache 内调用");
   return e;
 }
-const A = s({
+const O = y({
   name: "MicroRouteView",
   props: { name: { type: String, default: "default" } },
   slots: Object,
   setup(e, { slots: t }) {
-    const r = k(), a = d(), n = d(!1);
+    const r = D(), a = d(), n = d(!1);
     let o = !1, c = !1;
     async function i() {
       if (!(o || c)) {
         c = !0, n.value = !1;
         try {
-          const l = await import("./router-view-impl-C1KG6mxu.mjs");
+          const l = await import("./router-view-impl-B1NzCGKV.mjs");
           o || (a.value = l.MicroRouteViewImpl);
         } catch {
           o || (n.value = !0);
@@ -25,7 +26,7 @@ const A = s({
         }
       }
     }
-    return y(() => {
+    return m(() => {
       o = !0;
     }), i(), () => {
       var l, f;
@@ -35,7 +36,16 @@ const A = s({
       ]) : ((f = t.loading) == null ? void 0 : f.call(t, { tab: r })) ?? u("p", { role: "status" }, "页面加载中…");
     };
   }
-}), C = s({
+});
+function L(e) {
+  return {
+    hasPermission: (t) => v(s(e), t),
+    hasAny: (t) => C(s(e), t),
+    hasAll: (t) => x(s(e), t),
+    can: (t) => w(() => v(s(e), s(t)))
+  };
+}
+const S = y({
   name: "MicroAppContainer",
   props: {
     appId: { type: String, required: !0 },
@@ -50,17 +60,17 @@ const A = s({
         a.value = !0, r.value = "";
         try {
           await e.runtime.mount(e.appId, t.value);
-        } catch (i) {
-          n || (r.value = String(i));
+        } catch {
+          n || (r.value = "子应用加载失败，请重试或联系管理员");
         } finally {
           n || (a.value = !1);
         }
       }
     }
-    return p(() => {
+    return M(() => {
       o(!0);
-    }), y(() => {
-      n = !0, e.runtime.unmount(e.appId).catch(console.error);
+    }), m(() => {
+      n = !0, e.runtime.unmount(e.appId).catch(() => console.error("[fin-micro] 子应用资源释放失败"));
     }), () => u("section", { style: { height: "100%", minHeight: "420px" }, "aria-busy": a.value }, [
       r.value ? u("div", { role: "alert" }, [
         u("p", r.value),
@@ -73,13 +83,13 @@ const A = s({
     ]);
   }
 });
-function D(e) {
+function j(e) {
   const t = d(e.getState()), r = e.subscribe((a) => {
     t.value = a;
   });
-  return y(r), t;
+  return m(r), t;
 }
-const w = s({
+const T = y({
   name: "MicroTabBoundary",
   props: {
     tab: { type: Object, required: !0 },
@@ -87,16 +97,16 @@ const w = s({
   },
   setup(e, { slots: t }) {
     const r = Object.freeze({ ...e.tab });
-    h(m, r);
-    const a = s({ name: "MicroTabContent", setup: () => () => {
+    g(b, r);
+    const a = y({ name: "MicroTabContent", setup: () => () => {
       var n;
       return (n = t.default) == null ? void 0 : n.call(t, { tab: r });
     } });
     return () => u("section", { hidden: !e.active, "data-micro-tab": r.key }, [
-      u(M, null, { default: () => e.active ? u(a) : null })
+      u(k, null, { default: () => e.active ? u(a) : null })
     ]);
   }
-}), T = s({
+}), B = y({
   name: "MicroTabCache",
   props: {
     tabs: { type: Array, required: !0 },
@@ -105,7 +115,7 @@ const w = s({
   },
   setup(e, { slots: t }) {
     const r = d([]);
-    return g(() => [e.tabs, e.activeKey, e.max], () => {
+    return A(() => [e.tabs, e.activeKey, e.max], () => {
       const a = new Set(e.tabs.map((i) => i.key));
       let n = r.value.filter((i) => a.has(i.key));
       const o = e.tabs.find((i) => i.key === e.activeKey);
@@ -117,14 +127,14 @@ const w = s({
         n.splice(i, 1);
       }
       r.value = n;
-    }, { immediate: !0, flush: "sync" }), () => r.value.map((a) => u(w, {
+    }, { immediate: !0, flush: "sync" }), () => r.value.map((a) => u(T, {
       key: a.key,
       tab: a,
       active: a.key === e.activeKey
     }, t));
   }
 });
-function I(e, t, r = console.error) {
+function R(e, t, r = () => console.error("[fin-micro] 路由同步失败")) {
   let a = !1, n, o = !1, c = 0;
   async function i() {
     if (!o) {
@@ -135,8 +145,11 @@ function I(e, t, r = console.error) {
           f = c;
           try {
             await t.replace(n.route, n);
-          } catch (v) {
-            r(v);
+          } catch (h) {
+            try {
+              r(h);
+            } catch {
+            }
           }
         }
       } finally {
@@ -151,16 +164,17 @@ function I(e, t, r = console.error) {
     a = !0, l();
   };
 }
-function K(e, t) {
+function q(e, t) {
   const r = e.page(t.key);
-  return y(r.dispose), r;
+  return m(r.dispose), r;
 }
 export {
-  C as MicroAppContainer,
-  A as MicroRouteView,
-  T as MicroTabCache,
-  I as connectMicroRouter,
-  D as useMicroHost,
-  K as useMicroPage,
-  k as useMicroTab
+  S as MicroAppContainer,
+  O as MicroRouteView,
+  B as MicroTabCache,
+  R as connectMicroRouter,
+  j as useMicroHost,
+  q as useMicroPage,
+  D as useMicroTab,
+  L as usePermission
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axewo/fin-micro",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -86,7 +86,7 @@
   "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",
     "check:package": "node scripts/check-package.mjs"

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/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/DemoView.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)