@axewo/fin-micro 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,59 @@
+import { onBeforeUnmount, ref, shallowRef } from 'vue'
+import { activateSessionToken, clearAccessToken, getAccessToken, login, logout, restoreSession } from '../platform'
+import type { PlatformSession } from '../types/platform'
+
+/**
+ * 在组件 setup 内创建平台会话控制器，并立即发起恢复；组件卸载时中止请求。
+ * @returns 响应式身份/忙碌/错误状态及登录、恢复、退出操作；操作错误写入 error，不向表单抛出。
+ * 此处只管理身份请求，导航和页面资源由工作区负责；生产登录/CSRF协议在 platform.ts 替换。
+ */
+export function usePlatformSession() {
+  const session = shallowRef<PlatformSession | null>(null)
+  const loading = ref(false)
+  const error = ref('')
+  let request: AbortController | undefined
+  let generation = 0
+
+  /** 每次操作中止上一次请求；卸载与重试后晚到响应不能恢复旧身份。 */
+  async function run(action: (signal: AbortSignal) => Promise<PlatformSession | null>): Promise<void> {
+    const current = ++generation
+    request?.abort()
+    // 重新认证/恢复先撤销旧身份及凭据；失败不保留可用的旧 Token。
+    clearAccessToken()
+    session.value = null
+    const controller = new AbortController()
+    request = controller
+    loading.value = true
+    error.value = ''
+    try {
+      const value = await action(controller.signal)
+      if (current === generation && !controller.signal.aborted) {
+        activateSessionToken(value)
+        session.value = value
+      }
+    } catch (cause) {
+      if (current === generation && !controller.signal.aborted) error.value = String(cause)
+    } finally {
+      if (current === generation) loading.value = false
+    }
+  }
+
+  /** 输入表单凭据；完成身份与菜单加载后一次性替换会话，不持久化密码。 */
+  function signIn(username: string, password: string): Promise<void> {
+    return run(signal => login(username, password, signal))
+  }
+  /** 恢复接口失败保留错误，未登录返回空会话；不会回退为演示身份。 */
+  function restore(): Promise<void> {
+    return run(restoreSession)
+  }
+  /** 立即移除工作区触发资源释放；远程注销失败也不恢复本地旧会话。 */
+  function signOut(): void {
+    const previousToken = getAccessToken()
+    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 }
+}

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

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+defineProps<{ userName: string; pending: boolean }>()
+const emit = defineEmits<{ logout: [] }>()
+</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>
+</template>

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

@@ -0,0 +1,124 @@
+<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 { 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'
+const props = defineProps<{ session: PlatformSession }>()
+const emit = defineEmits<{ logout: [] }>()
+const notice = ref('')
+const exiting = ref(false)
+let alive = true
+const report = (error: unknown) => { if (alive) notice.value = String(error) }
+// 认证成功后才创建；只允许当前后台授权并经过可信注册表转换的应用。
+const host = createMicroHost<TokenCapabilities>(props.session.apps, {
+  capabilities: {
+    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() }),
+      // 业务替换点：可改为接收 context.signal 的异步后台读取；helper 会复查会话版本与存活。
+      provider: () => getAccessToken(),
+    }),
+  },
+  onError: report,
+  canOpen: input => alive && !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 state = useMicroHost(host)
+const active = computed(() => state.value.tabs.find(tab => tab.tabId === state.value.activeTabId))
+const menu = ref<MenuInstance>()
+const resetting = ref(false)
+const menuIndex = (appId: string, menuId: string) => JSON.stringify([appId, menuId])
+const selected = computed(() => active.value?.activeMenuId ? menuIndex(active.value.appId, active.value.activeMenuId) : '')
+/** Element 菜单会先选中点击项；重置公开 prop，确保异步守卫拒绝时仍高亮实际活动页。 */
+async function syncMenu(): Promise<void> {
+  resetting.value = true
+  await nextTick()
+  if (alive) resetting.value = false
+}
+/** 只计算菜单祖先，展开交给 Element Plus，不重新实现菜单状态机。 */
+function ancestors(menus: readonly MicroMenu[], id?: string): string[] {
+  for (const item of menus) {
+    if (item.menuId === id) return [item.menuId]
+    const children = ancestors(item.children ?? [], id)
+    if (children.length) return [item.menuId, ...children]
+  }
+  return []
+}
+// 首次渲染也展开恢复页的祖先；后续用户手动展开由 ElMenu 自己维护。
+const defaultOpeneds = computed(() => host.apps.flatMap(app => ancestors(app.menus ?? [], active.value?.appId === app.appId ? active.value.activeMenuId : undefined).slice(0, -1).map(id => menuIndex(app.appId, id))))
+watch(selected, () => {
+  const app = host.apps.find(item => item.appId === active.value?.appId)
+  if (!app) return
+  for (const id of ancestors(app.menus ?? [], active.value?.activeMenuId).slice(0, -1)) menu.value?.open(menuIndex(app.appId, id))
+}, { flush: 'post', immediate: true })
+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(operation)
+    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
+  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()
+  browser.dispose()
+  // 先撤销公开身份，再释放沙箱和核心；立即 dispose 阻止任何旧 SDK 发起新动作。
+  host.updateSession({ authenticated: false, permissions: [] })
+  void runtime.dispose().catch(error => console.error('子应用资源释放失败', error))
+  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" />
+      </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" />
+    </main>
+  </div>
+</template>

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

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import type { MicroMenu } from '@axewo/fin-micro'
+defineProps<{ appId: string; menus: readonly MicroMenu[] }>()
+const emit = defineEmits<{ open: [appId: string, menu: MicroMenu] }>()
+</script>
+<template>
+  <template v-for="menu in menus" :key="JSON.stringify([appId, menu.menuId])">
+    <el-sub-menu v-if="menu.children?.length" :index="JSON.stringify([appId, menu.menuId])">
+      <template #title>{{ menu.name }}</template>
+      <HostMenu :app-id="appId" :menus="menu.children" @open="(id, item) => emit('open', id, item)" />
+    </el-sub-menu>
+    <el-menu-item v-else-if="menu.target" :index="JSON.stringify([appId, menu.menuId])" @click="emit('open', appId, menu)">{{ menu.name }}</el-menu-item>
+  </template>
+</template>

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

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import type { MicroTab, NavigationOperation } from '@axewo/fin-micro'
+defineProps<{ tabs: readonly MicroTab[]; activeKey?: string }>()
+const emit = defineEmits<{ operate: [operation: NavigationOperation] }>()
+</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>
+  </nav>
+</template>

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

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+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)))
+</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" />
+  </section>
+</template>

package/scaffold/host/src/platform.ts

@@ -0,0 +1,208 @@
+import type { MicroApp, MicroMenu, OpenTab, SessionInput } from '@axewo/fin-micro'
+import { http } from './utils/request'
+
+import type { PlatformSession } from './types/platform'
+
+// 仅驻留基座私有模块内存；不写 localStorage、会话快照、URL 或事件总线。
+let accessToken: string | null = null
+let tokenRevision = 0
+const pendingTokens = new WeakMap<PlatformSession, string | null>()
+/** 返回基座当前私有凭据；null 表示无可读 Token，不单独代表用户已登录。不得记录或广播结果。 */
+export function getAccessToken(): string | null { return accessToken }
+/** 返回凭据版本；每次提交/清除均递增，供异步能力交付前判断身份或凭据是否变化。 */
+export function getTokenRevision(): number { return tokenRevision }
+/**
+ * 提交基座私有内存凭据并使旧版本失效；不持久化，也不建立登录身份。
+ * @param value 最新访问 Token 或 null；刷新成功后同样调用，调用方须先验证认证操作仍有效。
+ * @throws 格式无效时拒绝且不修改当前值，错误不回显凭据。
+ */
+export function setAccessToken(value: string | null): void {
+  if (value !== null && (typeof value !== 'string' || !value || value.length > 16384 || /[\s\u0000-\u001f\u007f]/.test(value))) throw new Error('平台 Token 格式错误')
+  accessToken = value
+  tokenRevision++
+}
+/** 清除本地凭据并递增版本；不替代服务端注销，已交付到可信子应用的凭据无法直接撤回。 */
+export function clearAccessToken(): void { setAccessToken(null) }
+/** 只在 usePlatformSession 的 generation 验证通过后提交候选凭据，晚到响应不会覆盖新用户。 */
+export function activateSessionToken(session: PlatformSession | null): void {
+  setAccessToken(session ? pendingTokens.get(session) ?? null : null)
+  if (session) pendingTokens.delete(session)
+}
+
+// 可配置部署注册表，不依赖项目生成顺序；实际子应用 appId 必须与此配置一致。
+const appId = import.meta.env.VITE_MICRO_APP_ID || 'business'
+const registry: MicroApp[] = [{
+  appId, name: '业务应用', entry: import.meta.env.VITE_MICRO_APP_ENTRY || 'http://localhost:7101',
+}]
+const demoMenus: MicroMenu[] = [{ menuId: 'business', name: '业务工作区', children: [
+  { menuId: 'records', name: '示例记录', target: { tabId: `${appId}:list`, route: '/list' } },
+] }]
+
+/** 仅在开发且显式启用时允许内存演示登录；任何真实接口失败均不会回退此身份。 */
+export const demoMode = import.meta.env.DEV && import.meta.env.VITE_AUTH_DEMO === 'true'
+
+/**
+ * 同源平台接口边界，signal 必须沿用当前认证操作的取消信号，body 存在时发送 POST。
+ * 返回未解码 JSON；401 返回 null，其他错误或网络失败拒绝 Promise。
+ * 默认采用 HttpOnly Cookie；仅 menus/logout 显式传入该次局部 Token，上线前接入后台自己的 CSRF 协议。
+ */
+async function request(path: string, signal: AbortSignal, body?: Record<string, unknown>, token: string | null = null): Promise<unknown> {
+  const headers = token === null ? undefined : { Authorization: `Bearer ${token}` }
+  try {
+    // 平台接口只发送 JSON 对象，编码、超时和取消由 fin-core 统一实现。
+    const value = body === undefined
+      ? await http.get<unknown>(path, { signal, headers })
+      : await http.post<unknown>(path, body, { signal, headers })
+    return value ?? null
+  } catch (error) {
+    // 只有身份协议将 401 解释为未登录；通用请求类不擅自改变认证或导航。
+    if (typeof error === 'object' && error !== null && 'isAxiosError' in error && error.isAxiosError === true &&
+        'response' in error && typeof error.response === 'object' && error.response !== null &&
+        'status' in error.response && error.response.status === 401) return null
+    throw error
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+function text(value: unknown, limit: number): value is string {
+  return typeof value === 'string' && !!value.trim() && value.length <= limit && !/[\u0000-\u001f\u007f]/.test(value)
+}
+function identifier(value: unknown): value is string {
+  // CLI 的 appId 最长 214 字符，派生 tabId 还包含业务后缀；与 core 的 500 字符标识边界一致。
+  return text(value, 500) && /^[a-zA-Z0-9:_-]+$/.test(value)
+}
+function localRoute(value: unknown): value is string {
+  return text(value, 1000) && value.startsWith('/') && !value.startsWith('//') && !value.includes('\\')
+}
+
+/** 只读取白名单身份字段；拒绝未知 appId，不允许接口提供 entry 或代码导入路径。 */
+function decodeIdentity(value: unknown): Omit<PlatformSession, 'apps'> & { appIds: string[] } {
+  if (!isObject(value) || !isObject(value.user) || !text(value.user.id, 120) || !text(value.user.name, 120) ||
+      !Array.isArray(value.permissions) || !value.permissions.every(item => text(item, 120)) ||
+      !Array.isArray(value.appIds) || !value.appIds.every(identifier)) {
+    throw new Error('平台身份格式错误，预期 {user:{id,name},permissions:string[],appIds:string[]}')
+  }
+  const ids = value.appIds as string[]
+  if (new Set(ids).size !== ids.length || ids.some(id => !registry.some(app => app.appId === id))) {
+    throw new Error('平台返回重复或未在可信注册表登记的 appId，请检查部署配置')
+  }
+  return { user: { id: value.user.id, name: value.user.name }, permissions: [...value.permissions] as string[], appIds: ids }
+}
+
+/**
+ * 解码后台递归菜单，只复制 SDK 的 menuId/name/children/target 四类字段。
+ * 限制深度和数量，并检查应用内 menuId、宿主内 tabId 唯一；不接受任意 entry 或 HTML。
+ * 分组与叶节点互斥；格式错误直接拒绝整次初始化，避免静默扩大或误缩权限。
+ */
+function decodeMenus(value: unknown, tabIds: Set<string>): MicroMenu[] {
+  const menuIds = new Set<string>()
+  let count = 0
+  function walk(items: unknown, depth: number): MicroMenu[] {
+    if (!Array.isArray(items) || depth > 8) throw new Error('菜单格式错误或嵌套超过 8 层')
+    return items.map(item => {
+      if (++count > 500 || !isObject(item) || !identifier(item.menuId) || !text(item.name, 80) || menuIds.has(item.menuId)) {
+        throw new Error('菜单超出数量限制或 menuId/name 无效、重复')
+      }
+      menuIds.add(item.menuId)
+      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) }
+      }
+      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 walk(value, 1)
+}
+
+/**
+ * 身份成功后再加载 /api/menus，明确协议为 {apps:[{appId,menus:MicroMenu[]}]}。
+ * 只接受当前身份 appIds 内的应用，名称和 entry 始终采用本地可信注册表。
+ * 接口应返回全部已授权应用（没有菜单可传空数组）；缺失、401 或解码失败均拒绝挂载宿主。
+ */
+async function loadSession(value: unknown, signal: AbortSignal): Promise<PlatformSession> {
+  const identity = decodeIdentity(value)
+  // 该次认证的局部凭据只用于可信平台菜单接口；此时尚未提交全局，不会污染新一代登录。
+  const token = isObject(value) && value.accessToken !== undefined ? value.accessToken : null
+  if (token !== null && (typeof token !== 'string' || !token || token.length > 16384 || /[\s\u0000-\u001f\u007f]/.test(token))) throw new Error('平台 Token 格式错误')
+  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>()
+  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')
+    }
+    seen.add(item.appId)
+    const registered = registry.find(app => app.appId === item.appId)!
+    const menus = decodeMenus(item.menus, tabIds)
+    const hasRecords = leaves(menus).some(menu => menu.menuId === 'records' && menu.target?.route === '/list')
+    return { ...registered, menus, menuRoutes: hasRecords ? [{ pathPrefix: '/detail', menuId: 'records' }] : [] }
+  })
+  if (seen.size !== identity.appIds.length) throw new Error('菜单接口遗漏已授权应用，请检查 /api/menus')
+  // signal 与上层 generation 双重隔离晚到结果；已取消操作不得创建新会话。
+  if (signal.aborted) throw new DOMException('会话加载已取消', 'AbortError')
+  // 后台可选 accessToken；省略保持默认 HttpOnly Cookie 模式，不生成演示 Token。
+  const session: PlatformSession = { user: identity.user, permissions: identity.permissions, apps }
+  pendingTokens.set(session, token)
+  return session
+}
+
+function leaves(menus: readonly MicroMenu[]): MicroMenu[] {
+  return menus.flatMap(menu => menu.children ? leaves(menu.children) : [menu])
+}
+
+/**
+ * 宿主统一导航授权入口。session 为完成菜单加载的当前会话，input 为待打开的页签元信息。
+ * 返回 true 仅代表前端准入：普通入口须精确匹配已授权菜单的 route/tabId；不根据 URL 猜测权限。
+ * 详情是显式演示业务规则：必须存在 records(/list) 菜单并具有 demo:read，且 ID 和 tabId 匹配。
+ * 新业务详情应替换本规则并在后台验证真实权限，不得笼统放行任意 /detail。
+ */
+export function canOpenRoute(session: PlatformSession, input: OpenTab): boolean {
+  const app = session.apps.find(item => item.appId === input.appId)
+  if (!app || !localRoute(input.route)) return false
+  const menus = leaves(app.menus ?? [])
+  if (menus.some(menu => menu.target?.route === input.route && menu.target.tabId === input.tabId)) return true
+  const detail = /^\/detail\?id=([1-9]\d{0,9})$/.exec(input.route)
+  return Boolean(detail && session.permissions.includes('demo:read') &&
+    menus.some(menu => menu.menuId === 'records' && menu.target?.route === '/list') &&
+    input.tabId === `${app.appId}:detail:${detail[1]}`)
+}
+
+/**
+ * 恢复会话并加载授权菜单。signal 为本次操作取消信号，未登录返回 null，接口/解码错误拒绝 Promise。
+ * 演示模式不自动恢复身份；真实模式必须等待两个接口均完成后才能创建宿主。
+ */
+export async function restoreSession(signal: AbortSignal): Promise<PlatformSession | null> {
+  if (demoMode) return null
+  const value = await request('session', signal)
+  return value === null ? null : loadSession(value, signal)
+}
+
+/**
+ * username/password 为登录表单输入，signal 同时覆盖登录和后续菜单请求。
+ * 返回完整平台会话；登录拒绝、菜单失败或取消均拒绝 Promise，不能显示半就绪工作区。
+ * 演示仅在显式开发开关下提供内存身份，绝非生产认证，不持久化密码或凭据。
+ */
+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' }] })) }
+  const value = await request('login', signal, { username, password })
+  if (value === null) throw new Error('用户名或密码错误')
+  return loadSession(value, signal)
+}
+
+/** signal 为注销取消信号，成功返回 void；远程失败拒绝 Promise，但调用方不得恢复旧本地身份。 */
+export async function logout(signal: AbortSignal, previousToken: string | null = null): Promise<void> {
+  // 本地凭据已清除；局部旧值仅用于可信注销接口，不重新写回私有存储。
+  if (!demoMode) await request('logout', signal, {}, previousToken)
+}
+
+/** 输入当前平台会话，返回 SDK 白名单公开字段；不包含 Token，不暴露后台响应的其他属性。 */
+export function publicSession(session: PlatformSession): SessionInput {
+  return { authenticated: true, user: { ...session.user }, permissions: [...session.permissions] }
+}

package/scaffold/host/src/types/platform.ts

@@ -0,0 +1,12 @@
+import type { MicroApp } from '@axewo/fin-micro'
+
+/**
+ * 完成身份及菜单加载后的平台会话，仅包含可公开字段。
+ * apps 的 entry 来自本地可信注册表，menus 来自已解码的后台授权菜单；不保存 Token。
+ * 此对象只能用于前端编排，不能替代服务端对每个业务请求的认证和权限校验。
+ */
+export interface PlatformSession {
+  user: { id: string; name: string }
+  permissions: string[]
+  apps: MicroApp[]
+}

package/scaffold/host/src/utils/request.ts

@@ -0,0 +1,15 @@
+import { AxiosHttpClient } from '@axewo/fin-core/http/axios'
+
+/**
+ * 基座平台接口专属 Axios 请求实例；不与子应用公共 requestUtils.ts 共享可变配置或凭据。
+ * Token 由 platform.ts 针对可信平台接口显式传入，不隐式读取子应用 bridge。
+ * 默认访问应用部署源的 /api/，开发代理及生产网关由项目部署配置决定。
+ * Cookie 仅同源携带；跨域请求须显式配置可信 baseURL、withCredentials 与服务端 CORS。
+ * 登录到菜单加载期间使用该次局部 Token，避免认证完成前将候选凭据提交到全局。
+ * 业务 code/data 解包、401 后的会话协调由业务适配层负责，本实例不弹窗或跳转。
+ */
+export const http = new AxiosHttpClient({
+  baseURL: '/api/',
+  timeout: 30000,
+  withCredentials: false,
+})

package/scaffold/host/src/views/LoginView.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { demoMode } from '../platform'
+
+// 表单只保留本地输入；会话恢复、取消与错误状态统一由上层会话组合函数管理。
+const props = defineProps<{
+  loading: boolean
+  error: string
+  signIn: (username: string, password: string) => Promise<void>
+}>()
+const emit = defineEmits<{ restore: [] }>()
+const username = ref('')
+const password = ref('')
+async function submit(): Promise<void> {
+  if (props.loading || !username.value.trim() || (!demoMode && !password.value)) return
+  const credential = password.value
+  // 提交即清空密码输入，不在会话或全局状态中保存凭据。
+  password.value = ''
+  await props.signIn(username.value.trim(), credential)
+}
+</script>
+
+<template>
+  <main class="login panel">
+    <h1>__PROJECT_NAME__</h1>
+    <el-alert v-if="demoMode" title="仅演示登录，不提供生产身份认证" type="warning" :closable="false" />
+    <p>请接入 src/platform.ts 的平台接口；默认不启用演示身份。</p>
+    <el-form label-position="top" @submit.prevent="submit">
+      <el-form-item label="用户名"><el-input v-model="username" autocomplete="username" /></el-form-item>
+      <el-form-item v-if="!demoMode" label="密码"><el-input v-model="password" type="password" autocomplete="current-password" /></el-form-item>
+      <p v-if="error" role="alert">{{ error }}</p>
+      <div class="actions">
+        <el-button type="primary" native-type="submit" :loading="loading">登录</el-button>
+        <el-button :disabled="loading" @click="emit('restore')">重试恢复会话</el-button>
+      </div>
+    </el-form>
+  </main>
+</template>

package/scaffold/vue/src/App.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { computed, provide } from 'vue'
+import AppProviders from './components/AppProviders.vue'
+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
+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>
+  </AppProviders>
+</template>

package/scaffold/vue/src/bootstrap.ts

@@ -0,0 +1,71 @@
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import { connectMicroRouter } from '@axewo/fin-micro'
+import { getToken } from '@axewo/fin-micro/sdk'
+import { installRequestTokenProvider } from './utils/requestUtils'
+import App from './App.vue'
+import { installAppLocale } from './locales'
+import { createBridgeSession } from './bridge/session'
+import { createMicroRouter } from './router'
+let cleanup: (() => void) | undefined
+
+/** 幂等卸载，停止路由握手和会话订阅；晚到的初始化不得再挂载旧实例。 */
+export function unmount(): void { cleanup?.(); cleanup = undefined }
+
+/** Wujie 与独立运行共用入口；每次创建全新 router/session，失败清理并展示可重试边界。 */
+export async function mount(): Promise<void> {
+  unmount()
+  const session = createBridgeSession()
+  const { bridge } = session
+  const router = createMicroRouter(Boolean(bridge))
+  const app = createApp(App, { session })
+  let stopped = false
+  let mounted = false
+  let offRouter: (() => void) | undefined
+  let offSession: (() => void) | undefined
+  let offToken: (() => void) | undefined
+  cleanup = () => {
+    stopped = true
+    // 先取消挂起的 Token 读取并还原 provider，避免旧 bridge 被后续请求复用。
+    offToken?.()
+    offRouter?.()
+    offSession?.()
+    if (mounted) app.unmount()
+    // 初始化在 app.mount 前取消/失败时，Vue 尚未接管销毁，仍须释放 history 的浏览器监听。
+    router.options.history.destroy()
+  }
+  try {
+    // 每轮挂载安装独立 i18n，重试/重挂载不复用上一轮语言实例。
+    installAppLocale(app)
+    app.use(ElementPlus)
+    app.use(router)
+    await router.isReady()
+    if (stopped) return
+    if (bridge) {
+      if (bridge.appId !== '__APP_ID__') throw new Error('宿主 appId 与子应用 __APP_ID__ 配置不一致')
+      if (!bridge.negotiate({ version: '1.0', capabilities: ['getToken'] }).compatible) throw new Error('宿主协议不兼容')
+      // 只在已验证的嵌入生命周期安装；独立模式与基座请求不会隐式探测 window bridge。
+      offToken = installRequestTokenProvider(signal => getToken({ bridge, signal }))
+      offSession = bridge.subscribeSession(value => { if (!stopped) session.identity.value = value })
+      // MicroRouteView 按固定页签快照解析真实路由，不全局 router.replace 污染其他缓存页面。
+      offRouter = connectMicroRouter(bridge, { async replace() { if (!stopped) session.status.value = '宿主已连接' } },
+        error => { if (!stopped) session.status.value = String(error) })
+    } else session.status.value = '独立演示：宿主命令不可用，CRUD 数据仅保存在当前页面内存'
+    app.mount('#app')
+    mounted = true
+  } catch (error) {
+    if (stopped) return
+    unmount()
+    const container = document.getElementById('app')
+    if (container) {
+      // 不插入错误 HTML，避免异常消息进入 innerHTML；重试只重建当前应用。
+      container.replaceChildren()
+      const text = document.createElement('p')
+      text.textContent = `应用启动失败：${String(error)}`
+      const retry = document.createElement('button')
+      retry.textContent = '重试启动'
+      retry.onclick = () => { void mount() }
+      container.append(text, retry)
+    }
+  }
+}

package/scaffold/vue/src/bridge/session.ts

@@ -0,0 +1,16 @@
+import { inject, ref, shallowRef, type InjectionKey } from 'vue'
+import { getMicroBridge, type SessionSnapshot } from '@axewo/fin-micro'
+
+/** 每次挂载获取独立会话；仅保存公开身份，不读取宿主 Token，不构造虚假的平台能力。 */
+export function createBridgeSession() {
+  return { bridge: getMicroBridge(), identity: shallowRef<SessionSnapshot>(), status: ref('正在连接宿主') }
+}
+export type BridgeSession = ReturnType<typeof createBridgeSession>
+export const sessionKey: InjectionKey<BridgeSession> = Symbol('micro-session')
+
+/** 页面 setup 内调用，返回本次挂载的会话；独立预览 bridge 为 undefined。 */
+export function useBridgeSession(): BridgeSession {
+  const session = inject(sessionKey)
+  if (!session) throw new Error('页面缺少应用会话')
+  return session
+}

package/scaffold/vue/src/main.ts

@@ -0,0 +1,10 @@
+import 'element-plus/dist/index.css'
+import '@axewo/fin-ui/style.css'
+import './styles/index.css'
+import { setupWujieLifecycle } from '@axewo/fin-micro/runtime'
+import { mount, unmount } from './bootstrap'
+
+// 环境判断、Wujie 回调注册、独立启动和 unload 统一由库管理。
+// 业务替换点在 bootstrap：创建/销毁应用，并取消本轮尚未完成的异步初始化。
+const dispose = setupWujieLifecycle({ mount, unmount })
+if (import.meta.hot) import.meta.hot.dispose(dispose)