huangzhenbao/medical-mall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
436b7b251f3dec9b1dd0c40188f2e302806dc90e
medical-mall/layouts/admin/CRMEB_ROUTER_MIGRATION_COMPLETE.md
huangzhenbao 21f4a0fa96 修改页面结构
2026-02-02 20:07:37 +08:00

7.6 KiB
Raw Blame History

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. 路由数据结构

// 一级菜单
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. 状态管理

// 核心状态
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. 组件渲染

<!-- 动态组件渲染 -->
<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 在顶层统一渲染

🧪 测试验证

编译检查

# 检查关键文件无错误
✅ 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

Reference in New Issue View Git Blame Copy Permalink