create-lumal-admin 0.0.5-beta → 0.0.6-beta

package/templates/base/src/app/module.ts

@@ -0,0 +1,46 @@
+import type { LumalMenuRecord } from '@lumal/core/router';
+
+export interface PermissionNode {
+  id: string;
+  label: string;
+  permission?: string;
+  children?: PermissionNode[];
+}
+export interface AppModule {
+  menus: LumalMenuRecord[];
+  views: Record<string, () => Promise<unknown>>;
+  permissions?: PermissionNode[];
+}
+
+export function collectPermissions(nodes: readonly PermissionNode[]): string[] {
+  return [
+    ...new Set(
+      nodes.flatMap((node) => [
+        ...(node.permission ? [node.permission] : []),
+        ...collectPermissions(node.children ?? []),
+      ]),
+    ),
+  ];
+}
+
+export function assembleModules(modules: AppModule[]) {
+  const views: Record<string, () => Promise<unknown>> = Object.create(null);
+  const permissions = modules.flatMap((module) => module.permissions ?? []);
+  for (const module of modules) {
+    for (const [name, loader] of Object.entries(module.views)) {
+      if (
+        ['constructor', '__proto__', 'prototype'].includes(name) ||
+        Object.hasOwn(views, name) ||
+        typeof loader !== 'function'
+      )
+        throw new Error(`模块组件名称重复或无效：${name}`);
+      views[name] = loader;
+    }
+  }
+  return {
+    views,
+    menus: modules.flatMap((module) => module.menus),
+    permissions,
+    permissionCodes: collectPermissions(permissions),
+  };
+}

package/templates/base/src/app/router/index.ts

@@ -0,0 +1,107 @@
+import type { LumalLayoutTabItem } from '@lumal/core/layout';
+import type { SidebarMenuItem } from '@lumal/core/router';
+import type { RouteRecordRaw, RouterHistory } from 'vue-router';
+import { setupPermissionGuard } from '@lumal/core/permission';
+import { createMenuRouteRuntime } from '@lumal/core/router';
+import { shallowRef } from 'vue';
+import { createRouter, createWebHashHistory, createWebHistory } from 'vue-router';
+import { appConfig } from '../../app.config';
+import { resolveView, validateMenus, withAccessibleRedirects } from '../menu-policy';
+import { application, permissionStore } from '../services/session';
+import { viewComponents } from './views';
+
+/***********************路由初始化*********************/
+export const routeError = shallowRef('');
+export function createAdminRouter(history?: RouterHistory) {
+  const targetRouter = createRouter({
+    history:
+      history ??
+      (appConfig.routerMode === 'history'
+        ? createWebHistory(import.meta.env.BASE_URL)
+        : createWebHashHistory(import.meta.env.BASE_URL)),
+    routes: [
+      {
+        path: '/login',
+        name: 'Login',
+        component: () => import('../views/auth/LoginView.vue'),
+        meta: { layout: 'public', requireLogin: false, title: '登录' },
+      },
+      { path: '/', redirect: '/dashboard' },
+      { path: '/403', component: () => import('../views/error/ForbiddenView.vue'), meta: { title: '无权限' } },
+      { path: '/404', component: () => import('../views/error/NotFoundView.vue'), meta: { title: '页面不存在' } },
+      { path: '/:pathMatch(.*)*', name: 'CatchAll', component: () => import('../views/error/NotFoundView.vue') },
+    ],
+  });
+  const runtime = createMenuRouteRuntime({
+    router: {
+      addRoute: (route) => targetRouter.addRoute(route as RouteRecordRaw),
+      getRoutes: () => targetRouter.getRoutes(),
+      hasRoute: (name) => targetRouter.hasRoute(name),
+      removeRoute: (name) => targetRouter.removeRoute(name),
+    },
+    componentResolver: (name) => resolveView(viewComponents, name),
+    hasPermission: (values) => permissionStore.hasPermission(values, 'every'),
+    hasRole: (values) => permissionStore.hasRole(values, 'some'),
+    loadRemoteMenus: async () => {
+      await application.initialize();
+      return withAccessibleRedirects(validateMenus(application.menus.value, viewComponents), {
+        permissions: permissionStore.permissions,
+        roles: permissionStore.roles,
+      });
+    },
+  });
+  application.onReset((expired) => {
+    runtime.resetRemote();
+    if (expired && targetRouter.currentRoute.value.path !== '/login')
+      void targetRouter.replace({ path: '/login', query: { redirect: targetRouter.currentRoute.value.fullPath } });
+  });
+  const navigationVersion = shallowRef(0);
+  application.onRefresh(async () => {
+    await runtime.reload();
+    navigationVersion.value += 1;
+    await targetRouter.replace(targetRouter.currentRoute.value.fullPath);
+  });
+
+  targetRouter.beforeEach(async (to) => {
+    if (!application.isAuthenticated())
+      return to.path === '/login' ? true : { path: '/login', query: { redirect: to.fullPath } };
+    const rematch = !runtime.remoteLoaded;
+    try {
+      await runtime.loadRemote();
+      routeError.value = '';
+    } catch (reason) {
+      routeError.value = reason instanceof Error ? reason.message : '菜单加载失败';
+      application.reset();
+      return { path: '/login', query: { redirect: to.fullPath } };
+    }
+    if (to.path === '/login' || to.path === '/') return runtime.firstAccessiblePath || '/403';
+    if (rematch) return to.fullPath;
+    return to.name === 'CatchAll' ? '/404' : true;
+  });
+  setupPermissionGuard(targetRouter, permissionStore, {
+    isAuthenticated: application.isAuthenticated,
+    mode: 'every',
+    roleMode: 'some',
+    requireLoginByDefault: true,
+    noAccessRedirect: '/403',
+  });
+  return { router: targetRouter, runtime, navigationVersion };
+}
+
+const { router, runtime, navigationVersion } = createAdminRouter();
+export { router };
+export function createAdminSidebarMenus(): SidebarMenuItem[] {
+  void navigationVersion.value;
+  // ready 使非响应式菜单运行时在退出和初始化完成后重新计算。
+  return application.ready.value ? runtime.sidebarMenus : [];
+}
+export function createAdminTabs(): LumalLayoutTabItem[] {
+  return runtime.routes
+    .filter(
+      (route) =>
+        route.meta.affixTab === true &&
+        permissionStore.hasPermission(route.meta.permissions, 'every') &&
+        permissionStore.hasRole(route.meta.roles, 'some'),
+    )
+    .map((route) => ({ path: route.path, title: route.meta.title, closable: false }));
+}

package/templates/base/src/app/router/views.ts

@@ -0,0 +1,12 @@
+import type { AppModule } from '../module';
+import { assembleModules } from '../module';
+
+// 只加载元数据，页面仍以动态 import 分包；业务子模块无需修改中心注册文件。
+const modules = import.meta.glob<AppModule>(['../../modules/*/module.ts', '../../modules/business/*/module.ts'], {
+  eager: true,
+});
+const assembled = assembleModules(Object.values(modules));
+export const localMenus = assembled.menus;
+export const viewComponents = { ...assembled.views, 'app/iframe': () => import('../views/SafeIframeView.vue') };
+export const permissionTree = assembled.permissions;
+export const permissionCodes = assembled.permissionCodes;

package/templates/base/src/{services → app/services}/access.ts

@@ -1,2 +1,2 @@
 // 单一权限 Store，由实际会话响应填充，不能持久化演示权限。
-export { permissionStore } from './session'
+export { permissionStore } from './session';

package/templates/base/src/app/services/contracts.ts

@@ -0,0 +1,54 @@
+import type { AuthSessionData } from '@lumal/core/auth';
+import type { LumalMenuRecord } from '@lumal/core/router';
+
+export interface LoginInput {
+  username: string;
+  password: string;
+}
+export interface CurrentUser {
+  id: string;
+  name: string;
+  username: string;
+}
+export interface AccessSnapshot {
+  permissions: string[];
+  roles: string[];
+}
+export type DataRow = Record<string, unknown>;
+export interface ListInput {
+  page: number;
+  pageSize: number;
+  query: DataRow;
+}
+export interface PageResult<T = DataRow> {
+  items: T[];
+  total: number;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface BusinessRequest {
+  body?: object;
+  query?: Record<string, string | number | boolean | undefined>;
+}
+export interface BusinessTransport {
+  request: <T>(method: HttpMethod, path: string, input?: BusinessRequest) => Promise<T>;
+}
+
+// 应用协议由 Local/HTTP 共同实现，后端包装和字段转换不进入 Core。
+export interface ApplicationService extends BusinessTransport {
+  login: (input: LoginInput, signal: AbortSignal) => Promise<AuthSessionData>;
+  getUser: (signal: AbortSignal) => Promise<CurrentUser>;
+  getAccess: (signal: AbortSignal) => Promise<AccessSnapshot>;
+  getMenus: (signal: AbortSignal) => Promise<LumalMenuRecord[]>;
+  logout: (accessToken: string) => Promise<void>;
+  clearCache: () => void;
+  list: (resource: string, input: ListInput) => Promise<PageResult>;
+  save: (resource: string, model: DataRow, id?: string) => Promise<unknown>;
+  remove: (resource: string, id: string) => Promise<void>;
+}
+
+export interface ServiceContext {
+  getSession: () => AuthSessionData | null;
+  getSignal: () => AbortSignal;
+  setSession: (value: AuthSessionData) => void;
+  expire: () => Promise<void>;
+}

package/templates/base/src/app/services/local-contracts.ts

@@ -0,0 +1,18 @@
+import type { BusinessRequest, CurrentUser, DataRow, HttpMethod } from './contracts';
+
+export interface LocalDatabase {
+  read: <T extends DataRow = DataRow>(resource: string, initial?: () => T[]) => T[];
+  write: <T extends DataRow>(resource: string, rows: T[]) => void;
+}
+export interface LocalBusinessContext {
+  db: LocalDatabase;
+  user: () => CurrentUser;
+  assertPermission: (code: string) => void;
+}
+export interface LocalHandler {
+  handles: (path: string) => boolean;
+  request: (method: HttpMethod, path: string, input: BusinessRequest) => Promise<unknown>;
+}
+export interface LocalModule {
+  createLocalHandler: (context: LocalBusinessContext) => LocalHandler;
+}

package/templates/base/src/{services → app/services}/preferences.ts

@@ -1,6 +1,6 @@
-import type { LumalPreferencesDefaults } from '@lumal/core/theme'
-import { createPreferencesStore } from '@lumal/core/theme'
-import { appConfig } from '../app.config'
+import type { LumalPreferencesDefaults } from '@lumal/core/theme';
+import { createPreferencesStore } from '@lumal/core/theme';
+import { appConfig } from '../../app.config';
 
 export const adminPreferenceDefaults = {
   app: { dynamicTitle: true, layout: 'sidebar-nav' },
@@ -25,17 +25,17 @@ export const adminPreferenceDefaults = {
   },
   theme: { fontSize: 14 },
   transition: { enable: true, name: 'fade-side' },
-} satisfies LumalPreferencesDefaults
+} satisfies LumalPreferencesDefaults;
 
 const preferencesStore = createPreferencesStore({
   defaults: adminPreferenceDefaults,
   storage: localStorage,
   storageKey: 'lumal-admin:preferences',
-})
+});
 
-export const adminPreferences = preferencesStore.state
-export const adminResolvedThemeMode = preferencesStore.resolvedThemeMode
+export const adminPreferences = preferencesStore.state;
+export const adminResolvedThemeMode = preferencesStore.resolvedThemeMode;
 
 export function patchAdminPreferences(preferences: Parameters<typeof preferencesStore.patch>[0]): void {
-  preferencesStore.patch(preferences)
+  preferencesStore.patch(preferences);
 }

package/templates/base/src/app/services/session-runtime.ts

@@ -0,0 +1,186 @@
+import type { LumalMenuRecord } from '@lumal/core/router';
+import type { ApplicationService, CurrentUser, LoginInput, ServiceContext } from './contracts';
+import { createAuthSession } from '@lumal/core/auth';
+import { createPermissionStore } from '@lumal/core/permission';
+import { readonly, shallowRef } from 'vue';
+
+export function createApplicationSession(
+  createService: (context: ServiceContext) => ApplicationService,
+  storage: Storage,
+  tabStorage?: Storage,
+) {
+  const permissionStore = createPermissionStore();
+  const user = shallowRef<CurrentUser | null>(null);
+  const menus = shallowRef<LumalMenuRecord[]>([]);
+  const ready = shallowRef(false);
+  const accessVersion = shallowRef(0);
+  const error = shallowRef('');
+  const resetHandlers = new Set<(expired: boolean) => void>();
+  const refreshHandlers = new Set<() => void | Promise<void>>();
+  const tabStorageKey = 'lumal-admin:tabs';
+  let generation = 0;
+  let controller = new AbortController();
+  let initializing: Promise<void> | undefined;
+  let refreshing: Promise<void> | undefined;
+  const session = createAuthSession({ storage, tokenKey: 'lumal-admin:session' });
+  let service: ApplicationService;
+
+  function reset(expired = false): void {
+    generation += 1;
+    controller.abort();
+    controller = new AbortController();
+    initializing = undefined;
+    refreshing = undefined;
+    accessVersion.value += 1;
+    ready.value = false;
+    user.value = null;
+    menus.value = [];
+    permissionStore.clear();
+    session.clearToken();
+    service.clearCache();
+    tabStorage?.removeItem(tabStorageKey);
+    resetHandlers.forEach((handler) => handler(expired));
+  }
+
+  service = createService({
+    getSession: session.getSession,
+    getSignal: () => controller.signal,
+    setSession: session.setSession,
+    expire: async () => reset(true),
+  });
+
+  /***********************会话初始化与隔离*********************/
+  function initialize(): Promise<void> {
+    if (ready.value || !session.isAuthenticated()) return Promise.resolve();
+    if (initializing) return initializing;
+    const version = generation;
+    const signal = controller.signal;
+    const pending = (async () => {
+      try {
+        const [nextUser, access, nextMenus] = await Promise.all([
+          service.getUser(signal),
+          service.getAccess(signal),
+          service.getMenus(signal),
+        ]);
+        signal.throwIfAborted();
+        if (version !== generation) throw new Error('会话已切换');
+        user.value = nextUser;
+        permissionStore.setPermissions(access.permissions);
+        permissionStore.setRoles(access.roles);
+        menus.value = nextMenus;
+        ready.value = true;
+        error.value = '';
+      } catch (reason) {
+        if (version === generation) {
+          reset();
+          error.value = reason instanceof Error ? reason.message : '会话初始化失败';
+        }
+        throw reason;
+      }
+    })();
+    initializing = pending;
+    void pending
+      .finally(() => {
+        if (initializing === pending) initializing = undefined;
+      })
+      .catch(() => {}); // 原始 Promise 仍向调用方传播异常，只消费 finally 分支。
+    return pending;
+  }
+
+  async function login(input: LoginInput): Promise<void> {
+    reset();
+    const version = generation;
+    const signal = controller.signal;
+    error.value = '';
+    try {
+      const result = await service.login(input, signal);
+      signal.throwIfAborted();
+      if (version !== generation) throw new Error('会话已切换');
+      session.setSession(result);
+      await initialize();
+    } catch (reason) {
+      if (version === generation) {
+        reset();
+        error.value = reason instanceof Error ? reason.message : '登录失败';
+      }
+      throw reason;
+    }
+  }
+
+  async function logout(): Promise<void> {
+    const token = session.getToken();
+    reset();
+    // 即使远端撤销失败，本地状态也已清理；错误交由界面反馈。
+    if (token) await service.logout(token);
+  }
+
+  function refreshAccess(): Promise<void> {
+    if (refreshing) return refreshing;
+    if (!session.isAuthenticated()) return Promise.reject(new Error('会话已失效，请重新登录'));
+    const version = generation;
+    const refreshController = new AbortController();
+    const signal = AbortSignal.any([controller.signal, refreshController.signal]);
+    const pending = (async () => {
+      const reads = [service.getUser(signal), service.getAccess(signal), service.getMenus(signal)] as const;
+      try {
+        const [nextUser, access, nextMenus] = await Promise.all(reads);
+        signal.throwIfAborted();
+        if (version !== generation) throw new Error('会话已切换');
+        user.value = nextUser;
+        permissionStore.setPermissions(access.permissions);
+        permissionStore.setRoles(access.roles);
+        menus.value = nextMenus;
+        ready.value = true;
+        await Promise.all([...refreshHandlers].map((handler) => handler()));
+        accessVersion.value += 1;
+        tabStorage?.removeItem(tabStorageKey);
+      } catch (reason) {
+        // 一个读取失败后取消其余请求并等待释放去重占位，立即重试不会撞上旧请求。
+        refreshController.abort(reason);
+        await Promise.allSettled(reads);
+        if (version === generation) {
+          // 重读失败时拒绝继续使用旧授权；保留 Token 以便显式重试。
+          permissionStore.clear();
+          menus.value = [];
+          ready.value = false;
+          tabStorage?.removeItem(tabStorageKey);
+          resetHandlers.forEach((handler) => handler(false));
+        }
+        throw reason;
+      }
+    })();
+    refreshing = pending;
+    void pending
+      .finally(() => {
+        if (refreshing === pending) refreshing = undefined;
+      })
+      .catch(() => {});
+    return pending;
+  }
+
+  return {
+    currentUser: readonly(user),
+    error: readonly(error),
+    menus: readonly(menus),
+    ready: readonly(ready),
+    accessVersion: readonly(accessVersion),
+    permissionStore,
+    session,
+    service,
+    tabStorageKey,
+    initialize,
+    isAuthenticated: session.isAuthenticated,
+    login,
+    logout,
+    reset,
+    refreshAccess,
+    onRefresh(handler: () => void | Promise<void>) {
+      refreshHandlers.add(handler);
+      return () => refreshHandlers.delete(handler);
+    },
+    onReset(handler: (expired: boolean) => void) {
+      resetHandlers.add(handler);
+      return () => resetHandlers.delete(handler);
+    },
+  };
+}

package/templates/base/src/{services → app/services}/session.ts

@@ -1,7 +1,7 @@
-import { createBackend } from './data-source'
-import { createApplicationSession } from './session-runtime'
+import { createBackend } from './data-source';
+import { createApplicationSession } from './session-runtime';
 
-export const application = createApplicationSession(createBackend, localStorage, sessionStorage)
+export const application = createApplicationSession(createBackend, localStorage, sessionStorage);
 export const {
   currentUser,
   initialize,
@@ -11,4 +11,4 @@ export const {
   permissionStore,
   service,
   tabStorageKey: adminTabSnapshotStorageKey,
-} = application
+} = application;

package/templates/base/src/app/stored-menus.ts

@@ -0,0 +1,72 @@
+import type { LumalMenuRecord } from '@lumal/core/router';
+import type { DataRow } from './services/contracts';
+import { assertHierarchy } from '../shared/tree';
+import { safeExternalUrl, stringArray, validateMenus } from './menu-policy';
+
+export function seedMenuRows(menus: LumalMenuRecord[], parentId = ''): DataRow[] {
+  return menus.flatMap((menu) => [
+    {
+      id: menu.name ?? menu.path,
+      parentId,
+      path: menu.path,
+      name: menu.name ?? menu.path,
+      type: menu.component ? 'menu' : 'directory',
+      title: String(menu.meta?.title ?? menu.name),
+      component: menu.component ?? '',
+      icon: menu.meta?.icon ?? '',
+      order: menu.meta?.order ?? 0,
+      hidden: menu.meta?.hideInMenu === true,
+      permissions: typeof menu.meta?.authority === 'string' ? [menu.meta.authority] : (menu.meta?.authority ?? []),
+      roles: typeof menu.meta?.roles === 'string' ? [menu.meta.roles] : (menu.meta?.roles ?? []),
+      keepAlive: menu.meta?.keepAlive !== false,
+      hideInTab: menu.meta?.hideInTab === true,
+      externalLink: '',
+    },
+    ...seedMenuRows(menu.children ?? [], menu.name ?? menu.path),
+  ]);
+}
+export function buildStoredMenus(rows: DataRow[], views: Record<string, () => Promise<unknown>>): LumalMenuRecord[] {
+  const items = rows.map((row): DataRow & { id: string; parentId: string } => ({
+    ...row,
+    id: String(row.id),
+    parentId: String(row.parentId ?? ''),
+  }));
+  assertHierarchy(items);
+  for (const row of items) {
+    const parent = items.find((item) => item.id === row.parentId);
+    if (parent && !['directory', 'menu'].includes(String(parent.type))) throw new Error('只有目录和菜单可以包含子节点');
+  }
+  function visit(parentId = ''): LumalMenuRecord[] {
+    return items
+      .filter((row) => row.parentId === parentId && row.type !== 'button')
+      .sort((a, b) => Number(a.order ?? 0) - Number(b.order ?? 0))
+      .map((row) => ({
+        path: String(row.path),
+        name: String(row.name),
+        component: ['directory', 'external'].includes(String(row.type)) ? undefined : String(row.component),
+        meta: {
+          title: String(row.title),
+          order: Number(row.order ?? 0),
+          icon: String(row.icon ?? ''),
+          hideInMenu: row.hidden === true,
+          keepAlive: row.keepAlive !== false,
+          hideInTab: row.hideInTab === true,
+          affixTab: row.path === '/dashboard',
+          authority: stringArray(row.permissions ?? []),
+          roles: stringArray(row.roles ?? []),
+          ...(row.type === 'external'
+            ? { externalLink: safeExternalUrl(row.externalLink), externalTarget: '_blank' }
+            : {}),
+          ...(row.type === 'embedded' ? { iframeSrc: safeExternalUrl(row.externalLink) } : {}),
+        },
+        children: visit(row.id),
+      }));
+  }
+  // 空目录允许先保存；隐藏该目录，直到存在可访问的页面。
+  const prune = (menus: LumalMenuRecord[]): LumalMenuRecord[] =>
+    menus.flatMap((menu) => {
+      const children = prune(menu.children ?? []);
+      return !menu.component && !menu.meta?.externalLink && !children.length ? [] : [{ ...menu, children }];
+    });
+  return validateMenus(prune(visit()), views);
+}

package/templates/base/src/app/views/SafeIframeView.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useRoute } from 'vue-router';
+import { safeExternalUrl } from '../menu-policy';
+
+/***********************独立 iframe 来源校验*********************/
+const route = useRoute();
+const src = computed(() => {
+  const value = safeExternalUrl(route.meta.iframeSrc);
+  const allowed = String(import.meta.env.VITE_IFRAME_ORIGINS ?? '')
+    .split(',')
+    .map((item) => item.trim());
+  if (!allowed.includes(new URL(value).origin)) throw new Error('iframe 来源未获授权');
+  return value;
+});
+</script>
+
+<template>
+  <iframe
+    class="app-iframe"
+    :src="src"
+    :title="String(route.meta.title ?? '内嵌页面')"
+    sandbox="allow-scripts allow-forms"
+    referrerpolicy="no-referrer"
+  />
+</template>
+
+<style scoped>
+.app-iframe {
+  width: 100%;
+  height: calc(100dvh - 160px);
+  border: 0;
+}
+</style>