菜单与路由

KMatrix 系统的路由机制是一个多层级、自动化且具有高度灵活性的架构。它基于 elegant-router 插件，结合 Vue Router 和 Pinia 状态管理，实现了静态路由、动态路由、自定义路由以及多语言菜单的无缝协作。
KMatrix 的路由机制实现了 “配置即菜单” 的高度集成。开发人员只需关注 src/views 下的页面开发，或者在后端配置权限，前端会自动处理组件映射、权限拦截、菜单展示及多语言适配，极大地降低了维护成本。

核心机制

以下是针对各核心元素的原理及协作机制的详细分析：

1. 核心原理与架构

系统路由采用了 “抽象定义 -> 状态管理 -> 动态注入” 的流水线模式：

• 抽象定义：通过 @elegant-router/vue 自动扫描 src/views 下的文件生成路由定义。
• 状态管理：通过 Pinia 的 useRouteStore 统一管理路由状态（是否初始化、权限过滤、菜单生成）。
• 动态注入：在路由守卫中，根据用户登录状态和权限，动态调用 router.addRoute 将路由注入到 Vue Router 实例中。

2. 核心元素详解

A. 静态路由 (Static Routes)

• 原理：在代码中预定义的、不需要权限校验（或权限固定）的路由。
• 包含内容：
  • 基础路由：如 /login、/404、/403、/500 等（定义在 src/router/routes/builtin.ts）。
  • 常驻路由：如 home 首页。
• 协作机制：系统初始化时（initConstantRoute）立即加载，确保用户在未登录时也能访问登录页或错误页。

B. 动态路由 (Dynamic Routes)

• 原理：根据用户的角色或从后端接口（fetchGetRoutes）实时获取的路由配置。
• 协作机制：
  1. 用户登录后，路由守卫触发 initAuthRoute。
  2. 从后端获取 JSON 格式的路由数据。
  3. 通过 parseRouter 函数进行标准化处理（将后端定义的组件字符串映射为前端的 Layout 或 View）。
  4. 调用 router.addRoute 动态添加到路由表中。

C. 自定义路由 (Custom Routes)

• 原理：用于处理复杂的路由结构，例如多步表单（分步上传）、不需要对应单一视图文件的嵌套结构。
• 定义位置：src/router/routes/index.ts 中的 customRoutes。
• 特点：它们手动指定 component（如 layout.base）和 meta 信息，能够覆盖自动生成的逻辑。

D. 页面 (Pages)

• 原理：每个页面对应 src/views 下的一个 .vue 文件。
• 命名约定：elegant-router 会根据文件夹结构生成唯一的路由 name（如 ai_model_mcp-manager）。
• 配置：页面可以通过 meta 属性控制自身行为，如 keepAlive（缓存）、constant（常量）、roles（权限要求）。

E. 菜单 (Menus)

• 原理：菜单并不是独立定义的，而是路由表的视觉投影。
• 协作机制：
  1. useRouteStore 在初始化路由后，调用 getGlobalMenusByAuthRoutes。
  2. 遍历路由树，过滤掉 hideInMenu: true 的项。
  3. 根据 meta.order 进行排序。
  4. 生成符合 UI 组件（如 Naive UI 的 NMenu）要求的树形结构。

F. 多语言 (Internationalization, i18n)

• 原理：路由标题支持响应式多语言切换。
• 协作机制：
  • 标识：在路由 meta.title 中使用 route.home 或 menu.system 这样的 Key。
  • 处理：parseRouter 会识别这些 Key 并存入 meta.i18nKey。
  • 更新：当用户切换系统语言时，useRouteStore 会触发 updateGlobalMenusByLocale，重新渲染菜单文字，而无需刷新页面。

3. 协作流程图解

4. 关键文件索引

页面、菜单调整

由于 KMatrix 使用了自动化的 elegant-router 机制，不同的改动涉及的层面略有不同。以下是详细的操作指南：

1. 调整目录结构 / 移动页面

这类改动会直接触发路由定义的自动更新，影响最广。

• 前端自动化更新：
  • 当您在 src/views 下移动文件或重命名文件夹时，elegant-router 会自动重新生成 src/router/elegant 目录下的路由表、类型定义和组件映射。
  • 注意：路由的 name（名称）和 path（路径）会随之改变（例如从 view.old_page 变为 view.new_page）。
• 后端权限配置（最重要）：
  • 如果您开启了动态路由模式（从数据库读取菜单），您必须在数据库的菜单表（通常是 sys_menu）中同步修改 component 字段，确保它指向新的组件名（如 ai/model/new-path/index）。
  • 如果权限是按路由名称挂钩的，也需要更新权限标识。
• 代码调用更新：
  • 全局搜索代码中所有的 router.push({ name: 'old_name' }) 或 <router-link :to="{ name: 'old_name' }">，将其修改为新的路由名称。
• 国际化 Key 迁移：
  • 由于系统默认生成的 i18nKey 是 route.路由名，移动目录后路由名变了，您需要去 src/locales/langs/ 下将旧的翻译词条移动到新的 Key 下。

2. 改动菜单名 / 页面标签标题

在 KMatrix 中，菜单名和页面标签（Tab）标题通常是共用一个配置的，即路由元数据中的 title 或 i18nKey。

• 修改方式 A：通过国际化文件（推荐）：
  • 定位到 src/locales/langs/{zh-cn|en-us}/ 目录。
  • 找到对应的 route.ts 或相关语言文件。
  • 修改对应 Key 的值。例如，将 route.ai_model_mcp-manager: 'MCP管理' 改为 '模型上下文协议'。
  • 优点：无需改动代码或重启，支持多语言实时切换。
• 修改方式 B：后端数据库修改（动态模式下）：
  • 如果是动态路由，直接在后台“菜单管理”中修改菜单名称。刷新页面后，前端会自动获取新的标题并展示在菜单和 Tab 标签上。

3. 改动页面内的面包屑或特定标题

• 如果某些页面的标题是动态生成的（例如“编辑用户：张三”），这通常是在页面组件内部通过 useTabStore 或修改 route.meta 实现的。
• 这种情况下，您需要修改具体的 .vue 页面文件中的逻辑。

4. 总结清单

温馨提示：在进行目录调整后，建议运行 npm run dev 让插件重新扫描并生成最新的类型文件，以修复可能出现的 TypeScript 报错。