307 lines
7.6 KiB
Markdown
307 lines
7.6 KiB
Markdown
# CRMEB 路由体系 1:1 复刻 - 完成报告
|
|
|
|
## 📋 项目概述
|
|
|
|
本次重构成功将 CRMEB v5 标准版管理端前端的**路由体系 + 侧边栏布局**在 uni-app-x admin 项目中实现了 1:1 复刻,采用"内部路由/状态驱动渲染"模式,实现了类似单页应用(SPA)的用户体验。
|
|
|
|
## ✅ 已完成工作
|
|
|
|
### 1. 核心架构文件
|
|
|
|
#### 路由配置
|
|
|
|
- ✅ `layouts/admin/router/adminRoutes.uts` - CRMEB 路由映射配置
|
|
- 9 个一级菜单 (home, user, product, order, marketing, cms, finance, statistic, setting)
|
|
- 30+ 路由记录
|
|
- 工具函数: getTopMenus(), findRouteById(), getBreadcrumb() 等
|
|
|
|
#### 状态管理
|
|
|
|
- ✅ `layouts/admin/store/adminNavStore.uts` - 导航状态管理
|
|
- activeTopMenuId: 当前选中的一级菜单
|
|
- activeRouteId: 当前激活的路由
|
|
- tabs: 标签页列表
|
|
- openRoute(), closeTab(), closeOtherTabs(), closeAllTabs() 等方法
|
|
|
|
#### 组件映射
|
|
|
|
- ✅ `layouts/admin/router/adminComponentMap.uts` - 组件映射表
|
|
- 30+ 组件静态导入
|
|
- getComponent() 方法
|
|
- PlaceholderPage 占位组件
|
|
|
|
### 2. 布局组件重构
|
|
|
|
#### 主布局
|
|
|
|
- ✅ `layouts/admin/AdminLayout.uvue` - 完全重构
|
|
- 移除 slot 模式
|
|
- 改用 `<component :is="currentComponent" />` 动态渲染
|
|
- 集成状态管理和路由逻辑
|
|
|
|
#### 侧边栏组件
|
|
|
|
- ✅ `layouts/admin/components/AdminAside.uvue` - CRMEB 风格主侧边栏
|
|
- 显示一级菜单图标+文本
|
|
- 宽度: 96px
|
|
- 折叠/展开功能
|
|
|
|
- ✅ `layouts/admin/components/AdminSubSider.uvue` - CRMEB 风格二级侧边栏
|
|
- 显示分组和菜单项
|
|
- 宽度: 180px
|
|
- 位于内容区左侧
|
|
|
|
#### 占位组件
|
|
|
|
- ✅ `layouts/admin/components/PlaceholderPage.uvue` - 统一占位页面
|
|
|
|
### 3. 页面文件
|
|
|
|
#### 批量创建
|
|
|
|
- ✅ 使用 Python 脚本批量创建 26 个占位页面
|
|
- 用户模块: 8 个页面
|
|
- 商品模块: 7 个页面
|
|
- 订单模块: 1 个页面
|
|
- 营销模块: 5 个页面
|
|
- 内容模块: 2 个页面
|
|
- 财务模块: 1 个页面
|
|
- 数据模块: 1 个页面
|
|
- 设置模块: 3 个页面
|
|
|
|
#### 首页重构
|
|
|
|
- ✅ `pages/mall/admin/homePage/index.uvue` - 移除 AdminLayout 包裹
|
|
- 改为纯内容页面
|
|
- 保留完整的 KPI 卡片和数据展示
|
|
|
|
### 4. 入口文件
|
|
|
|
- ✅ `layouts/admin/index.uvue` - 更新为直接渲染 AdminLayout
|
|
- ✅ `pages.json` - 保持现有配置(内部路由不需要注册所有子页面)
|
|
|
|
## 🎯 核心特性
|
|
|
|
### 1. 内部路由系统
|
|
|
|
**流程**: 点击菜单 → 更新状态 → 切换组件渲染 → 不打开新页面
|
|
|
|
**优势**:
|
|
|
|
- 避免页面栈堆积
|
|
- 保持布局和侧边栏状态
|
|
- 实现 CRMEB 风格的标签页系统
|
|
- 更快的页面切换速度
|
|
|
|
### 2. 双侧边栏布局
|
|
|
|
**结构**: 主侧边栏(一级菜单) + 二级侧边栏(分组+菜单项)
|
|
|
|
**特点**:
|
|
|
|
- 完全复刻 CRMEB 的视觉风格和交互逻辑
|
|
- 支持折叠/展开
|
|
- 选中态高亮
|
|
- 响应式宽度调整
|
|
|
|
### 3. 标签页系统
|
|
|
|
**功能**:
|
|
|
|
- 打开/关闭标签
|
|
- 关闭其他标签
|
|
- 关闭所有标签
|
|
- 固定标签(首页等,不可关闭)
|
|
|
|
### 4. 组件映射机制
|
|
|
|
**原理**: 静态导入 + Map 查找
|
|
|
|
**优势**:
|
|
|
|
- 打包可静态分析
|
|
- 避免动态 import 的限制
|
|
- 类型安全
|
|
|
|
## 📁 目录结构
|
|
|
|
```
|
|
layouts/admin/
|
|
├── router/
|
|
│ ├── adminRoutes.uts # 路由配置
|
|
│ └── adminComponentMap.uts # 组件映射表
|
|
├── store/
|
|
│ └── adminNavStore.uts # 状态管理
|
|
├── components/
|
|
│ ├── AdminAside.uvue # 主侧边栏
|
|
│ ├── AdminSubSider.uvue # 二级侧边栏
|
|
│ ├── AdminHeader.uvue # 顶部栏
|
|
│ ├── AdminTagsView.uvue # 标签页
|
|
│ └── PlaceholderPage.uvue # 占位组件
|
|
├── AdminLayout.uvue # 布局容器
|
|
└── index.uvue # 入口文件
|
|
|
|
pages/mall/admin/
|
|
├── homePage/
|
|
│ └── index.uvue # 首页(已有完整内容)
|
|
├── user/ # 用户模块页面 ✅
|
|
├── product/ # 商品模块页面 ✅
|
|
├── order/ # 订单模块页面 ✅
|
|
├── marketing/ # 营销模块页面 ✅
|
|
├── cms/ # 内容模块页面 ✅
|
|
├── finance/ # 财务模块页面 ✅
|
|
├── statistic/ # 数据模块页面 ✅
|
|
└── setting/ # 设置模块页面 ✅
|
|
```
|
|
|
|
## 🔧 技术要点
|
|
|
|
### 1. 路由数据结构
|
|
|
|
```typescript
|
|
// 一级菜单
|
|
type TopMenu = {
|
|
id: string;
|
|
title: string;
|
|
icon: string;
|
|
path: string;
|
|
order: number;
|
|
groups: MenuGroup[];
|
|
};
|
|
|
|
// 路由记录
|
|
type RouteRecord = {
|
|
id: string;
|
|
title: string;
|
|
path: string;
|
|
componentKey: string;
|
|
parentId?: string;
|
|
groupId?: string;
|
|
auth?: string[];
|
|
};
|
|
```
|
|
|
|
### 2. 状态管理
|
|
|
|
```typescript
|
|
// 核心状态
|
|
export const activeTopMenuId = ref<string>("home");
|
|
export const activeRouteId = ref<string>("home_index");
|
|
export const tabs = ref<TabItem[]>([]);
|
|
|
|
// 核心方法
|
|
export function openRoute(routeId: string): void;
|
|
export function closeTab(tabId: string): void;
|
|
```
|
|
|
|
### 3. 组件渲染
|
|
|
|
```vue
|
|
<!-- 动态组件渲染 -->
|
|
<component :is="currentComponent" />
|
|
|
|
<!-- 计算属性 -->
|
|
const currentComponent = computed(() => { const route =
|
|
findRouteById(activeRouteId.value) return getComponent(route.componentKey) })
|
|
```
|
|
|
|
## 📝 使用指南
|
|
|
|
### 添加新路由
|
|
|
|
1. 在 `adminRoutes.uts` 中添加路由记录
|
|
2. 创建对应的页面文件 `.uvue`
|
|
3. 在 `adminComponentMap.uts` 中添加映射
|
|
4. 运行项目,点击菜单测试
|
|
|
|
### 添加新的一级菜单
|
|
|
|
1. 在 `topMenus` 数组中添加配置
|
|
2. 在 `AdminAside.uvue` 的 `iconMap` 中添加图标
|
|
3. 添加该菜单下的所有子路由
|
|
|
|
## ⚠️ 注意事项
|
|
|
|
### 1. 路径约束
|
|
|
|
- ❌ 禁止使用相对路径 `./` `../`
|
|
- ✅ 必须使用绝对路径别名 `@/`
|
|
|
|
### 2. 编码规范
|
|
|
|
- ❌ 禁止乱码(确保 UTF-8)
|
|
- ✅ 移除特殊 emoji 字符
|
|
- ✅ 确保所有标签正确闭合
|
|
|
|
### 3. 组件导入
|
|
|
|
- ❌ 禁止动态 `import()`
|
|
- ✅ 必须静态导入
|
|
- ✅ 使用 Map 映射
|
|
|
|
### 4. 页面模式
|
|
|
|
- ❌ 不再使用 `<AdminLayout currentPage="xxx">` 包裹
|
|
- ✅ 页面只写纯内容
|
|
- ✅ AdminLayout 在顶层统一渲染
|
|
|
|
## 🧪 测试验证
|
|
|
|
### 编译检查
|
|
|
|
```bash
|
|
# 检查关键文件无错误
|
|
✅ layouts/admin/AdminLayout.uvue
|
|
✅ layouts/admin/router/adminRoutes.uts
|
|
✅ layouts/admin/store/adminNavStore.uts
|
|
✅ layouts/admin/components/*.uvue
|
|
```
|
|
|
|
### 功能测试
|
|
|
|
- ✅ 主侧边栏显示所有一级菜单
|
|
- ✅ 点击一级菜单,二级侧边栏显示分组
|
|
- ✅ 点击菜单项,内容区渲染对应组件
|
|
- ✅ 标签页正确添加/切换/关闭
|
|
- ✅ 无页面栈堆积
|
|
|
|
## 📖 文档更新
|
|
|
|
- ✅ `docs/UNI_APP_X_PAGE_FIX_GUIDE.md` - 新增"阶段十五: CRMEB 路由体系复刻"章节
|
|
- 背景与目标
|
|
- 核心架构设计
|
|
- 实施步骤总结
|
|
- 关键技术点
|
|
- 常见问题与解决方案
|
|
- 扩展开发指南
|
|
- 验收标准
|
|
|
|
## 🎉 成果总结
|
|
|
|
1. **完整性**: 实现了 CRMEB 路由体系的 1:1 复刻
|
|
2. **可维护性**: 清晰的目录结构和代码组织
|
|
3. **可扩展性**: 提供了完善的扩展开发指南
|
|
4. **规范性**: 统一的编码规范和最佳实践
|
|
5. **文档化**: 完整的技术文档和使用指南
|
|
|
|
## 🚀 后续规划
|
|
|
|
### 短期优化
|
|
|
|
1. 完善各模块的具体功能实现
|
|
2. 添加权限控制逻辑
|
|
3. 实现页面缓存机制(keep-alive 替代方案)
|
|
|
|
### 长期规划
|
|
|
|
1. 性能优化(懒加载、虚拟滚动)
|
|
2. 状态持久化(localStorage)
|
|
3. 国际化支持(i18n)
|
|
4. 主题切换功能
|
|
|
|
---
|
|
|
|
**作者**: GitHub Copilot (Claude Sonnet 4.5)
|
|
**日期**: 2026年2月2日
|
|
**版本**: v1.0
|