@axewo/fin-micro 1.0.0 → 2.0.0

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

@@ -0,0 +1,92 @@
+/** 可直接展示/记录的错误分类，不附带原始异常、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 检查模块导出及依赖能力' : ''}`
+}
+
+/** 启动失败的纯文本可重试边界；不插入错误 HTML，不依赖尚未成功安装的 Vue/UI 插件。 */
+export function showStartupError(error: unknown, retry: () => Promise<void>, stage: 'load-bootstrap' | 'mount' = 'mount'): void {
+  if (toSafeError(error).kind === 'cancelled' || 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).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
+    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) }
+  }
+}

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

@@ -1,4 +1,6 @@
 import { AxiosHttpClient } from '@axewo/fin-core/http/axios'
+import { appConfig, validateAddress } from './appConfig'
+import { toSafeError, reportError } from './errorUtils'
 
 /**
  * 应用独立的 Axios 请求实例；由 base 生成到基座和子应用，各项目自行定义拦截器。
@@ -11,9 +13,9 @@ import { AxiosHttpClient } from '@axewo/fin-core/http/axios'
  * 响应拦截器须返回AxiosResponse，而不是直接返回response.data；错误保持AxiosError/isCancel语义。
  */
 export const http = new AxiosHttpClient({
-  baseURL: '/api/',
-  timeout: 30000,
-  withCredentials: false,
+  baseURL: appConfig.apiBase,
+  timeout: appConfig.timeout,
+  withCredentials: appConfig.withCredentials,
 })
 
 /** 按请求读取最新凭据；独立应用可显式安装自己的 provider，基座默认不读取 bridge。 */
@@ -24,6 +26,12 @@ interface TokenBinding {
   active: boolean
   pending: Set<AbortController>
   previous?: TokenBinding
+  begin?: (signal: AbortSignal) => Promise<() => Promise<unknown>>
+}
+const requestFailures = new WeakMap<object, () => Promise<unknown>>()
+/** 失效回调只影响认证；自身失败隔离，不覆盖原始 Axios/SDK 错误。 */
+async function notifyFailure(callback: (() => Promise<unknown>) | undefined): Promise<void> {
+  try { await callback?.() } catch (error) { reportError(error) }
 }
 let tokenBinding: TokenBinding | undefined
 /**
@@ -35,13 +43,15 @@ let tokenBinding: TokenBinding | undefined
  * @returns 幂等释放函数，取消挂起读取并恢复仍有效的前一个绑定，不撤回已发出的网络请求。
  * @throws 可信地址无效时立即抛错；provider 失败使本次请求拒绝，不降级匿名重发。
  */
-export function installRequestTokenProvider(provider: RequestTokenProvider, trustedApiBase = '/api/'): () => void {
+export function installRequestTokenProvider(provider: RequestTokenProvider, trustedApiBase = appConfig.trustedApiBase,
+  begin?: (signal: AbortSignal) => Promise<() => Promise<unknown>>): () => void {
   const location = globalThis.location
   if (!location && !/^https:\/\//i.test(trustedApiBase)) throw new Error('无浏览器来源时必须显式配置绝对 HTTPS API')
+  validateAddress(trustedApiBase)
   const api = new URL(trustedApiBase, location?.href)
   if (!['http:', 'https:'].includes(api.protocol) || api.username || api.password || api.search || api.hash || !api.pathname.endsWith('/')) throw new Error('可信 API 必须是 HTTP(S) 目录地址')
   if (api.protocol !== 'https:' && (!location || api.origin !== location.origin)) throw new Error('跨源可信 API 必须使用 HTTPS')
-  const binding: TokenBinding = { provider, api, active: true, pending: new Set(), previous: tokenBinding }
+  const binding: TokenBinding = { provider, api, begin, active: true, pending: new Set(), previous: tokenBinding }
   tokenBinding = binding
   return () => {
     binding.active = false
@@ -79,10 +89,12 @@ http.interceptors.request.use(
     config.signal?.addEventListener?.('abort', abort)
     binding.pending.add(controller)
     try {
-      if (controller.signal.aborted) throw new Error('凭据读取已取消')
+      if (controller.signal.aborted) throw new DOMException('凭据读取已取消', 'AbortError')
+      const failure = await binding.begin?.(controller.signal)
+      if (failure) requestFailures.set(config, async () => { if (binding.active && tokenBinding === binding) await failure() })
       // Promise 竞速确保不合作的独立 provider 也不会在卸载后继续发送请求。
       const token = await new Promise<string | null>((resolve, reject) => {
-        const cancelled = () => reject(new Error('凭据读取已取消'))
+        const cancelled = () => reject(new DOMException('凭据读取已取消', 'AbortError'))
         controller.signal.addEventListener('abort', cancelled, { once: true })
         // 竞速一旦结束立即释放监听，不等待不合作 provider 的底层 Promise。
         const settle = <T>(callback: (value: T) => void, value: T) => {
@@ -91,11 +103,15 @@ http.interceptors.request.use(
         }
         Promise.resolve().then(() => binding.provider(controller.signal)).then(value => settle(resolve, value), error => settle(reject, error))
       })
-      if (controller.signal.aborted || !binding.active || tokenBinding !== binding) throw new Error('凭据来源已释放')
+      if (controller.signal.aborted || !binding.active || tokenBinding !== binding) throw new DOMException('凭据来源已释放', 'AbortError')
       if (token !== null && (typeof token !== 'string' || !token || token.length > 16384 || /[\s\u0000-\u001f\u007f]/.test(token))) throw new Error('凭据格式无效')
       // Cookie 模式的 null 不添加头；不缓存凭据，不刷新登录、不自动重试写请求。
       if (token !== null) config.headers.set('Authorization', `Bearer ${token}`)
       return config
+    } catch (error) {
+      if (toSafeError(error).kind === 'unauthenticated') await notifyFailure(requestFailures.get(config))
+      requestFailures.delete(config)
+      throw error
     } finally {
       binding.pending.delete(controller)
       config.signal?.removeEventListener?.('abort', abort)
@@ -113,11 +129,16 @@ http.interceptors.request.use(
  */
 http.interceptors.response.use(
   response => {
-    // 业务替换点：检查 response.data 中的业务状态，不假设固定 code/data 结构。
+    requestFailures.delete(response.config)
     return response
   },
-  error => {
-    // 业务替换点：按应用规范区分取消、网络异常、HTTP 401 及其他错误。
+  async error => {
+    const config = error?.config ?? error?.response?.config
+    if (config && typeof config === 'object') {
+      const callback = requestFailures.get(config)
+      requestFailures.delete(config)
+      if (toSafeError(error).kind === 'unauthenticated') await notifyFailure(callback)
+    }
     return Promise.reject(error)
   },
 )

package/scaffold/base/src/views/DemoView.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { storeToRefs } from 'pinia'
+import { useI18n } from 'vue-i18n'
+import { useDemoStore } from '../stores/demo'
+
+// 全局词条来自 installAppLocale，切换仅影响当前 Vue App 的 Provider。
+const { t, locale } = useI18n({ useScope: 'global' })
+const demo = useDemoStore()
+// 解构响应式状态使用 storeToRefs；action 仍通过 store 调用。
+const { count, doubled } = storeToRefs(demo)
+function switchLanguage(): void {
+  locale.value = locale.value === 'zh-CN' ? 'en' : 'zh-CN'
+}
+</script>
+
+<template>
+  <section>
+    <h1>{{ t('demo.title') }}</h1>
+    <p>{{ t('demo.description') }}</p>
+    <p aria-live="polite">{{ t('demo.count', { count }) }}</p>
+    <p>{{ t('demo.doubled', { count: doubled }) }}</p>
+    <button type="button" @click="demo.increment()">{{ t('demo.increment') }}</button>
+    <button type="button" @click="demo.reset()">{{ t('demo.reset') }}</button>
+    <button type="button" @click="switchLanguage">{{ t('demo.switchLanguage') }}</button>
+  </section>
+</template>

package/scaffold/host/.env.example

@@ -1,5 +1,13 @@
-# 仅本地演示可打开；正式部署必须接入 src/platform.ts 的真实认证接口。
-VITE_AUTH_DEMO=false
-# 业务子应用地址和 appId 必须与子应用部署配置一致；仅允许可信 HTTP(S) 地址。
+# 开发默认演示登录，无需后端、不收集账号密码；设为 false 后联调真实认证。
+# 生产构建始终禁用演示，即使设置 true；必须接入 src/platform.ts 的真实认证接口。
+VITE_AUTH_DEMO=true
+# 公开 API 配置会进入浏览器产物，严禁填写密码或 Token；子应用可在自己的 .env.local 使用同名字段。
+# 两个目录必须完全一致且以 / 结尾；跨源网关使用 HTTPS。超时单位为毫秒。
+VITE_API_BASE=/api/
+VITE_TRUSTED_API_BASE=/api/
+VITE_API_TIMEOUT=30000
+# 跨源 Cookie 必须显式打开，并在服务端配置精确 CORS、HttpOnly、SameSite 与 CSRF 防护。
+VITE_API_CREDENTIALS=false
+# 业务子应用地址和 appId 必须与子应用部署配置一致；仅本机开发允许 HTTP，正式入口使用 HTTPS。
 VITE_MICRO_APP_ID=business
 VITE_MICRO_APP_ENTRY=http://localhost:7101

package/scaffold/host/src/App.vue

@@ -1,16 +1,4 @@
 <script setup lang="ts">
 import AppProviders from './components/AppProviders.vue'
-import HostLayout from './layout/HostLayout.vue'
-import LoginView from './views/LoginView.vue'
-import { usePlatformSession } from './hooks/usePlatformSession'
-
-// 根组件只切换登录页与已认证工作区；身份就绪前不创建微前端宿主。
-const { session, loading, error, signIn, restore, signOut } = usePlatformSession()
 </script>
-
-<template>
-  <AppProviders>
-    <HostLayout v-if="session" :key="session.user.id" :session="session" @logout="signOut" />
-    <LoginView v-else :loading="loading" :error="error" :sign-in="signIn" @restore="restore" />
-  </AppProviders>
-</template>
+<template><AppProviders><RouterView /></AppProviders></template>

package/scaffold/host/src/bootstrap.ts

@@ -1,18 +1,50 @@
-import { createApp, type App as VueApp } from 'vue'
+import { createApp } from 'vue'
+import { disposePinia } from 'pinia'
 import ElementPlus from 'element-plus'
 import App from './App.vue'
 import { installAppLocale } from './locales'
-let app: VueApp | undefined
+import { createAppRouter } from './router'
+import { createAppPinia } from './stores'
+import { reportError, cleanupAll } from './utils/errorUtils'
+import { createPlatformSession, platformSessionKey } from './hooks/usePlatformSession'
+let cleanup: (() => void) | undefined
 
 /** 幂等释放整个认证与宿主组件树，组件内负责停止请求、会话订阅及 runtime。 */
-export function unmount(): void { app?.unmount(); app = undefined }
+export function unmount(): void { cleanup?.(); cleanup = undefined }
 
 /** 无参数启动平台；宿主只会在 App 完成认证后创建，不在此绕过登录门禁。 */
 export async function mount(): Promise<void> {
   unmount()
-  app = createApp(App)
-  // 根组件 setup 前安装，登录页和工作区共用当前应用的语言上下文。
-  installAppLocale(app)
-  app.use(ElementPlus)
-  app.mount('#app')
+  const app = createApp(App)
+  const controller = createPlatformSession()
+  const router = createAppRouter(controller, undefined, { onError: reportError })
+  app.provide(platformSessionKey, controller)
+  const pinia = createAppPinia()
+  let mounted = false
+  let stopped = false
+  cleanup = () => {
+    if (stopped) return
+    stopped = true
+    cleanupAll([
+      () => { if (mounted) app.unmount() },
+      () => router.disposeGuards(), () => router.options.history.destroy(), () => disposePinia(pinia), () => controller.dispose(),
+    ])
+  }
+  try {
+    // 根组件 setup 前安装，登录页和工作区共用当前应用的语言上下文。
+    app.config.errorHandler = reportError
+    installAppLocale(app)
+    app.use(ElementPlus)
+    app.use(pinia)
+    // 首次导航等待一次性认证恢复，不渲染半就绪工作区。
+    app.use(router)
+    await router.isReady()
+    if (stopped) return
+    app.mount('#app')
+    mounted = true
+  } catch (error) {
+    unmount()
+    // 启动文案与可重试边界由 main 的代次保护入口统一展示，不遗留旧启动回调。
+    throw error
+  }
 }

package/scaffold/host/src/hooks/usePlatformSession.ts

@@ -1,21 +1,39 @@
-import { onBeforeUnmount, ref, shallowRef } from 'vue'
-import { activateSessionToken, clearAccessToken, getAccessToken, login, logout, restoreSession } from '../platform'
+import { inject, ref, shallowRef, type InjectionKey } from 'vue'
+import { activateSessionToken, clearAccessToken, clearDemoSession, getAccessToken, login, logout, restoreSession } from '../platform'
 import type { PlatformSession } from '../types/platform'
+import { getTokenRevision } from '../platform'
+import { installPlatformExpiry } from '../utils/request'
+import { toSafeError } from '../utils/errorUtils'
 
 /**
- * 在组件 setup 内创建平台会话控制器，并立即发起恢复；组件卸载时中止请求。
+ * 每个 App 在 bootstrap 创建一次控制器并发起恢复；卸载时必须调用 dispose。
  * @returns 响应式身份/忙碌/错误状态及登录、恢复、退出操作；操作错误写入 error，不向表单抛出。
  * 此处只管理身份请求，导航和页面资源由工作区负责；生产登录/CSRF协议在 platform.ts 替换。
  */
-export function usePlatformSession() {
+export function createPlatformSession() {
   const session = shallowRef<PlatformSession | null>(null)
   const loading = ref(false)
   const error = ref('')
   let request: AbortController | undefined
   let generation = 0
+  let disposed = false
+  /** 真正失效优先撤销凭据和身份；同步推进版本合并并发 401，不运行正常退出守卫。 */
+  function expire(revision: number): void {
+    if (!session.value || revision !== getTokenRevision()) return
+    generation++
+    request?.abort()
+    clearAccessToken()
+    // 演示失效也必须撤销刷新恢复标记，不能在下一次刷新复活身份。
+    clearDemoSession()
+    session.value = null
+    loading.value = false
+    error.value = '登录已失效，请重新登录'
+  }
+  const offExpiry = installPlatformExpiry(() => session.value ? getTokenRevision() : undefined, expire)
 
   /** 每次操作中止上一次请求；卸载与重试后晚到响应不能恢复旧身份。 */
   async function run(action: (signal: AbortSignal) => Promise<PlatformSession | null>): Promise<void> {
+    if (disposed) return
     const current = ++generation
     request?.abort()
     // 重新认证/恢复先撤销旧身份及凭据；失败不保留可用的旧 Token。
@@ -32,7 +50,7 @@ export function usePlatformSession() {
         session.value = value
       }
     } catch (cause) {
-      if (current === generation && !controller.signal.aborted) error.value = String(cause)
+      if (current === generation && !controller.signal.aborted) error.value = toSafeError(cause).message
     } finally {
       if (current === generation) loading.value = false
     }
@@ -49,11 +67,25 @@ export function usePlatformSession() {
   /** 立即移除工作区触发资源释放；远程注销失败也不恢复本地旧会话。 */
   function signOut(): void {
     const previousToken = getAccessToken()
+    clearDemoSession()
     session.value = null
     void run(async signal => { await logout(signal, previousToken); return null })
   }
 
-  void restore()
-  onBeforeUnmount(() => { generation++; request?.abort(); clearAccessToken(); session.value = null })
-  return { session, loading, error, signIn, restore, signOut }
+  const ready = restore()
+  function dispose(): void {
+    if (disposed) return
+    disposed = true
+    offExpiry(); generation++; request?.abort(); clearAccessToken(); session.value = null
+  }
+  return { session, loading, error, signIn, restore, signOut, expire, ready, dispose }
+}
+
+export type PlatformSessionController = ReturnType<typeof createPlatformSession>
+export const platformSessionKey: InjectionKey<PlatformSessionController> = Symbol('platform-session')
+/** 只读取当前 App 提供的控制器，不发起第二次恢复或注册监听。 */
+export function usePlatformSession(): PlatformSessionController {
+  const controller = inject(platformSessionKey)
+  if (!controller) throw new Error('未安装平台会话控制器')
+  return controller
 }

package/scaffold/host/src/layout/HostHeader.vue

@@ -1,9 +1,69 @@
 <script setup lang="ts">
-defineProps<{ userName: string; pending: boolean }>()
-const emit = defineEmits<{ logout: [] }>()
+import { computed, ref, watch } from 'vue'
+import { ArrowDown, Bell, Expand, Fold, Search, SwitchButton, User } from '@element-plus/icons-vue'
+import type { MicroApp, MicroMenu } from '@axewo/fin-micro'
+
+/** 顶栏仅维护展示状态；搜索结果仍交由父级授权导航，退出必须经过核心守卫。 */
+const props = defineProps<{ userName: string; activeTitle: string; pending: boolean; collapsed: boolean; apps: readonly MicroApp[] }>()
+const emit = defineEmits<{
+  logout: []
+  profile: []
+  'update:collapsed': [value: boolean]
+  open: [appId: string, menu: MicroMenu]
+  'popover-opened': []
+}>()
+const search = ref('')
+const popover = ref<'search' | 'messages' | 'user' | null>(null)
+/** 只检索当前会话已经授权的真实菜单，不构造额外路由或演示入口。 */
+const entries = computed(() => {
+  const collect = (appId: string, menus: readonly MicroMenu[], parent: string): { appId: string; menu: MicroMenu; path: string }[] => menus.flatMap(menu => {
+    const path = `${parent} / ${menu.name}`
+    return [...(menu.target ? [{ appId, menu, path }] : []), ...collect(appId, menu.children ?? [], path)]
+  })
+  return props.apps.flatMap(app => collect(app.appId, app.menus ?? [], app.name))
+})
+const results = computed(() => entries.value.filter(entry => entry.path.toLowerCase().includes(search.value.trim().toLowerCase())))
+function closePopovers(): void { popover.value = null }
+function showPopover(name: 'search' | 'messages' | 'user'): void {
+  if (props.pending) return
+  popover.value = popover.value === name && name !== 'search' ? null : name
+  if (popover.value) emit('popover-opened')
+}
+function navigate(entry: { appId: string; menu: MicroMenu }): void {
+  if (props.pending) return
+  closePopovers()
+  search.value = ''
+  emit('open', entry.appId, entry.menu)
+}
+// 退出确认可能由业务应用弹窗完成，必须先移除顶栏背板。
+watch(() => props.pending, pending => { if (pending) closePopovers() })
+defineExpose({ closePopovers })
 </script>
 <template>
-  <header class="shell-header"><strong>__PROJECT_NAME__</strong><div class="actions">
-    <span>{{ userName }}</span><el-button :loading="pending" @click="emit('logout')">退出登录</el-button>
-  </div></header>
+  <button v-if="popover" class="popover-backdrop" aria-label="关闭弹出菜单" tabindex="-1" @click="closePopovers" />
+  <header class="shell-topbar" :inert="pending || undefined" @keydown.esc="closePopovers">
+    <div class="brand"><span class="brand-icon" aria-hidden="true">F</span><strong>FIN <span>__PROJECT_NAME__</span></strong></div>
+    <button class="icon-button collapse-toggle" :aria-label="collapsed ? '展开侧栏' : '折叠侧栏'" :aria-expanded="!collapsed" @click="!pending && emit('update:collapsed', !collapsed)">
+      <el-icon aria-hidden="true"><component :is="collapsed ? Expand : Fold" /></el-icon>
+    </button>
+    <div class="shell-breadcrumb"><span>工作空间</span><span>/</span><strong>{{ props.activeTitle }}</strong></div>
+    <!-- 弹性间隔把搜索及账号操作推向右侧，面包屑仍紧跟折叠按钮。 -->
+    <div class="topbar-spacer" />
+    <div class="menu-search">
+      <el-icon aria-hidden="true"><Search /></el-icon><input v-model="search" aria-label="搜索菜单" placeholder="搜索菜单、应用…" @focus="showPopover('search')" @keydown.enter.prevent="!$event.isComposing && results[0] && navigate(results[0])" />
+      <div v-if="popover === 'search'" class="shell-popover search-results">
+        <p class="popover-label">菜单搜索</p>
+        <button v-for="entry in results" :key="JSON.stringify([entry.appId, entry.menu.menuId])" @click="navigate(entry)"><strong>{{ entry.menu.name }}</strong><small>{{ entry.path }}</small></button>
+        <p v-if="!results.length" class="popover-empty">未找到匹配的菜单</p>
+      </div>
+    </div>
+    <div class="topbar-action">
+      <button class="icon-button" aria-label="消息通知" :aria-expanded="popover === 'messages'" @click="showPopover('messages')"><el-icon aria-hidden="true"><Bell /></el-icon></button>
+      <div v-if="popover === 'messages'" class="shell-popover message-popover"><h3>消息通知</h3><div class="empty-state"><strong>尚未接入消息服务</strong><p>接入后将在这里显示真实的通知消息。</p></div></div>
+    </div>
+    <div class="topbar-action">
+      <button class="user-trigger" :aria-expanded="popover === 'user'" @click="showPopover('user')"><span class="avatar">{{ userName.slice(0, 1) }}</span><span>{{ userName }}</span><el-icon aria-hidden="true"><ArrowDown /></el-icon></button>
+      <div v-if="popover === 'user'" class="shell-popover user-popover"><strong>{{ userName }}</strong><hr /><button :disabled="pending" @click="closePopovers(); !pending && emit('profile')"><el-icon aria-hidden="true"><User /></el-icon>个人中心</button><button :disabled="pending" @click="!pending && emit('logout')"><el-icon aria-hidden="true"><SwitchButton /></el-icon>{{ pending ? '正在确认退出…' : '退出登录' }}</button></div>
+    </div>
+  </header>
 </template>

package/scaffold/host/src/layout/HostLayout.vue

@@ -1,41 +1,74 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
 import type { MenuInstance } from 'element-plus'
-import { createMicroHost, createWujieRuntime, connectMicroBrowser, useMicroHost, type MicroMenu, type NavigationOperation } from '@axewo/fin-micro'
-import { createTokenCapability, type TokenCapabilities } from '@axewo/fin-micro/sdk'
+import { createMicroHost, createWujieRuntime, useMicroHost, type MicroMenu, type NavigationOperation } from '@axewo/fin-micro'
+import { createTokenCapability, createAuthFailureCapabilities, type AuthCapabilities } from '@axewo/fin-micro/sdk'
 import { canOpenRoute, getAccessToken, getTokenRevision, publicSession } from '../platform'
 import type { PlatformSession } from '../types/platform'
 import HostHeader from './HostHeader.vue'
 import HostMenu from './HostMenu.vue'
 import HostTabs from './HostTabs.vue'
 import HostWorkspace from './HostWorkspace.vue'
+import { localApp, localTarget, workspaceOperation } from '../localPages'
+import { useRouter } from 'vue-router'
+import { connectWorkspaceBrowser, connectWorkspaceRouter } from '../router/workspace'
+import '../styles/shell.css'
+import { toSafeError, reportError } from '../utils/errorUtils'
 const props = defineProps<{ session: PlatformSession }>()
-const emit = defineEmits<{ logout: [] }>()
+const emit = defineEmits<{ logout: []; expired: [revision: number] }>()
+// 折叠及弹层仅影响宿主展示，不改变授权菜单、浏览器恢复或应用运行时。
+const collapsed = ref(false)
+const header = ref<InstanceType<typeof HostHeader>>()
+const tabBar = ref<InstanceType<typeof HostTabs>>()
+function closePopovers(): void {
+  header.value?.closePopovers()
+  tabBar.value?.closePopovers()
+}
 const notice = ref('')
 const exiting = ref(false)
 let alive = true
-const report = (error: unknown) => { if (alive) notice.value = String(error) }
+const sessionRevision = getTokenRevision()
+const authenticated = () => alive && getTokenRevision() === sessionRevision
+const report = (error: unknown) => { if (alive) notice.value = toSafeError(error).message }
+const trustedApps = props.session.apps.filter(app => app.appId === (import.meta.env.VITE_MICRO_APP_ID || 'business')).map(app => app.appId)
+const failureCapabilities = createAuthFailureCapabilities({
+  apps: trustedApps,
+  getRevision: getTokenRevision,
+  invalidate: () => {
+    if (!alive) return
+    // 立即撤销公开身份与新能力准入；父控制器同步清除私有凭据，不能被 beforeLeave 阻断。
+    host.updateSession({ authenticated: false, permissions: [] })
+    emit('expired', getTokenRevision())
+    alive = false
+  },
+})
 // 认证成功后才创建；只允许当前后台授权并经过可信注册表转换的应用。
-const host = createMicroHost<TokenCapabilities>(props.session.apps, {
+const host = createMicroHost<AuthCapabilities>([localApp, ...props.session.apps], {
   capabilities: {
+    ...failureCapabilities,
     getToken: createTokenCapability({
       // 只授权当前已登录且出自本地可信注册表的业务应用，不使用接口传入的任意 appId。
       apps: props.session.apps.filter(app => app.appId === (import.meta.env.VITE_MICRO_APP_ID || 'business')).map(app => app.appId),
       // exiting 只是离页确认状态；守卫中的保存仍需凭据，确认退出后才由认证控制器清除。
-      getSession: () => ({ ...publicSession(props.session), authenticated: alive, revision: getTokenRevision() }),
+      getSession: () => ({ ...publicSession(props.session), authenticated: authenticated(), revision: getTokenRevision() }),
       // 业务替换点：可改为接收 context.signal 的异步后台读取；helper 会复查会话版本与存活。
       provider: () => getAccessToken(),
     }),
   },
   onError: report,
-  canOpen: input => alive && !exiting.value && canOpenRoute(props.session, input),
+  canOpen: input => authenticated() && !exiting.value && canOpenRoute(props.session, input),
   // 不开放任意请求代理；Token 仅由上面的显式白名单能力提供，跨应用导航另行制定白名单。
   canNavigate: () => false,
 })
 host.updateSession(publicSession(props.session))
 // 身份与授权菜单就绪后才能恢复 URL；用户隔离存储，禁止恢复未通过 canOpen 的入口。
-const browser = connectMicroBrowser(host, { storageKey: `fin-micro:tabs:${props.session.user.id}`, onError: report })
-const runtime = createWujieRuntime({ apps: host.apps, bridge: host.bridge })
+const router = useRouter()
+// 源示例同样在恢复前登记主页：首位、去重并迁移缺少主页的旧快照，不先清空再补页。
+// 此时没有页面或业务守卫；交互切回主页仍须经过 operate 的离页确认。
+const browser = connectWorkspaceBrowser(host, router, { storageKey: `fin-micro:tabs:${props.session.user.id}`, onError: report })
+const workspaceRouter = connectWorkspaceRouter(host, router, () => authenticated() && !exiting.value, report)
+// 运行时只接收远端注册表，本地应用永远不会变成 Wujie 网络加载目标。
+const runtime = createWujieRuntime({ apps: host.apps.filter(app => app.kind !== 'local'), bridge: host.bridge })
 const state = useMicroHost(host)
 const active = computed(() => state.value.tabs.find(tab => tab.tabId === state.value.activeTabId))
 const menu = ref<MenuInstance>()
@@ -77,7 +110,7 @@ const off = host.subscribe(snapshot => {
 async function operate(operation: NavigationOperation): Promise<void> {
   if (exiting.value) return
   try {
-    const result = await host.operate(operation)
+    const result = await host.operate(workspaceOperation(operation, host.getState().tabs))
     if (result.status === 'cancelled') notice.value = '操作已取消'
     if (result.status === 'stale') notice.value = '目标页签已变化，请重试'
   } catch (error) { report(error) }
@@ -88,6 +121,7 @@ function open(appId: string, menu: MicroMenu): void {
 /** 退出先由核心统一确认全部页面；取消不注销，确认后由父组件撤销会话并卸载工作区。 */
 async function signOut(): Promise<void> {
   if (exiting.value) return
+  closePopovers()
   exiting.value = true
   try {
     const result = await host.operate({ type: 'closeMany', scope: 'all' })
@@ -99,26 +133,36 @@ async function signOut(): Promise<void> {
 onBeforeUnmount(() => {
   alive = false
   off()
+  workspaceRouter.dispose()
   browser.dispose()
   // 先撤销公开身份，再释放沙箱和核心；立即 dispose 阻止任何旧 SDK 发起新动作。
   host.updateSession({ authenticated: false, permissions: [] })
-  void runtime.dispose().catch(error => console.error('子应用资源释放失败', error))
+  void runtime.dispose().catch(reportError)
   host.dispose()
 })
 </script>
 
 <template>
-  <div class="shell">
-    <HostHeader :user-name="session.user.name" :pending="exiting" @logout="signOut" />
-    <aside class="sidebar" :inert="exiting || undefined"><el-menu ref="menu" :default-active="resetting ? '__reset__' : selected" :default-openeds="defaultOpeneds" @select="syncMenu">
-      <template v-for="app in host.apps" :key="app.appId">
-        <HostMenu :app-id="app.appId" :menus="app.menus ?? []" @open="open" />
+  <div class="host-shell" :class="{ 'is-collapsed': collapsed }" :aria-busy="exiting" @keydown.esc="closePopovers">
+    <!-- 只锁定宿主入口，不能锁住业务容器内的未保存确认框。 -->
+    <HostHeader ref="header" v-model:collapsed="collapsed" :apps="host.apps" :user-name="session.user.name" :active-title="active?.title ?? '工作台'" :pending="exiting" @logout="signOut" @profile="operate({ type: 'open', input: localTarget('profile') })" @open="open" @popover-opened="tabBar?.closePopovers()" />
+    <aside class="shell-sidebar" aria-label="主导航" :inert="exiting || undefined">
+      <!-- 折叠后显示应用缩写；再次点击展开，菜单状态仍由同一个 Element Plus 实例维护。 -->
+      <template v-if="collapsed">
+        <button v-for="app in host.apps.filter(item => item.menus?.length)" :key="app.appId" class="collapsed-entry" :class="{ selected: active?.appId === app.appId }" :title="app.name" :aria-label="`展开 ${app.name} 菜单`" @click="!exiting && (collapsed = false)">{{ app.name.slice(0, 1) }}</button>
       </template>
-    </el-menu></aside>
-    <main class="workspace">
-      <HostTabs :tabs="state.tabs" :active-key="active?.key" @operate="operate" />
-      <p v-if="notice" class="feedback" role="status">{{ notice }}</p>
-      <HostWorkspace :apps="host.apps" :tabs="state.tabs" :active="active" :runtime="runtime" :epochs="epochs" :pending="exiting" />
+      <!-- 侧栏用 v-show 保留菜单实例；禁用 ElMenu 折叠过渡，避免隐藏时写入窄宽度和 overflow:hidden，展开后仍裁剪菜单。 -->
+      <el-menu v-show="!collapsed" :collapse-transition="false" ref="menu" class="sidebar-menu" :default-active="resetting ? '__reset__' : selected" :default-openeds="defaultOpeneds" :router="false" @select="syncMenu">
+        <template v-for="app in host.apps" :key="app.appId">
+          <HostMenu :app-id="app.appId" :menus="app.menus ?? []" @open="open" />
+        </template>
+      </el-menu>
+      <div class="sidebar-footer"><span class="status-dot" /><span class="sidebar-label">工作空间已就绪</span></div>
+    </aside>
+    <main class="shell-main">
+      <HostTabs ref="tabBar" :tabs="state.tabs" :active-key="active?.key" :pending="exiting" @operate="operate" @error="report" @popover-opened="header?.closePopovers()" />
+      <div v-if="notice" class="shell-feedback" role="status"><span>{{ notice }}</span><button aria-label="关闭操作提示" @click="notice = ''">×</button></div>
+      <HostWorkspace :apps="host.apps" :tabs="state.tabs" :active="active" :runtime="runtime" :epochs="epochs" :pending="exiting" :session="session" @home="operate({ type: 'open', input: localTarget('home') })" @profile="operate({ type: 'open', input: localTarget('profile') })" @logout="signOut" />
     </main>
   </div>
 </template>