# Ether 项目前端路由最佳实践

## 概述

本文档总结了 Ether 项目前端路由开发中的最佳实践，以及常见问题和解决方案。

## 路由架构设计

### 1. 路由分层结构

```
路由层级：
├── 公开路由 (Public Routes)
│   ├── /login - 登录页
│   └── /no-project - 无项目提示页
│
├── 布局路由 (Layout Route)
│   └── / (Layout)
│       ├── /space-node - 空间节点管理
│       ├── /mdm/projects - 项目管理
│       ├── /mdm/visitors - 访客管理
│       └── ... 其他业务页面
│
└── 404 路由
    └── /* - 匹配所有未定义路由
```

### 2. 动态路由生成机制

```typescript
// 1. 定义组件映射表
const dynamicRouteComponents: Record<string, () => Promise<any>> = {
  "Mdm/projects": () => import("../views/mdm/project/index.vue"),
  "Mdm/visitors": () => import("../views/mdm/visitor/index.vue"),
  // ...
};

// 2. 根据后端菜单数据生成路由
function generateRoutesFromMenus(menus: MenuInfo[]): RouteRecordRaw[] {
  return menus.map(menu => ({
    path: menu.menuPath,      // 如: "/mdm/visitors"
    name: menu.componentName, // 如: "Mdm/visitors"
    component: dynamicRouteComponents[menu.componentName],
    meta: {
      title: menu.permissionName,
      icon: menu.menuIcon,
    },
  }));
}

// 3. 动态添加到路由表
menuRoutes.forEach(route => {
  router.addRoute("Layout", {
    path: route.path.substring(1), // 移除开头的 "/"
    name: route.name,
    component: route.component,
    meta: route.meta,
  });
});
```

## 常见问题与解决方案

### 问题 1: 菜单点击后页面不跳转

**症状**: 点击侧边栏菜单，页面没有切换，URL 不变。

**根本原因**: 
- 菜单点击使用 `router.push({ name: key })`，但动态路由的 `name` 可能未正确注册
- 路由守卫中动态添加路由后，使用 `name` 导航可能找不到对应路由

**解决方案**:
```typescript
// ❌ 错误方式：使用 name 导航
const handleMenuClick = ({ key }: { key: string }) => {
  router.push({ name: key }); // 可能找不到路由
};

// ✅ 正确方式：使用 path 导航
const handleMenuClick = ({ key }: { key: string }) => {
  const menu = findMenuByComponentName(menus, key);
  if (menu?.menuPath) {
    router.push(menu.menuPath); // 使用 path 更可靠
  }
};
```

### 问题 2: 动态路由添加后刷新 404

**症状**: 动态添加路由后可以访问，但刷新页面后显示 404。

**根本原因**: 
- 动态路由只在路由守卫中添加一次，刷新后需要重新添加
- 404 路由优先级问题

**解决方案**:
```typescript
// 1. 确保每次路由守卫都检查并添加路由
router.beforeEach(async (to, from, next) => {
  if (!permissionStore.isInitialized) {
    await permissionStore.fetchUserPermissions();
    
    // 重新生成并添加路由
    const menuRoutes = generateRoutesFromMenus(permissionStore.menus);
    menuRoutes.forEach(route => {
      const existing = router.getRoutes().find(r => r.name === route.name);
      if (!existing) {
        router.addRoute("Layout", route);
      }
    });
    
    // 重新导航
    next({ ...to, replace: true });
    return;
  }
  next();
});

// 2. 404 路由最后添加，确保优先级最低
router.addRoute({
  path: "/:pathMatch(.*)*",
  name: "NotFound",
  component: () => import("../views/404/index.vue"),
});
```

### 问题 3: 路由名称冲突

**症状**: 控制台警告路由名称已存在。

**根本原因**: 
- 多次添加相同 name 的路由
- 热更新时重复添加

**解决方案**:
```typescript
// 添加前检查是否已存在
menuRoutes.forEach(route => {
  const existingRoute = router.getRoutes().find(r => r.name === route.name);
  if (!existingRoute) {
    router.addRoute("Layout", route);
  }
});
```

### 问题 4: 路由路径格式不一致

**症状**: 菜单数据和路由配置的路径不匹配。

**根本原因**: 
- 后端返回的 `menuPath` 包含前导 `/`，但动态添加时需要移除
- 路由配置中 path 格式不统一

**解决方案**:
```typescript
// 统一路径格式
const normalizePath = (path: string): string => {
  // 确保以 / 开头
  if (!path.startsWith('/')) {
    path = '/' + path;
  }
  // 移除尾部 /
  return path.replace(/\/$/, '') || '/';
};

// 动态添加时移除前导 /
router.addRoute("Layout", {
  path: route.path.substring(1), // "/mdm/visitors" -> "mdm/visitors"
  ...
});
```

## 数据流设计

### 菜单数据结构

```typescript
interface MenuInfo {
  id: string;
  permissionCode: string;   // 权限编码: "mdm:visitor:menu"
  permissionName: string;   // 显示名称: "访客管理"
  menuPath: string;         // 路由路径: "/mdm/visitors"
  menuIcon?: string;        // 图标: "UserAddOutlined"
  componentName: string;    // 组件名: "Mdm/visitors"
  parentId?: string;        // 父菜单ID
  sortOrder: number;        // 排序
  children?: MenuInfo[];    // 子菜单
}
```

### 关键映射关系

| 后端字段 | 前端用途 | 示例 |
|---------|---------|------|
| `componentName` | 路由 name / 菜单 key | `Mdm/visitors` |
| `menuPath` | 路由 path | `/mdm/visitors` |
| `permissionName` | 页面标题 / 菜单标签 | `访客管理` |
| `menuIcon` | 菜单图标 | `UserAddOutlined` |

## 开发规范

### 1. 新增页面步骤

1. **创建页面组件**: `src/views/{module}/{page}/index.vue`
2. **注册路由映射**: 在 `src/router/index.ts` 的 `dynamicRouteComponents` 中添加
3. **配置后端权限**: 在数据库中添加菜单和权限数据
4. **验证路由**: 确保 `componentName` 和 `menuPath` 匹配

### 2. 路由配置检查清单

- [ ] `componentName` 在 `dynamicRouteComponents` 中有对应映射
- [ ] `menuPath` 格式统一（以 `/` 开头）
- [ ] 路由 `name` 唯一，不与其他路由冲突
- [ ] 动态路由添加前检查是否已存在

### 3. 调试技巧

```typescript
// 查看所有已注册路由
console.log(router.getRoutes());

// 检查特定路由是否存在
const route = router.getRoutes().find(r => r.name === 'Mdm/visitors');
console.log(route);

// 监听路由变化
router.beforeEach((to, from) => {
  console.log('Navigating from', from.path, 'to', to.path);
});
```

## 相关文件

- `src/router/index.ts` - 路由配置和动态路由生成
- `src/views/layout/index.vue` - 布局组件和菜单处理
- `src/stores/permission.ts` - 权限状态和菜单数据

## 更新记录

| 日期 | 更新内容 | 作者 |
|------|---------|------|
| 2026-02-10 | 初始版本，总结路由问题和解决方案 | AI Assistant |