create-lumal-admin 0.0.4-beta → 0.0.6-beta

package/templates/base/src/App.vue

@@ -0,0 +1,206 @@
+<script setup lang="ts">
+import type { LumalLayoutTabItem } from '@lumal/core/layout';
+import type { LumalPreferences } from '@lumal/core/theme';
+import type { RouteLocationNormalizedLoaded } from 'vue-router';
+import { findMenuItemByPath, LumalLayout, LumalRouterView } from '@lumal/core/layout';
+import { ElAlert, ElConfigProvider, ElMessage } from 'element-plus';
+import zhCn from 'element-plus/es/locale/lang/zh-cn';
+import { computed, defineAsyncComponent, onErrorCaptured, reactive, shallowRef, watch } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { appConfig } from './app.config';
+import AppHeaderActions from './app/components/AppHeaderActions.vue';
+import { safeExternalUrl } from './app/menu-policy';
+import { createAdminSidebarMenus, createAdminTabs } from './app/router';
+import {
+  adminPreferenceDefaults,
+  adminPreferences,
+  adminResolvedThemeMode,
+  patchAdminPreferences,
+} from './app/services/preferences';
+import { adminTabSnapshotStorageKey, application, currentUser, logout } from './app/services/session';
+
+/***********************页面状态*********************/
+const AppSettingsDrawer = defineAsyncComponent(() => import('./app/components/AppSettingsDrawer.vue'));
+const title = appConfig.title;
+const settingsVisible = shallowRef(false);
+const pageError = shallowRef('');
+const routeRefreshKeys = reactive<Record<string, number>>({});
+onErrorCaptured((error) => {
+  pageError.value = error.message;
+  return false;
+});
+
+/***********************路由状态*********************/
+const route = useRoute();
+const router = useRouter();
+const isPublicLayout = computed(() => route.meta.layout === 'public');
+const allMenus = computed(() => createAdminSidebarMenus());
+const fixedTabs = computed<LumalLayoutTabItem[]>(() => createAdminTabs());
+// 标签和视图使用相同的 path/version 身份，刷新只替换当前标签的缓存。
+function resolveRouteViewKey(path: string): string {
+  return `${path}:${routeRefreshKeys[path] ?? 0}`;
+}
+const routeViewKey = computed(() => resolveRouteViewKey(route.path));
+const routeViewCache = computed(() => adminPreferences.value.tabbar.enable && adminPreferences.value.tabbar.cache);
+const activePath = computed({
+  get: () => route.path,
+  set: (path: string) => {
+    if (path !== route.path) {
+      void router.push(path);
+    }
+  },
+});
+
+watch(
+  [() => route.meta.title, () => adminPreferences.value.app.dynamicTitle],
+  () => {
+    const routeTitle = typeof route.meta.title === 'string' ? route.meta.title.trim() : '';
+    document.title = adminPreferences.value.app.dynamicTitle && routeTitle ? `${routeTitle} - ${title}` : title;
+  },
+  { immediate: true },
+);
+
+/***********************导航事件*********************/
+function handleMenuSelect(path: string): void {
+  const item = findMenuItemByPath(allMenus.value, path);
+
+  if (item?.externalLink) {
+    const url = safeExternalUrl(item.externalLink);
+    if (item.externalTarget === '_self') window.location.assign(url);
+    else window.open(url, '_blank', 'noopener,noreferrer');
+    return;
+  }
+
+  activePath.value = path;
+}
+
+function handleToggleSidebar(): void {
+  patchAdminPreferences({
+    sidebar: { collapsed: !adminPreferences.value.sidebar.collapsed },
+  });
+}
+
+function handleTabChange(path: string): void {
+  activePath.value = path;
+}
+
+function resolveAdminRouteTab(currentRoute: RouteLocationNormalizedLoaded): LumalLayoutTabItem | undefined {
+  if (currentRoute.meta.layout === 'public' || currentRoute.meta.hideInTab === true) {
+    return undefined;
+  }
+
+  const menu = findMenuItemByPath(allMenus.value, currentRoute.path);
+  const tabTitle = menu?.title ?? (typeof currentRoute.meta.title === 'string' ? currentRoute.meta.title : undefined);
+
+  if (!tabTitle) {
+    return undefined;
+  }
+
+  return {
+    closable: !['/403', '/404'].includes(currentRoute.path),
+    icon: menu?.icon ?? (typeof currentRoute.meta.icon === 'string' ? currentRoute.meta.icon : undefined),
+    path: currentRoute.path,
+    title: tabTitle,
+  };
+}
+
+async function handleTabRefresh(path: string): Promise<void> {
+  if (path !== route.path) {
+    await router.push(path);
+  }
+
+  routeRefreshKeys[path] = (routeRefreshKeys[path] ?? 0) + 1;
+}
+
+function handleTabsChange(tabs: LumalLayoutTabItem[]): void {
+  const paths = new Set(tabs.map((tab) => tab.path));
+  for (const path of Object.keys(routeRefreshKeys)) {
+    if (!paths.has(path)) delete routeRefreshKeys[path];
+  }
+}
+
+function handlePreferencesChange(preferences: LumalPreferences): void {
+  patchAdminPreferences(preferences);
+}
+
+function toggleTheme(): void {
+  patchAdminPreferences({
+    theme: {
+      mode: adminResolvedThemeMode.value === 'dark' ? 'light' : 'dark',
+    },
+  });
+}
+
+async function handleLogout(): Promise<void> {
+  try {
+    await logout();
+  } catch (error) {
+    ElMessage.warning(error instanceof Error ? error.message : '远端退出失败，本地会话已清理');
+  } finally {
+    pageError.value = '';
+    await router.replace('/login');
+  }
+}
+</script>
+
+<template>
+  <ElConfigProvider :locale="zhCn">
+    <LumalRouterView v-if="isPublicLayout" :view-key="routeViewKey" transition transition-name="fade" />
+
+    <LumalLayout
+      v-else
+      :key="`${currentUser?.username}:${application.accessVersion.value}`"
+      v-model:active-tab-path="activePath"
+      :title="title"
+      :menus="allMenus"
+      :preferences="adminPreferences"
+      route-driven
+      :fixed-tabs="fixedTabs"
+      :route-tab-resolver="resolveAdminRouteTab"
+      tab-fallback-path="/dashboard"
+      :tab-storage-key="currentUser ? adminTabSnapshotStorageKey : ''"
+      :active-menu-path="activePath"
+      @menu-select="handleMenuSelect"
+      @toggle-sidebar="handleToggleSidebar"
+      @tab-change="handleTabChange"
+      @tab-refresh="handleTabRefresh"
+      @tabs-change="handleTabsChange"
+    >
+      <template #headerActions>
+        <AppHeaderActions
+          :resolved-theme-mode="adminResolvedThemeMode"
+          :user-name="currentUser?.name"
+          :has-profile="router.hasRoute('Profile')"
+          @open-profile="router.push('/profile')"
+          @logout="handleLogout"
+          @open-settings="settingsVisible = true"
+          @toggle-theme="toggleTheme"
+        />
+      </template>
+
+      <template #default="{ tabs }">
+        <ElAlert v-if="pageError" :title="pageError" type="error" role="alert" closable @close="pageError = ''" />
+        <LumalRouterView
+          :view-key="routeViewKey"
+          :cache-keys="tabs.map((tab: LumalLayoutTabItem) => resolveRouteViewKey(tab.path))"
+          :progress="adminPreferences.transition.progress"
+          :loading="adminPreferences.transition.loading"
+          :cache="routeViewCache"
+          :cache-max="adminPreferences.tabbar.maxCount"
+          :transition="adminPreferences.transition.enable"
+          :transition-name="adminPreferences.transition.name"
+        />
+      </template>
+    </LumalLayout>
+
+    <AppSettingsDrawer
+      v-if="settingsVisible"
+      v-model:visible="settingsVisible"
+      :defaults="adminPreferenceDefaults"
+      :preferences="adminPreferences"
+      @change="handlePreferencesChange"
+      @reset="handlePreferencesChange"
+      @update:preferences="handlePreferencesChange"
+    />
+  </ElConfigProvider>
+</template>

package/templates/base/src/app/components/AppHeaderActions.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import type { ResolvedThemeMode } from '@lumal/core/theme';
+import { LumalIcon } from '@lumal/icons-vue';
+import { ElButton } from 'element-plus';
+
+/***********************头部操作契约*********************/
+withDefaults(
+  defineProps<{
+    resolvedThemeMode: ResolvedThemeMode;
+    userName?: string;
+    hasProfile?: boolean;
+  }>(),
+  {
+    userName: '管理员',
+  },
+);
+
+defineEmits<{
+  logout: [];
+  openSettings: [];
+  toggleTheme: [];
+  openProfile: [];
+}>();
+</script>
+
+<template>
+  <div class="lumal-admin-header-actions">
+    <ElButton
+      text
+      :title="resolvedThemeMode === 'dark' ? '切换浅色模式' : '切换深色模式'"
+      :aria-label="resolvedThemeMode === 'dark' ? '切换浅色模式' : '切换深色模式'"
+      @click="$emit('toggleTheme')"
+    >
+      <LumalIcon :name="resolvedThemeMode === 'dark' ? 'lumal:sun' : 'lumal:moon'" />
+    </ElButton>
+    <ElButton text title="偏好设置" aria-label="偏好设置" @click="$emit('openSettings')">
+      <LumalIcon name="lumal:settings" />
+    </ElButton>
+    <ElButton v-if="hasProfile" text :title="userName" aria-label="个人中心" @click="$emit('openProfile')">
+      <LumalIcon name="lumal:user" />
+      <span class="lumal-admin-header-actions__user">{{ userName }}</span>
+    </ElButton>
+    <span v-else class="lumal-admin-header-actions__user">{{ userName }}</span>
+    <ElButton text aria-label="退出登录" @click="$emit('logout')"> 退出 </ElButton>
+  </div>
+</template>

package/templates/base/src/app/components/AppSettingsDrawer.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import type { LumalPreferences, LumalPreferencesDefaults } from '@lumal/core/theme';
+import { LumalThemeSettingsPanel } from '@lumal/core/theme';
+import { ElDrawer } from 'element-plus';
+import { computed } from 'vue';
+
+/***********************偏好设置抽屉*********************/
+const props = defineProps<{
+  defaults: LumalPreferencesDefaults;
+  preferences: LumalPreferences;
+  visible: boolean;
+}>();
+
+const emit = defineEmits<{
+  change: [preferences: LumalPreferences];
+  reset: [preferences: LumalPreferences];
+  'update:preferences': [preferences: LumalPreferences];
+  'update:visible': [visible: boolean];
+}>();
+
+const visible = computed({
+  get: () => props.visible,
+  set: (value) => emit('update:visible', value),
+});
+</script>
+
+<template>
+  <ElDrawer v-model="visible" title="偏好设置" size="384px" append-to-body>
+    <LumalThemeSettingsPanel
+      :defaults="defaults"
+      :preferences="preferences"
+      @change="$emit('change', $event)"
+      @reset="$emit('reset', $event)"
+      @update:preferences="$emit('update:preferences', $event)"
+    />
+  </ElDrawer>
+</template>

package/templates/base/src/app/menu-policy.ts

@@ -0,0 +1,163 @@
+import type { LumalMenuRecord, LumalRouteMeta } from '@lumal/core/router';
+import type { AccessSnapshot } from './services/contracts';
+
+const dangerousKeys = new Set(['constructor', '__proto__', 'prototype']);
+const reservedPaths = new Set(['/', '/login', '/403', '/404']);
+
+export function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('响应必须是对象');
+  return value as Record<string, unknown>;
+}
+
+export function stringArray(value: unknown): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.some((item) => typeof item !== 'string' || !item.trim() || item !== item.trim() || dangerousKeys.has(item))
+  )
+    throw new Error('角色和权限必须是有效的字符串数组');
+  return [...new Set(value)] as string[];
+}
+
+export function safeExternalUrl(value: unknown): string {
+  if (
+    typeof value !== 'string' ||
+    value !== value.trim() ||
+    !/^https?:\/\/[^/\\]/i.test(value) ||
+    /[\p{Cc}\s\\]/u.test(value)
+  )
+    throw new Error('外链仅支持明确的 HTTP(S) 绝对地址');
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password)
+    throw new Error('外链地址格式不安全');
+  return url.href;
+}
+
+export function isInternalLocation(value: unknown): value is string {
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || /[\\\p{Cc}\s]/u.test(value))
+    return false;
+  const path = value.split(/[?#]/)[0]!;
+  return !/%|:|\/\/|(?:^|\/)\.\.?(?:\/|$)/.test(path);
+}
+
+export function assertRoutePath(value: unknown): asserts value is string {
+  if (!isInternalLocation(value) || /[?#]/.test(value) || reservedPaths.has(value))
+    throw new Error(`菜单 path 必须是非保留的站内绝对路径：${String(value)}`);
+}
+
+export function resolveView(
+  views: Record<string, () => Promise<unknown>>,
+  key: unknown,
+): (() => Promise<unknown>) | undefined {
+  return typeof key === 'string' &&
+    !dangerousKeys.has(key) &&
+    Object.hasOwn(views, key) &&
+    typeof views[key] === 'function'
+    ? views[key]
+    : undefined;
+}
+
+/** 不直接透传远程 meta；后端数据不能关闭登录检查或绕开权限守卫。 */
+export function validateMenus(value: unknown, views: Record<string, () => Promise<unknown>>): LumalMenuRecord[] {
+  const seen = new WeakSet<object>();
+  const paths = new Set<string>();
+  const names = new Set<string>();
+  let count = 0;
+  function visit(items: unknown, parent = '', depth = 0): LumalMenuRecord[] {
+    if (!Array.isArray(items) || depth > 30) throw new Error('菜单响应必须是有限层级的数组');
+    return items.map((item) => {
+      const raw = object(item);
+      if (++count > 1000 || seen.has(raw)) throw new Error('菜单存在循环或超过数量限制');
+      seen.add(raw);
+      assertRoutePath(raw.path);
+      if (parent && !raw.path.startsWith(`${parent}/`)) throw new Error('子路由必须属于父级绝对路径');
+      if (typeof raw.name !== 'string' || !raw.name.trim() || dangerousKeys.has(raw.name))
+        throw new Error('菜单 name 必须是安全的非空字符串');
+      if (paths.has(raw.path) || names.has(raw.name)) throw new Error('菜单路径或名称重复');
+      paths.add(raw.path);
+      names.add(raw.name);
+      const component = raw.component === '' || raw.component == null ? undefined : raw.component;
+      if (component !== undefined && !resolveView(views, component))
+        throw new Error(`菜单组件不在白名单中：${String(component)}`);
+      const source = raw.meta === undefined ? {} : object(raw.meta);
+      const authority =
+        source.authority === undefined
+          ? []
+          : stringArray(typeof source.authority === 'string' ? [source.authority] : source.authority);
+      const roles =
+        source.roles === undefined ? [] : stringArray(typeof source.roles === 'string' ? [source.roles] : source.roles);
+      const meta: LumalRouteMeta = { authority, roles };
+      for (const key of ['title', 'icon', 'activeMenu'] as const) {
+        if (source[key] !== undefined && typeof source[key] !== 'string') throw new Error(`菜单 ${key} 必须是字符串`);
+        if (typeof source[key] === 'string') meta[key] = source[key];
+      }
+      if (meta.activeMenu && !isInternalLocation(meta.activeMenu)) throw new Error('激活菜单必须是站内路径');
+      for (const key of ['hideInMenu', 'hideInBreadcrumb', 'hideInTab', 'keepAlive', 'affixTab', 'topMenu'] as const) {
+        if (source[key] !== undefined && typeof source[key] !== 'boolean') throw new Error(`菜单 ${key} 必须是布尔值`);
+        if (source[key] !== undefined) meta[key] = source[key];
+      }
+      if (source.order !== undefined) {
+        if (typeof source.order !== 'number' || !Number.isFinite(source.order))
+          throw new Error('菜单排序必须是有限数字');
+        meta.order = source.order;
+      }
+      const external = raw.externalLink ?? source.externalLink;
+      if (external !== undefined && external !== '') {
+        meta.externalLink = safeExternalUrl(external);
+        meta.externalTarget = source.externalTarget === '_self' ? '_self' : '_blank';
+      }
+      // iframe 使用单独的本地组件和构建时来源白名单，不能使用任意页面加载器。
+      if (source.iframeSrc !== undefined) {
+        const src = safeExternalUrl(source.iframeSrc);
+        const allowed = String(import.meta.env.VITE_IFRAME_ORIGINS ?? '')
+          .split(',')
+          .map((item) => item.trim())
+          .filter(Boolean);
+        if (component !== 'app/iframe' || !allowed.includes(new URL(src).origin))
+          throw new Error('iframe 组件或来源不在独立白名单中');
+        meta.iframeSrc = src;
+      }
+      if (raw.redirect !== undefined && !isInternalLocation(raw.redirect)) throw new Error('菜单重定向必须是站内路径');
+      return {
+        path: raw.path,
+        name: raw.name,
+        component: component as string | undefined,
+        redirect: typeof raw.redirect === 'string' ? raw.redirect : undefined,
+        meta,
+        children: raw.children === undefined ? undefined : visit(raw.children, raw.path, depth + 1),
+      };
+    });
+  }
+  return visit(value);
+}
+
+/** 保留未授权路由供守卫返回 403，目录只重定向到当前身份可访问的后代。 */
+export function withAccessibleRedirects(menus: LumalMenuRecord[], access: AccessSnapshot): LumalMenuRecord[] {
+  const can = (menu: LumalMenuRecord) => {
+    const permissions = menu.meta?.authority;
+    const roles = menu.meta?.roles;
+    const required = typeof permissions === 'string' ? [permissions] : (permissions ?? []);
+    const roleCodes = typeof roles === 'string' ? [roles] : (roles ?? []);
+    return (
+      required.every((code) => access.permissions.includes(code)) &&
+      (!roleCodes.length || roleCodes.some((role) => access.roles.includes(role)))
+    );
+  };
+  function first(items: LumalMenuRecord[]): string | undefined {
+    for (const item of items) {
+      if (!can(item) || item.meta?.hideInMenu || item.meta?.externalLink) continue;
+      const target = first(item.children ?? []);
+      if (target) return target;
+      if (item.component && !item.children?.length) return item.path;
+    }
+  }
+  return menus.map((menu) => {
+    const children = withAccessibleRedirects(menu.children ?? [], access);
+    const directory = !menu.component && !menu.meta?.externalLink;
+    return {
+      ...menu,
+      children,
+      redirect: directory ? ((can(menu) ? first(children) : undefined) ?? '/403') : menu.redirect,
+      meta: { ...menu.meta, ...(directory && !first(children) ? { hideInMenu: true } : {}) },
+    };
+  });
+}

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/app/services/access.ts

@@ -0,0 +1,2 @@
+// 单一权限 Store，由实际会话响应填充，不能持久化演示权限。
+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>;
+}