@axewo/fin-micro 0.0.0-stage → 2.0.0

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

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

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

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

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

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

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

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