feat: 重构前端项目结构并优化代码

refactor: 迁移前端资源文件至web目录
feat: 新增多种图标资源
style: 统一代码风格和格式化配置
docs: 更新README和文档说明
chore: 更新依赖和配置文件
fix: 修复部分类型定义和枚举
perf: 优化路由和组件加载逻辑

frontend/web/src/store/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Pinia Store 配置模块
+ *
+ * 提供全局状态管理的初始化和配置
+ *
+ * ## 主要功能
+ *
+ * - Pinia Store 实例创建
+ * - 持久化插件配置（pinia-plugin-persistedstate）
+ * - 版本化存储键管理
+ * - 自动数据迁移（跨版本）
+ * - LocalStorage 序列化配置
+ * - Store 初始化函数
+ *
+ * ## 持久化策略
+ *
+ * - 使用 StorageKeyManager 生成版本化的存储键
+ * - 格式：sys-v{version}-{storeId}
+ * - 自动迁移旧版本数据到当前版本
+ * - 使用 localStorage 作为存储介质
+ *
+ * @module store/index
+ * @author Fastapi Admin Team
+ */
+
+import type { App } from 'vue';
+import { createPinia } from 'pinia';
+import piniaPluginPersistedstate, { createPersistedState } from 'pinia-plugin-persistedstate';
+import { StorageKeyManager } from '@/utils/storage/storage-key-manager';
+
+export const store = createPinia();
+
+// 创建存储键管理器实例
+const storageKeyManager = new StorageKeyManager();
+store.use(piniaPluginPersistedstate);
+// 配置持久化插件
+store.use(
+  createPersistedState({
+    key: (storeId: string) => storageKeyManager.getStorageKey(storeId),
+    storage: localStorage,
+    serializer: {
+      serialize: JSON.stringify,
+      deserialize: JSON.parse,
+    },
+  })
+);
+
+/**
+ * 初始化 Store
+ */
+export function initStore(app: App<Element>): void {
+  app.use(store);
+}
+
+export * from './modules/app.store';
+export * from './modules/settings.store';
+export * from './modules/tags-view.store';
+export * from './modules/lock.store';
+export * from './modules/permission.store';
+export * from './modules/user.store';
+export * from './modules/dict.store';
+export * from './modules/config.store';
+export * from './modules/notice.store';
+
+// ------------------------------
+// 🔄 刷新缓存统一入口
+// ------------------------------
+import router from '@/router';
+import { useUserStoreHook } from './modules/user.store';
+import { usePermissionStoreHook } from './modules/permission.store';
+import { useDictStoreHook } from './modules/dict.store';
+import { useConfigStoreHook } from './modules/config.store';
+import { useNoticeStoreHook } from './modules/notice.store';
+import { useTagsViewStore } from './modules/tags-view.store';
+
+export interface RefreshCacheOptions {
+  /** 需要刷新的字典类型列表，不传则不刷新字典 */
+  dictTypes?: string[];
+  /** 是否刷新用户信息（含角色与权限） */
+  refreshUser?: boolean; // 默认 true
+  /** 是否重置并重新生成动态路由 */
+  refreshRoutes?: boolean; // 默认 true
+  /** 是否刷新系统配置 */
+  refreshConfig?: boolean; // 默认 true
+  /** 是否刷新通知公告 */
+  refreshNotice?: boolean; // 默认 true
+  /** 是否清空标签视图（避免路由变化后出现不一致） */
+  clearTags?: boolean; // 默认 false
+  /** 刷新字典前是否先清空本地字典缓存 */
+  clearDictBefore?: boolean; // 默认 false
+}
+
+/**
+ * 一键刷新常用缓存项，可按需选择。
+ * 建议：服务端数据（配置、字典、公告、用户/权限）适合刷新；UI 偏好（app/settings/lock）不刷新。
+ */
+export async function refreshAppCaches(opts: RefreshCacheOptions = {}) {
+  const {
+    dictTypes,
+    refreshUser = true,
+    refreshRoutes = true,
+    refreshConfig = true,
+    refreshNotice = true,
+    clearTags = false,
+    clearDictBefore = false,
+  } = opts;
+
+  const userStore = useUserStoreHook();
+  const permStore = usePermissionStoreHook();
+  const dictStore = useDictStoreHook();
+  const noticeStore = useNoticeStoreHook();
+  const configStore = useConfigStoreHook();
+  const tagsViewStore = useTagsViewStore(store);
+
+  const tasks: Promise<any>[] = [];
+
+  if (refreshUser) {
+    tasks.push(userStore.getUserInfo());
+  }
+  if (refreshConfig) {
+    tasks.push(configStore.getConfig(true));
+  }
+  if (refreshNotice) {
+    tasks.push(noticeStore.getNotice());
+  }
+  if (dictTypes && dictTypes.length > 0) {
+    if (clearDictBefore) dictStore.clearDictData();
+    tasks.push(dictStore.getDict(dictTypes));
+  }
+
+  // 并行刷新服务端数据
+  await Promise.allSettled(tasks);
+
+  // 路由需要串行处理，先重置再生成
+  if (refreshRoutes) {
+    permStore.resetRouter();
+    const dynamicRoutes = await permStore.generateRoutes();
+    // 将新生成的动态路由注册到路由器，确保可用
+    dynamicRoutes.forEach((route) => router.addRoute(route));
+  }
+
+  // 可选：清空标签视图，避免路由变更后的不一致
+  if (clearTags) {
+    await tagsViewStore.delAllViews();
+  }
+}

frontend/web/src/store/modules/app.store.ts

@@ -0,0 +1,126 @@
+import { defaultSettings } from '@/settings';
+
+// 导入 Element Plus 中英文语言包
+import zhCn from 'element-plus/es/locale/lang/zh-cn';
+import en from 'element-plus/es/locale/lang/en';
+import { store } from '@/store';
+import { DeviceEnum } from '@/enums/settings/device.enum';
+import { SidebarStatus } from '@/enums/settings/layout.enum';
+
+export const useAppStore = defineStore('app', () => {
+  // 设备类型
+  const device = useStorage('device', DeviceEnum.DESKTOP);
+  // 布局大小
+  const size = useStorage('size', defaultSettings.size);
+  // 语言
+  const language = useStorage('language', defaultSettings.language);
+  // 侧边栏状态
+  const sidebarStatus = useStorage('sidebarStatus', SidebarStatus.CLOSED);
+  const sidebar = reactive({
+    opened: sidebarStatus.value === SidebarStatus.OPENED,
+    withoutAnimation: false,
+  });
+
+  // 顶部菜单激活路径
+  const activeTopMenuPath = useStorage('activeTopMenuPath', '');
+  // 项目引导
+  const guideVisible = useStorage('guideVisible', defaultSettings.guideVisible);
+
+  /**
+   * 根据语言标识读取对应的语言包
+   */
+  const locale = computed(() => {
+    if (language?.value == 'en') {
+      return en;
+    } else {
+      return zhCn;
+    }
+  });
+
+  /**
+   * 切换侧边栏
+   */
+  function toggleSidebar() {
+    sidebar.opened = !sidebar.opened;
+    sidebarStatus.value = sidebar.opened ? SidebarStatus.OPENED : SidebarStatus.CLOSED;
+  }
+
+  /**
+   * 关闭侧边栏
+   */
+  function closeSideBar() {
+    sidebar.opened = false;
+    sidebarStatus.value = SidebarStatus.CLOSED;
+  }
+
+  /**
+   * 打开侧边栏
+   */
+  function openSideBar() {
+    sidebar.opened = true;
+    sidebarStatus.value = SidebarStatus.OPENED;
+  }
+
+  /**
+   * 切换设备
+   * @param val 设备类型
+   */
+  function toggleDevice(val: string) {
+    device.value = val;
+  }
+
+  /**
+   * 改变布局大小
+   * @param val 布局大小 default | small | large
+   */
+  function changeSize(val: string) {
+    size.value = val;
+  }
+  /**
+   * 切换语言
+   * @param val
+   */
+  function changeLanguage(val: string) {
+    language.value = val;
+  }
+  /**
+   * 混合模式顶部切换
+   * @param val
+   */
+  function activeTopMenu(val: string) {
+    activeTopMenuPath.value = val;
+  }
+  /**
+   * 显示或隐藏引导
+   * @param val 是否显示引导
+   */
+  function showGuide(val: boolean) {
+    guideVisible.value = val;
+  }
+  return {
+    device,
+    sidebar,
+    language,
+    locale,
+    size,
+    activeTopMenu,
+    toggleDevice,
+    showGuide,
+    changeSize,
+    changeLanguage,
+    toggleSidebar,
+    closeSideBar,
+    openSideBar,
+    activeTopMenuPath,
+    guideVisible,
+  };
+});
+
+/**
+ * 用于在组件外部（如在Pinia Store 中）使用 Pinia 提供的 store 实例。
+ * 官方文档解释了如何在组件外部使用 Pinia Store：
+ * https://pinia.vuejs.org/core-concepts/outside-component-usage.html#using-a-store-outside-of-a-component
+ */
+export function useAppStoreHook() {
+  return useAppStore(store);
+}

frontend/web/src/store/modules/config.store.ts

@@ -0,0 +1,59 @@
+import { store } from '@/store';
+import ParamsAPI, { ConfigTable } from '@/api/module_system/params';
+
+interface ConfigState {
+  // 网站信息
+  sys_web_title: ConfigTable;
+  sys_web_version: ConfigTable;
+  sys_web_description: ConfigTable;
+  // 网站图标
+  sys_login_background: ConfigTable;
+  sys_web_favicon: ConfigTable;
+  sys_web_logo: ConfigTable;
+  // 安全隐私配置
+  sys_keep_record: ConfigTable;
+  sys_web_clause: ConfigTable;
+  sys_web_copyright: ConfigTable;
+  sys_web_privacy: ConfigTable;
+  sys_git_code: ConfigTable;
+  sys_help_doc: ConfigTable;
+  // 接口安全配置
+  white_api_list_path: ConfigTable;
+  ip_black_list: ConfigTable;
+  // 演示环境配置
+  demo_enable: ConfigTable;
+  ip_white_list: ConfigTable;
+}
+
+export const useConfigStore = defineStore('config', {
+  state: () => ({
+    configData: {} as ConfigState,
+    isConfigLoaded: false,
+    configLoading: false,
+  }),
+
+  actions: {
+    async getConfig(force = false) {
+      if ((this.isConfigLoaded && !force) || this.configLoading) {
+        return;
+      }
+      this.configLoading = true;
+      try {
+        const response = await ParamsAPI.getInitConfig();
+        response.data.data.forEach((item: ConfigTable) => {
+          if (item.config_value !== undefined) {
+            this.configData[item.config_key as keyof ConfigState] = item;
+          }
+        });
+        this.isConfigLoaded = true;
+      } finally {
+        this.configLoading = false;
+      }
+    },
+  },
+  persist: true,
+});
+
+export function useConfigStoreHook() {
+  return useConfigStore(store);
+}

frontend/web/src/store/modules/dict.store.ts

@@ -0,0 +1,86 @@
+import { store } from '@/store';
+import DictAPI, { DictDataTable } from '@/api/module_system/dict';
+
+export const useDictStore = defineStore('dict', {
+  state: () => ({
+    dictData: {} as Record<string, DictDataTable[]>,
+    isLoaded: false,
+  }),
+  getters: {
+    getDictData(): Record<string, DictDataTable[]> {
+      return this.dictData;
+    },
+
+    // 获取指定类型的字典数据，确保返回数组
+    getDictArray() {
+      return (type: string): Array<{ dict_value: string; dict_label: string }> => {
+        return (this.dictData[type] || [])
+          .filter((item) => item.dict_value !== undefined && item.dict_label !== undefined)
+          .map((item) => ({
+            dict_value: item.dict_value!,
+            dict_label: item.dict_label!,
+          }));
+      };
+    },
+  },
+  actions: {
+    // 批量获取字典数据
+    async getDict(types: string[]): Promise<Record<string, DictDataTable[]>> {
+      try {
+        for (const type of types) {
+          if (!this.dictData[type]) {
+            const response = await DictAPI.getInitDict(type);
+            // 确保数据格式正确
+            this.dictData[type] = ((response.data.data as DictDataTable[]) || []).filter(
+              (item) => item.dict_value !== undefined && item.dict_label !== undefined
+            );
+            this.isLoaded = true;
+          }
+        }
+        // 返回请求的字典数据
+        return types.reduce(
+          (result, type) => {
+            result[type] = this.getDictArray(type);
+            return result;
+          },
+          {} as Record<string, DictDataTable[]>
+        );
+      } catch (error) {
+        console.error('获取字典数据失败', error);
+        return {};
+      }
+    },
+
+    getDictLabel(type: string, value: string) {
+      const result = this.dictData[type].find((item) => item.dict_value === value);
+      if (!result) {
+        return value;
+      }
+      const dict_data = {
+        id: result.id,
+        dict_value: result.dict_value,
+        dict_label: result.dict_label,
+        dict_type: result.dict_type,
+        css_class: result.css_class,
+        list_class: result.list_class,
+        is_default: result.is_default,
+        dict_sort: result.dict_sort,
+        dict_type_id: result.dict_type_id,
+        uuid: result.uuid,
+        status: result.status,
+        description: result.description,
+        created_time: result.created_time,
+        updated_time: result.updated_time,
+      };
+      return dict_data;
+    },
+    clearDictData() {
+      this.dictData = {};
+    },
+  },
+  persist: true,
+});
+
+export function useDictStoreHook() {
+  return useDictStore(store);
+}

frontend/web/src/store/modules/lock.store.ts

@@ -0,0 +1,48 @@
+import { defineStore } from 'pinia';
+import { store } from '../index';
+
+interface lockInfo {
+  isLock?: boolean;
+  password?: string;
+}
+
+interface LockState {
+  lockInfo: lockInfo;
+}
+
+export const useLockStore = defineStore('lock', {
+  state: (): LockState => {
+    return {
+      lockInfo: {
+        // isLock: false, // 是否锁定屏幕
+        // password: '' // 锁屏密码
+      },
+    };
+  },
+  getters: {
+    getLockInfo(): lockInfo {
+      return this.lockInfo;
+    },
+  },
+  actions: {
+    setLockInfo(lockInfo: lockInfo) {
+      this.lockInfo = lockInfo;
+    },
+    resetLockInfo() {
+      this.lockInfo = {};
+    },
+    unLock(password: string) {
+      if (this.lockInfo?.password === password) {
+        this.resetLockInfo();
+        return true;
+      } else {
+        return false;
+      }
+    },
+  },
+  persist: true,
+});
+
+export const useLockStoreWithOut = () => {
+  return useLockStore(store);
+};

frontend/web/src/store/modules/menu.ts

@@ -0,0 +1,109 @@
+/**
+ * 菜单状态管理模块
+ *
+ * 提供菜单数据和动态路由的状态管理
+ *
+ * ## 主要功能
+ *
+ * - 菜单列表存储和管理
+ * - 首页路径配置
+ * - 动态路由注册和移除
+ * - 路由移除函数管理
+ * - 菜单宽度配置
+ *
+ * ## 使用场景
+ *
+ * - 动态菜单加载和渲染
+ * - 路由权限控制
+ * - 首页路径动态设置
+ * - 登出时清理动态路由
+ *
+ * ## 工作流程
+ *
+ * 1. 获取菜单数据（前端/后端模式）
+ * 2. 设置菜单列表和首页路径
+ * 3. 注册动态路由并保存移除函数
+ * 4. 登出时调用移除函数清理路由
+ *
+ * @module store/modules/menu
+ * @author Fastapi Admin Team
+ */
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+import { AppRouteRecord } from '@/types/router';
+import { getFirstMenuPath } from '@/utils';
+import { HOME_PAGE_PATH } from '@/router';
+
+/**
+ * 菜单状态管理
+ * 管理应用的菜单列表、首页路径、菜单宽度和动态路由移除函数
+ */
+export const useMenuStore = defineStore('menuStore', () => {
+  /** 首页路径 */
+  const homePath = ref(HOME_PAGE_PATH);
+  /** 菜单列表 */
+  const menuList = ref<AppRouteRecord[]>([]);
+  /** 菜单宽度 */
+  const menuWidth = ref('');
+  /** 存储路由移除函数的数组 */
+  const removeRouteFns = ref<(() => void)[]>([]);
+
+  /**
+   * 设置菜单列表
+   * @param list 菜单路由记录数组
+   */
+  const setMenuList = (list: AppRouteRecord[]) => {
+    menuList.value = list;
+    setHomePath(HOME_PAGE_PATH || getFirstMenuPath(list));
+  };
+
+  /**
+   * 获取首页路径
+   * @returns 首页路径字符串
+   */
+  const getHomePath = () => homePath.value;
+
+  /**
+   * 设置主页路径
+   * @param path 主页路径
+   */
+  const setHomePath = (path: string) => {
+    homePath.value = path;
+  };
+
+  /**
+   * 添加路由移除函数
+   * @param fns 要添加的路由移除函数数组
+   */
+  const addRemoveRouteFns = (fns: (() => void)[]) => {
+    removeRouteFns.value.push(...fns);
+  };
+
+  /**
+   * 移除所有动态路由
+   * 执行所有存储的路由移除函数并清空数组
+   */
+  const removeAllDynamicRoutes = () => {
+    removeRouteFns.value.forEach((fn) => fn());
+    removeRouteFns.value = [];
+  };
+
+  /**
+   * 清空路由移除函数数组
+   */
+  const clearRemoveRouteFns = () => {
+    removeRouteFns.value = [];
+  };
+
+  return {
+    menuList,
+    menuWidth,
+    removeRouteFns,
+    setMenuList,
+    getHomePath,
+    setHomePath,
+    addRemoveRouteFns,
+    removeAllDynamicRoutes,
+    clearRemoveRouteFns,
+  };
+});

frontend/web/src/store/modules/notice.store.ts

@@ -0,0 +1,62 @@
+import { store } from '@/store';
+import NoticeAPI, { NoticeTable } from '@/api/module_system/notice';
+
+export const useNoticeStore = defineStore('notice', {
+  state: () => ({
+    noticeList: [] as NoticeTable[],
+    total: 0,
+    isNoticeLoaded: false,
+    // 已读通知ID集合（前端持久化，避免刷新后重复展示）
+    readIds: [] as number[],
+  }),
+  actions: {
+    async getNotice() {
+      const response = await NoticeAPI.listNoticeAvailable();
+      const items = response.data.data.items || [];
+      // 过滤掉已读的通知
+      const readSet = new Set(this.readIds);
+      const filtered = items.filter(
+        (item) => item.id !== undefined && !readSet.has(item.id as number)
+      );
+      this.noticeList = filtered;
+      this.total = filtered.length;
+      this.isNoticeLoaded = true;
+    },
+    // 标记单条通知为已读
+    markAsRead(id?: number) {
+      if (id === undefined) return;
+      if (!this.readIds.includes(id)) {
+        this.readIds.push(id);
+      }
+      // 同步过滤当前列表
+      this.noticeList = this.noticeList.filter((item) => item.id !== id);
+      this.total = this.noticeList.length;
+    },
+    // 标记当前列表全部为已读
+    markAllAsRead(ids: number[] = []) {
+      const targets = ids.length
+        ? ids
+        : this.noticeList.map((item) => item.id!).filter((id): id is number => id !== undefined);
+      const readSet = new Set(this.readIds);
+      targets.forEach((id) => {
+        if (!readSet.has(id)) this.readIds.push(id);
+      });
+      // 同步过滤当前列表
+      this.noticeList = this.noticeList.filter(
+        (item) => item.id !== undefined && !this.readIds.includes(item.id as number)
+      );
+      this.total = this.noticeList.length;
+    },
+    clearUserInfo() {
+      this.noticeList = [];
+      this.total = 0;
+      this.isNoticeLoaded = false;
+      this.readIds = [];
+    },
+  },
+  persist: true,
+});
+
+export function useNoticeStoreHook() {
+  return useNoticeStore(store);
+}

frontend/web/src/store/modules/permission.store.ts

@@ -0,0 +1,223 @@
+import type { RouteRecordRaw } from 'vue-router';
+import router, { constantRoutes } from '@/router';
+import { store, useUserStore } from '@/store';
+import { MenuTable } from '@/api/module_system/menu';
+
+const modules = import.meta.glob('../../views/**/**.vue');
+const Layout = () => import('@/layouts/index.vue');
+
+export interface Meta {
+  /** 【目录】只有一个子路由是否始终显示 */
+  alwaysShow?: boolean;
+  /** 是否隐藏(true-是 false-否) */
+  hidden?: boolean;
+  /** 菜单终端（后端 sys_menu.client，PC 动态路由仅下发 pc） */
+  client?: string;
+  /** ICON */
+  icon?: string;
+  /** 【菜单】是否开启页面缓存 */
+  keepAlive?: boolean;
+  /** 路由title */
+  title?: string;
+  /** 排序 */
+  order?: number;
+  /** 参数 */
+  params?: { key: string; value: string }[];
+  /** 是否固定路由 */
+  affix?: boolean;
+}
+
+// 修改 component 类型，使其能接受动态导入函数
+export interface RouteVO {
+  /** 子路由列表 */
+  children: RouteVO[];
+  /** 组件路径或组件导入函数 */
+  component?: string | (() => Promise<Component>);
+  /** 路由属性 */
+  meta?: Meta;
+  /** 路由名称 */
+  name?: string;
+  /** 路由路径 */
+  path?: string;
+  /** 跳转链接 */
+  redirect?: string;
+}
+
+/**
+ * 后端常把「模块目录」与「其下功能菜单」写成同一绝对 route_path（如均为 /module_xxx/demo02）。
+ * Vue Router 嵌套子路由应使用空 path 挂到父 path 下，否则重复绝对路径会导致匹配异常。
+ */
+function normalizeMenuNestedPaths(items: MenuTable[], parentAbsolutePath?: string): MenuTable[] {
+  return items.map((node) => {
+    const raw = (node.route_path ?? '').trim();
+    let routePath: string | null | undefined = node.route_path;
+    if (parentAbsolutePath && raw && raw === parentAbsolutePath) {
+      routePath = '';
+    }
+    const canonical = raw.startsWith('/') ? raw : parentAbsolutePath;
+    const children = node.children?.length
+      ? normalizeMenuNestedPaths(node.children, canonical)
+      : undefined;
+    return { ...node, route_path: routePath, children };
+  });
+}
+
+export const generator = (routers: MenuTable[]): RouteVO[] => {
+  return routers.map((item) => {
+    const currentRouter: RouteVO = {
+      children: [],
+      path: item.route_path,
+      name: item.route_name,
+      component: item.component_path,
+      redirect: item.redirect,
+      meta: {
+        title: item.title,
+        icon: item.icon || undefined,
+        client: item.client,
+        keepAlive: item.keep_alive,
+        hidden: item.hidden,
+        order: item.order,
+        alwaysShow: item.always_show,
+        params: item.params,
+        affix: item.affix,
+      },
+    };
+    if (item.children && item.children.length > 0) {
+      currentRouter.children = item.children ? generator(item.children) : [];
+    }
+    return currentRouter;
+  });
+};
+
+export const usePermissionStore = defineStore('permission', () => {
+  // 存储所有路由，包括静态路由和动态路由
+  const routes = ref<RouteRecordRaw[]>([]);
+  // 混合模式左侧菜单路由
+  const mixLayoutSideMenus = ref<RouteRecordRaw[]>([]);
+  // 路由是否加载完成
+  const isRouteGenerated = ref(false);
+
+  /**
+   * 获取后台动态路由数据，解析并注册到全局路由
+   *
+   * @returns Promise<RouteRecordRaw[]> 解析后的动态路由列表
+   */
+  async function generateRoutes(): Promise<RouteRecordRaw[]> {
+    try {
+      const userStore = useUserStore();
+      // 确保获取用户信息和路由列表
+      if (!userStore.hasGetRoute) {
+        await userStore.getUserInfo();
+      }
+
+      const data = generator(normalizeMenuNestedPaths(userStore.routeList));
+
+      // 解析动态路由
+      const dynamicRoutes = transformRoutes(data);
+
+      routes.value = [...constantRoutes, ...dynamicRoutes];
+
+      isRouteGenerated.value = true;
+
+      return dynamicRoutes;
+    } catch (error: any) {
+      // 即使失败也要设置状态，避免无限重试
+      isRouteGenerated.value = false;
+      throw error;
+    }
+  }
+
+  /**
+   * 根据父菜单路径设置侧边菜单
+   *
+   * @param parentPath 父菜单的路径，用于查找对应的菜单项
+   */
+  const setMixLayoutSideMenus = (parentPath: string) => {
+    const parentMenu = routes.value.find((item) => item.path === parentPath);
+    mixLayoutSideMenus.value = parentMenu?.children || [];
+  };
+
+  /**
+   * 重置路由
+   */
+  const resetRouter = () => {
+    // 创建常量路由名称集合，用于O(1)时间复杂度的查找
+    const constantRouteNames = new Set(constantRoutes.map((route) => route.name).filter(Boolean));
+
+    // 从 router 实例中移除动态路由
+    routes.value.forEach((route) => {
+      if (route.name && !constantRouteNames.has(route.name)) {
+        router.removeRoute(route.name);
+      }
+    });
+
+    // 重置所有状态
+    routes.value = [...constantRoutes];
+    mixLayoutSideMenus.value = [];
+    isRouteGenerated.value = false;
+  };
+
+  return {
+    routes,
+    mixLayoutSideMenus,
+    isRouteGenerated,
+    generateRoutes,
+    setMixLayoutSideMenus,
+    resetRouter,
+  };
+});
+
+/**
+ * 转换后端路由数据为Vue Router配置
+ * 处理组件路径映射和Layout层级嵌套
+ */
+const transformRoutes = (routes: RouteVO[], isTopLevel: boolean = true): RouteRecordRaw[] => {
+  return routes.map((route) => {
+    // 创建路由对象，保留所有路由属性
+    const normalizedRoute = { ...route } as RouteRecordRaw;
+
+    // 处理组件路径映射
+    // normalizedRoute.component = !normalizedRoute.component
+    //   ? Layout
+    //   : modules[`../../views/${normalizedRoute.component}.vue`] ||
+    //     modules["../../views/error/404.vue"];
+
+    // 关键优化：
+    // 1. 顶级路由（一级目录）使用Layout组件，确保菜单和navbar能正常显示
+    // 2. 二级及以上的父路由不使用Layout组件，只作为路由容器，避免Layout嵌套
+    // 3. 叶子路由使用实际组件
+    // 4. 递归处理子路由，实现无限层级菜单
+    if (normalizedRoute.children && normalizedRoute.children.length > 0) {
+      // normalizedRoute.children = transformRoutes(route.children);
+
+      // 非叶子路由
+      if (isTopLevel) {
+        // 顶级路由（一级目录），使用Layout组件
+        normalizedRoute.component = Layout;
+      } else {
+        // 二级及以上的父路由，不使用Layout组件，只作为路由容器
+        normalizedRoute.component = undefined;
+      }
+      // 递归处理子路由，标记为非顶级路由
+      normalizedRoute.children = transformRoutes(route.children, false);
+    } else {
+      // 叶子路由，使用实际组件
+      normalizedRoute.component = normalizedRoute.component
+        ? modules[`../../views/${normalizedRoute.component}.vue`] ||
+          modules['../../views/error/404.vue']
+        : modules['../../views/error/404.vue'];
+    }
+
+    return normalizedRoute;
+  });
+};
+
+/**
+ * 导出此hook函数用于在非组件环境(如其他store、工具函数等)中获取权限store实例
+ *
+ * 在组件中可直接使用usePermissionStore()，但在组件外部需要传入store实例
+ * 此函数简化了这个过程，避免每次都手动传入store参数
+ */
+export function usePermissionStoreHook() {
+  return usePermissionStore(store);
+}

frontend/web/src/store/modules/setting.ts

@@ -0,0 +1,450 @@
+/**
+ * 系统设置状态管理模块
+ *
+ * 提供完整的系统设置状态管理
+ *
+ * ## 主要功能
+ *
+ * - 菜单布局配置（左侧、顶部、混合、双栏）
+ * - 主题管理（亮色、暗色、自动）
+ * - 菜单主题样式配置
+ * - 界面显示开关（面包屑、标签页、语言切换等）
+ * - 功能开关（手风琴模式、色弱模式、水印等）
+ * - 样式配置（边框、圆角、容器宽度、页面过渡）
+ * - 节日功能配置
+ * - Element Plus 主题色动态设置
+ *
+ * ## 使用场景
+ *
+ * - 设置面板配置管理
+ * - 主题切换和样式定制
+ * - 界面功能开关控制
+ * - 用户偏好设置持久化
+ *
+ * ## 持久化
+ *
+ * - 使用 localStorage 存储
+ * - 存储键：sys-v{version}-setting
+ * - 支持跨版本数据迁移
+ *
+ * @module store/modules/setting
+ * @author Fastapi Admin Team
+ */
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import { MenuThemeType } from '@/types/store';
+import AppConfig from '@/config';
+import { SystemThemeEnum, MenuThemeEnum, MenuTypeEnum, ContainerWidthEnum } from '@/enums/appEnum';
+import { setElementThemeColor } from '@/utils/ui';
+import { useCeremony } from '@/hooks/core/useCeremony';
+import { StorageConfig } from '@/utils/storage/storage-config';
+import { SETTING_DEFAULT_CONFIG } from '@/config/setting';
+
+/**
+ * 系统设置状态管理
+ * 管理应用的菜单、主题、界面显示等各项设置
+ */
+export const useSettingStore = defineStore(
+  'settingStore',
+  () => {
+    // 菜单相关设置
+    /** 菜单类型 */
+    const menuType = ref(SETTING_DEFAULT_CONFIG.menuType);
+    /** 菜单展开宽度 */
+    const menuOpenWidth = ref(SETTING_DEFAULT_CONFIG.menuOpenWidth);
+    /** 菜单是否展开 */
+    const menuOpen = ref(SETTING_DEFAULT_CONFIG.menuOpen);
+    /** 双菜单是否显示文本 */
+    const dualMenuShowText = ref(SETTING_DEFAULT_CONFIG.dualMenuShowText);
+
+    // 主题相关设置
+    /** 系统主题类型 */
+    const systemThemeType = ref(SETTING_DEFAULT_CONFIG.systemThemeType);
+    /** 系统主题模式 */
+    const systemThemeMode = ref(SETTING_DEFAULT_CONFIG.systemThemeMode);
+    /** 菜单主题类型 */
+    const menuThemeType = ref(SETTING_DEFAULT_CONFIG.menuThemeType);
+    /** 系统主题颜色 */
+    const systemThemeColor = ref(SETTING_DEFAULT_CONFIG.systemThemeColor);
+
+    // 界面显示设置
+    /** 是否显示菜单按钮 */
+    const showMenuButton = ref(SETTING_DEFAULT_CONFIG.showMenuButton);
+    /** 是否显示快速入口 */
+    const showFastEnter = ref(SETTING_DEFAULT_CONFIG.showFastEnter);
+    /** 是否显示刷新按钮 */
+    const showRefreshButton = ref(SETTING_DEFAULT_CONFIG.showRefreshButton);
+    /** 是否显示面包屑 */
+    const showCrumbs = ref(SETTING_DEFAULT_CONFIG.showCrumbs);
+    /** 是否显示工作台标签 */
+    const showWorkTab = ref(SETTING_DEFAULT_CONFIG.showWorkTab);
+    /** 是否显示语言切换 */
+    const showLanguage = ref(SETTING_DEFAULT_CONFIG.showLanguage);
+    /** 是否显示进度条 */
+    const showNprogress = ref(SETTING_DEFAULT_CONFIG.showNprogress);
+    /** 是否显示设置引导 */
+    const showSettingGuide = ref(SETTING_DEFAULT_CONFIG.showSettingGuide);
+    /** 是否显示节日文本 */
+    const showFestivalText = ref(SETTING_DEFAULT_CONFIG.showFestivalText);
+    /** 是否显示水印 */
+    const watermarkVisible = ref(SETTING_DEFAULT_CONFIG.watermarkVisible);
+
+    // 功能设置
+    /** 是否自动关闭 */
+    const autoClose = ref(SETTING_DEFAULT_CONFIG.autoClose);
+    /** 是否唯一展开 */
+    const uniqueOpened = ref(SETTING_DEFAULT_CONFIG.uniqueOpened);
+    /** 是否色弱模式 */
+    const colorWeak = ref(SETTING_DEFAULT_CONFIG.colorWeak);
+    /** 是否刷新 */
+    const refresh = ref(SETTING_DEFAULT_CONFIG.refresh);
+    /** 是否加载节日烟花 */
+    const holidayFireworksLoaded = ref(SETTING_DEFAULT_CONFIG.holidayFireworksLoaded);
+
+    // 样式设置
+    /** 边框模式 */
+    const boxBorderMode = ref(SETTING_DEFAULT_CONFIG.boxBorderMode);
+    /** 页面过渡效果 */
+    const pageTransition = ref(SETTING_DEFAULT_CONFIG.pageTransition);
+    /** 标签页样式 */
+    const tabStyle = ref(SETTING_DEFAULT_CONFIG.tabStyle);
+    /** 自定义圆角 */
+    const customRadius = ref(SETTING_DEFAULT_CONFIG.customRadius);
+    /** 容器宽度 */
+    const containerWidth = ref(SETTING_DEFAULT_CONFIG.containerWidth);
+
+    // 节日相关
+    /** 节日日期 */
+    const festivalDate = ref('');
+
+    /**
+     * 获取菜单主题
+     * 根据当前主题类型和暗色模式返回对应的主题配置
+     */
+    const getMenuTheme = computed((): MenuThemeType => {
+      const list = AppConfig.themeList.filter((item) => item.theme === menuThemeType.value);
+      if (isDark.value) {
+        return AppConfig.darkMenuStyles[0];
+      } else {
+        return list[0];
+      }
+    });
+
+    /**
+     * 判断是否为暗色模式
+     */
+    const isDark = computed((): boolean => {
+      return systemThemeType.value === SystemThemeEnum.DARK;
+    });
+
+    /**
+     * 获取菜单展开宽度
+     */
+    const getMenuOpenWidth = computed((): string => {
+      return menuOpenWidth.value + 'px' || SETTING_DEFAULT_CONFIG.menuOpenWidth + 'px';
+    });
+
+    /**
+     * 获取自定义圆角
+     */
+    const getCustomRadius = computed((): string => {
+      return customRadius.value + 'rem' || SETTING_DEFAULT_CONFIG.customRadius + 'rem';
+    });
+
+    /**
+     * 是否显示烟花
+     * 根据当前日期和节日日期判断是否显示烟花效果
+     */
+    const isShowFireworks = computed((): boolean => {
+      return festivalDate.value === useCeremony().currentFestivalData.value?.date ? false : true;
+    });
+
+    /**
+     * 切换菜单布局
+     * @param type 菜单类型
+     */
+    const switchMenuLayouts = (type: MenuTypeEnum) => {
+      menuType.value = type;
+    };
+
+    /**
+     * 设置菜单展开宽度
+     * @param width 宽度值
+     */
+    const setMenuOpenWidth = (width: number) => {
+      menuOpenWidth.value = width;
+    };
+
+    /**
+     * 设置全局主题
+     * @param theme 主题类型
+     * @param themeMode 主题模式
+     */
+    const setGlopTheme = (theme: SystemThemeEnum, themeMode: SystemThemeEnum) => {
+      systemThemeType.value = theme;
+      systemThemeMode.value = themeMode;
+      localStorage.setItem(StorageConfig.THEME_KEY, theme);
+    };
+
+    /**
+     * 切换菜单样式
+     * @param theme 菜单主题
+     */
+    const switchMenuStyles = (theme: MenuThemeEnum) => {
+      menuThemeType.value = theme;
+    };
+
+    /**
+     * 设置Element Plus主题颜色
+     * @param theme 主题颜色
+     */
+    const setElementTheme = (theme: string) => {
+      systemThemeColor.value = theme;
+      setElementThemeColor(theme);
+    };
+
+    /**
+     * 切换边框模式
+     */
+    const setBorderMode = () => {
+      boxBorderMode.value = !boxBorderMode.value;
+    };
+
+    /**
+     * 设置容器宽度
+     * @param width 容器宽度枚举值
+     */
+    const setContainerWidth = (width: ContainerWidthEnum) => {
+      containerWidth.value = width;
+    };
+
+    /**
+     * 切换唯一展开模式
+     */
+    const setUniqueOpened = () => {
+      uniqueOpened.value = !uniqueOpened.value;
+    };
+
+    /**
+     * 切换菜单按钮显示
+     */
+    const setButton = () => {
+      showMenuButton.value = !showMenuButton.value;
+    };
+
+    /**
+     * 切换快速入口显示
+     */
+    const setFastEnter = () => {
+      showFastEnter.value = !showFastEnter.value;
+    };
+
+    /**
+     * 切换自动关闭
+     */
+    const setAutoClose = () => {
+      autoClose.value = !autoClose.value;
+    };
+
+    /**
+     * 切换刷新按钮显示
+     */
+    const setShowRefreshButton = () => {
+      showRefreshButton.value = !showRefreshButton.value;
+    };
+
+    /**
+     * 切换面包屑显示
+     */
+    const setCrumbs = () => {
+      showCrumbs.value = !showCrumbs.value;
+    };
+
+    /**
+     * 设置工作台标签显示
+     * @param show 是否显示
+     */
+    const setWorkTab = (show: boolean) => {
+      showWorkTab.value = show;
+    };
+
+    /**
+     * 切换语言切换显示
+     */
+    const setLanguage = () => {
+      showLanguage.value = !showLanguage.value;
+    };
+
+    /**
+     * 切换进度条显示
+     */
+    const setNprogress = () => {
+      showNprogress.value = !showNprogress.value;
+    };
+
+    /**
+     * 切换色弱模式
+     */
+    const setColorWeak = () => {
+      colorWeak.value = !colorWeak.value;
+    };
+
+    /**
+     * 隐藏设置引导
+     */
+    const hideSettingGuide = () => {
+      showSettingGuide.value = false;
+    };
+
+    /**
+     * 显示设置引导
+     */
+    const openSettingGuide = () => {
+      showSettingGuide.value = true;
+    };
+
+    /**
+     * 设置页面过渡效果
+     * @param transition 过渡效果名称
+     */
+    const setPageTransition = (transition: string) => {
+      pageTransition.value = transition;
+    };
+
+    /**
+     * 设置标签页样式
+     * @param style 样式名称
+     */
+    const setTabStyle = (style: string) => {
+      tabStyle.value = style;
+    };
+
+    /**
+     * 设置菜单展开状态
+     * @param open 是否展开
+     */
+    const setMenuOpen = (open: boolean) => {
+      menuOpen.value = open;
+    };
+
+    /**
+     * 刷新页面
+     */
+    const reload = () => {
+      refresh.value = !refresh.value;
+    };
+
+    /**
+     * 设置水印显示
+     * @param visible 是否显示
+     */
+    const setWatermarkVisible = (visible: boolean) => {
+      watermarkVisible.value = visible;
+    };
+
+    /**
+     * 设置自定义圆角
+     * @param radius 圆角值
+     */
+    const setCustomRadius = (radius: string) => {
+      customRadius.value = radius;
+      document.documentElement.style.setProperty('--custom-radius', `${radius}rem`);
+    };
+
+    /**
+     * 设置节日烟花加载状态
+     * @param isLoad 是否已加载
+     */
+    const setholidayFireworksLoaded = (isLoad: boolean) => {
+      holidayFireworksLoaded.value = isLoad;
+    };
+
+    /**
+     * 设置节日文本显示
+     * @param show 是否显示
+     */
+    const setShowFestivalText = (show: boolean) => {
+      showFestivalText.value = show;
+    };
+
+    const setFestivalDate = (date: string) => {
+      festivalDate.value = date;
+    };
+
+    const setDualMenuShowText = (show: boolean) => {
+      dualMenuShowText.value = show;
+    };
+
+    return {
+      menuType,
+      menuOpenWidth,
+      systemThemeType,
+      systemThemeMode,
+      menuThemeType,
+      systemThemeColor,
+      boxBorderMode,
+      uniqueOpened,
+      showMenuButton,
+      showFastEnter,
+      showRefreshButton,
+      showCrumbs,
+      autoClose,
+      showWorkTab,
+      showLanguage,
+      showNprogress,
+      colorWeak,
+      showSettingGuide,
+      pageTransition,
+      tabStyle,
+      menuOpen,
+      refresh,
+      watermarkVisible,
+      customRadius,
+      holidayFireworksLoaded,
+      showFestivalText,
+      festivalDate,
+      dualMenuShowText,
+      containerWidth,
+      getMenuTheme,
+      isDark,
+      getMenuOpenWidth,
+      getCustomRadius,
+      isShowFireworks,
+      switchMenuLayouts,
+      setMenuOpenWidth,
+      setGlopTheme,
+      switchMenuStyles,
+      setElementTheme,
+      setBorderMode,
+      setContainerWidth,
+      setUniqueOpened,
+      setButton,
+      setFastEnter,
+      setAutoClose,
+      setShowRefreshButton,
+      setCrumbs,
+      setWorkTab,
+      setLanguage,
+      setNprogress,
+      setColorWeak,
+      hideSettingGuide,
+      openSettingGuide,
+      setPageTransition,
+      setTabStyle,
+      setMenuOpen,
+      reload,
+      setWatermarkVisible,
+      setCustomRadius,
+      setholidayFireworksLoaded,
+      setShowFestivalText,
+      setFestivalDate,
+      setDualMenuShowText,
+    };
+  },
+  {
+    persist: {
+      key: 'setting',
+      storage: localStorage,
+    },
+  }
+);

frontend/web/src/store/modules/settings.store.ts

@@ -0,0 +1,300 @@
+import { defaultSettings } from '@/settings';
+import { SidebarColor, ThemeMode } from '@/enums/settings/theme.enum';
+import type { LayoutMode } from '@/enums/settings/layout.enum';
+import { applyTheme, generateThemeColors, toggleDarkMode, toggleSidebarColor } from '@/utils/theme';
+import { SETTINGS_KEYS } from '@/constants';
+
+// 🎯 设置项类型定义
+interface SettingsState {
+  // 界面显示设置
+  settingsVisible: boolean;
+  showTagsView: boolean;
+  showAppLogo: boolean;
+  showWatermark: boolean;
+  showSettings: boolean;
+  showGuide: boolean;
+
+  // 桌面端工具显示设置
+  showMenuSearch: boolean;
+  showFullscreen: boolean;
+  showSizeSelect: boolean;
+  showLangSelect: boolean;
+  showNotification: boolean;
+
+  // 布局设置
+  layout: LayoutMode;
+  sidebarColorScheme: string;
+  grayMode: boolean;
+  userEnableAi: boolean;
+  pageSwitchingAnimation: string;
+
+  // 主题设置
+  theme: ThemeMode;
+  themeColor: string;
+}
+
+// 🎯 可变更的设置项类型
+type MutableSetting = Exclude<keyof SettingsState, 'settingsVisible'>;
+type SettingValue<K extends MutableSetting> = SettingsState[K];
+
+export const useSettingsStore = defineStore('setting', () => {
+  // 🎯 基础设置 - 非持久化
+  const settingsVisible = ref<boolean>(false);
+
+  // 🎯 界面显示设置 - 持久化
+  const showTagsView = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_TAGS_VIEW,
+    defaultSettings.showTagsView
+  );
+  const showAppLogo = useStorage<boolean>(SETTINGS_KEYS.SHOW_APP_LOGO, defaultSettings.showAppLogo);
+  // 是否显示水印
+  const showWatermark = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_WATERMARK,
+    defaultSettings.showWatermark
+  );
+
+  // 是否显示系统设置
+  const showSettings = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_SETTINGS,
+    defaultSettings.showSettings
+  );
+
+  // 是否显示引导功能
+  const showGuide = useStorage<boolean>(SETTINGS_KEYS.SHOW_GUIDE, defaultSettings.showGuide);
+
+  // 🎯 桌面端工具设置 - 持久化
+  const showMenuSearch = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_MENU_SEARCH,
+    defaultSettings.showMenuSearch
+  );
+
+  // 是否显示全屏切换
+  const showFullscreen = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_FULLSCREEN,
+    defaultSettings.showFullscreen
+  );
+
+  // 是否显示布局大小选择
+  const showSizeSelect = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_SIZE_SELECT,
+    defaultSettings.showSizeSelect
+  );
+
+  // 是否显示语言选择
+  const showLangSelect = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_LANG_SELECT,
+    defaultSettings.showLangSelect
+  );
+
+  // 是否显示通知
+  const showNotification = useStorage<boolean>(
+    SETTINGS_KEYS.SHOW_NOTIFICATION,
+    defaultSettings.showNotification
+  );
+
+  // 🎯 布局和主题设置 - 持久化
+  const sidebarColorScheme = useStorage<string>(
+    SETTINGS_KEYS.SIDEBAR_COLOR_SCHEME,
+    defaultSettings.sidebarColorScheme
+  );
+
+  // 布局设置
+  const layout = useStorage<LayoutMode>(SETTINGS_KEYS.LAYOUT, defaultSettings.layout as LayoutMode);
+  // 主题颜色
+  const themeColor = useStorage<string>(SETTINGS_KEYS.THEME_COLOR, defaultSettings.themeColor);
+  // 主题模式
+  const theme = useStorage<ThemeMode>(SETTINGS_KEYS.THEME, defaultSettings.theme);
+
+  // 是否开启灰色模式
+  const grayMode = useStorage<boolean>(SETTINGS_KEYS.GRAY_MODE, defaultSettings.grayMode);
+  // 是否开启AI助手
+  const userEnableAi = useStorage<boolean>(SETTINGS_KEYS.AI_ENABLED, defaultSettings.aiEnabled);
+  // 页面切换动画
+  const pageSwitchingAnimation = useStorage<string>(
+    SETTINGS_KEYS.PAGE_SWITCHING_ANIMATION,
+    defaultSettings.pageSwitchingAnimation
+  );
+
+  // 🎯 设置项映射
+  const settingsMap = {
+    showTagsView,
+    showAppLogo,
+    showWatermark,
+    showSettings,
+    showGuide,
+    showMenuSearch,
+    showFullscreen,
+    showSizeSelect,
+    showLangSelect,
+    showNotification,
+    sidebarColorScheme,
+    layout,
+    grayMode,
+    userEnableAi,
+  } as const;
+
+  // 🎯 监听器 - 主题变化
+  watch(
+    [theme, themeColor],
+    ([newTheme, newThemeColor]) => {
+      toggleDarkMode(newTheme === ThemeMode.DARK);
+      const colors = generateThemeColors(newThemeColor, newTheme);
+      applyTheme(colors);
+    },
+    { immediate: true }
+  );
+
+  // 🎯 监听器 - 侧边栏配色方案变化
+  watch(
+    [sidebarColorScheme],
+    ([newSidebarColorScheme]) => {
+      toggleSidebarColor(newSidebarColorScheme === SidebarColor.CLASSIC_BLUE);
+    },
+    { immediate: true }
+  );
+
+  // 灰色模式监听
+  watch(
+    grayMode,
+    (v) => {
+      document.documentElement.style.filter = v ? 'grayscale(100%)' : '';
+    },
+    { immediate: true }
+  );
+
+  // 🎯 统一的设置更新方法 - 类型安全
+  function updateSetting<K extends keyof typeof settingsMap>(key: K, value: SettingValue<K>): void {
+    const setting = settingsMap[key];
+    if (setting) {
+      (setting as Ref<any>).value = value;
+    }
+  }
+
+  // 🎯 主题相关的专用更新方法
+  function updateTheme(newTheme: ThemeMode): void {
+    theme.value = newTheme;
+  }
+
+  // 更新主题颜色
+  function updateThemeColor(newColor: string): void {
+    themeColor.value = newColor;
+  }
+
+  // 更新侧边栏配色方案
+  function updateSidebarColorScheme(newScheme: string): void {
+    sidebarColorScheme.value = newScheme;
+  }
+
+  // 更新布局
+  function updateLayout(newLayout: LayoutMode): void {
+    layout.value = newLayout;
+  }
+
+  // 🎯 设置面板显示控制
+  function toggleSettingsPanel(): void {
+    settingsVisible.value = !settingsVisible.value;
+  }
+
+  // 显示设置面板
+  function showSettingsPanel(): void {
+    settingsVisible.value = true;
+  }
+
+  // 隐藏设置面板
+  function hideSettingsPanel(): void {
+    settingsVisible.value = false;
+  }
+
+  // 更新AI助手状态
+  function updateUserEnableAi(newValue: boolean): void {
+    userEnableAi.value = newValue;
+  }
+
+  // 更新灰色模式状态
+  function updateGrayMode(newValue: boolean): void {
+    grayMode.value = newValue;
+  }
+
+  // 更新页面切换动画
+  function updatePageSwitchingAnimation(newValue: string): void {
+    pageSwitchingAnimation.value = newValue;
+  }
+
+  // 🎯 批量重置设置
+  function resetSettings(): void {
+    // 界面显示设置
+    showTagsView.value = defaultSettings.showTagsView;
+    showAppLogo.value = defaultSettings.showAppLogo;
+    showWatermark.value = defaultSettings.showWatermark;
+    showSettings.value = defaultSettings.showSettings;
+    showGuide.value = defaultSettings.showGuide;
+
+    // 桌面端工具设置
+    showMenuSearch.value = defaultSettings.showMenuSearch;
+    showFullscreen.value = defaultSettings.showFullscreen;
+    showSizeSelect.value = defaultSettings.showSizeSelect;
+    showLangSelect.value = defaultSettings.showLangSelect;
+    showNotification.value = defaultSettings.showNotification;
+
+    // 布局和主题设置
+    sidebarColorScheme.value = defaultSettings.sidebarColorScheme;
+    layout.value = defaultSettings.layout as LayoutMode;
+    themeColor.value = defaultSettings.themeColor;
+    theme.value = defaultSettings.theme;
+
+    // 系统设置
+    grayMode.value = defaultSettings.grayMode;
+    userEnableAi.value = defaultSettings.aiEnabled;
+    pageSwitchingAnimation.value = defaultSettings.pageSwitchingAnimation;
+  }
+
+  return {
+    // 🎯 基础状态
+    settingsVisible,
+
+    // 🎯 界面显示状态
+    showTagsView,
+    showAppLogo,
+    showWatermark,
+    showSettings,
+    showGuide,
+
+    // 🎯 桌面端工具状态
+    showMenuSearch,
+    showFullscreen,
+    showSizeSelect,
+    showLangSelect,
+    showNotification,
+
+    // 🎯 布局和主题状态
+    sidebarColorScheme,
+    layout,
+    themeColor,
+    theme,
+
+    // 🎯 更新方法
+    updateSetting,
+    updateTheme,
+    updateThemeColor,
+    updateSidebarColorScheme,
+    updateLayout,
+
+    // 🎯 面板控制
+    toggleSettingsPanel,
+    showSettingsPanel,
+    hideSettingsPanel,
+
+    // 🎯 系统设置状态
+    grayMode,
+    userEnableAi,
+    pageSwitchingAnimation,
+    updatePageSwitchingAnimation,
+
+    // 🎯 更新系统设置方法
+    updateUserEnableAi,
+    updateGrayMode,
+
+    // 🎯 重置功能
+    resetSettings,
+  };
+});

frontend/web/src/store/modules/table.ts

@@ -0,0 +1,97 @@
+/**
+ * 表格状态管理模块
+ *
+ * 提供表格显示配置的状态管理
+ *
+ * ## 主要功能
+ *
+ * - 表格尺寸配置（紧凑、默认、宽松）
+ * - 斑马纹显示开关
+ * - 边框显示开关
+ * - 表头背景显示开关
+ * - 全屏模式开关
+ *
+ * ## 使用场景
+ * - 表格组件样式配置
+ * - 用户表格偏好设置
+ * - 表格工具栏功能控制
+ *
+ * ## 持久化
+ *
+ * - 使用 localStorage 存储
+ * - 存储键：sys-v{version}-table
+ * - 用户配置跨页面保持
+ *
+ * @module store/modules/table
+ * @author Fastapi Admin Team
+ */
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+import { TableSizeEnum } from '@/enums/formEnum';
+
+// 表格
+export const useTableStore = defineStore(
+  'tableStore',
+  () => {
+    // 表格大小
+    const tableSize = ref(TableSizeEnum.DEFAULT);
+    // 斑马纹
+    const isZebra = ref(false);
+    // 边框
+    const isBorder = ref(false);
+    // 表头背景
+    const isHeaderBackground = ref(false);
+
+    // 是否全屏
+    const isFullScreen = ref(false);
+
+    /**
+     * 设置表格大小
+     * @param size 表格大小枚举值
+     */
+    const setTableSize = (size: TableSizeEnum) => (tableSize.value = size);
+
+    /**
+     * 设置斑马纹显示状态
+     * @param value 是否显示斑马纹
+     */
+    const setIsZebra = (value: boolean) => (isZebra.value = value);
+
+    /**
+     * 设置表格边框显示状态
+     * @param value 是否显示边框
+     */
+    const setIsBorder = (value: boolean) => (isBorder.value = value);
+
+    /**
+     * 设置表头背景显示状态
+     * @param value 是否显示表头背景
+     */
+    const setIsHeaderBackground = (value: boolean) => (isHeaderBackground.value = value);
+
+    /**
+     * 设置是否全屏
+     * @param value 是否全屏
+     */
+    const setIsFullScreen = (value: boolean) => (isFullScreen.value = value);
+
+    return {
+      tableSize,
+      isZebra,
+      isBorder,
+      isHeaderBackground,
+      setTableSize,
+      setIsZebra,
+      setIsBorder,
+      setIsHeaderBackground,
+      isFullScreen,
+      setIsFullScreen,
+    };
+  },
+  {
+    persist: {
+      key: 'table',
+      storage: localStorage,
+    },
+  }
+);

frontend/web/src/store/modules/tags-view.store.ts

@@ -0,0 +1,258 @@
+// tags缓存
+export const useTagsViewStore = defineStore('tagsView', () => {
+  const visitedViews = ref<TagView[]>([]);
+  const cachedViews = ref<string[]>([]);
+  const router = useRouter();
+  const route = useRoute();
+
+  /**
+   * 添加已访问视图到已访问视图列表中
+   */
+  function addVisitedView(view: TagView) {
+    // 如果已经存在于已访问的视图列表中或者是重定向地址，则不再添加
+    if (view.path.startsWith('/redirect')) {
+      return;
+    }
+    if (visitedViews.value.some((v) => v.name === view.name)) {
+      return;
+    }
+    // 如果视图是固定的（affix），则在已访问的视图列表的开头添加
+    if (view.affix) {
+      visitedViews.value.unshift(view);
+    } else {
+      // 如果视图不是固定的，则在已访问的视图列表的末尾添加
+      visitedViews.value.push(view);
+    }
+  }
+
+  /**
+   * 添加缓存视图到缓存视图列表中
+   */
+  function addCachedView(view: TagView) {
+    const viewName = view.name;
+    // 如果缓存视图名称已经存在于缓存视图列表中，则不再添加
+    if (cachedViews.value.includes(viewName)) {
+      return;
+    }
+
+    // 如果视图需要缓存（keepAlive），则将其路由名称添加到缓存视图列表中
+    if (view.keepAlive) {
+      cachedViews.value.push(viewName);
+    }
+  }
+
+  /**
+   * 从已访问视图列表中删除指定的视图
+   */
+  function delVisitedView(view: TagView) {
+    return new Promise((resolve) => {
+      for (const [i, v] of visitedViews.value.entries()) {
+        // 找到与指定视图路径匹配的视图，在已访问视图列表中删除该视图
+        if (v.path === view.path) {
+          visitedViews.value.splice(i, 1);
+          break;
+        }
+      }
+      resolve([...visitedViews.value]);
+    });
+  }
+
+  function delCachedView(view: TagView) {
+    const viewName = view.name;
+    return new Promise((resolve) => {
+      const index = cachedViews.value.indexOf(viewName);
+      if (index > -1) {
+        cachedViews.value.splice(index, 1);
+      }
+      resolve([...cachedViews.value]);
+    });
+  }
+  function delOtherVisitedViews(view: TagView) {
+    return new Promise((resolve) => {
+      visitedViews.value = visitedViews.value.filter((v) => {
+        return v?.affix || v.path === view.path;
+      });
+      resolve([...visitedViews.value]);
+    });
+  }
+
+  function delOtherCachedViews(view: TagView) {
+    const viewName = view.name as string;
+    return new Promise((resolve) => {
+      const index = cachedViews.value.indexOf(viewName);
+      if (index > -1) {
+        cachedViews.value = cachedViews.value.slice(index, index + 1);
+      } else {
+        // if index = -1, there is no cached tags
+        cachedViews.value = [];
+      }
+      resolve([...cachedViews.value]);
+    });
+  }
+
+  function updateVisitedView(view: TagView) {
+    for (let v of visitedViews.value) {
+      if (v.path === view.path) {
+        v = Object.assign(v, view);
+        break;
+      }
+    }
+  }
+
+  function addView(view: TagView) {
+    addVisitedView(view);
+    addCachedView(view);
+  }
+
+  function delView(view: TagView) {
+    return new Promise((resolve) => {
+      delVisitedView(view);
+      delCachedView(view);
+      resolve({
+        visitedViews: [...visitedViews.value],
+        cachedViews: [...cachedViews.value],
+      });
+    });
+  }
+
+  function delOtherViews(view: TagView) {
+    return new Promise((resolve) => {
+      delOtherVisitedViews(view);
+      delOtherCachedViews(view);
+      resolve({
+        visitedViews: [...visitedViews.value],
+        cachedViews: [...cachedViews.value],
+      });
+    });
+  }
+
+  function delLeftViews(view: TagView) {
+    return new Promise((resolve) => {
+      const currIndex = visitedViews.value.findIndex((v) => v.path === view.path);
+      if (currIndex === -1) {
+        return;
+      }
+      visitedViews.value = visitedViews.value.filter((item, index) => {
+        if (index >= currIndex || item?.affix) {
+          return true;
+        }
+
+        const cacheIndex = cachedViews.value.indexOf(item.name);
+        if (cacheIndex > -1) {
+          cachedViews.value.splice(cacheIndex, 1);
+        }
+        return false;
+      });
+      resolve({
+        visitedViews: [...visitedViews.value],
+      });
+    });
+  }
+
+  function delRightViews(view: TagView) {
+    return new Promise((resolve) => {
+      const currIndex = visitedViews.value.findIndex((v) => v.path === view.path);
+      if (currIndex === -1) {
+        return;
+      }
+      visitedViews.value = visitedViews.value.filter((item, index) => {
+        if (index <= currIndex || item?.affix) {
+          return true;
+        }
+      });
+      resolve({
+        visitedViews: [...visitedViews.value],
+      });
+    });
+  }
+
+  function delAllViews() {
+    return new Promise((resolve) => {
+      const affixTags = visitedViews.value.filter((tag) => tag?.affix);
+      visitedViews.value = affixTags;
+      cachedViews.value = [];
+      resolve({
+        visitedViews: [...visitedViews.value],
+        cachedViews: [...cachedViews.value],
+      });
+    });
+  }
+
+  function delAllVisitedViews() {
+    return new Promise((resolve) => {
+      const affixTags = visitedViews.value.filter((tag) => tag?.affix);
+      visitedViews.value = affixTags;
+      resolve([...visitedViews.value]);
+    });
+  }
+
+  function delAllCachedViews() {
+    return new Promise((resolve) => {
+      cachedViews.value = [];
+      resolve([...cachedViews.value]);
+    });
+  }
+
+  /**
+   * 关闭当前tagView
+   */
+  function closeCurrentView() {
+    const tags: TagView = {
+      name: route.name as string,
+      title: route.meta.title as string,
+      path: route.path,
+      fullPath: route.fullPath,
+      affix: route.meta?.affix,
+      keepAlive: route.meta?.keepAlive,
+      query: route.query,
+    };
+    delView(tags).then((res: any) => {
+      if (isActive(tags)) {
+        toLastView(res.visitedViews, tags);
+      }
+    });
+  }
+
+  function isActive(tag: TagView) {
+    return tag.path === route.path;
+  }
+
+  function toLastView(visitedViews: TagView[], view?: TagView) {
+    const latestView = visitedViews.slice(-1)[0];
+    if (latestView && latestView.fullPath) {
+      router.push(latestView.fullPath);
+    } else {
+      // now the default is to redirect to the home page if there is no tags-view,
+      // you can adjust it according to your needs.
+      if (view?.name === 'Dashboard') {
+        // to reload home page
+        router.replace('/redirect' + view.fullPath);
+      } else {
+        router.push('/');
+      }
+    }
+  }
+
+  return {
+    visitedViews,
+    cachedViews,
+    addVisitedView,
+    addCachedView,
+    delVisitedView,
+    delCachedView,
+    delOtherVisitedViews,
+    delOtherCachedViews,
+    updateVisitedView,
+    addView,
+    delView,
+    delOtherViews,
+    delLeftViews,
+    delRightViews,
+    delAllViews,
+    delAllVisitedViews,
+    delAllCachedViews,
+    closeCurrentView,
+    isActive,
+    toLastView,
+  };
+});

frontend/web/src/store/modules/user.store.ts

@@ -0,0 +1,180 @@
+import { store, useTagsViewStore, usePermissionStoreHook, useDictStoreHook } from '@/store';
+
+import AuthAPI, { type LoginFormData } from '@/api/module_system/auth';
+import UserAPI, { type UserInfo } from '@/api/module_system/user';
+import type { MenuTable } from '@/api/module_system/menu';
+import { Auth } from '@/utils/auth';
+import { ResultEnum } from '@/enums';
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    basicInfo: {} as UserInfo,
+    routeList: [] as MenuTable[],
+    prems: [] as string[],
+    hasGetRoute: false,
+
+    // 记住我状态
+    rememberMe: ref(Auth.getRememberMe()),
+  }),
+
+  getters: {
+    getBasicInfo: (state) => state.basicInfo,
+    getRouteList: (state) => state.routeList,
+    getPerms: (state) => state.prems,
+    getHasGetRoute: (state) => state.hasGetRoute,
+  },
+
+  actions: {
+    // 获取用户信息
+    async getUserInfo() {
+      const response = await UserAPI.getCurrentUserInfo();
+      const routers: MenuTable[] = response.data.data.menus || [];
+      delete response.data.data.menus;
+      this.basicInfo = { ...this.basicInfo, ...response.data.data };
+      // 然后设置路由信息
+      this.setRoute(routers);
+    },
+
+    // 设置用户信息
+    setUserInfo(info: UserInfo) {
+      this.basicInfo = info;
+      // 设置用户信息后自动更新权限
+      this.setPermissions([]);
+    },
+
+    // 设置路由
+    setRoute(routers: MenuTable[]) {
+      this.routeList = routers;
+      this.hasGetRoute = true;
+      // 设置路由后自动更新权限
+      this.setPermissions(routers);
+    },
+
+    setPermissions(menus: MenuTable[]) {
+      this.prems = []; // 先清空现有权限
+
+      // 确保 basicInfo.roles 存在，避免空值错误
+      if (!this.basicInfo.roles) {
+        return;
+      }
+
+      // 合并所有角色的菜单列表，使用数组扁平化方法简化代码并过滤undefined
+      const roleMenus = this.basicInfo.roles
+        .filter((role) => role.menus && role.menus.length > 0)
+        .flatMap((role) => role.menus)
+        .filter((menu): menu is MenuTable => menu !== undefined);
+
+      // 合并传入的菜单和角色菜单
+      const allMenus = [...menus, ...roleMenus];
+
+      const permissionSet = new Set<string>();
+      const collect = (items: MenuTable[]) => {
+        items.forEach((item) => {
+          // 收集当前菜单的权限
+          if (item.permission) {
+            permissionSet.add(item.permission);
+          }
+
+          // 递归收集子菜单的权限，确保子菜单不包含undefined
+          if (item.children && item.children.length > 0) {
+            collect(item.children.filter((child): child is MenuTable => child !== undefined));
+          }
+        });
+      };
+
+      // 收集所有权限
+      collect(allMenus);
+      this.prems = Array.from(permissionSet);
+    },
+    setAvatar(avatar: string) {
+      this.basicInfo = { ...this.basicInfo, avatar };
+    },
+    clearUserInfo() {
+      this.basicInfo = {};
+      this.routeList = [];
+      this.hasGetRoute = false;
+    },
+
+    // 登录
+    async login(LoginFormData: LoginFormData) {
+      const response = await AuthAPI.login(LoginFormData);
+      if (response.data.code === ResultEnum.SUCCESS) {
+        ElNotification({
+          title: '通知',
+          message: response.data.msg,
+          type: 'success',
+        });
+      }
+      this.rememberMe = LoginFormData.remember;
+      Auth.setTokens(
+        response.data.data.access_token,
+        response.data.data.refresh_token,
+        this.rememberMe
+      );
+    },
+
+    // 登出
+    async logout() {
+      const response = await AuthAPI.logout({ token: Auth.getAccessToken() });
+      if (response.data.code === ResultEnum.SUCCESS) {
+        ElNotification({
+          title: '通知',
+          message: response.data.msg,
+          type: 'success',
+        });
+      }
+      this.resetAllState();
+    },
+
+    // 重置所有状态
+    resetAllState() {
+      // 重置用户状态
+      Auth.clearAuth();
+      // 重置用户信息
+      this.clearUserInfo();
+      // 重置路由
+      usePermissionStoreHook().resetRouter();
+      // 清除标签视图
+      useTagsViewStore().delAllViews();
+      // 重置字典
+      useDictStoreHook().clearDictData();
+
+      return Promise.resolve();
+    },
+
+    // 刷新token
+    refreshToken() {
+      const refreshToken = Auth.getRefreshToken();
+
+      if (!refreshToken) {
+        return Promise.reject(new Error('没有有效的刷新令牌'));
+      }
+
+      return new Promise<void>((resolve, reject) => {
+        AuthAPI.refreshToken({ refresh_token: refreshToken })
+          .then((response) => {
+            // 更新令牌，保持当前记住我状态
+            Auth.setTokens(
+              response.data.data.access_token,
+              response.data.data.refresh_token,
+              Auth.getRememberMe()
+            );
+            resolve();
+          })
+          .catch((error) => {
+            reject(error);
+          });
+      });
+    },
+  },
+
+  persist: true,
+});
+
+/**
+ * 在组件外部使用UserStore的钩子函数
+ * @see https://pinia.vuejs.org/core-concepts/outside-component-usage.html
+ */
+export function useUserStoreHook() {
+  return useUserStore(store);
+}

frontend/web/src/store/modules/user.ts

@@ -0,0 +1,235 @@
+/**
+ * 用户状态管理模块
+ *
+ * 提供用户相关的状态管理
+ *
+ * ## 主要功能
+ *
+ * - 用户登录状态管理
+ * - 用户信息存储
+ * - 访问令牌和刷新令牌管理
+ * - 语言设置
+ * - 搜索历史记录
+ * - 锁屏状态和密码管理
+ * - 登出清理逻辑
+ *
+ * ## 使用场景
+ *
+ * - 用户登录和认证
+ * - 权限验证
+ * - 个人信息展示
+ * - 多语言切换
+ * - 锁屏功能
+ * - 搜索历史管理
+ *
+ * ## 持久化
+ *
+ * - 使用 localStorage 存储
+ * - 存储键：sys-v{version}-user
+ * - 登出时自动清理
+ *
+ * @module store/modules/user
+ * @author Fastapi Admin Team
+ */
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import { LanguageEnum } from '@/enums/appEnum';
+import router from '@/router';
+import { useSettingStore } from './setting';
+import { useWorktabStore } from './worktab';
+import { AppRouteRecord } from '@/types/router';
+import { setPageTitle } from '@/utils/router';
+import { resetRouterState } from '@/router/guards/beforeEach';
+import { useMenuStore } from './menu';
+import { StorageConfig } from '@/utils/storage/storage-config';
+
+/**
+ * 用户状态管理
+ * 管理用户登录状态、个人信息、语言设置、搜索历史、锁屏状态等
+ */
+export const useUserStore = defineStore(
+  'userStore',
+  () => {
+    // 语言设置
+    const language = ref(LanguageEnum.ZH);
+    // 登录状态
+    const isLogin = ref(false);
+    // 锁屏状态
+    const isLock = ref(false);
+    // 锁屏密码
+    const lockPassword = ref('');
+    // 用户信息
+    const info = ref<Partial<Api.Auth.UserInfo>>({});
+    // 搜索历史记录
+    const searchHistory = ref<AppRouteRecord[]>([]);
+    // 访问令牌
+    const accessToken = ref('');
+    // 刷新令牌
+    const refreshToken = ref('');
+
+    // 计算属性：获取用户信息
+    const getUserInfo = computed(() => info.value);
+    // 计算属性：获取设置状态
+    const getSettingState = computed(() => useSettingStore().$state);
+    // 计算属性：获取工作台状态
+    const getWorktabState = computed(() => useWorktabStore().$state);
+
+    /**
+     * 设置用户信息
+     * @param newInfo 新的用户信息
+     */
+    const setUserInfo = (newInfo: Api.Auth.UserInfo) => {
+      info.value = newInfo;
+    };
+
+    /**
+     * 设置登录状态
+     * @param status 登录状态
+     */
+    const setLoginStatus = (status: boolean) => {
+      isLogin.value = status;
+    };
+
+    /**
+     * 设置语言
+     * @param lang 语言枚举值
+     */
+    const setLanguage = (lang: LanguageEnum) => {
+      setPageTitle(router.currentRoute.value);
+      language.value = lang;
+    };
+
+    /**
+     * 设置搜索历史
+     * @param list 搜索历史列表
+     */
+    const setSearchHistory = (list: AppRouteRecord[]) => {
+      searchHistory.value = list;
+    };
+
+    /**
+     * 设置锁屏状态
+     * @param status 锁屏状态
+     */
+    const setLockStatus = (status: boolean) => {
+      isLock.value = status;
+    };
+
+    /**
+     * 设置锁屏密码
+     * @param password 锁屏密码
+     */
+    const setLockPassword = (password: string) => {
+      lockPassword.value = password;
+    };
+
+    /**
+     * 设置令牌
+     * @param newAccessToken 访问令牌
+     * @param newRefreshToken 刷新令牌（可选）
+     */
+    const setToken = (newAccessToken: string, newRefreshToken?: string) => {
+      accessToken.value = newAccessToken;
+      if (newRefreshToken) {
+        refreshToken.value = newRefreshToken;
+      }
+    };
+
+    /**
+     * 退出登录
+     * 清空所有用户相关状态并跳转到登录页
+     * 如果是同一账号重新登录，保留工作台标签页
+     */
+    const logOut = () => {
+      // 保存当前用户 ID，用于下次登录时判断是否为同一用户
+      const currentUserId = info.value.userId;
+      if (currentUserId) {
+        localStorage.setItem(StorageConfig.LAST_USER_ID_KEY, String(currentUserId));
+      }
+
+      // 清空用户信息
+      info.value = {};
+      // 重置登录状态
+      isLogin.value = false;
+      // 重置锁屏状态
+      isLock.value = false;
+      // 清空锁屏密码
+      lockPassword.value = '';
+      // 清空访问令牌
+      accessToken.value = '';
+      // 清空刷新令牌
+      refreshToken.value = '';
+      // 注意：不清空工作台标签页，等下次登录时根据用户判断
+      // 移除iframe路由缓存
+      sessionStorage.removeItem('iframeRoutes');
+      // 清空主页路径
+      useMenuStore().setHomePath('');
+      // 重置路由状态
+      resetRouterState(500);
+      // 跳转到登录页，携带当前路由作为 redirect 参数
+      const currentRoute = router.currentRoute.value;
+      const redirect = currentRoute.path !== '/login' ? currentRoute.fullPath : undefined;
+      router.push({
+        name: 'Login',
+        query: redirect ? { redirect } : undefined,
+      });
+    };
+
+    /**
+     * 检查并清理工作台标签页
+     * 如果不是同一用户登录，清空工作台标签页
+     * 应在登录成功后调用
+     */
+    const checkAndClearWorktabs = () => {
+      const lastUserId = localStorage.getItem(StorageConfig.LAST_USER_ID_KEY);
+      const currentUserId = info.value.userId;
+
+      // 无法获取当前用户 ID，跳过检查
+      if (!currentUserId) return;
+
+      // 首次登录或缓存已清除，保留现有标签页
+      if (!lastUserId) {
+        return;
+      }
+
+      // 不同用户登录，清空工作台标签页
+      if (String(currentUserId) !== lastUserId) {
+        const worktabStore = useWorktabStore();
+        worktabStore.opened = [];
+        worktabStore.keepAliveExclude = [];
+      }
+
+      // 清除临时存储
+      localStorage.removeItem(StorageConfig.LAST_USER_ID_KEY);
+    };
+
+    return {
+      language,
+      isLogin,
+      isLock,
+      lockPassword,
+      info,
+      searchHistory,
+      accessToken,
+      refreshToken,
+      getUserInfo,
+      getSettingState,
+      getWorktabState,
+      setUserInfo,
+      setLoginStatus,
+      setLanguage,
+      setSearchHistory,
+      setLockStatus,
+      setLockPassword,
+      setToken,
+      logOut,
+      checkAndClearWorktabs,
+    };
+  },
+  {
+    persist: {
+      key: 'user',
+      storage: localStorage,
+    },
+  }
+);

frontend/web/src/store/modules/worktab.ts

@@ -0,0 +1,568 @@
+/**
+ * 工作标签页状态管理模块
+ *
+ * 提供多标签页功能的完整状态管理
+ *
+ * ## 主要功能
+ *
+ * - 标签页打开和关闭
+ * - 标签页固定和取消固定
+ * - 批量关闭（左侧、右侧、其他、全部）
+ * - 标签页缓存管理（KeepAlive）
+ * - 标签页标题自定义
+ * - 标签页路由验证
+ * - 动态路由参数处理
+ *
+ * ## 使用场景
+ *
+ * - 多标签页导航
+ * - 页面缓存控制
+ * - 标签页右键菜单
+ * - 固定常用页面
+ * - 批量关闭标签
+ *
+ * ## 核心特性
+ *
+ * - 智能标签页复用（同路由名称复用）
+ * - 固定标签页保护（不可关闭）
+ * - KeepAlive 缓存排除管理
+ * - 路由有效性验证
+ * - 首页自动保留
+ *
+ * ## 持久化
+ * - 使用 localStorage 存储
+ * - 存储键：sys-v{version}-worktab
+ * - 刷新页面保持标签状态
+ *
+ * @module store/modules/worktab
+ * @author Fastapi Admin Team
+ */
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import router from '@/router';
+import { LocationQueryRaw, Router } from 'vue-router';
+import { WorkTab } from '@/types';
+import { useCommon } from '@/hooks/core/useCommon';
+
+interface WorktabState {
+  current: Partial<WorkTab>;
+  opened: WorkTab[];
+  keepAliveExclude: string[];
+}
+
+/**
+ * 工作台标签页管理 Store
+ */
+export const useWorktabStore = defineStore(
+  'worktabStore',
+  () => {
+    // 状态定义
+    const current = ref<Partial<WorkTab>>({});
+    const opened = ref<WorkTab[]>([]);
+    const keepAliveExclude = ref<string[]>([]);
+
+    // 计算属性
+    const hasOpenedTabs = computed(() => opened.value.length > 0);
+    const hasMultipleTabs = computed(() => opened.value.length > 1);
+    const currentTabIndex = computed(() =>
+      current.value.path ? opened.value.findIndex((tab) => tab.path === current.value.path) : -1
+    );
+
+    /**
+     * 查找标签页索引
+     */
+    const findTabIndex = (path: string): number => {
+      return opened.value.findIndex((tab) => tab.path === path);
+    };
+
+    /**
+     * 获取标签页
+     */
+    const getTab = (path: string): WorkTab | undefined => {
+      return opened.value.find((tab) => tab.path === path);
+    };
+
+    /**
+     * 检查标签页是否可关闭
+     */
+    const isTabClosable = (tab: WorkTab): boolean => {
+      return !tab.fixedTab;
+    };
+
+    /**
+     * 安全的路由跳转
+     */
+    const safeRouterPush = (tab: Partial<WorkTab>): void => {
+      if (!tab.path) {
+        console.warn('尝试跳转到无效路径的标签页');
+        return;
+      }
+
+      try {
+        router.push({
+          path: tab.path,
+          query: tab.query as LocationQueryRaw,
+        });
+      } catch (error) {
+        console.error('路由跳转失败:', error);
+      }
+    };
+
+    /**
+     * 打开或激活一个选项卡
+     */
+    const openTab = (tab: WorkTab): void => {
+      if (!tab.path) {
+        console.warn('尝试打开无效的标签页');
+        return;
+      }
+
+      // 从 keepAlive 排除列表中移除
+      if (tab.name) {
+        removeKeepAliveExclude(tab.name);
+      }
+
+      // 先根据路由名称查找（应对动态路由参数导致的多开问题），找不到再根据路径查找
+      let existingIndex = -1;
+      if (tab.name) {
+        existingIndex = opened.value.findIndex((t) => t.name === tab.name);
+      }
+      if (existingIndex === -1) {
+        existingIndex = findTabIndex(tab.path);
+      }
+
+      if (existingIndex === -1) {
+        // 新增标签页
+        const insertIndex = tab.fixedTab ? findFixedTabInsertIndex() : opened.value.length;
+        const newTab = { ...tab };
+
+        if (tab.fixedTab) {
+          opened.value.splice(insertIndex, 0, newTab);
+        } else {
+          opened.value.push(newTab);
+        }
+
+        current.value = newTab;
+      } else {
+        // 更新现有标签页（当动态路由参数或查询变更时，复用同一标签）
+        const existingTab = opened.value[existingIndex];
+
+        opened.value[existingIndex] = {
+          ...existingTab,
+          path: tab.path,
+          params: tab.params,
+          query: tab.query,
+          title: tab.title || existingTab.title,
+          fixedTab: tab.fixedTab ?? existingTab.fixedTab,
+          keepAlive: tab.keepAlive ?? existingTab.keepAlive,
+          name: tab.name || existingTab.name,
+          icon: tab.icon || existingTab.icon,
+        };
+
+        current.value = opened.value[existingIndex];
+      }
+    };
+
+    /**
+     * 查找固定标签页的插入位置
+     */
+    const findFixedTabInsertIndex = (): number => {
+      let insertIndex = 0;
+      for (let i = 0; i < opened.value.length; i++) {
+        if (opened.value[i].fixedTab) {
+          insertIndex = i + 1;
+        } else {
+          break;
+        }
+      }
+      return insertIndex;
+    };
+
+    /**
+     * 关闭指定的选项卡
+     */
+    const removeTab = (path: string): void => {
+      const targetTab = getTab(path);
+      const targetIndex = findTabIndex(path);
+
+      if (targetIndex === -1) {
+        console.warn(`尝试关闭不存在的标签页: ${path}`);
+        return;
+      }
+
+      if (targetTab && !isTabClosable(targetTab)) {
+        console.warn(`尝试关闭固定标签页: ${path}`);
+        return;
+      }
+
+      // 从标签页列表中移除
+      opened.value.splice(targetIndex, 1);
+
+      // 处理缓存排除
+      if (targetTab?.name) {
+        addKeepAliveExclude(targetTab);
+      }
+
+      const { homePath } = useCommon();
+
+      // 如果关闭后无标签页，跳转首页
+      if (!hasOpenedTabs.value) {
+        if (path !== homePath.value) {
+          current.value = {};
+          safeRouterPush({ path: homePath.value });
+        }
+        return;
+      }
+
+      // 如果关闭的是当前激活标签，需要激活其他标签
+      if (current.value.path === path) {
+        const newIndex = targetIndex >= opened.value.length ? opened.value.length - 1 : targetIndex;
+        current.value = opened.value[newIndex];
+        safeRouterPush(current.value);
+      }
+    };
+
+    /**
+     * 关闭左侧选项卡
+     */
+    const removeLeft = (path: string): void => {
+      const targetIndex = findTabIndex(path);
+
+      if (targetIndex === -1) {
+        console.warn(`尝试关闭左侧标签页，但目标标签页不存在: ${path}`);
+        return;
+      }
+
+      // 获取左侧可关闭的标签页
+      const leftTabs = opened.value.slice(0, targetIndex);
+      const closableLeftTabs = leftTabs.filter(isTabClosable);
+
+      if (closableLeftTabs.length === 0) {
+        console.warn('左侧没有可关闭的标签页');
+        return;
+      }
+
+      // 标记为缓存排除
+      markTabsToRemove(closableLeftTabs);
+
+      // 移除左侧可关闭的标签页
+      opened.value = opened.value.filter(
+        (tab, index) => index >= targetIndex || !isTabClosable(tab)
+      );
+
+      // 确保当前标签是激活状态
+      const targetTab = getTab(path);
+      if (targetTab) {
+        current.value = targetTab;
+      }
+    };
+
+    /**
+     * 关闭右侧选项卡
+     */
+    const removeRight = (path: string): void => {
+      const targetIndex = findTabIndex(path);
+
+      if (targetIndex === -1) {
+        console.warn(`尝试关闭右侧标签页，但目标标签页不存在: ${path}`);
+        return;
+      }
+
+      // 获取右侧可关闭的标签页
+      const rightTabs = opened.value.slice(targetIndex + 1);
+      const closableRightTabs = rightTabs.filter(isTabClosable);
+
+      if (closableRightTabs.length === 0) {
+        console.warn('右侧没有可关闭的标签页');
+        return;
+      }
+
+      // 标记为缓存排除
+      markTabsToRemove(closableRightTabs);
+
+      // 移除右侧可关闭的标签页
+      opened.value = opened.value.filter(
+        (tab, index) => index <= targetIndex || !isTabClosable(tab)
+      );
+
+      // 确保当前标签是激活状态
+      const targetTab = getTab(path);
+      if (targetTab) {
+        current.value = targetTab;
+      }
+    };
+
+    /**
+     * 关闭其他选项卡
+     */
+    const removeOthers = (path: string): void => {
+      const targetTab = getTab(path);
+
+      if (!targetTab) {
+        console.warn(`尝试关闭其他标签页，但目标标签页不存在: ${path}`);
+        return;
+      }
+
+      // 获取其他可关闭的标签页
+      const otherTabs = opened.value.filter((tab) => tab.path !== path);
+      const closableTabs = otherTabs.filter(isTabClosable);
+
+      if (closableTabs.length === 0) {
+        console.warn('没有其他可关闭的标签页');
+        return;
+      }
+
+      // 标记为缓存排除
+      markTabsToRemove(closableTabs);
+
+      // 只保留当前标签和固定标签
+      opened.value = opened.value.filter((tab) => tab.path === path || !isTabClosable(tab));
+
+      // 确保当前标签是激活状态
+      current.value = targetTab;
+    };
+
+    /**
+     * 关闭所有可关闭的标签页
+     */
+    const removeAll = (): void => {
+      const { homePath } = useCommon();
+      const hasFixedTabs = opened.value.some((tab) => tab.fixedTab);
+
+      // 获取可关闭的标签页
+      const closableTabs = opened.value.filter((tab) => {
+        if (!isTabClosable(tab)) return false;
+        // 如果有固定标签，则所有可关闭的都可以关闭；否则保留首页
+        return hasFixedTabs || tab.path !== homePath.value;
+      });
+
+      if (closableTabs.length === 0) {
+        console.warn('没有可关闭的标签页');
+        return;
+      }
+
+      // 标记为缓存排除
+      markTabsToRemove(closableTabs);
+
+      // 保留不可关闭的标签页和首页（当没有固定标签时）
+      opened.value = opened.value.filter((tab) => {
+        return !isTabClosable(tab) || (!hasFixedTabs && tab.path === homePath.value);
+      });
+
+      // 处理激活状态
+      if (!hasOpenedTabs.value) {
+        current.value = {};
+        safeRouterPush({ path: homePath.value });
+        return;
+      }
+
+      // 选择激活的标签页：优先首页，其次第一个可用标签
+      const homeTab = opened.value.find((tab) => tab.path === homePath.value);
+      const targetTab = homeTab || opened.value[0];
+
+      current.value = targetTab;
+      safeRouterPush(targetTab);
+    };
+
+    /**
+     * 将指定选项卡添加到 keepAlive 排除列表中
+     */
+    const addKeepAliveExclude = (tab: WorkTab): void => {
+      if (!tab.keepAlive || !tab.name) return;
+
+      if (!keepAliveExclude.value.includes(tab.name)) {
+        keepAliveExclude.value.push(tab.name);
+      }
+    };
+
+    /**
+     * 从 keepAlive 排除列表中移除指定组件名称
+     */
+    const removeKeepAliveExclude = (name: string): void => {
+      if (!name) return;
+
+      keepAliveExclude.value = keepAliveExclude.value.filter((item) => item !== name);
+    };
+
+    /**
+     * 将传入的一组选项卡的组件名称标记为排除缓存
+     */
+    const markTabsToRemove = (tabs: WorkTab[]): void => {
+      tabs.forEach((tab) => {
+        if (tab.name) {
+          addKeepAliveExclude(tab);
+        }
+      });
+    };
+
+    /**
+     * 切换指定标签页的固定状态
+     */
+    const toggleFixedTab = (path: string): void => {
+      const targetIndex = findTabIndex(path);
+
+      if (targetIndex === -1) {
+        console.warn(`尝试切换不存在标签页的固定状态: ${path}`);
+        return;
+      }
+
+      const tab = { ...opened.value[targetIndex] };
+      tab.fixedTab = !tab.fixedTab;
+
+      // 移除原位置
+      opened.value.splice(targetIndex, 1);
+
+      if (tab.fixedTab) {
+        // 固定标签插入到所有固定标签的末尾
+        const firstNonFixedIndex = opened.value.findIndex((t) => !t.fixedTab);
+        const insertIndex = firstNonFixedIndex === -1 ? opened.value.length : firstNonFixedIndex;
+        opened.value.splice(insertIndex, 0, tab);
+      } else {
+        // 非固定标签插入到所有固定标签后
+        const fixedCount = opened.value.filter((t) => t.fixedTab).length;
+        opened.value.splice(fixedCount, 0, tab);
+      }
+
+      // 更新当前标签引用
+      if (current.value.path === path) {
+        current.value = tab;
+      }
+    };
+
+    /**
+     * 验证工作台标签页的路由有效性
+     */
+    const validateWorktabs = (routerInstance: Router): void => {
+      try {
+        // 动态路由校验：优先使用路由 name 判断有效性；否则用 resolve 匹配参数化路径
+        const isTabRouteValid = (tab: Partial<WorkTab>): boolean => {
+          try {
+            if (tab.name) {
+              const routes = routerInstance.getRoutes();
+              if (routes.some((r) => r.name === tab.name)) return true;
+            }
+            if (tab.path) {
+              const resolved = routerInstance.resolve({
+                path: tab.path,
+                query: (tab.query as LocationQueryRaw) || undefined,
+              });
+              return resolved.matched.length > 0;
+            }
+            return false;
+          } catch {
+            return false;
+          }
+        };
+
+        // 过滤出有效的标签页
+        const validTabs = opened.value.filter((tab) => isTabRouteValid(tab));
+
+        if (validTabs.length !== opened.value.length) {
+          console.warn('发现无效的标签页路由，已自动清理');
+          opened.value = validTabs;
+        }
+
+        // 验证当前激活标签的有效性
+        const isCurrentValid = current.value && isTabRouteValid(current.value);
+
+        if (!isCurrentValid && validTabs.length > 0) {
+          console.warn('当前激活标签无效，已自动切换');
+          current.value = validTabs[0];
+        } else if (!isCurrentValid) {
+          current.value = {};
+        }
+      } catch (error) {
+        console.error('验证工作台标签页失败:', error);
+      }
+    };
+
+    /**
+     * 清空所有状态（用于登出等场景）
+     */
+    const clearAll = (): void => {
+      current.value = {};
+      opened.value = [];
+      keepAliveExclude.value = [];
+    };
+
+    /**
+     * 获取状态快照（用于持久化存储）
+     */
+    const getStateSnapshot = (): WorktabState => {
+      return {
+        current: { ...current.value },
+        opened: [...opened.value],
+        keepAliveExclude: [...keepAliveExclude.value],
+      };
+    };
+
+    /**
+     * 获取标签页标题
+     */
+    const getTabTitle = (path: string): WorkTab | undefined => {
+      const tab = getTab(path);
+      return tab;
+    };
+
+    /**
+     * 更新标签页标题
+     */
+    const updateTabTitle = (path: string, title: string): void => {
+      const tab = getTab(path);
+      if (tab) {
+        tab.customTitle = title;
+      }
+    };
+
+    /**
+     * 重置标签页标题
+     */
+    const resetTabTitle = (path: string): void => {
+      const tab = getTab(path);
+      if (tab) {
+        tab.customTitle = '';
+      }
+    };
+
+    return {
+      // 状态
+      current,
+      opened,
+      keepAliveExclude,
+
+      // 计算属性
+      hasOpenedTabs,
+      hasMultipleTabs,
+      currentTabIndex,
+
+      // 方法
+      openTab,
+      removeTab,
+      removeLeft,
+      removeRight,
+      removeOthers,
+      removeAll,
+      toggleFixedTab,
+      validateWorktabs,
+      clearAll,
+      getStateSnapshot,
+
+      // 工具方法
+      findTabIndex,
+      getTab,
+      isTabClosable,
+      addKeepAliveExclude,
+      removeKeepAliveExclude,
+      markTabsToRemove,
+      getTabTitle,
+      updateTabTitle,
+      resetTabTitle,
+    };
+  },
+  {
+    persist: {
+      key: 'worktab',
+      storage: localStorage,
+    },
+  }
+);