@axewo/fin-micro 2.0.0 → 2.0.1

package/scaffold/host/src/localPages.ts

@@ -5,8 +5,8 @@ export const LOCAL_APP_ID = 'host-local'
 export const localApp: MicroApp = {
   kind: 'local', appId: LOCAL_APP_ID, name: '工作台',
   menus: [
-    { menuId: 'home', name: '主页', target: { tabId: 'host-local:home', route: '/home' } },
-    { menuId: 'profile', name: '个人中心', target: { tabId: 'host-local:profile', route: '/profile' } },
+    { menuId: 'home', name: '主页', icon: 'HomeFilled', target: { tabId: 'host-local:home', route: '/home' } },
+    { menuId: 'profile', name: '个人中心', icon: 'User', target: { tabId: 'host-local:profile', route: '/profile' } },
   ],
 }
 

package/scaffold/host/src/platform.ts

@@ -39,8 +39,8 @@ if (appId === LOCAL_APP_ID) throw new Error('业务 appId 不能占用宿主保
 const registry: MicroApp[] = [{
   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' } },
 ] }]
 
 /** 开发默认可体验；显式 false 可联调真实认证。生产即使配置 true 也绝不启用或失败降级。 */
@@ -128,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)
@@ -216,11 +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 (signal.aborted) throw new DOMException('登录已取消', 'AbortError')
-  if (demoMode) return demoSession()
+  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)

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

@@ -1,7 +1,7 @@
 import { createRouter, createWebHistory, type RouterHistory } from 'vue-router'
-import LoginRoute from '../views/LoginRoute.vue'
-import WorkspaceRoute from '../views/WorkspaceRoute.vue'
-import NotFoundView from '../views/NotFoundView.vue'
+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'
 

package/scaffold/host/src/styles/shell.css

@@ -313,7 +313,8 @@
 .host-shell .tab-strip {
   display: flex;
   overflow-x: auto;
-  scrollbar-width: thin;
+  overflow-y: hidden;
+  scrollbar-width: none;
   flex: 1;
   min-width: 0;
   gap: 4px;
@@ -358,6 +359,20 @@
 .host-shell .shell-tab .tab-close:hover {
   color: #cf4b4b;
 }
+.host-shell .tab-strip::-webkit-scrollbar { display: none; }
+.host-shell .tab-scroll {
+  flex: 0 0 32px;
+  width: 32px;
+  padding: 0;
+  border: 0;
+  border-right: 1px solid var(--shell-border);
+  background: white;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.host-shell .tab-scroll svg { width: 14px; height: 14px; }
+.host-shell .tab-scroll:not(:disabled):hover { background: #f0f5ff; color: #3267e3; }
 .host-shell .tab-more {
   border: 0;
   border-left: 1px solid var(--shell-border);

package/scaffold/host/src/views/{LoginView.vue → login/components/LoginForm.vue}

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import { demoMode } from '../platform'
+import { demoMode } from '../../../platform'
 
 // 表单只保留本地输入；会话恢复、取消与错误状态统一由上层会话组合函数管理。
 const props = defineProps<{
@@ -9,15 +9,10 @@ const props = defineProps<{
   signIn: (username: string, password: string) => Promise<void>
 }>()
 const emit = defineEmits<{ restore: [] }>()
-const username = ref('')
-const password = ref('')
+const username = ref(demoMode ? 'demo' : '')
+const password = ref(demoMode ? '123456' : '')
 async function submit(): Promise<void> {
   if (props.loading) return
-  if (demoMode) {
-    // 演示不展示或采集账号密码；固定身份只用于本地工作台体验。
-    await props.signIn('', '')
-    return
-  }
   if (!username.value.trim() || !password.value) return
   const credential = password.value
   // 提交即清空密码输入，不在会话或全局状态中保存凭据。
@@ -36,12 +31,12 @@ async function submit(): Promise<void> {
       </div><p class="login-brand-footer">FIN MICRO · 企业应用基座模板</p>
     </section>
     <section class="login-panel" aria-labelledby="login-title"><div class="login-card" :aria-busy="loading">
-    <p class="login-eyebrow">欢迎回来</p><h2 id="login-title">登录工作台</h2><p class="login-subtitle">{{ demoMode ? '以固定演示用户体验本地主页，无需账号或密码。' : '使用你的工作账号，继续 __PROJECT_NAME__ 的工作。' }}</p>
+    <p class="login-eyebrow">欢迎回来</p><h2 id="login-title">登录工作台</h2><p class="login-subtitle">{{ demoMode ? '仅开发模拟：使用 demo / 123456 登录本地主页。' : '使用你的工作账号，继续 __PROJECT_NAME__ 的工作。' }}</p>
     <el-alert v-if="demoMode" title="仅演示登录，不提供生产身份认证" type="warning" :closable="false" />
-    <p>{{ demoMode ? '仅开发演示，不连接认证接口、不收集真实密码；刷新仅恢复当前标签页的演示会话。' : '请接入 src/platform.ts 的真实平台接口；认证失败不会降级为演示身份。' }}</p>
+    <p>{{ demoMode ? '仅开发模拟，校验演示账号密码，不连接认证接口，请勿输入真实凭据；刷新仅恢复当前标签页的演示会话。' : '请接入 src/platform.ts 的真实平台接口；认证失败不会降级为演示身份。' }}</p>
     <el-form class="login-form" label-position="top" size="large" @submit.prevent="submit">
-      <el-form-item v-if="!demoMode" label="用户名"><el-input v-model="username" autocomplete="username" placeholder="请输入你的工作账号" :disabled="loading" /></el-form-item>
-      <el-form-item v-if="!demoMode" label="密码"><el-input v-model="password" type="password" autocomplete="current-password" placeholder="请输入登录密码" show-password :disabled="loading" /></el-form-item>
+      <el-form-item label="用户名"><el-input v-model="username" autocomplete="username" placeholder="请输入你的工作账号" :disabled="loading" /></el-form-item>
+      <el-form-item label="密码"><el-input v-model="password" type="password" autocomplete="current-password" placeholder="请输入登录密码" show-password :disabled="loading" /></el-form-item>
       <p v-if="error" class="login-error" role="alert">{{ error }}</p>
       <div class="actions">
         <el-button class="login-submit" type="primary" native-type="submit" :loading="loading" :disabled="loading">{{ demoMode ? '演示登录，进入主页' : '登录工作台' }}</el-button>

package/scaffold/host/src/views/{LoginRoute.vue → login/index.vue}

@@ -1,10 +1,10 @@
 <script setup lang="ts">
 import { watch } from 'vue'
 import { useRouter, useRoute } from 'vue-router'
-import LoginView from './LoginView.vue'
-import { usePlatformSession } from '../hooks/usePlatformSession'
-import { authorizedRedirect } from '../router/targets'
-import { reportError } from '../utils/errorUtils'
+import LoginForm from './components/LoginForm.vue'
+import { usePlatformSession } from '../../hooks/usePlatformSession'
+import { authorizedRedirect } from '../../router/targets'
+import { reportError } from '../../utils/errorUtils'
 const controller = usePlatformSession()
 const { session, loading, error, signIn, restore } = controller
 const router = useRouter()
@@ -13,4 +13,4 @@ watch(session, value => {
   if (value) void router.replace(authorizedRedirect(router, value, route.query.redirect)).catch(reportError)
 })
 </script>
-<template><LoginView :loading="loading" :error="error" :sign-in="signIn" @restore="restore" /></template>
+<template><LoginForm :loading="loading" :error="error" :sign-in="signIn" @restore="restore" /></template>

package/scaffold/host/src/views/{ProfileView.vue → profile/index.vue}

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PlatformSession } from '../types/platform'
+import type { PlatformSession } from '../../types/platform'
 /** 仅展示平台公开会话字段，不读取、显示或持久化私有凭据。操作交回宿主统一导航与退出守卫。 */
 defineProps<{ session: PlatformSession; demo: boolean; pending: boolean }>()
 const emit = defineEmits<{ home: []; logout: [] }>()

package/scaffold/host/src/views/{WorkspaceRoute.vue → workspace/index.vue}

@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { watch } from 'vue'
 import { useRouter } from 'vue-router'
-import HostLayout from '../layout/HostLayout.vue'
-import { usePlatformSession } from '../hooks/usePlatformSession'
-import { reportError } from '../utils/errorUtils'
+import HostLayout from '../../layout/HostLayout.vue'
+import { usePlatformSession } from '../../hooks/usePlatformSession'
+import { reportError } from '../../utils/errorUtils'
 const { session, signOut, expire } = usePlatformSession()
 const router = useRouter()
 watch(session, value => { if (!value) void router.replace('/login').catch(reportError) }, { flush: 'sync' })

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

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref } from 'vue'
+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 { HostShell } from '@axewo/fin-micro/layout'
+import '@axewo/fin-micro/layout/style.css'
+import HostWorkspace from './HostWorkspace.vue'
+import { isHome, 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: []; expired: [revision: number] }>()
+const shell = ref<InstanceType<typeof HostShell>>()
+const notice = ref('')
+const exiting = ref(false)
+let alive = true
+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<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: authenticated(), revision: getTokenRevision() }),
+      // 业务替换点：可改为接收 context.signal 的异步后台读取；helper 会复查会话版本与存活。
+      provider: () => getAccessToken(),
+    }),
+  },
+  onError: report,
+  canOpen: input => authenticated() && !exiting.value && canOpenRoute(props.session, input),
+  // 不开放任意请求代理；Token 仅由上面的显式白名单能力提供，跨应用导航另行制定白名单。
+  canNavigate: () => false,
+})
+host.updateSession(publicSession(props.session))
+// 身份与授权菜单就绪后才能恢复 URL；用户隔离存储，禁止恢复未通过 canOpen 的入口。
+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 epochs = ref<Record<string, number>>({})
+let previous = new Set<string>()
+const off = host.subscribe(snapshot => {
+  const present = new Set(snapshot.tabs.map(tab => tab.appId))
+  // 同 tick 关闭最后一页后重开，也不能复用已经失效的 bridge 和应用容器。
+  for (const appId of previous) if (!present.has(appId)) epochs.value[appId] = (epochs.value[appId] ?? 0) + 1
+  previous = present
+})
+
+/** 所有 UI 导航均走核心事务，携带原 key，避免异步操作误关重开后的新页签。 */
+async function operate(operation: NavigationOperation): Promise<void> {
+  if (exiting.value) return
+  try {
+    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) }
+}
+function open(appId: string, menu: MicroMenu): void {
+  if (menu.target) void operate({ type: 'open', input: { appId, ...menu.target, title: menu.name, activeMenuId: menu.menuId } })
+}
+/** 退出先由核心统一确认全部页面；取消不注销，确认后由父组件撤销会话并卸载工作区。 */
+async function signOut(): Promise<void> {
+  if (exiting.value) return
+  shell.value?.closePopovers()
+  exiting.value = true
+  try {
+    const result = await host.operate({ type: 'closeMany', scope: 'all' })
+    if (result.status === 'committed' || result.status === 'noop') emit('logout')
+    else notice.value = '退出已取消，请先处理未保存页面'
+  } catch (error) { report(error) }
+  finally { exiting.value = false }
+}
+onBeforeUnmount(() => {
+  alive = false
+  off()
+  workspaceRouter.dispose()
+  browser.dispose()
+  // 先撤销公开身份，再释放沙箱和核心；立即 dispose 阻止任何旧 SDK 发起新动作。
+  host.updateSession({ authenticated: false, permissions: [] })
+  void runtime.dispose().catch(reportError)
+  host.dispose()
+})
+</script>
+
+<template>
+  <!-- 外壳只发事件；认证、导航守卫与生命周期仍由本项目唯一核心管理。 -->
+  <HostShell ref="shell" :brand="{ title: '__PROJECT_NAME__' }" :apps="host.apps" :tabs="state.tabs" :active-key="active?.key" :user-name="session.user.name" :pending="exiting" :notice="notice" :is-fixed-tab="isHome" @open="open" @operate="operate" @logout="signOut" @profile="operate({ type: 'open', input: localTarget('profile') })" @dismiss-notice="notice = ''" @error="report">
+    <!-- 业务替换点：主页/个人资料和每应用唯一容器仍属项目，不由外壳创建运行时。 -->
+    <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" />
+  </HostShell>
+</template>

package/scaffold/layouts/standard/host/src/styles/shell.css

@@ -0,0 +1,168 @@
+/* 项目本地业务页面样式，公共外壳样式从 npm 子路径导入。 */
+.host-shell .home-view {
+  max-width: 1440px;
+  margin: 0 auto;
+}
+.host-shell .welcome-panel {
+  background: #f4f7fc;
+  border: 1px solid #e5ebf5;
+  border-radius: 10px;
+  padding: 28px 32px;
+  min-height: 152px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 22px;
+  overflow: hidden;
+}
+.host-shell .eyebrow {
+  color: #7f94b4 !important;
+  font-size: 10px !important;
+  letter-spacing: 1.8px;
+  margin: 0 0 10px !important;
+}
+.host-shell .welcome-panel h1 {
+  font-size: 23px;
+  letter-spacing: 0.3px;
+  margin: 0 0 9px;
+  font-weight: 600;
+  color: #25344e;
+}
+.host-shell .welcome-panel p {
+  font-size: 12px;
+  color: #8b97aa;
+  margin: 0;
+}
+.host-shell .home-panel {
+  background: #fff;
+  border: 1px solid var(--shell-border);
+  border-radius: 9px;
+  padding: 22px 24px;
+  margin-bottom: 22px;
+}
+.host-shell .panel-heading {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 20px;
+}
+.host-shell .panel-heading h2 {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 600;
+}
+.host-shell .panel-heading > span {
+  color: #9ba4b4;
+  font-size: 11px;
+}
+.host-shell .shortcut-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+.host-shell .shortcut-card {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 18px;
+  background: white;
+  border: 1px solid #e9edf5;
+  border-radius: 7px;
+  text-align: left;
+  transition:
+    border-color 0.15s,
+    background 0.15s;
+}
+.host-shell .shortcut-card:hover {
+  border-color: #acc2f5;
+  background: #fafcff;
+}
+.host-shell .entry-icon {
+  width: 40px;
+  height: 40px;
+  display: grid;
+  place-items: center;
+  border-radius: 9px;
+  background: #edf3ff;
+  color: #4c79dc;
+  font-size: 17px;
+}
+.host-shell .shortcut-card:nth-child(2) .entry-icon {
+  background: #edf8f5;
+  color: #4a9a88;
+}
+.host-shell .shortcut-card strong {
+  display: block;
+  font-size: 13px;
+  font-weight: 500;
+}
+.host-shell .shortcut-card small {
+  display: block;
+  color: #99a3b4;
+  font-size: 11px;
+  margin-top: 4px;
+}
+.host-shell .entry-arrow {
+  margin-left: auto;
+  color: #a0acbe;
+}
+.host-shell .home-columns {
+  display: grid;
+  grid-template-columns: 1.2fr 1fr;
+  gap: 22px;
+}
+.host-shell .home-columns .home-panel {
+  min-height: 266px;
+}
+.host-shell .empty-state {
+  text-align: center;
+  color: #9ba5b4;
+  padding: 25px 12px;
+  font-size: 12px;
+}
+.host-shell .empty-state strong {
+  display: block;
+  font-weight: 400;
+  color: #8491a6;
+  margin-bottom: 6px;
+}
+.host-shell .empty-state p {
+  margin: 0;
+  font-size: 11px;
+}
+.host-shell .empty-symbol {
+  display: block;
+  color: #ced7e5;
+  font-size: 32px;
+  line-height: 1.2;
+  margin-bottom: 13px;
+}
+.host-shell .recent-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.host-shell .recent-list li + li {
+  border-top: 1px solid #f1f3f7;
+}
+.host-shell .recent-list button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  width: 100%;
+  border: 0;
+  background: white;
+  text-align: left;
+  padding: 12px 0;
+  font-size: 12px;
+}
+.host-shell .recent-list button:hover {
+  color: #3267e3;
+}
+.host-shell .recent-list small {
+  color: #99a5b5;
+  font-size: 11px;
+  white-space: nowrap;
+}

package/scaffold/layouts/standard/vue/src/layout/StandaloneLayout.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { FinWatermark } from '@axewo/fin-micro/watermark'
+import { watermarkConfig } from '../utils/watermarkConfig'
+import { useRoute, useRouter } from 'vue-router'
+import { StandaloneShell } from '@axewo/fin-micro/layout'
+import '@axewo/fin-micro/layout/style.css'
+import { createStandaloneMenus, standaloneActiveMenu } from '../router/menu'
+import { reportError } from '../utils/errorUtils'
+
+// 菜单映射与路由实例归项目；公共外壳不创建第二个 router 或读取后台权限。
+const router = useRouter()
+const route = useRoute()
+const menus = computed(() => createStandaloneMenus(router.options.routes))
+const activeMenu = computed(() => standaloneActiveMenu(route))
+/** 路由失败进入项目脱敏错误边界，不产生未处理 Promise；路由守卫仍由 router 执行。 */
+function navigate(path: string): void { void router.push(path).catch(reportError) }
+</script>
+<template>
+  <!-- 业务替换点：品牌、header-actions 等局部插槽不会接管其他默认区域。 -->
+  <StandaloneShell :brand="{ title: '__PROJECT_NAME__' }" :title="route.meta.title ?? '业务应用'" :menus="menus" :active-menu="activeMenu" @navigate="navigate">
+    <slot />
+    <!-- 公共外壳提供稳定业务视口；嵌入时 App 不挂载本布局。 -->
+    <template #workspace-overlay><FinWatermark :config="watermarkConfig" /></template>
+  </StandaloneShell>
+</template>

package/scaffold/vue/src/App.vue

@@ -1,24 +1,30 @@
 <script setup lang="ts">
 import { computed, provide } from 'vue'
 import AppProviders from './components/AppProviders.vue'
+import StandaloneLayout from './layout/StandaloneLayout.vue'
+import { isMicroFrontend } from '@axewo/fin-micro/runtime'
 import { RouterView } from 'vue-router'
 import { MicroTabCache, MicroRouteView, useMicroHost } from '@axewo/fin-micro'
 import { sessionKey, type BridgeSession } from './bridge/session'
 const props = defineProps<{ session: BridgeSession }>()
 provide(sessionKey, props.session)
 const { bridge, status, identity } = props.session
+// 环境与连接状态分开：嵌入但未取得 bridge 时也不能显示第二套头部菜单。
+const embedded = isMicroFrontend()
 const state = bridge ? useMicroHost(bridge) : undefined
 const tabs = computed(() => state?.value.tabs.filter(tab => tab.appId === bridge?.appId) ?? [])
 const activeKey = computed(() => state?.value.tabs.find(tab => tab.tabId === state.value.activeTabId)?.key)
 </script>
 <template>
   <AppProviders>
-    <main class="page">
-      <small role="status">{{ status }} · {{ identity?.user?.name ?? '未连接公开身份' }}</small>
-      <!-- 缓存以核心 tab.key 为身份；关闭、刷新和淘汰销毁实例，切换只停用。
-           LRU 不是持久化，重要草稿需要业务另行保存，不能依赖守卫阻止浏览器刷新。 -->
-      <MicroTabCache v-if="bridge && state" :tabs="tabs" :active-key="activeKey" :max="20"><MicroRouteView /></MicroTabCache>
-      <RouterView v-else />
-    </main>
+    <component :is="embedded ? 'main' : StandaloneLayout">
+      <div class="page">
+        <small role="status">{{ status }} · {{ identity?.user?.name ?? '未连接公开身份' }}</small>
+        <!-- 缓存以核心 tab.key 为身份；关闭、刷新和淘汰销毁实例，切换只停用。
+             LRU 不是持久化，重要草稿需要业务另行保存，不能依赖守卫阻止浏览器刷新。 -->
+        <MicroTabCache v-if="bridge && state" :tabs="tabs" :active-key="activeKey" :max="20"><MicroRouteView /></MicroTabCache>
+        <RouterView v-else />
+      </div>
+    </component>
   </AppProviders>
 </template>

package/scaffold/vue/src/bootstrap.ts

@@ -2,6 +2,7 @@ import { createApp } from 'vue'
 import { disposePinia } from 'pinia'
 import ElementPlus from 'element-plus'
 import { connectMicroRouter } from '@axewo/fin-micro'
+import { isMicroFrontend } from '@axewo/fin-micro/runtime'
 import { installBridgeAuth } from './bridge/auth'
 import { reportError, toSafeError, cleanupAll } from './utils/errorUtils'
 import App from './App.vue'
@@ -19,7 +20,9 @@ export async function mount(): Promise<void> {
   unmount()
   const session = createBridgeSession()
   const { bridge } = session
-  const router = createMicroRouter(Boolean(bridge))
+  // history 与布局使用同一 SDK 环境标识，缺桥不应争用宿主 URL。
+  const embedded = isMicroFrontend()
+  const router = createMicroRouter(embedded)
   const app = createApp(App, { session })
   const pinia = createAppPinia()
   let stopped = false
@@ -55,7 +58,9 @@ export async function mount(): Promise<void> {
       // MicroRouteView 按固定页签快照解析真实路由，不全局 router.replace 污染其他缓存页面。
       offRouter = connectMicroRouter(bridge, { async replace() { if (!stopped) session.status.value = '宿主已连接' } },
         error => { if (!stopped) session.status.value = toSafeError(error).message })
-    } else session.status.value = '独立演示：宿主命令不可用，CRUD 数据仅保存在当前页面内存'
+    } else session.status.value = embedded
+      ? '嵌入运行：未连接宿主'
+      : '独立演示：宿主命令不可用，CRUD 数据仅保存在当前页面内存'
     app.mount('#app')
     mounted = true
   } catch (error) {

package/scaffold/vue/src/layout/Header.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+/** 独立应用顶栏只展示本地标题，不创建登录状态或宿主能力。 */
+defineProps<{ title: string }>()
+</script>
+
+<template>
+  <header class="standalone-header">
+    <strong>__PROJECT_NAME__</strong>
+    <span>{{ title }} · 独立运行</span>
+  </header>
+</template>
+
+<style scoped>
+.standalone-header { grid-column: 1 / -1; display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 0 24px; background: #fff; border-bottom: 1px solid #e5e7eb; }
+</style>

package/scaffold/vue/src/layout/Sidebar.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { ElMenu } from 'element-plus'
+import type { StandaloneMenu } from '../router/menu'
+import SidebarItem from './SidebarItem.vue'
+
+/** 菜单只负责本地导航；活动项随路由更新，详情页可显式关联列表。 */
+defineProps<{ menus: StandaloneMenu[]; activeMenu: string }>()
+</script>
+
+<template>
+  <aside class="standalone-sidebar" aria-label="独立应用导航">
+    <ElMenu router :default-active="activeMenu" :collapse-transition="false">
+      <SidebarItem v-for="item in menus" :key="item.path" :item="item" />
+    </ElMenu>
+  </aside>
+</template>
+
+<style scoped>
+.standalone-sidebar { overflow: auto; background: #fff; border-right: 1px solid #e5e7eb; }
+.standalone-sidebar :deep(.el-menu) { border-right: 0; }
+</style>

package/scaffold/vue/src/layout/SidebarItem.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { ElIcon, ElMenuItem, ElSubMenu } from 'element-plus'
+import type { StandaloneMenu } from '../router/menu'
+
+/** 递归保留实际路由分组；叶子使用完整路径交给同一个 Vue Router。 */
+defineProps<{ item: StandaloneMenu }>()
+</script>
+
+<template>
+  <ElSubMenu v-if="item.children.length" :index="item.path">
+    <template #title>
+      <ElIcon v-if="item.icon"><component :is="item.icon" /></ElIcon>
+      <span>{{ item.title }}</span>
+    </template>
+    <SidebarItem v-for="child in item.children" :key="child.path" :item="child" />
+  </ElSubMenu>
+  <ElMenuItem v-else :index="item.path">
+    <ElIcon v-if="item.icon"><component :is="item.icon" /></ElIcon>
+    <span>{{ item.title }}</span>
+  </ElMenuItem>
+</template>