@axewo/fin-micro 1.0.0 → 2.0.1

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

@@ -1,14 +1,97 @@
 <script setup lang="ts">
+import { nextTick, onMounted, onBeforeUnmount, ref, watch } from 'vue'
+import { ArrowLeft, ArrowRight } from '@element-plus/icons-vue'
 import type { MicroTab, NavigationOperation } from '@axewo/fin-micro'
-defineProps<{ tabs: readonly MicroTab[]; activeKey?: string }>()
-const emit = defineEmits<{ operate: [operation: NavigationOperation] }>()
+import { isHome } from '../localPages'
+
+/** 页签仅发出真实核心命令；菜单保存原 key，防止异步操作作用于重开的新页面。 */
+const props = defineProps<{ tabs: readonly MicroTab[]; activeKey?: string; pending: boolean }>()
+const emit = defineEmits<{ operate: [operation: NavigationOperation]; 'popover-opened': []; error: [error: unknown] }>()
+const strip = ref<HTMLElement>()
+const menu = ref<{ tab: MicroTab; x?: number; y?: number } | null>(null)
+function closePopovers(): void { menu.value = null }
+function showMenu(tab: MicroTab, event?: MouseEvent): void {
+  if (props.pending) return
+  menu.value = { tab, ...(event ? { x: Math.max(8, Math.min(event.clientX, window.innerWidth - 184)), y: Math.max(8, Math.min(event.clientY, window.innerHeight - 264)) } : {}) }
+  emit('popover-opened')
+}
+function command(action: 'refresh' | 'close' | 'all' | 'others' | 'left' | 'right'): void {
+  const tab = menu.value?.tab
+  closePopovers()
+  if (!tab || props.pending || (isHome(tab) && (action === 'close' || action === 'refresh'))) return
+  const target = { tabId: tab.tabId, key: tab.key }
+  emit('operate', action === 'refresh' || action === 'close' ? { type: action, target } : { type: 'closeMany', scope: action, anchor: target })
+}
+/** 仅调整页签条的水平位置，不滚动业务容器，也不触发页签激活事务。 */
+const overflowing = ref(false)
+const canScrollLeft = ref(false)
+const canScrollRight = ref(false)
+let observer: ResizeObserver | undefined
+let disposed = false
+function measure(): void {
+  const el = strip.value
+  if (!el || disposed) return
+  // 两枚箭头各占 32px；按不含箭头时的总宽度判定，避免临界尺寸反复闪现。
+  overflowing.value = el.scrollWidth > el.clientWidth + (overflowing.value ? 64 : 0) + 1
+  canScrollLeft.value = el.scrollLeft > 1
+  canScrollRight.value = el.scrollLeft + el.clientWidth < el.scrollWidth - 1
+}
+function revealActive(): void {
+  const el = strip.value
+  const tab = el?.querySelector<HTMLElement>('[aria-selected="true"]')?.parentElement
+  if (!el || !tab || disposed) return
+  const viewport = el.getBoundingClientRect()
+  const bounds = tab.getBoundingClientRect()
+  if (bounds.left < viewport.left) el.scrollLeft += bounds.left - viewport.left
+  else if (bounds.right > viewport.right) el.scrollLeft += Math.min(bounds.right - viewport.right, bounds.left - viewport.left)
+  measure()
+}
+/** 箭头每次移动约一屏，保留部分重叠便于定位；边界由滚动事件重新测量。 */
+function scrollTabs(direction: -1 | 1): void {
+  if (props.pending) return
+  strip.value?.scrollBy({ left: direction * Math.max(80, strip.value.clientWidth * 0.8), behavior: 'smooth' })
+}
+function updateViewport(): void {
+  void nextTick().then(() => {
+    if (disposed) return
+    measure()
+    // 箭头出现或消失后，可视宽度会再次变化，等布局提交后再定位活动项。
+    return nextTick().then(revealActive)
+  }).catch(error => emit('error', error))
+}
+onMounted(() => {
+  if (typeof ResizeObserver !== 'undefined') {
+    observer = new ResizeObserver(updateViewport)
+    if (strip.value) observer.observe(strip.value)
+  }
+  if (typeof window !== 'undefined') window.addEventListener('resize', updateViewport)
+  updateViewport()
+})
+onBeforeUnmount(() => {
+  disposed = true
+  observer?.disconnect()
+  if (typeof window !== 'undefined') window.removeEventListener('resize', updateViewport)
+})
+watch(() => [props.activeKey, ...props.tabs.map(tab => `${tab.key}:${tab.title}`)], updateViewport)
+watch(() => props.pending, pending => { if (pending) closePopovers() })
+defineExpose({ closePopovers })
 </script>
 <template>
-  <nav class="tabbar" aria-label="已打开页面">
-    <div v-for="tab in tabs" :key="tab.key" class="tab">
-      <el-button :type="tab.key === activeKey ? 'primary' : 'default'" @click="emit('operate', { type: 'activate', target: { tabId: tab.tabId, key: tab.key } })">{{ tab.title }}</el-button>
-      <el-button aria-label="刷新页面" @click="emit('operate', { type: 'refresh', target: { tabId: tab.tabId, key: tab.key } })">刷新</el-button>
-      <el-button aria-label="关闭页面" @click="emit('operate', { type: 'close', target: { tabId: tab.tabId, key: tab.key } })">×</el-button>
+  <div class="shell-tabbar" :inert="pending || undefined" @keydown.esc="closePopovers">
+    <button v-if="menu" class="popover-backdrop" aria-label="关闭页签菜单" tabindex="-1" @click="closePopovers" />
+    <button v-if="overflowing" class="tab-scroll" aria-label="向左查看页签" title="向左查看页签" :disabled="pending || !canScrollLeft" @click="scrollTabs(-1)"><ArrowLeft aria-hidden="true" /></button>
+    <div ref="strip" class="tab-strip" role="tablist" aria-label="已打开页面" @scroll="measure">
+      <div v-for="tab in tabs" :key="tab.key" class="shell-tab" :class="{ active: tab.key === activeKey }" @contextmenu.prevent="showMenu(tab, $event)">
+        <button role="tab" :aria-selected="tab.key === activeKey" :title="tab.title" @click="!pending && emit('operate', { type: 'activate', target: { tabId: tab.tabId, key: tab.key } })">{{ tab.title }}</button>
+        <button v-if="!isHome(tab)" class="tab-close" :aria-label="`关闭 ${tab.title}`" @click="!pending && emit('operate', { type: 'close', target: { tabId: tab.tabId, key: tab.key } })">×</button>
+      </div>
     </div>
-  </nav>
+    <button v-if="overflowing" class="tab-scroll" aria-label="向右查看页签" title="向右查看页签" :disabled="pending || !canScrollRight" @click="scrollTabs(1)"><ArrowRight aria-hidden="true" /></button>
+    <button class="tab-more" aria-label="更多页签操作" :aria-expanded="!!menu" :disabled="!tabs.length || pending" @click="tabs.find(tab => tab.key === activeKey) && showMenu(tabs.find(tab => tab.key === activeKey)!)">···</button>
+    <div v-if="menu" class="shell-popover tab-actions" :class="{ 'context-actions': menu.x !== undefined }" :style="menu.x !== undefined ? { left: `${menu.x}px`, top: `${menu.y}px` } : undefined" role="menu" aria-label="页签操作菜单">
+      <p class="popover-label">{{ menu.tab.title }}</p>
+      <button role="menuitem" :disabled="isHome(menu.tab)" @click="command('refresh')">刷新页面</button><button role="menuitem" :disabled="isHome(menu.tab)" @click="command('close')">关闭当前</button><hr />
+      <button role="menuitem" @click="command('others')">关闭其他</button><button role="menuitem" @click="command('left')">关闭左侧</button><button role="menuitem" @click="command('right')">关闭右侧</button><button role="menuitem" @click="command('all')">关闭全部业务页</button>
+    </div>
+  </div>
 </template>

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

@@ -1,14 +1,36 @@
 <script setup lang="ts">
 import { computed } from 'vue'
+import { FinWatermark } from '@axewo/fin-micro/watermark'
+import { watermarkConfig } from '../utils/watermarkConfig'
 import { MicroAppContainer, type MicroApp, type MicroTab, type MicroRuntime } from '@axewo/fin-micro'
-const props = defineProps<{ apps: readonly MicroApp[]; tabs: readonly MicroTab[]; active?: MicroTab; runtime: MicroRuntime; epochs: Record<string, number>; pending: boolean }>()
-// 应用按 appId 唯一挂载而非按 tabId 创建沙箱；同应用的页面缓存交给子应用 SDK。
-const mounted = computed(() => props.apps.filter(app => props.tabs.some(tab => tab.appId === app.appId)))
+import { demoMode } from '../platform'
+import { LOCAL_APP_ID } from '../localPages'
+import type { PlatformSession } from '../types/platform'
+import HomeView from '../views/home/index.vue'
+import ProfileView from '../views/profile/index.vue'
+const props = defineProps<{ apps: readonly MicroApp[]; tabs: readonly MicroTab[]; active?: MicroTab; runtime: MicroRuntime; epochs: Record<string, number>; pending: boolean; session: PlatformSession }>()
+const emit = defineEmits<{ home: []; profile: []; logout: [] }>()
+// 远端按 appId 唯一挂载；本地页面使用相同 core 页签及 key，但不创建沙箱或第二套页签状态。
+const mounted = computed(() => props.apps.filter(app => app.kind !== 'local' && props.tabs.some(tab => tab.appId === app.appId)))
+const local = computed(() => props.active?.appId === LOCAL_APP_ID ? props.active : undefined)
 </script>
 <template>
-  <section class="micro-workspace">
-    <div v-if="!active" class="panel"><h2>工作台</h2><p>从左侧多级菜单打开业务页面；平台只负责会话、菜单与页签编排。</p></div>
-    <!-- 容器内置加载、失败和重试状态；切换仅隐藏，最后一个页签关闭才卸载。 -->
-    <MicroAppContainer v-for="app in mounted" v-show="active?.appId === app.appId" :key="`${app.appId}:${epochs[app.appId] ?? 0}`" :app-id="app.appId" :runtime="runtime" :retry-disabled="pending" />
+  <!-- 稳定视口与原滚动区分离；不改变 appId/key 或子应用缓存身份。 -->
+  <div class="workspace-viewport">
+  <section class="shell-content">
+    <!-- 仅清理或异常空快照时兜底；正常交互始终保留核心主页，不用此入口模拟固定页签。 -->
+    <div v-if="!active && !pending" class="home-view"><section class="home-panel"><h1>工作区暂不可用</h1><p>可返回本地主页重新开始。</p><el-button type="primary" @click="emit('home')">打开主页</el-button></section></div>
+    <!-- key 直接使用 core 生命周期身份，页签刷新会重建本地 SFC；不使用 h 拼装业务页面。 -->
+    <HomeView v-if="local?.route === '/home'" :key="local.key" :user-name="session.user.name" :demo="demoMode" :pending="pending" @profile="emit('profile')" />
+    <ProfileView v-else-if="local?.route === '/profile'" :key="local.key" :session="session" :demo="demoMode" :pending="pending" @home="emit('home')" @logout="emit('logout')" />
+    <!-- 容器内置加载、失败和重试状态；切换仅隐藏，最后一个远端页签关闭才卸载。 -->
+    <!-- 仅局部覆盖通用容器的最小高度；挂载身份与保活策略不变，低视口不会撑开整个基座。 -->
+    <MicroAppContainer class="shell-app-container" v-for="app in mounted" v-show="active?.appId === app.appId" :key="`${app.appId}:${epochs[app.appId] ?? 0}`" :app-id="app.appId" :runtime="runtime" :retry-disabled="pending" />
   </section>
+  <FinWatermark :config="watermarkConfig" />
+  </div>
 </template>
+<style scoped>
+.workspace-viewport { position: relative; isolation: isolate; display: flex; flex: 1 1 auto; min-width: 0; min-height: 0; overflow: hidden; }
+.workspace-viewport > .shell-content { min-width: 0; }
+</style>

package/scaffold/host/src/localPages.ts

@@ -0,0 +1,45 @@
+import type { MicroApp, MicroMenu, MicroTab, NavigationOperation, OpenTab } from '@axewo/fin-micro'
+
+/** 宿主保留身份，不接受后台同名应用或组件路径；与远端共用 core 的页签标识及生命周期。 */
+export const LOCAL_APP_ID = 'host-local'
+export const localApp: MicroApp = {
+  kind: 'local', appId: LOCAL_APP_ID, name: '工作台',
+  menus: [
+    { menuId: 'home', name: '主页', icon: 'HomeFilled', target: { tabId: 'host-local:home', route: '/home' } },
+    { menuId: 'profile', name: '个人中心', icon: 'User', target: { tabId: 'host-local:profile', route: '/profile' } },
+  ],
+}
+
+/** 固定本地白名单；仅接受精确的 appId/tabId/route 组合，绝不动态导入接口指定的页面。 */
+export function canOpenLocal(input: OpenTab): boolean {
+  return input.appId === LOCAL_APP_ID && Boolean(localApp.menus?.some(menu =>
+    menu.target?.tabId === input.tabId && menu.target.route === input.route))
+}
+
+/** 顶栏、主页快捷入口和首次登录共用菜单元信息，不创建第二套本地导航状态。 */
+export function localMenu(id: 'home' | 'profile'): MicroMenu {
+  return localApp.menus!.find(menu => menu.menuId === id)!
+}
+/** 只按保留身份识别主页，不依赖标题、索引或活动状态。 */
+export function isHome(tab: Pick<MicroTab, 'appId' | 'tabId'>): boolean {
+  return tab.appId === LOCAL_APP_ID && tab.tabId === localMenu('home').target!.tabId
+}
+
+/** 交互关闭沿用源示例的排除协议；注销不调用此适配，仍确认并关闭完整快照。 */
+export function workspaceOperation(operation: NavigationOperation, tabs: readonly MicroTab[]): NavigationOperation {
+  const home = tabs.find(isHome)
+  if (!home) return operation
+  const ref = { tabId: home.tabId, key: home.key }
+  if ((operation.type === 'close' || operation.type === 'refresh') && operation.target.tabId === home.tabId) {
+    // 转为空关闭集合，保留核心的取消和销毁检查，也不切换当前业务页。
+    return { type: 'closeMany', scope: 'all', exclude: tabs.map(tab => ({ tabId: tab.tabId, key: tab.key })), signal: operation.signal }
+  }
+  if (operation.type === 'close') return { ...operation, closeFallback: ref }
+  if (operation.type === 'closeMany') return { ...operation, exclude: [...operation.exclude ?? [], ref], closeFallback: ref }
+  return operation
+}
+
+export function localTarget(id: 'home' | 'profile'): OpenTab {
+  const menu = localMenu(id)
+  return { appId: LOCAL_APP_ID, ...menu.target!, title: menu.name, activeMenuId: menu.menuId }
+}

package/scaffold/host/src/platform.ts

@@ -1,7 +1,9 @@
 import type { MicroApp, MicroMenu, OpenTab, SessionInput } from '@axewo/fin-micro'
 import { http } from './utils/request'
+import { resolveTrustedApp } from './utils/appConfig'
 
 import type { PlatformSession } from './types/platform'
+import { canOpenLocal, localApp, LOCAL_APP_ID } from './localPages'
 
 // 仅驻留基座私有模块内存；不写 localStorage、会话快照、URL 或事件总线。
 let accessToken: string | null = null
@@ -27,19 +29,39 @@ export function clearAccessToken(): void { setAccessToken(null) }
 export function activateSessionToken(session: PlatformSession | null): void {
   setAccessToken(session ? pendingTokens.get(session) ?? null : null)
   if (session) pendingTokens.delete(session)
+  // 仅提交成功且仍属当前代次的演示身份；标记不是 Token，不可用于真实平台接口认证。
+  if (demoMode && session) writeDemoSession(true)
 }
 
 // 可配置部署注册表，不依赖项目生成顺序；实际子应用 appId 必须与此配置一致。
-const appId = import.meta.env.VITE_MICRO_APP_ID || 'business'
+const { appId, entry } = resolveTrustedApp(import.meta.env)
+if (appId === LOCAL_APP_ID) throw new Error('业务 appId 不能占用宿主保留身份 host-local')
 const registry: MicroApp[] = [{
-  appId, name: '业务应用', entry: import.meta.env.VITE_MICRO_APP_ENTRY || 'http://localhost:7101',
+  appId, name: '业务应用', entry,
 }]
-const demoMenus: MicroMenu[] = [{ menuId: 'business', name: '业务工作区', children: [
-  { menuId: 'records', name: '示例记录', target: { tabId: `${appId}:list`, route: '/list' } },
+const demoMenus: MicroMenu[] = [{ menuId: 'business', name: '业务工作区', icon: 'Folder', children: [
+  { menuId: 'records', name: '示例记录', icon: 'List', target: { tabId: `${appId}:list`, route: '/list' } },
 ] }]
 
-/** 仅在开发且显式启用时允许内存演示登录；任何真实接口失败均不会回退此身份。 */
-export const demoMode = import.meta.env.DEV && import.meta.env.VITE_AUTH_DEMO === 'true'
+/** 开发默认可体验；显式 false 可联调真实认证。生产即使配置 true 也绝不启用或失败降级。 */
+export const demoMode = import.meta.env.DEV && import.meta.env.VITE_AUTH_DEMO !== 'false'
+const DEMO_SESSION_KEY = 'fin-micro:demo-session:v1'
+/** 当前浏览器标签页只保存版本标记，不保存用户名、密码、Token 或服务端身份。存储禁用仍可内存体验。 */
+function writeDemoSession(enabled: boolean): void {
+  if (!demoMode) return
+  try {
+    if (enabled) window.sessionStorage.setItem(DEMO_SESSION_KEY, '1')
+    else window.sessionStorage.removeItem(DEMO_SESSION_KEY)
+  } catch { /* 浏览器禁止存储时，仅放弃刷新恢复，不阻断登录或退出。 */ }
+}
+/** 正常退出或认证失效撤销演示恢复标记；组件卸载不清除此标记，允许整页刷新恢复。 */
+export function clearDemoSession(): void { writeDemoSession(false) }
+function demoSession(): PlatformSession {
+  return {
+    user: { id: 'demo', name: '演示用户' }, permissions: ['demo:read'],
+    apps: registry.map(app => ({ ...app, menus: demoMenus, menuRoutes: [{ pathPrefix: '/detail', menuId: 'records' }] })),
+  }
+}
 
 /**
  * 同源平台接口边界，signal 必须沿用当前认证操作的取消信号，body 存在时发送 POST。
@@ -106,15 +128,18 @@ function decodeMenus(value: unknown, tabIds: Set<string>): MicroMenu[] {
         throw new Error('菜单超出数量限制或 menuId/name 无效、重复')
       }
       menuIds.add(item.menuId)
+      // 后台只传图标标识；不接收 SVG、组件代码、HTML 或外部 URL，未知名称由展示层回退。
+      if (item.icon != null && (typeof item.icon !== 'string' || !/^[A-Za-z][A-Za-z0-9-]{0,63}$/.test(item.icon))) throw new Error('菜单图标标识无效')
+      const icon = typeof item.icon === 'string' && item.icon ? { icon: item.icon } : {}
       if (item.children !== undefined) {
         if (item.target !== undefined || !Array.isArray(item.children) || item.children.length === 0) throw new Error('菜单分组需要非空 children 且不能同时具有 target')
-        return { menuId: item.menuId, name: item.name, children: walk(item.children, depth + 1) }
+        return { menuId: item.menuId, name: item.name, ...icon, children: walk(item.children, depth + 1) }
       }
       if (!isObject(item.target) || !identifier(item.target.tabId) || !localRoute(item.target.route) || tabIds.has(item.target.tabId)) {
         throw new Error('菜单入口 target 无效或 tabId 在宿主内重复')
       }
       tabIds.add(item.target.tabId)
-      return { menuId: item.menuId, name: item.name, target: { tabId: item.target.tabId, route: item.target.route } }
+      return { menuId: item.menuId, name: item.name, ...icon, target: { tabId: item.target.tabId, route: item.target.route } }
     })
   }
   return walk(value, 1)
@@ -133,7 +158,8 @@ async function loadSession(value: unknown, signal: AbortSignal): Promise<Platfor
   const payload = await request('menus', signal, undefined, token)
   if (!isObject(payload) || !Array.isArray(payload.apps)) throw new Error('平台菜单加载失败，预期 /api/menus 返回 {apps:[{appId,menus}]}')
   const seen = new Set<string>()
-  const tabIds = new Set<string>()
+  // 本地页与远端共享宿主 tabId 命名空间，后台不能占用保留页签导致本地主页无法打开。
+  const tabIds = new Set(localApp.menus!.map(menu => menu.target!.tabId))
   const apps: MicroApp[] = payload.apps.map(item => {
     if (!isObject(item) || !identifier(item.appId) || !identity.appIds.includes(item.appId) || seen.has(item.appId)) {
       throw new Error('菜单接口包含未授权或重复 appId')
@@ -164,6 +190,8 @@ function leaves(menus: readonly MicroMenu[]): MicroMenu[] {
  * 新业务详情应替换本规则并在后台验证真实权限，不得笼统放行任意 /detail。
  */
 export function canOpenRoute(session: PlatformSession, input: OpenTab): boolean {
+  // 本地页面仅在已创建的认证工作区使用，不依赖后台 appIds，也不扩大远端应用权限。
+  if (input.appId === LOCAL_APP_ID) return canOpenLocal(input)
   const app = session.apps.find(item => item.appId === input.appId)
   if (!app || !localRoute(input.route)) return false
   const menus = leaves(app.menus ?? [])
@@ -176,10 +204,14 @@ export function canOpenRoute(session: PlatformSession, input: OpenTab): boolean
 
 /**
  * 恢复会话并加载授权菜单。signal 为本次操作取消信号，未登录返回 null，接口/解码错误拒绝 Promise。
- * 演示模式不自动恢复身份；真实模式必须等待两个接口均完成后才能创建宿主。
+ * 演示模式仅按当前标签页的版本标记恢复固定体验身份；真实模式必须等待两个接口均完成。
  */
 export async function restoreSession(signal: AbortSignal): Promise<PlatformSession | null> {
-  if (demoMode) return null
+  if (demoMode) {
+    if (signal.aborted) throw new DOMException('会话恢复已取消', 'AbortError')
+    try { return window.sessionStorage.getItem(DEMO_SESSION_KEY) === '1' ? demoSession() : null }
+    catch { return null }
+  }
   const value = await request('session', signal)
   return value === null ? null : loadSession(value, signal)
 }
@@ -187,10 +219,14 @@ export async function restoreSession(signal: AbortSignal): Promise<PlatformSessi
 /**
  * username/password 为登录表单输入，signal 同时覆盖登录和后续菜单请求。
  * 返回完整平台会话；登录拒绝、菜单失败或取消均拒绝 Promise，不能显示半就绪工作区。
- * 演示仅在显式开发开关下提供内存身份，绝非生产认证，不持久化密码或凭据。
+ * 演示仅在开发模式校验 demo/123456 后提供固定身份；绝非生产认证，不持久化凭据。
  */
 export async function login(username: string, password: string, signal: AbortSignal): Promise<PlatformSession> {
-  if (demoMode) return { user: { id: 'demo', name: username }, permissions: ['demo:read'], apps: registry.map(app => ({ ...app, menus: demoMenus, menuRoutes: [{ pathPrefix: '/detail', menuId: 'records' }] })) }
+  if (signal.aborted) throw new DOMException('登录已取消', 'AbortError')
+  if (demoMode) {
+    if (username !== 'demo' || password !== '123456') throw new Error('用户名或密码错误')
+    return demoSession()
+  }
   const value = await request('login', signal, { username, password })
   if (value === null) throw new Error('用户名或密码错误')
   return loadSession(value, signal)
@@ -199,7 +235,8 @@ export async function login(username: string, password: string, signal: AbortSig
 /** signal 为注销取消信号，成功返回 void；远程失败拒绝 Promise，但调用方不得恢复旧本地身份。 */
 export async function logout(signal: AbortSignal, previousToken: string | null = null): Promise<void> {
   // 本地凭据已清除；局部旧值仅用于可信注销接口，不重新写回私有存储。
-  if (!demoMode) await request('logout', signal, {}, previousToken)
+  if (demoMode) clearDemoSession()
+  else await request('logout', signal, {}, previousToken)
 }
 
 /** 输入当前平台会话，返回 SDK 白名单公开字段；不包含 Token，不暴露后台响应的其他属性。 */

package/scaffold/host/src/router/guards.ts

@@ -0,0 +1,128 @@
+import { watch } from 'vue'
+import type { NavigationGuardReturn, RouteLocationNormalized, Router } from 'vue-router'
+import type { PlatformSessionController } from '../hooks/usePlatformSession'
+import type { PlatformSession } from '../types/platform'
+import { canOpenRoute } from '../platform'
+import { authorizedRedirect, routeTarget } from './targets'
+
+/** 扩展只接收本次公开身份及导航快照；signal 在新导航、注销或守卫移除时协作取消。 */
+export interface HostGuardContext {
+  to: RouteLocationNormalized
+  from: RouteLocationNormalized
+  session: PlatformSession
+  signal: AbortSignal
+}
+export interface HostGuardOptions {
+  /** 已通过内置认证及路由白名单后执行；false 取消，void/true 继续，不得替代服务端鉴权。 */
+  beforeEnter?: (context: HostGuardContext) => boolean | void | Promise<boolean | void>
+  /** 接收恢复、扩展或离页异常；调用方必须脱敏展示，回调自身异常不会放行导航。 */
+  onError?: (error: unknown) => void
+}
+/** 工作区只返回核心事务对应的放行/取消结果，不重复实现认证或重定向策略。 */
+export type WorkspaceGuard = (context: HostGuardContext) => NavigationGuardReturn | Promise<NavigationGuardReturn>
+const installations = new WeakMap<Router, {
+  workspace?: WorkspaceGuard
+  invalidate: () => void
+  dispose: () => void
+}>()
+
+/**
+ * 每个 router 只安装一次统一前置守卫：等待恢复、认证、授权、业务扩展，最后委托核心离页事务。
+ * @param router 当前 App 独享的 Vue Router。
+ * @param controller 当前 App 的认证控制器；ready 只等待首次恢复，之后每次读取最新 session。
+ * @param options 可选前置扩展与脱敏错误接收器；不额外注册 beforeEach。
+ * @returns 幂等撤销函数；重挂载及启动失败必须调用，取消所有待决导航并移除工作区委托。
+ * @throws 重复安装时抛错；异步恢复、扩展或委托异常会报告并取消导航，不形成重定向循环。
+ */
+export function installHostGuards(router: Router, controller: PlatformSessionController, options: HostGuardOptions = {}): () => void {
+  if (installations.has(router)) throw new Error('当前路由器已安装宿主守卫')
+  let disposed = false
+  let generation = 0
+  let restored = false
+  let pending: AbortController | undefined
+  const invalidate = () => { generation++; pending?.abort() }
+  // 首次恢复提交身份是 ready 的一部分，不取消首次导航；之后的身份替换立即撤销旧事务。
+  const offSession = watch(controller.session, () => { if (restored) invalidate() }, { flush: 'sync' })
+  const installation = { invalidate, dispose: () => {}, workspace: undefined as WorkspaceGuard | undefined }
+  const off = router.beforeEach(async (to, from) => {
+    invalidate()
+    const current = generation
+    const navigation = new AbortController()
+    pending = navigation
+    const valid = () => !disposed && current === generation && !navigation.signal.aborted
+    // 取消只终止导航等待，不假定能终止后台副作用；迟到成功和异常均由 race 消费。
+    const wait = async <T>(value: T | Promise<T>): Promise<T | undefined> => {
+      let cancel = () => {}
+      try {
+        return await Promise.race([value, new Promise<undefined>(resolve => {
+          cancel = () => resolve(undefined)
+          navigation.signal.addEventListener('abort', cancel, { once: true })
+          if (navigation.signal.aborted) cancel()
+        })])
+      } finally { navigation.signal.removeEventListener('abort', cancel) }
+    }
+    try {
+      await wait(controller.ready)
+      if (!valid()) return false
+      restored = true
+      // 恢复在控制器内有代次保护；这里绝不缓存 await 之前的身份，避免旧恢复放行。
+      const session = controller.session.value
+      if (to.meta.authenticated && !session) return { path: '/login', query: { redirect: to.fullPath }, replace: true }
+      if (to.path === '/login' && session) {
+        const target = router.resolve(authorizedRedirect(router, session, to.query.redirect))
+        return { path: target.path, query: target.query, replace: true }
+      }
+      // 注销和真实失效优先移除身份；此时不能再调用旧工作区的未保存守卫。
+      if (!session) return
+      const context = { to, from, session, signal: navigation.signal }
+      if (to.meta.authenticated) {
+        const target = routeTarget(to)
+        const permissions = to.meta.permissions
+        const forbidden = (to.path !== '/workspace' || to.query.tab !== undefined) && (!target || !canOpenRoute(session, target))
+        const denied = permissions !== undefined && (!Array.isArray(permissions) || !permissions.every(value => typeof value === 'string' && session.permissions.includes(value)))
+        if (forbidden || denied) return to.path === '/home' ? false : { path: '/home', replace: true }
+        const accepted = await wait(options.beforeEnter?.(context))
+        if (!valid() || controller.session.value !== session) return false
+        if (accepted === false) return false
+      }
+      const result = await wait(installation.workspace?.(context))
+      if (!valid() || controller.session.value !== session) return false
+      return result
+    } catch (error) {
+      if (valid()) {
+        try { options.onError?.(error) } catch { /* 展示异常不能成为放行依据。 */ }
+      }
+      return false
+    }
+  })
+  installation.dispose = () => {
+    if (disposed) return
+    disposed = true
+    invalidate()
+    off()
+    offSession()
+    installation.workspace = undefined
+    installations.delete(router)
+  }
+  installations.set(router, installation)
+  return installation.dispose
+}
+
+/**
+ * 将当前工作区的核心离页事务挂到统一守卫，不注册第二个 beforeEach。
+ * @param router 已调用 installHostGuards 的路由器。
+ * @param guard 工作区事务委托；正常离页必须等待其结果，认证失效时不调用。
+ * @returns 幂等撤销函数；工作区卸载时调用，旧撤销函数不会删除新工作区的委托。
+ * @throws 未安装统一守卫或已有存活工作区时抛错，防止悄悄生成重复导航状态。
+ */
+export function attachWorkspaceGuard(router: Router, guard: WorkspaceGuard): () => void {
+  const installation = installations.get(router)
+  if (!installation) throw new Error('请先安装宿主路由守卫')
+  if (installation.workspace) throw new Error('当前路由器已连接工作区')
+  installation.workspace = guard
+  return () => {
+    if (installation.workspace !== guard) return
+    installation.invalidate()
+    installation.workspace = undefined
+  }
+}

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

@@ -0,0 +1,25 @@
+import { createRouter, createWebHistory, type RouterHistory } from 'vue-router'
+import LoginRoute from '../views/login/index.vue'
+import WorkspaceRoute from '../views/workspace/index.vue'
+import NotFoundView from '../views/not-found/index.vue'
+import type { PlatformSessionController } from '../hooks/usePlatformSession'
+import { installHostGuards, type HostGuardOptions } from './guards'
+
+/**
+ * 创建独占顶级 URL 的宿主路由器，生产服务器需配置 SPA 回退。
+ * @param controller 本轮 App 的认证控制器；统一守卫等待其首次恢复。
+ * @param history 本轮 history，可在测试中传入 memory history。
+ * @param guards 可选业务准入扩展，例如按 to.meta.permissions 声明权限，或通过 beforeEnter 校验业务条件。
+ * @returns 带 disposeGuards 的 router；卸载须先撤销守卫，再销毁 history。
+ * @throws 路由构造或守卫安装失败时抛错，由 bootstrap 失败清理处理。
+ */
+export function createAppRouter(controller: PlatformSessionController, history: RouterHistory = createWebHistory(import.meta.env.BASE_URL), guards: HostGuardOptions = {}) {
+  const router = createRouter({ history, routes: [
+    { path: '/', redirect: '/home' },
+    { path: '/login', component: LoginRoute },
+    { path: '/:page(home|profile|workspace)', component: WorkspaceRoute, meta: { authenticated: true } },
+    { path: '/:pathMatch(.*)*', component: NotFoundView },
+  ] })
+  const disposeGuards = installHostGuards(router, controller, guards)
+  return Object.assign(router, { disposeGuards })
+}

package/scaffold/host/src/router/targets.ts

@@ -0,0 +1,30 @@
+import type { RouteLocationNormalized, Router } from 'vue-router'
+import { decodeMicroLocation, encodeMicroLocation, type OpenTab } from '@axewo/fin-micro'
+import { localTarget, LOCAL_APP_ID } from '../localPages'
+import { canOpenRoute } from '../platform'
+import type { PlatformSession } from '../types/platform'
+
+/** URL 只携带公开导航元信息；授权仍由会话及 core 双重检查。 */
+export function routeTarget(route: Pick<RouteLocationNormalized, 'path' | 'query'>): OpenTab | null {
+  if (route.path === '/home') return localTarget('home')
+  if (route.path === '/profile') return localTarget('profile')
+  if (route.path !== '/workspace' || typeof route.query.tab !== 'string') return null
+  try {
+    const target = decodeMicroLocation(route.query.tab)
+    return target && target.appId !== LOCAL_APP_ID ? { ...target, title: '业务页面' } : null
+  } catch { return null }
+}
+export function tabLocation(tab?: OpenTab) {
+  if (!tab) return { path: '/workspace', query: {} }
+  if (tab.appId === LOCAL_APP_ID) return { path: tab.route, query: {} }
+  return { path: '/workspace', query: { tab: encodeMicroLocation(tab) } }
+}
+/** 只接受可解析、同站且当前会话已授权的固定宿主路由，不回显任意输入。 */
+export function authorizedRedirect(router: Router, session: PlatformSession, value: unknown): string {
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || /[\\\u0000-\u0020\u007f]/.test(value)) return '/home'
+  try {
+    const resolved = router.resolve(value)
+    const target = routeTarget(resolved)
+    return target && !resolved.hash && canOpenRoute(session, target) ? router.resolve(tabLocation(target)).fullPath : '/home'
+  } catch { return '/home' }
+}

package/scaffold/host/src/router/workspace.ts

@@ -0,0 +1,63 @@
+import { connectMicroBrowser, type MicroHost, type MicroBrowserOptions } from '@axewo/fin-micro'
+import type { Router } from 'vue-router'
+import { routeTarget, tabLocation } from './targets'
+import { localTarget, workspaceOperation } from '../localPages'
+import { attachWorkspaceGuard } from './guards'
+
+/**
+ * 渲染前先登记主页，旧存储与深链恢复复用同一核心状态，主页始终首位且不重复。
+ * @param host 已认证且尚未挂载业务组件的宿主。
+ * @param router 已完成首次导航的路由器，提供授权后的初始深链。
+ * @param options 用户隔离存储及错误回调；URL 始终交给 Vue Router。
+ * @returns 浏览器存储连接器，卸载时须调用 dispose。
+ * @throws 主页准入失败时抛错；存储或恢复错误由 options.onError 接收。
+ */
+export function connectWorkspaceBrowser(host: MicroHost, router: Router, options: MicroBrowserOptions) {
+  host.openTab(localTarget('home'))
+  return connectMicroBrowser(host, { ...options, url: false, initialLocation: routeTarget(router.currentRoute.value) })
+}
+
+/**
+ * 统一 URL 与核心状态；工作区只挂接离页事务，不另建 beforeEach。
+ * @param host 当前工作区唯一宿主，所有离页仍委托核心 beforeLeave。
+ * @param router 已安装 installHostGuards 的路由器。
+ * @param authenticated 当前身份仍有效且未进入退出确认时返回 true。
+ * @param onError 脱敏错误接收器；事务异常会取消导航，不修改固定主页策略。
+ * @returns 带 dispose 的连接，卸载时撤销委托、取消待决事务并释放状态订阅。
+ * @throws 统一守卫未安装或工作区重复连接时抛错。
+ */
+export function connectWorkspaceRouter(host: MicroHost, router: Router, authenticated: () => boolean, onError: (error: unknown) => void = () => {}) {
+  let navigating = false
+  let disposed = false
+  let generation = 0
+  const currentLocation = () => tabLocation(host.getState().tabs.find(tab => tab.tabId === host.getState().activeTabId))
+  function sync(replace = false): void {
+    if (disposed || navigating || !authenticated()) return
+    const target = currentLocation()
+    if (router.resolve(target).fullPath === router.currentRoute.value.fullPath) return
+    void (replace ? router.replace(target) : router.push(target)).catch(onError)
+  }
+  const offGuard = attachWorkspaceGuard(router, async ({ to, signal }) => {
+    const current = ++generation
+    navigating = false
+    // 认证失效由统一守卫优先放行清理；仍有身份但正在退出确认时，拒绝新的工作区导航。
+    if (!authenticated()) return false
+    const target = routeTarget(to)
+    const active = host.getState().tabs.find(tab => tab.tabId === host.getState().activeTabId)
+    if (target && active?.appId === target.appId && active.tabId === target.tabId && active.route === target.route) return
+    // 空工作区路径保留当前页签；外部页面或登录页离开前统一确认全部页签。
+    if (to.path === '/workspace' && !target) return
+    navigating = true
+    try {
+      const result = await host.operate(workspaceOperation(target ? { type: 'open', input: target, signal } : { type: 'closeMany', scope: 'all', signal }, host.getState().tabs))
+      if (disposed || current !== generation) return false
+      return result.status === 'committed' || result.status === 'noop'
+    } catch (error) {
+      if (!disposed && current === generation) onError(error)
+      return false
+    } finally { if (current === generation) navigating = false }
+  })
+  const off = host.subscribe(() => sync())
+  sync(true)
+  return { dispose() { disposed = true; generation++; off(); offGuard() } }
+}