@axewo/fin-micro 0.0.0-stage → 2.0.0

package/scaffold/base/src/utils/.gitkeep

@@ -0,0 +1 @@
+# 预留业务通用工具目录；没有复用需求时不创建空工具封装。

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

@@ -0,0 +1,49 @@
+/** 构建时公开配置；VITE_* 均会进入前端产物，禁止放入任何密码或 Token。 */
+export interface AppConfig {
+  /** Axios API 目录；相对地址仅允许当前源的绝对路径。 */
+  readonly apiBase: string
+  /** 凭据允许发送的精确 API 目录，不从请求参数推断或扩大。 */
+  readonly trustedApiBase: string
+  /** 请求超时毫秒数，必须为正有限整数且不超过原生计时器上限。 */
+  readonly timeout: number
+  /** 是否允许跨源 Cookie；服务端仍须配置精确 CORS 与 CSRF 防护。 */
+  readonly withCredentials: boolean
+}
+
+/** 校验公开 HTTP(S) 地址；拒绝凭据、查询、片段、协议相对地址及编码路径歧义，不回显输入。 */
+export function validateAddress(value: string, directory = true): string {
+  if (typeof value !== 'string' || !value || value.trim() !== value || /[\\\s\u0000-\u001f\u007f]/.test(value) || /%(?:2f|5c|2e)/i.test(value) || /(?:^|\/)\.{1,2}(?:\/|$)/.test(value)) throw new Error('应用地址配置无效')
+  const relative = value.startsWith('/') && !value.startsWith('//')
+  if (!relative && !/^https?:\/\//i.test(value)) throw new Error('应用地址必须为 HTTP(S) 或同源绝对路径')
+  const url = new URL(value, 'https://config.invalid')
+  if (url.username || url.password || /[?#]/.test(value) || (directory && !url.pathname.endsWith('/'))) throw new Error('应用地址必须为无凭据、查询和片段的目录')
+  // 只有本机开发地址允许 HTTP；生产网关和代码入口必须使用 HTTPS。
+  if (!relative && url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('非本机应用地址必须使用 HTTPS')
+  return value
+}
+
+/** 将 Vite 环境转换成只读配置；非法值立即拒绝启动，默认值不扩大凭据目录。 */
+export function resolveAppConfig(env: Record<string, unknown> = {}): AppConfig {
+  const apiBase = validateAddress((env.VITE_API_BASE ?? '/api/') as string)
+  const trustedApiBase = validateAddress((env.VITE_TRUSTED_API_BASE ?? apiBase) as string)
+  if (apiBase !== trustedApiBase) throw new Error('API 与可信凭据目录必须一致')
+  const rawTimeout = env.VITE_API_TIMEOUT ?? 30000
+  if ((typeof rawTimeout !== 'string' && typeof rawTimeout !== 'number') || !/^\d+$/.test(String(rawTimeout))) throw new Error('API 超时配置无效')
+  const timeout = Number(rawTimeout)
+  if (!Number.isInteger(timeout) || timeout <= 0 || timeout > 2147483647) throw new Error('API 超时配置无效')
+  const credentials = env.VITE_API_CREDENTIALS ?? 'false'
+  if (credentials !== 'true' && credentials !== 'false') throw new Error('API credentials 配置必须为 true 或 false')
+  return Object.freeze({ apiBase, trustedApiBase, timeout, withCredentials: credentials === 'true' })
+}
+
+/** 解析部署者控制的可信代码入口；只读取构建环境，后台 appIds/menus 不得覆盖 entry。 */
+export function resolveTrustedApp(env: Record<string, unknown> = {}): { readonly appId: string; readonly entry: string } {
+  const appId = env.VITE_MICRO_APP_ID ?? 'business'
+  const entry = env.VITE_MICRO_APP_ENTRY ?? 'http://localhost:7101'
+  if (typeof appId !== 'string' || appId.length > 214 || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(appId)) throw new Error('可信应用 appId 配置无效')
+  if (typeof entry !== 'string' || !/^https?:\/\//i.test(entry)) throw new Error('可信应用 entry 必须为完整 HTTP(S) 地址')
+  return Object.freeze({ appId, entry: validateAddress(entry, false) })
+}
+
+/** 应用模块专属公开配置，不包含宿主认证状态；Node 测试环境使用相同默认值。 */
+export const appConfig = resolveAppConfig(import.meta.env)

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

@@ -0,0 +1,92 @@
+/** 可直接展示/记录的错误分类，不附带原始异常、URL、请求头、响应体或堆栈。 */
+export interface SafeError {
+  readonly kind: 'cancelled' | 'unauthenticated' | 'forbidden' | 'timeout' | 'network' | 'unknown'
+  readonly message: string
+}
+
+/** 复用 Axios、HttpError 和 SDK 的公开判别字段；绝不采用外部 message/cause 作为用户文案。 */
+export function toSafeError(error: unknown): SafeError {
+  const value = error && typeof error === 'object' ? error as Record<string, unknown> : {}
+  const response = value.response && typeof value.response === 'object' ? value.response as Record<string, unknown> : {}
+  const code = value.code
+  const status = response.status ?? value.status
+  // 分段读取 Axios 旧版取消标识，避免被脚手架的大写双下划线占位符校验误识别。
+  if (code === 'ERR_CANCELED' || code === 'CANCELLED' || code === 'SESSION_CHANGED' || value.name === 'AbortError' || value['__CANCEL' + '__'] === true) return { kind: 'cancelled', message: '' }
+  if (status === 401 || code === 'UNAUTHENTICATED') return { kind: 'unauthenticated', message: '登录已失效，请重新登录' }
+  if (status === 403 || code === 'FORBIDDEN') return { kind: 'forbidden', message: '403：无权执行此操作，请联系管理员' }
+  if (code === 'ECONNABORTED' || code === 'ETIMEDOUT' || code === 'TIMEOUT') return { kind: 'timeout', message: '操作超时，请稍后重试' }
+  if (code === 'ERR_NETWORK' || value.name === 'TypeError') return { kind: 'network', message: '连接失败，请检查网络后重试' }
+  return { kind: 'unknown', message: '操作失败，请稍后重试或联系管理员' }
+}
+
+/** Vue/启动边界的保底接收器；只记录白名单分类与固定文案，不日志原始敏感对象。 */
+export function reportError(error: unknown): void {
+  const safe = toSafeError(error)
+  if (safe.kind !== 'cancelled') console.error(safe.message + devDiagnostic(error, 'runtime'))
+}
+
+/** DEV 仅输出固定阶段和标准错误名；不采用外部 name/message、请求、响应或栈。 */
+export function devDiagnostic(error: unknown, stage: 'load-bootstrap' | 'mount' | 'runtime'): string {
+  if (!import.meta.env?.DEV) return ''
+  const name = error && typeof error === 'object' && 'name' in error ? error.name : ''
+  const allowed = ['Error', 'TypeError', 'SyntaxError', 'ReferenceError', 'RangeError', 'URIError', 'AbortError']
+  const kind = typeof name === 'string' && allowed.includes(name) ? name : 'UnknownError'
+  return ` [阶段=${stage}; 错误=${kind}]${kind === 'SyntaxError' ? ' 请先执行 npm run check:runtime 检查模块导出及依赖能力' : ''}`
+}
+
+/** 启动失败的纯文本可重试边界；不插入错误 HTML，不依赖尚未成功安装的 Vue/UI 插件。 */
+export function showStartupError(error: unknown, retry: () => Promise<void>, stage: 'load-bootstrap' | 'mount' = 'mount'): void {
+  if (toSafeError(error).kind === 'cancelled' || typeof document === 'undefined') return
+  const container = document.getElementById('app')
+  if (!container) return
+  const text = document.createElement('p')
+  text.setAttribute('role', 'alert')
+  text.textContent = `应用启动失败：${toSafeError(error).message}${devDiagnostic(error, stage)}`
+  const button = document.createElement('button')
+  button.textContent = '重试启动'
+  button.onclick = () => { void retry().catch(reportError) }
+  container.replaceChildren(text, button)
+}
+
+/**
+ * 在入口动态加载 bootstrap，捕获其静态依赖中的配置解析/代码加载失败。
+ * 入口卸载立即推进代次；尚未完成的 import 不得在卸载或下一轮启动后挂载旧应用。
+ * 仅协调启动边界，不替代 bootstrap 内的 router、Pinia 和身份资源清理。
+ */
+export function createStartupLifecycle(load: () => Promise<{ mount(): Promise<void>; unmount(): void }>) {
+  let generation = 0
+  let current: { unmount(): void } | undefined
+  function unmount(): void {
+    generation++
+    const previous = current
+    current = undefined
+    previous?.unmount()
+  }
+  async function mount(): Promise<void> {
+    unmount()
+    const version = generation
+    let stage: 'load-bootstrap' | 'mount' = 'load-bootstrap'
+    try {
+      const bootstrap = await load()
+      if (generation !== version) return
+      current = bootstrap
+      stage = 'mount'
+      await bootstrap.mount()
+    } catch (error) {
+      if (generation !== version) return
+      unmount()
+      reportError(error)
+      // 仅当前失败轮次可重试；卸载后遗留按钮或旧回调不得重启已释放的应用。
+      const failedVersion = generation
+      showStartupError(error, () => generation === failedVersion ? mount() : Promise.resolve(), stage)
+    }
+  }
+  return { mount, unmount }
+}
+
+/** 独立执行全部清理回调；一个回调失败不能阻断后续凭据撤销或资源释放。 */
+export function cleanupAll(callbacks: readonly (() => void)[]): void {
+  for (const callback of callbacks) {
+    try { callback() } catch (error) { reportError(error) }
+  }
+}

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

@@ -0,0 +1,144 @@
+import { AxiosHttpClient } from '@axewo/fin-core/http/axios'
+import { appConfig, validateAddress } from './appConfig'
+import { toSafeError, reportError } from './errorUtils'
+
+/**
+ * 应用独立的 Axios 请求实例；由 base 生成到基座和子应用，各项目自行定义拦截器。
+ * 仅共享模板与封装实现，不跨应用共享可变配置、请求实例或身份信息。
+ * 默认 /api/ 指向当前应用运行环境解析出的源，嵌入运行也不会自动代理到基座后端。
+ * 部署时须配置真实API网关/开发代理；跨域Cookie须显式启用withCredentials并由后端配置CORS。
+ * 如需Token，通过installRequestTokenProvider每次读取最新值；不要在模块初始化时缓存Token。
+ * 不擅自从window/localStorage读取基座凭据，不硬编码Token，不自动刷新登录或重试写请求。
+ * get/post等返回整个响应体；业务code/data解包和401会话协调由业务层明确实现。
+ * 响应拦截器须返回AxiosResponse，而不是直接返回response.data；错误保持AxiosError/isCancel语义。
+ */
+export const http = new AxiosHttpClient({
+  baseURL: appConfig.apiBase,
+  timeout: appConfig.timeout,
+  withCredentials: appConfig.withCredentials,
+})
+
+/** 按请求读取最新凭据；独立应用可显式安装自己的 provider，基座默认不读取 bridge。 */
+export type RequestTokenProvider = (signal: AbortSignal) => Promise<string | null> | string | null
+interface TokenBinding {
+  provider: RequestTokenProvider
+  api: URL
+  active: boolean
+  pending: Set<AbortController>
+  previous?: TokenBinding
+  begin?: (signal: AbortSignal) => Promise<() => Promise<unknown>>
+}
+const requestFailures = new WeakMap<object, () => Promise<unknown>>()
+/** 失效回调只影响认证；自身失败隔离，不覆盖原始 Axios/SDK 错误。 */
+async function notifyFailure(callback: (() => Promise<unknown>) | undefined): Promise<void> {
+  try { await callback?.() } catch (error) { reportError(error) }
+}
+let tokenBinding: TokenBinding | undefined
+/**
+ * 在应用挂载时安装，卸载必须调用返回的还原函数；同时取消所有尚未完成的凭据读取。
+ * trustedApiBase 是业务明确配置的可信 API 目录（默认当前源 /api/），不是从请求的 baseURL 推断。
+ * 跨源网关必须显式传完整 HTTPS 地址，且与 http 的 baseURL 保持一致。
+ * @param provider 每次读取最新凭据，接收请求取消信号；null 代表 Cookie 模式，不伪造已登录。
+ * @param trustedApiBase 可信 API 目录，必须以 / 结束；SSR 无浏览器来源时只能显式使用绝对 HTTPS 地址。
+ * @returns 幂等释放函数，取消挂起读取并恢复仍有效的前一个绑定，不撤回已发出的网络请求。
+ * @throws 可信地址无效时立即抛错；provider 失败使本次请求拒绝，不降级匿名重发。
+ */
+export function installRequestTokenProvider(provider: RequestTokenProvider, trustedApiBase = appConfig.trustedApiBase,
+  begin?: (signal: AbortSignal) => Promise<() => Promise<unknown>>): () => void {
+  const location = globalThis.location
+  if (!location && !/^https:\/\//i.test(trustedApiBase)) throw new Error('无浏览器来源时必须显式配置绝对 HTTPS API')
+  validateAddress(trustedApiBase)
+  const api = new URL(trustedApiBase, location?.href)
+  if (!['http:', 'https:'].includes(api.protocol) || api.username || api.password || api.search || api.hash || !api.pathname.endsWith('/')) throw new Error('可信 API 必须是 HTTP(S) 目录地址')
+  if (api.protocol !== 'https:' && (!location || api.origin !== location.origin)) throw new Error('跨源可信 API 必须使用 HTTPS')
+  const binding: TokenBinding = { provider, api, begin, active: true, pending: new Set(), previous: tokenBinding }
+  tokenBinding = binding
+  return () => {
+    binding.active = false
+    for (const controller of binding.pending) controller.abort()
+    binding.pending.clear()
+    if (tokenBinding === binding) {
+      tokenBinding = binding.previous
+      while (tokenBinding && !tokenBinding.active) tokenBinding = tokenBinding.previous
+    }
+  }
+}
+
+/**
+ * 应用级请求拦截器：每次请求时处理当前应用的动态配置。
+ * 业务替换点：从应用的身份模块读取最新 Token，按后台协议设置请求头；
+ * 不在这里缓存初始 Token，也不默认读取基座的 window/localStorage 凭据。
+ * 必须返回 config；异常原样拒绝，由调用方继续处理。
+ */
+http.interceptors.request.use(
+  async config => {
+    const binding = tokenBinding
+    if (!binding?.active) return config
+    const origin = globalThis.location?.href
+    if (!origin && !/^https:\/\//i.test(config.baseURL ?? '')) return config
+    const base = new URL(config.baseURL ?? '', origin)
+    const url = config.url ?? ''
+    // 不对绝对 URL、协议相对地址、反斜线或被覆盖的 baseURL 发送任何宿主凭据。
+    // 即使绝对 URL 指向可信源也拒绝自动注入，防止后续调用者无意扩大授权面。
+    if (url.trim() !== url || /[\u0000-\u001f\u007f]/.test(url) || /%(?:2f|5c)/i.test(url) || /^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith('//') || url.includes('\\') || base.href !== binding.api.href) return config
+    const target = new URL(url.replace(/^\/+/, ''), base)
+    if (target.origin !== binding.api.origin || !target.pathname.startsWith(binding.api.pathname)) return config
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+    if (config.signal?.aborted) controller.abort()
+    config.signal?.addEventListener?.('abort', abort)
+    binding.pending.add(controller)
+    try {
+      if (controller.signal.aborted) throw new DOMException('凭据读取已取消', 'AbortError')
+      const failure = await binding.begin?.(controller.signal)
+      if (failure) requestFailures.set(config, async () => { if (binding.active && tokenBinding === binding) await failure() })
+      // Promise 竞速确保不合作的独立 provider 也不会在卸载后继续发送请求。
+      const token = await new Promise<string | null>((resolve, reject) => {
+        const cancelled = () => reject(new DOMException('凭据读取已取消', 'AbortError'))
+        controller.signal.addEventListener('abort', cancelled, { once: true })
+        // 竞速一旦结束立即释放监听，不等待不合作 provider 的底层 Promise。
+        const settle = <T>(callback: (value: T) => void, value: T) => {
+          controller.signal.removeEventListener('abort', cancelled)
+          callback(value)
+        }
+        Promise.resolve().then(() => binding.provider(controller.signal)).then(value => settle(resolve, value), error => settle(reject, error))
+      })
+      if (controller.signal.aborted || !binding.active || tokenBinding !== binding) throw new DOMException('凭据来源已释放', 'AbortError')
+      if (token !== null && (typeof token !== 'string' || !token || token.length > 16384 || /[\s\u0000-\u001f\u007f]/.test(token))) throw new Error('凭据格式无效')
+      // Cookie 模式的 null 不添加头；不缓存凭据，不刷新登录、不自动重试写请求。
+      if (token !== null) config.headers.set('Authorization', `Bearer ${token}`)
+      return config
+    } catch (error) {
+      if (toSafeError(error).kind === 'unauthenticated') await notifyFailure(requestFailures.get(config))
+      requestFailures.delete(config)
+      throw error
+    } finally {
+      binding.pending.delete(controller)
+      config.signal?.removeEventListener?.('abort', abort)
+    }
+  },
+  error => Promise.reject(error),
+)
+
+/**
+ * 应用级响应拦截器：业务码校验、错误提示及 401 会话协调在此按实际协议实现。
+ * 成功分支必须保留完整 AxiosResponse；http.get/post 等已统一返回 response.data，
+ * 此处再次解包会破坏客户端返回契约。业务失败可抛出应用定义的错误。
+ * 错误分支保持拒绝，不能吞掉错误、返回 undefined 或自动重试写请求；
+ * 如需登录失效处理，应协调并发请求，取消请求通常不展示错误提示。
+ */
+http.interceptors.response.use(
+  response => {
+    requestFailures.delete(response.config)
+    return response
+  },
+  async error => {
+    const config = error?.config ?? error?.response?.config
+    if (config && typeof config === 'object') {
+      const callback = requestFailures.get(config)
+      requestFailures.delete(config)
+      if (toSafeError(error).kind === 'unauthenticated') await notifyFailure(callback)
+    }
+    return Promise.reject(error)
+  },
+)

package/scaffold/base/src/views/.gitkeep

@@ -0,0 +1 @@
+# 预留页面业务视图目录；布局与跨页面逻辑分别放入 layout 和 hooks。

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

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

package/scaffold/base/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/scaffold/base/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+// 只引用已发布依赖，不配置指向 monorepo 源码的 alias。
+export default defineConfig({
+  plugins: [vue()],
+  server: { port: __PORT__, strictPort: true, cors: true },
+})

package/scaffold/host/.env.example

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

package/scaffold/host/src/App.vue

@@ -0,0 +1,4 @@
+<script setup lang="ts">
+import AppProviders from './components/AppProviders.vue'
+</script>
+<template><AppProviders><RouterView /></AppProviders></template>

package/scaffold/host/src/bootstrap.ts

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

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

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

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

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