@axewo/fin-micro 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,168 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+import type { MenuInstance } from 'element-plus'
+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: []; 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 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 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(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
+  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>
+  <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>
+      <!-- 侧栏用 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>

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

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { MicroMenu } from '@axewo/fin-micro'
+/** 薄递归只渲染后台授权菜单，展开与选中状态交给 Element Plus。 */
+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,47 @@
+<script setup lang="ts">
+import { nextTick, ref, watch } from 'vue'
+import type { MicroTab, NavigationOperation } from '@axewo/fin-micro'
+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 })
+}
+// 只滚动当前页签，不触碰业务容器及其缓存生命周期。
+watch(() => props.activeKey, () => {
+  void nextTick().then(() => strip.value?.querySelector<HTMLElement>('[aria-selected="true"]')?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })).catch(error => emit('error', error))
+})
+watch(() => props.pending, pending => { if (pending) closePopovers() })
+defineExpose({ closePopovers })
+</script>
+<template>
+  <div class="shell-tabbar" :inert="pending || undefined" @keydown.esc="closePopovers">
+    <button v-if="menu" class="popover-backdrop" aria-label="关闭页签菜单" tabindex="-1" @click="closePopovers" />
+    <div ref="strip" class="tab-strip" role="tablist" aria-label="已打开页面">
+      <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>
+    <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

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { MicroAppContainer, type MicroApp, type MicroTab, type MicroRuntime } from '@axewo/fin-micro'
+import { demoMode } from '../platform'
+import { LOCAL_APP_ID } from '../localPages'
+import type { PlatformSession } from '../types/platform'
+import HomeView from '../views/HomeView.vue'
+import ProfileView from '../views/ProfileView.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="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>
+</template>

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: '主页', target: { tabId: 'host-local:home', route: '/home' } },
+    { menuId: 'profile', name: '个人中心', 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

@@ -0,0 +1,239 @@
+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
+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)
+  // 仅提交成功且仍属当前代次的演示身份；标记不是 Token，不可用于真实平台接口认证。
+  if (demoMode && session) writeDemoSession(true)
+}
+
+// 可配置部署注册表，不依赖项目生成顺序；实际子应用 appId 必须与此配置一致。
+const { appId, entry } = resolveTrustedApp(import.meta.env)
+if (appId === LOCAL_APP_ID) throw new Error('业务 appId 不能占用宿主保留身份 host-local')
+const registry: MicroApp[] = [{
+  appId, name: '业务应用', entry,
+}]
+const demoMenus: MicroMenu[] = [{ menuId: 'business', name: '业务工作区', children: [
+  { menuId: 'records', name: '示例记录', target: { tabId: `${appId}:list`, route: '/list' } },
+] }]
+
+/** 开发默认可体验；显式 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。
+ * 返回未解码 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>()
+  // 本地页与远端共享宿主 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')
+    }
+    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 {
+  // 本地页面仅在已创建的认证工作区使用，不依赖后台 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 ?? [])
+  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) {
+    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)
+}
+
+/**
+ * username/password 为登录表单输入，signal 同时覆盖登录和后续菜单请求。
+ * 返回完整平台会话；登录拒绝、菜单失败或取消均拒绝 Promise，不能显示半就绪工作区。
+ * 演示仅在开发模式提供固定身份，忽略任何传入账号密码；绝非生产认证，不持久化凭据。
+ */
+export async function login(username: string, password: string, signal: AbortSignal): Promise<PlatformSession> {
+  if (signal.aborted) throw new DOMException('登录已取消', 'AbortError')
+  if (demoMode) return demoSession()
+  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) clearDemoSession()
+  else await request('logout', signal, {}, previousToken)
+}
+
+/** 输入当前平台会话，返回 SDK 白名单公开字段；不包含 Token，不暴露后台响应的其他属性。 */
+export function publicSession(session: PlatformSession): SessionInput {
+  return { authenticated: true, user: { ...session.user }, permissions: [...session.permissions] }
+}