# 路由与导航

<cite>
**本文档中引用的文件**  
- [index.ts](file://src/router/index.ts)
- [routes/index.ts](file://src/router/routes/index.ts)
- [constants.ts](file://src/router/constants.ts)
- [routes/base.ts](file://src/router/routes/base.ts)
- [guard/index.ts](file://src/router/guard/index.ts)
- [guard/permission.ts](file://src/router/guard/permission.ts)
- [guard/userLoginInfo.ts](file://src/router/guard/userLoginInfo.ts)
- [routes/types.ts](file://src/router/routes/types.ts)
- [app-menus/index.ts](file://src/router/app-menus/index.ts)
- [routes/modules/dashboard.ts](file://src/router/routes/modules/dashboard.ts)
- [routes/modules/user.ts](file://src/router/routes/modules/user.ts)
- [routes/modules/apple-account.ts](file://src/router/routes/modules/apple-account.ts)
- [routes/modules/walmart-account.ts](file://src/router/routes/modules/walmart-account.ts)
- [routes/modules/jd-account.ts](file://src/router/routes/modules/jd-account.ts)
</cite>

## 目录

1. [项目结构](#项目结构)
2. [路由配置与组织结构](#路由配置与组织结构)
3. [路由常量与基础路由](#路由常量与基础路由)
4. [路由守卫机制](#路由守卫机制)
5. [权限控制实现](#权限控制实现)
6. [用户登录状态验证](#用户登录状态验证)
7. [动态路由与懒加载](#动态路由与懒加载)
8. [嵌套路由结构](#嵌套路由结构)
9. [路由与菜单系统集成](#路由与菜单系统集成)
10. [编程式导航与声明式导航](#编程式导航与声明式导航)
11. [路由参数与查询参数处理](#路由参数与查询参数处理)
12. [路由与状态管理集成](#路由与状态管理集成)
13. [路由性能优化与最佳实践](#路由性能优化与最佳实践)
14. [路由测试策略与常见问题](#路由测试策略与常见问题)

## 项目结构

kami_frontend项目的路由系统位于`src/router`目录下，采用模块化设计，将路由配置、守卫、常量和类型定义分离。核心路由配置通过动态导入机制从`modules`目录加载各个功能模块的路由定义，实现了良好的可维护性和扩展性。

```mermaid
graph TB
subgraph "路由系统"
Router[index.ts]
Routes[routes/index.ts]
Base[base.ts]
Constants[constants.ts]
Guard[guard/index.ts]
Permission[permission.ts]
UserLoginInfo[userLoginInfo.ts]
Types[types.ts]
AppMenus[app-menus/index.ts]
end
Router --> Routes
Router --> Base
Router --> Guard
Guard --> Permission
Guard --> UserLoginInfo
Routes --> Types
AppMenus --> Routes
```

**Diagram sources**

- [index.ts](file://src/router/index.ts)
- [routes/index.ts](file://src/router/routes/index.ts)
- [routes/base.ts](file://src/router/routes/base.ts)
- [constants.ts](file://src/router/constants.ts)

**Section sources**

- [index.ts](file://src/router/index.ts)
- [routes/index.ts](file://src/router/routes/index.ts)

## 路由配置与组织结构

路由系统采用分层组织结构，主路由配置文件`index.ts`负责创建Vue Router实例并集成路由守卫。`routes/index.ts`文件通过`import.meta.glob`动态导入`modules`目录下的所有路由模块，实现了路由的自动注册和懒加载。

```mermaid
classDiagram
class AppRouteRecordRaw {
+path : string
+name? : string | symbol
+meta? : RouteMeta
+redirect? : string
+component : Component | string
+children? : AppRouteRecordRaw[]
+alias? : string | string[]
+props? : Record<string, any>
+beforeEnter? : NavigationGuard | NavigationGuard[]
+fullPath? : string
}
class RouteRecordNormalized
class RouteRecordRaw
AppRouteRecordRaw <|-- RouteRecordRaw
RouteRecordRaw <|-- RouteRecordNormalized
```

**Diagram sources**

- [routes/types.ts](file://src/router/routes/types.ts)
- [routes/base.ts](file://src/router/routes/base.ts)

**Section sources**

- [routes/index.ts](file://src/router/routes/index.ts)
- [routes/types.ts](file://src/router/routes/types.ts)

## 路由常量与基础路由

系统定义了多个路由常量用于控制路由行为，包括白名单、未找到路由、重定向路由名称和默认路由等。基础路由配置包含登录页、重定向页和404页面，为应用提供了基本的导航框架。

```mermaid
flowchart TD
Start([应用启动]) --> CheckAuth{是否需要认证?}
CheckAuth --> |否| Login[跳转到登录页]
CheckAuth --> |是| Redirect[重定向到主页面]
Redirect --> NotFound[404页面]
style Login fill:#f9f,stroke:#333
style Redirect fill:#bbf,stroke:#333
style NotFound fill:#f96,stroke:#333
```

**Diagram sources**

- [constants.ts](file://src/router/constants.ts)
- [routes/base.ts](file://src/router/routes/base.ts)

**Section sources**

- [constants.ts](file://src/router/constants.ts)
- [routes/base.ts](file://src/router/routes/base.ts)

## 路由守卫机制

路由守卫系统采用组合式设计，`guard/index.ts`文件负责注册所有路由守卫，包括页面守卫、用户登录信息守卫和权限守卫。这种设计模式提高了代码的可维护性和可测试性。

```mermaid
sequenceDiagram
participant Router as 路由器
participant Guard as 路由守卫
participant PageGuard as 页面守卫
participant UserGuard as 用户登录守卫
participant PermissionGuard as 权限守卫
Router->>Guard : beforeEach
Guard->>PageGuard : setRouteEmitter
Guard->>UserGuard : 验证登录状态
UserGuard-->>Guard : 返回验证结果
Guard->>PermissionGuard : 检查权限
PermissionGuard-->>Guard : 返回权限检查结果
Guard-->>Router : next()
```

**Diagram sources**

- [guard/index.ts](file://src/router/guard/index.ts)
- [index.ts](file://src/router/index.ts)

**Section sources**

- [guard/index.ts](file://src/router/guard/index.ts)
- [index.ts](file://src/router/index.ts)

## 权限控制实现

权限控制通过`permission.ts`文件实现，系统根据用户角色和路由元数据中的角色要求进行访问控制。支持从服务器动态获取菜单配置，并根据用户权限动态生成可访问的路由。

```mermaid
flowchart TD
A[路由跳转] --> B{是否需要认证?}
B --> |否| C[直接放行]
B --> |是| D{菜单来自服务器?}
D --> |是| E[获取服务器菜单配置]
E --> F{路由存在且有权限?}
F --> |是| G[放行]
F --> |否| H[跳转到404]
D --> |否| I{有权限访问?}
I --> |是| J[放行]
I --> |否| K[查找第一个有权限的路由]
K --> L[重定向]
```

**Diagram sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [constants.ts](file://src/router/constants.ts)

**Section sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [constants.ts](file://src/router/constants.ts)

## 用户登录状态验证

用户登录状态验证在`userLoginInfo.ts`中实现，通过`isLogin()`工具函数检查用户是否已登录，并根据路由的认证要求决定是否重定向到登录页面。系统还支持通过查询参数传递重定向目标。

```mermaid
flowchart TD
A[路由跳转] --> B{用户已登录?}
B --> |是| C{需要认证?}
C --> |是| D[放行]
C --> |否| E[放行]
B --> |否| F{是登录页或404?}
F --> |是| G[放行]
F --> |否| H{需要认证?}
H --> |是| I[重定向到登录页]
H --> |否| J{有token?}
J --> |是| K[放行]
J --> |否| L[跳转到404]
```

**Diagram sources**

- [guard/userLoginInfo.ts](file://src/router/guard/userLoginInfo.ts)
- [utils/auth.ts](file://src/utils/auth.ts)

**Section sources**

- [guard/userLoginInfo.ts](file://src/router/guard/userLoginInfo.ts)
- [utils/auth.ts](file://src/utils/auth.ts)

## 动态路由与懒加载

系统采用动态导入语法`() => import('@/views/xxx')`实现路由组件的懒加载，有效减少了初始包大小。路由模块通过`import.meta.glob`批量导入，实现了路由的动态注册。

```mermaid
flowchart LR
A[路由配置] --> B[动态导入]
B --> C[代码分割]
C --> D[按需加载]
D --> E[性能优化]
style B fill:#f9f,stroke:#333
style C fill:#bbf,stroke:#333
style D fill:#9f9,stroke:#333
```

**Diagram sources**

- [routes/index.ts](file://src/router/routes/index.ts)
- [index.ts](file://src/router/index.ts)

**Section sources**

- [routes/index.ts](file://src/router/routes/index.ts)
- [index.ts](file://src/router/index.ts)

## 嵌套路由结构

系统采用嵌套路由结构，父路由通常对应布局组件，子路由对应具体页面。例如`/appleAccountInfo`作为父路由，其子路由包括账户管理、订单记录和充值记录等。

```mermaid
erDiagram
PARENT_ROUTE ||--o{ CHILD_ROUTE : contains
PARENT_ROUTE {
string path
string name
function component
object meta
}
CHILD_ROUTE {
string path
string name
function component
object meta
}
PARENT_ROUTE ||--o{ CHILD_ROUTE : "1对多"
```

**Diagram sources**

- [routes/modules/apple-account.ts](file://src/router/routes/modules/apple-account.ts)
- [routes/modules/walmart-account.ts](file://src/router/routes/modules/walmart-account.ts)

**Section sources**

- [routes/modules/apple-account.ts](file://src/router/routes/modules/apple-account.ts)
- [routes/modules/jd-account.ts](file://src/router/routes/modules/jd-account.ts)

## 路由与菜单系统集成

路由系统与菜单系统紧密集成，`app-menus/index.ts`文件从应用路由中提取可用于菜单显示的路由，根据`meta.showInMenu`属性决定是否在菜单中显示。这实现了路由与菜单的一致性维护。

```mermaid
flowchart TD
A[应用路由] --> B{过滤条件}
B --> C[showInMenu未定义]
B --> D[showInMenu为true]
C --> E[包含在菜单]
D --> E
E --> F[菜单数据]
F --> G[渲染菜单]
style C fill:#f9f,stroke:#333
style D fill:#f9f,stroke:#333
style E fill:#bbf,stroke:#333
```

**Diagram sources**

- [app-menus/index.ts](file://src/router/app-menus/index.ts)
- [routes/index.ts](file://src/router/routes/index.ts)

**Section sources**

- [app-menus/index.ts](file://src/router/app-menus/index.ts)
- [routes/index.ts](file://src/router/routes/index.ts)

## 编程式导航与声明式导航

系统支持两种导航方式：声明式导航使用`<router-link>`组件，编程式导航使用`router.push()`方法。在多个组件中通过`useRouter()`获取路由实例进行编程式导航。

```mermaid
classDiagram
class Router {
+push(location)
+replace(location)
+go(delta)
+back()
+forward()
}
class RouterLink {
+to
+tag
+activeClass
+exactActiveClass
}
class Navigation {
+useRouter()
+useRoute()
}
Navigation --> Router : "useRouter()"
Navigation --> RouterLink : "useRoute()"
```

**Diagram sources**

- [index.ts](file://src/router/index.ts)
- [views/login/index.vue](file://src/views/login/index.vue)

**Section sources**

- [index.ts](file://src/router/index.ts)
- [hooks/user.ts](file://src/hooks/user.ts)

## 路由参数与查询参数处理

系统通过路由的`params`和`query`属性处理动态参数和查询参数。路由配置中使用`:param`语法定义动态段，查询参数通过URL的查询字符串传递。

```mermaid
flowchart LR
A[URL] --> B{包含动态参数?}
B --> |是| C[解析params]
B --> |否| D[继续]
D --> E{包含查询参数?}
E --> |是| F[解析query]
E --> |否| G[继续]
C --> H[路由匹配]
F --> H
H --> I[组件接收参数]
style C fill:#f9f,stroke:#333
style F fill:#f9f,stroke:#333
style H fill:#bbf,stroke:#333
```

**Diagram sources**

- [routes/types.ts](file://src/router/routes/types.ts)
- [index.ts](file://src/router/index.ts)

**Section sources**

- [routes/types.ts](file://src/router/routes/types.ts)
- [index.ts](file://src/router/index.ts)

## 路由与状态管理集成

路由系统与Pinia状态管理集成，通过`useAppStore`和`useUserStore`获取应用状态和用户信息，用于权限判断和菜单生成。路由变化时通过`setRouteEmitter`通知其他组件。

```mermaid
sequenceDiagram
participant Router as 路由器
participant Store as 状态管理
participant Component as 组件
Router->>Store : 获取用户角色
Store-->>Router : 返回角色信息
Router->>Store : 获取菜单配置
Store-->>Router : 返回菜单数据
Router->>Component : 路由变化
Component->>Store : 更新状态
Store-->>Component : 状态更新完成
```

**Diagram sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [store/index.ts](file://src/store/index.ts)

**Section sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [store/index.ts](file://src/store/index.ts)

## 路由性能优化与最佳实践

系统通过路由懒加载、代码分割和进度条提示等技术优化路由性能。NProgress库提供页面跳转时的进度条反馈，提升用户体验。路由配置中设置`scrollBehavior`确保页面跳转后滚动到顶部。

```mermaid
flowchart TD
A[性能优化] --> B[路由懒加载]
A --> C[代码分割]
A --> D[NProgress进度条]
A --> E[滚动行为控制]
A --> F[白名单优化]
B --> G[减少初始加载]
C --> G
D --> H[提升用户体验]
E --> H
F --> I[快速访问]
style B fill:#f9f,stroke:#333
style C fill:#f9f,stroke:#333
style D fill:#bbf,stroke:#333
```

**Diagram sources**

- [index.ts](file://src/router/index.ts)
- [guard/index.ts](file://src/router/guard/index.ts)

**Section sources**

- [index.ts](file://src/router/index.ts)
- [guard/index.ts](file://src/router/guard/index.ts)

## 路由测试策略与常见问题

针对路由系统的测试应覆盖路由守卫逻辑、权限控制、重定向行为和错误处理。常见问题包括路由循环、权限判断错误和动态路由加载失败，可通过单元测试和集成测试预防。

```mermaid
flowchart TD
A[路由测试] --> B[单元测试]
A --> C[集成测试]
B --> D[路由守卫]
B --> E[权限检查]
C --> F[导航流程]
C --> G[页面渲染]
D --> H[模拟状态]
E --> H
F --> I[端到端测试]
G --> I
style B fill:#f9f,stroke:#333
style C fill:#f9f,stroke:#333
style D fill:#bbf,stroke:#333
```

**Diagram sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [guard/userLoginInfo.ts](file://src/router/guard/userLoginInfo.ts)

**Section sources**

- [guard/permission.ts](file://src/router/guard/permission.ts)
- [guard/userLoginInfo.ts](file://src/router/guard/userLoginInfo.ts)
