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

package/templates/base/API-CONTRACT.md

@@ -1,37 +1,84 @@
 # 应用 API 契约
 
-Local 与 HTTP 实现 `src/services/contracts.ts` 的同一服务接口。Core 不包含业务协议。
-
-| 方法 | 路径 | 标准 JSON 响应 |
-| --- | --- | --- |
-| POST | `/auth/login`，body `{ username, password }` | `{ accessToken, refreshToken?, expiresAt? }` |
-| POST | `/auth/refresh`，body `{ refreshToken }` | 同上 |
-| GET | `/session/me` | `{ id, username, name }`，均为字符串 |
-| GET | `/session/access` | `{ roles: string[], permissions: string[] }` |
-| GET | `/menus` | `LumalMenuRecord[]` |
-| POST | `/auth/logout` | 204 或 JSON |
-| GET | `/system/:resource?page=1&pageSize=10&keyword=` | `{ items: object[], total: number }` |
-| POST/PUT/DELETE | `/system/:resource[/:id]` | JSON 或 204 |
-
-菜单组件使用 `src/router/views.ts` 的本地白名单，禁止任意远程 import。标准模块资源为
-`users`、`roles`、`menus`、`organizations`、`dictionaries/types`、`dictionaries/items`、`config`。
-标准 CRUD 接口按记录管理；配置记录使用 `id/key/value/description`。
-后端仍需检查每项权限，不能依赖前端隐藏按钮。
+基础契约在 `src/app/services/contracts.ts`，业务入参和解析在各模块 `api.ts/types.ts`。
+Local 与 HTTP 使用同一组页面及端点；Core 不包含业务协议。
+系统接口仅在选择 system 时调用，个人中心仅 standard / vben-compatible 启用。
+
+| 方法            | 路径                                                                   | 标准 JSON 响应                                                       |
+| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| POST            | `/auth/login`，body `{ username, password }`                           | `{ accessToken, refreshToken?, expiresAt? }`                         |
+| POST            | `/auth/refresh`，body `{ refreshToken }`                               | 同上                                                                 |
+| GET             | `/session/me`                                                          | `{ id, username, name }`，均为字符串                                 |
+| GET             | `/session/access`                                                      | `{ roles: string[], permissions: string[] }`                         |
+| GET             | `/menus`                                                               | `LumalMenuRecord[]`                                                  |
+| POST            | `/auth/logout`                                                         | 204 或 JSON                                                          |
+| GET             | `/system/users`、`/system/roles`                                       | `{ items: User[] \| Role[], total }`                                 |
+| POST/PUT/DELETE | `/system/users[/:id]`、`/system/roles[/:id]`                           | 对应模块输入 / 记录；删除 204 或 JSON                                |
+| PATCH           | `/system/users/:id/status`                                             | `{ status }` / `User`                                                |
+| PUT             | `/system/users/:id/roles`                                              | `{ roles: string[] }` / `User`                                       |
+| PATCH           | `/system/users/batch/status`                                           | `{ ids, status }` / `{ items, updated }`                             |
+| PUT             | `/system/users/batch/roles`                                            | `{ ids, roles, mode: 'append' \| 'replace' }` / `{ items, updated }` |
+| POST            | `/system/users/:id/reset-password`                                     | `{ temporaryPassword }`                                              |
+| GET             | `/system/roles/options`、`/system/organizations/options`               | `{ label, value, disabled?, children? }[]`                           |
+| GET             | `/system/permissions/tree`                                             | `{ id, label, permission?, children? }[]`                            |
+| GET/PUT         | `/system/roles/:code/permissions`                                      | PUT `{ permissions: string[] }`；响应 `string[]`                     |
+| GET             | `/system/menus`、`/system/organizations`                               | 对应树形记录数组，`children`；机构可带 `userCount`                   |
+| POST/PUT/DELETE | `/system/menus[/:id]`、`/system/organizations[/:id]`                   | 对应模块输入 / 记录                                                  |
+| GET             | `/system/dictionaries/types`、`/system/dictionaries/items?typeCode=`   | 对应记录数组                                                         |
+| POST/PUT/DELETE | `/system/dictionaries/types[/:id]`、`/system/dictionaries/items[/:id]` | 对应模块输入 / 记录                                                  |
+| GET             | `/system/dictionaries/options/:code`                                   | `{ label, value, color? }[]`                                         |
+| GET/PUT         | `/system/config`                                                       | `{ appName, colorPrimary, layout, tabbarEnable, transitionEnable }`  |
+| POST            | `/system/config/restore`                                               | 恢复默认，响应同上                                                   |
+| GET/PUT         | `/profile`                                                             | GET `User`；PUT `{ nickname, phone }` / `User`                       |
+| PUT             | `/profile/password`                                                    | `{ currentPassword, newPassword }` / 204 或 JSON                     |
+
+用户查询支持 `page/pageSize/keyword/organizationId/roles/status`，角色支持
+`page/pageSize/keyword/status`。分页默认第一页，页号和每页条数必须为正整数。
+`UserInput` 为 `username/nickname/organizationId/roles/phone/status`；响应另有 `id/createdAt`。
+`RoleInput` 为 `code/name/description/status`；响应另有 `id/builtIn`，不接收 permissions。
+
+## 业务约束与权限
+
+- 用户操作对应 `system:user:list/create/update/delete/status/assign-roles/reset-password`。
+- 角色对应 `system:role:list/create/update/delete/authorize`；资料和授权分别保存，不宣称两个请求是事务。
+- 授权树来自真实接口，非叶访问权限独立回显；授权已写入但会话重读失败时明确提示部分成功，只重试重读。
+- 菜单、机构、字典的权限前缀分别为 `system:menu`、`system:organization`、`system:dict`，操作是 `list/create/update/delete`。
+- 配置读取需 `system:config:view`，写入需 `system:config:update`；无写权限显示只读表单，不是 key/value 记录列表。
+- 服务端须保护内置管理员和角色、角色引用、机构关联用户和父子关系；批量写入应先校验全部目标。
+- 字典同分类值唯一，删除分类级联处理字典项；修改后清理共享 `dictionaryStore`，业务表单应使用同一 Store。
+- 个人中心由后端确认当前身份；密码必须经后端验证并持久化。接口不存在时展示真实错误，不伪造成功。
+
+完整字段以各模块 types.ts 为准。没有指标接口时工作台不请求或编造业务指标。
 
 HTTP 模式必须配置 `VITE_API_BASE_URL`，未配置立即报错，绝不回退本地登录。
 默认直接消费标准 JSON。包装、字段及权限映射集中在应用 `http-adapter.ts`。
 需要 Cookie/CSRF、租户或 SSO 时在应用 transport 接入，不将密钥写到 `VITE_*`。
 默认凭据存于 localStorage，请按安全要求选择内存/HttpOnly Cookie 策略。
 
+## 菜单信任边界
+
+菜单组件使用 `src/app/router/views.ts` 汇集的本地白名单，键必须是自有函数加载器；
+拒绝 constructor、**proto**、prototype 和任意 import URL，递归子菜单同样校验。
+HTTP 菜单替换本地菜单，不静默融合。子路由使用属于父路径的绝对地址；
+目录默认跳到当前身份可访问的首个子页，无子页时隐藏。路由守卫逐层检查父子权限，
+远程 ignoreAccess/requireLogin 不能关闭认证或权限。
+
+外链只接受无用户名密码的 HTTP(S) 绝对地址，禁止 javascript/data/vbscript、
+协议相对地址、反斜线和控制字符。iframe 只能使用 `app/iframe`，且完整来源必须
+注册在 `VITE_IFRAME_ORIGINS`（逗号分隔），使用独立 sandbox。
+
 ## 接入仓库 Lumal Mock API
 
 启动独立的 `lumal-mock-api` 后，设置 `VITE_API_BASE_URL=http://127.0.0.1:5320/api`
 和 `VITE_API_ADAPTER=lumal-mock`。这是显式选择的演示后端，不是生产默认值。
 该 adapter 映射 `statusCode/result/resultMsg`、snake_case Token、`records/totalNum`；
 只选择本预设存在的菜单，其余示例页面不生成。
-Mock 的系统配置通过显式 adapter 转换为记录型配置；更新时保留原值类型。
+Mock 的配置字段与上表一致；历史写权限 `system:config:view` 显式映射到应用 update 权限。
+第三方后端应按真实协议调整 Adapter，不假定均兼容此演示协议。
 
 401 GET 自动单飞刷新并最多重放一次；写请求不自动重放，避免重复提交。
-初始化等待用户、权限和菜单全部就绪后注册路由。退出、刷新失败和重新登录清理
-权限、菜单、动态路由、请求缓存、标签和页面缓存；旧会话请求会被取消。
+初始化等待用户、权限和菜单全部就绪后注册路由。退出、Token 刷新失败和重新登录清理
+凭据、权限、菜单、动态路由、请求缓存和标签；旧会话请求会被取消。
+主动重读权限失败时清空旧授权及路由，保留凭据供显式重试。
 真实接口的 403、校验或网络错误保持可见，不转换成成功响应。
+Local 存储可被浏览器用户修改，仅供开发，不能替代服务端鉴权。

package/templates/base/README.md

@@ -23,7 +23,7 @@ pnpm preview
 HTTP 接入前配置 `.env.development`，完整接口见 [API 契约](./API-CONTRACT.md)。
 Local 模式是明确的开发演示，账号 `admin/guest`，密码 `lumal123`；
 生产默认禁用，不应将演示模式当作生产认证。
-标准业务模块使用应用服务和原生 CRUD，初始数据为空，可自行新增。
+系统模块包含有明确关联的开发种子数据；示例数据与系统数据分离。
 
 ## 部署
 
@@ -38,5 +38,22 @@ localStorage Token 示例不是生产安全策略的唯一选择。
 
 minimal 没有管理页面与兼容层；standard 的 system/examples 是可选模板层。
 系统页面的 CRUD 和 Schema 不进入 Core 的业务实现。图表、驾驶舱、富文本、
-国际化与 VXE 高级编辑均不默认安装。新增页面时在 `src/modules` 声明白名单懒加载器，
-并让后端菜单使用相应 component key。服务端菜单改变后需重新加载会话。
+国际化与 VXE 高级编辑均不默认安装。
+
+```text
+src/app/                     路由、认证、请求、布局接线与异常页
+src/modules/dashboard/       工作台
+src/modules/profile/         个人中心（标准预设）
+src/modules/system/          系统父模块（可选）
+  user/ role/ menu/ organization/ dictionary/ config/
+src/modules/examples/        开发示例（可选）
+src/modules/vben-migration/  迁移示例（仅兼容预设）
+src/modules/business/        自有业务模块
+src/shared/                  共享组件、类型与组合式函数
+```
+
+每个模块通过 `module.ts` 导出 menus/views/permissions，注册表只加载小型元数据，
+页面使用动态 import。在 business 中新增一个子目录及 module.ts 即可注册，不需要修改中心文件；
+完整接入示例见该目录 README。业务类型和强类型 API 放在模块内，不写入全局实体配置。
+系统、开发示例和迁移示例各有真实父路由，权限变化后目录重定向重新计算。
+HTTP 菜单使用已生成页面的 component key，并由后端提供完整菜单；不会静默混入本地菜单。

package/templates/base/src/App.vue

@@ -1,101 +1,99 @@
 <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 './components/app/AppHeaderActions.vue'
-import { createAdminSidebarMenus, createAdminTabs } from './router'
+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 './services/preferences'
-import { adminTabSnapshotStorageKey, currentUser, logout } from './services/session'
+} from './app/services/preferences';
+import { adminTabSnapshotStorageKey, application, currentUser, logout } from './app/services/session';
 
 /***********************页面状态*********************/
-const AppSettingsDrawer = defineAsyncComponent(() => import('./components/app/AppSettingsDrawer.vue'))
-const title = appConfig.title
-const settingsVisible = shallowRef(false)
-const pageError = shallowRef('')
-const routeRefreshKeys = reactive<Record<string, number>>({})
+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
-})
+  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())
+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}`
+  return `${path}:${routeRefreshKeys[path] ?? 0}`;
 }
-const routeViewKey = computed(() => resolveRouteViewKey(route.path))
-const routeViewCache = computed(() => adminPreferences.value.tabbar.enable && adminPreferences.value.tabbar.cache)
+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)
+      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 })
+});
+
+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)
+  const item = findMenuItemByPath(allMenus.value, path);
 
-  if (item?.externalLink && item.externalTarget !== '_self') {
-    window.open(item.externalLink, item.externalTarget ?? '_blank', 'noopener,noreferrer')
-    return
+  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
+  activePath.value = path;
 }
 
 function handleToggleSidebar(): void {
   patchAdminPreferences({
     sidebar: { collapsed: !adminPreferences.value.sidebar.collapsed },
-  })
+  });
 }
 
 function handleTabChange(path: string): void {
-  activePath.value = path
+  activePath.value = path;
 }
 
 function resolveAdminRouteTab(currentRoute: RouteLocationNormalizedLoaded): LumalLayoutTabItem | undefined {
   if (currentRoute.meta.layout === 'public' || currentRoute.meta.hideInTab === true) {
-    return undefined
+    return undefined;
   }
 
-  const menu = findMenuItemByPath(allMenus.value, currentRoute.path)
-  const tabTitle = menu?.title ?? (typeof currentRoute.meta.title === 'string' ? currentRoute.meta.title : 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 undefined;
   }
 
   return {
@@ -103,27 +101,26 @@ function resolveAdminRouteTab(currentRoute: RouteLocationNormalizedLoaded): Luma
     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)
+    await router.push(path);
   }
 
-  routeRefreshKeys[path] = (routeRefreshKeys[path] ?? 0) + 1
+  routeRefreshKeys[path] = (routeRefreshKeys[path] ?? 0) + 1;
 }
 
 function handleTabsChange(tabs: LumalLayoutTabItem[]): void {
-  const paths = new Set(tabs.map(tab => tab.path))
+  const paths = new Set(tabs.map((tab) => tab.path));
   for (const path of Object.keys(routeRefreshKeys)) {
-    if (!paths.has(path))
-      delete routeRefreshKeys[path]
+    if (!paths.has(path)) delete routeRefreshKeys[path];
   }
 }
 
 function handlePreferencesChange(preferences: LumalPreferences): void {
-  patchAdminPreferences(preferences)
+  patchAdminPreferences(preferences);
 }
 
 function toggleTheme(): void {
@@ -131,35 +128,28 @@ function toggleTheme(): void {
     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')
+    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"
-    />
+    <LumalRouterView v-if="isPublicLayout" :view-key="routeViewKey" transition transition-name="fade" />
 
     <LumalLayout
       v-else
-      :key="currentUser?.username"
+      :key="`${currentUser?.username}:${application.accessVersion.value}`"
       v-model:active-tab-path="activePath"
       :title="title"
       :menus="allMenus"
@@ -180,6 +170,8 @@ async function handleLogout(): Promise<void> {
         <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"

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/{components/app → app/components}/AppSettingsDrawer.vue

@@ -1,27 +1,27 @@
 <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'
+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
-}>()
+  defaults: LumalPreferencesDefaults;
+  preferences: LumalPreferences;
+  visible: boolean;
+}>();
 
 const emit = defineEmits<{
-  'change': [preferences: LumalPreferences]
-  'reset': [preferences: LumalPreferences]
-  'update:preferences': [preferences: LumalPreferences]
-  'update:visible': [visible: boolean]
-}>()
+  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),
-})
+  set: (value) => emit('update:visible', value),
+});
 </script>
 
 <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 } : {}) },
+    };
+  });
+}