# zed-admin **Repository Path**: caoerlei/zed-admin ## Basic Information - **Project Name**: zed-admin - **Description**: Zed Admin 是一个基于 Vue 3 + TypeScript + Vite 的现代化前端项目模板，集成路由、状态管理、国际化、单元测试与样式体系（Tailwind/SCSS），用于快速搭建中后台页面与数据可视化应用。项目内置丰富的 Smart 系列组件（SmartForm、SmartTable、SmartCard、SmartDialog、SmartDrawer 等），遵循团队统一的工程化与 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2025-11-15 - **Last Updated**: 2026-03-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Zed Admin ## 项目介绍 Zed Admin 是一个基于 Vue 3 + TypeScript + Vite 的现代化前端项目模板，集成路由、状态管理、国际化、单元测试与样式体系（SCSS），用于快速搭建中后台页面与数据可视化应用。项目内置丰富的 Smart 系列组件（SmartForm、SmartTable、SmartCard、SmartDialog、SmartDrawer 等），遵循团队统一的工程化与样式规范，开箱即用、可按需扩展。 ### 核心功能特性 - **现代构建**：Vite 7 + TypeScript 5.9，开发/构建极速，支持 HMR - **组件化开发**：Vue 3.5 组合式 API（Composition API），代码模块清晰、可维护性强 - **路由系统**：Vue Router 4.6，支持动态路由、嵌套路由、路由守卫与权限控制 - **状态管理**：Pinia 3.0 + 持久化插件，支持多 Store 模块化管理 - **国际化**：Vue I18n 11.1，支持中英文切换，Element Plus 组件库同步国际化 - **UI 组件库**：Element Plus 2.11，提供丰富的企业级组件 - **样式体系**：SCSS + 组件内样式，支持主题变量与轻量工具类 - **图标系统**：Iconify 5.0 + unplugin-icons，支持 200+ 图标集，按需加载 - **进度反馈**：NProgress 0.2，路由切换时显示加载进度条 - **主题切换**：支持明暗主题切换，自动持久化用户偏好 - **单元测试**：Vitest 3.2，支持 Vue 组件测试与工具函数测试 - **代码规范**：Prettier 3.6，统一代码格式化标准 - **开发工具**：集成 Vue DevTools，支持开发环境调试 - **Smart 组件库**：内置 SmartForm、SmartTable、SmartCard、SmartDialog、SmartDrawer 等业务组件，提供统一的 API 和交互体验 - **表单设计器**：集成 FormCreate 表单设计器，支持可视化表单配置 - **数据可视化**：集成 ECharts 图表库，支持丰富的数据可视化场景 - **安全验证**：集成拼图验证码组件，提供安全的用户验证机制 ### 技术栈 #### 核心框架 - **Vue** 3.5.22 - 渐进式 JavaScript 框架 - **TypeScript** 5.9.0 - 类型安全的 JavaScript 超集 - **Vite** 7.1.11 - 下一代前端构建工具 #### 路由与状态管理 - **Vue Router** 4.6.3 - 官方路由管理器 - **Pinia** 3.0.3 - Vue 官方状态管理库 - **pinia-plugin-persistedstate** 4.7.1 - Pinia 持久化插件 #### UI 与样式 - **Element Plus** 2.11.8 - 基于 Vue 3 的组件库 - **Sass** 1.94.0 - CSS 预处理器 - **modern-normalize** 3.0.1 - 现代浏览器样式重置 - **animate.css** 4.1.1 - CSS 动画库 #### 国际化 - **Vue I18n** 11.1.12 - Vue.js 国际化插件 #### 图标与工具 - **@iconify/vue** 5.0.0 - Iconify Vue 组件 - **unplugin-icons** 22.5.0 - 按需加载图标插件 #### HTTP 请求 - **Axios** 1.13.2 - 基于 Promise 的 HTTP 客户端 - **qs** 6.14.0 - 查询字符串解析库 #### 表单与数据可视化 - **@form-create/designer** 3.4.0 - 表单设计器 - **@form-create/element-ui** 3.2.33 - FormCreate Element Plus 适配器 - **ECharts** 6.0.0 - 数据可视化图表库 #### 工具库 - **lodash** 4.17.21 - JavaScript 工具库 - **crypto-js** 4.2.0 - 加密工具库 - **vue3-json-viewer** 2.4.1 - JSON 数据查看器组件 - **vue3-puzzle-vcode** 1.1.7 - 拼图验证码组件 #### 进度条 - **NProgress** 0.2.0 - 页面加载进度条 #### 开发工具 - **@vitejs/plugin-vue** 6.0.1 - Vue 单文件组件支持 - **vite-plugin-vue-devtools** 8.0.3 - Vue DevTools 集成 - **vue-tsc** 3.1.1 - Vue TypeScript 类型检查 - **Prettier** 3.6.2 - 代码格式化工具 - **npm-run-all2** 8.0.4 - 并行执行 npm 脚本 #### 测试 - **Vitest** 3.2.4 - 基于 Vite 的单元测试框架 - **@vue/test-utils** 2.4.6 - Vue 组件测试工具 - **jsdom** 27.0.1 - DOM 环境模拟（用于测试） #### TypeScript 类型定义 - **@types/node** 22.18.11 - Node.js 类型定义 - **@types/jsdom** 27.0.0 - jsdom 类型定义 - **@tsconfig/node22** 22.0.2 - Node.js 22 TypeScript 配置 - **@vue/tsconfig** 0.8.1 - Vue TypeScript 配置 ### 环境要求 - **Node.js**: ^20.19.0 || >=22.12.0 - **npm**: 建议使用最新稳定版本 - **包管理器**: npm / yarn / pnpm（推荐使用 npm） ## 快速开始 ### 安装依赖 ```bash npm install ``` ### 开发环境运行 ```bash npm run dev ``` 启动后，开发服务器默认运行在 `http://localhost:5173`（可通过环境变量 `VITE_PORT` 自定义端口）。 ### 构建生产版本 ```bash npm run build ``` 构建产物将输出到 `dist` 目录。 ### 预览生产构建 ```bash npm run preview ``` 预览服务器默认运行在 `http://localhost:4173`（可通过环境变量 `VITE_PREVIEW_PORT` 自定义端口）。 ### 类型检查 ```bash npm run type-check ``` ### 代码格式化 ```bash npm run format ``` ### 运行单元测试 ```bash npm run test:unit ``` ## 环境变量配置 项目支持通过环境变量进行配置，环境变量文件应放置在项目根目录，命名格式为 `.env.[mode]`（如 `.env.development`、`.env.production`）。 ### 可用环境变量 | 变量名 | 说明 | 默认值 | 示例 | | ------------------- | ------------------ | ----------------------- | ------------------------- | | `VITE_BASE_URL` | 应用部署的基础路径 | `/` | `/zed-admin/` | | `VITE_PORT` | 开发服务器端口 | `5173` | `3000` | | `VITE_PREVIEW_PORT` | 预览服务器端口 | `4173` | `5000` | | `VITE_API_BASE_URL` | API 请求基础地址 | `http://localhost:3000` | `https://api.example.com` | | `VITE_API_PREFIX` | API 代理路径前缀 | `/api` | `/api/v1` | ### 环境变量使用示例 在代码中使用环境变量： ```typescript const apiBaseUrl = import.meta.env.VITE_API_BASE_URL; ``` ## 目录结构 ``` zed-admin/ ├── doc/ # 项目文档目录 │ ├── SmartForm使用说明.md # SmartForm 组件使用文档 │ ├── SmartTable使用说明.md # SmartTable 组件使用文档 │ ├── 国际化系统说明.md # 国际化系统架构与使用文档 │ ├── 组件自动注册系统说明.md # 全局组件自动注册机制文档 │ └── 路由系统逻辑说明.md # 路由系统架构与权限控制文档 ├── public/ # 静态资源目录 │ └── favicon.png # 网站图标 ├── src/ # 源代码目录 │ ├── __tests__/ # 单元测试文件 │ │ ├── router.spec.ts # 路由测试 │ │ └── setup.ts # 测试配置 │ ├── components/ # 公共组件目录 │ │ ├── index.ts # 组件导出入口（自动注册所有组件） │ │ ├── SmartCard/ # 卡片组件 │ │ │ ├── index.vue │ │ │ └── type.ts # 组件类型定义 │ │ ├── SmartDialog/ # 对话框组件 │ │ │ ├── index.vue │ │ │ └── type.ts # 组件类型定义 │ │ ├── SmartDrawer/ # 抽屉组件 │ │ │ ├── index.vue │ │ │ └── type.ts # 组件类型定义 │ │ ├── SmartForm/ # 表单组件 │ │ │ ├── index.vue │ │ │ └── types.ts # 组件类型定义 │ │ ├── SmartIconifyIcon/ # 图标组件 │ │ │ └── index.vue │ │ ├── SmartImgPuzzle/ # 拼图验证码组件 │ │ │ └── index.vue │ │ ├── SmartLanguageToggle/ # 语言切换组件 │ │ │ └── index.vue │ │ ├── SmartQuickTools/ # 快捷工具组件 │ │ │ └── index.vue │ │ ├── SmartTable/ # 表格组件 │ │ │ ├── index.vue │ │ │ └── types.ts # 组件类型定义 │ │ ├── SmartTagsViews/ # 标签页视图组件 │ │ │ └── index.vue │ │ └── SmartThemeToggle/ # 主题切换组件 │ │ └── index.vue │ ├── i18n/ # 国际化配置 │ │ ├── index.ts # i18n 模块导出入口 │ │ ├── composable.ts # i18n 组合式函数（useLocale） │ │ ├── core.ts # i18n 核心实例创建与语言切换 │ │ ├── elementPlus.ts # Element Plus 国际化适配 │ │ ├── locale.ts # 语言标识与名称映射 │ │ ├── types.ts # i18n 类型定义 │ │ └── locales/ # 语言包目录 │ │ ├── zh-CN.ts # 中文语言包 │ │ └── en-US.ts # 英文语言包 │ ├── images/ # 图片资源目录 │ │ └── login.png # 登录页图片 │ ├── layout/ # 布局组件目录 │ │ ├── index.vue # 主布局组件 │ │ ├── appContent/ # 应用内容区组件 │ │ │ └── index.vue │ │ ├── appLogo/ # 应用 Logo 组件 │ │ │ └── index.vue │ │ ├── headerBar/ # 顶部栏组件 │ │ │ ├── index.vue │ │ │ └── modules/ # 顶部栏子模块 │ │ │ ├── BreadcrumbNav.vue # 面包屑导航 │ │ │ ├── MenuToggle.vue # 菜单折叠按钮 │ │ │ ├── PageRefresh.vue # 页面刷新按钮 │ │ │ └── UserDropdown.vue # 用户下拉菜单 │ │ ├── sidebarMenu/ # 侧边栏菜单组件 │ │ │ ├── index.vue │ │ │ └── MenuNode.vue # 菜单节点递归组件 │ │ └── tabsBar/ # 标签页栏组件 │ │ └── index.vue │ ├── router/ # 路由配置 │ │ ├── index.ts # 路由主文件 │ │ ├── constants.ts # 路由常量定义 │ │ └── modules/ # 路由模块 │ │ ├── staticRoutes.ts # 静态路由（登录、404 等） │ │ ├── nestedRouter.ts # 嵌套路由示例 │ │ └── exampleRouter.ts # 组件示例路由 │ ├── stores/ # Pinia Store 目录 │ │ ├── authStore.ts # 认证状态管理 │ │ ├── routeStore.ts # 路由状态管理 │ │ ├── sidebarMenuStore.ts # 侧边栏菜单状态管理 │ │ ├── tabsStore.ts # 标签页状态管理 │ │ └── themeStore.ts # 主题状态管理 │ ├── styles/ # 样式文件目录 │ │ ├── index.scss # 全局样式入口 │ │ └── modules/ # 样式模块 │ │ ├── variables.scss # SCSS 变量定义 │ │ ├── nprogress.scss # 进度条样式 │ │ └── transition.scss # 过渡动画样式 │ ├── types/ # TypeScript 类型定义 │ │ ├── components.d.ts # 全局组件类型声明 │ │ └── menu.ts # 菜单数据类型定义 │ ├── utils/ # 工具函数目录 │ │ ├── authToken.ts # Token 管理工具 │ │ ├── httpClient.ts # HTTP 客户端（Axios 封装） │ │ ├── iconifyLocalLoader.ts # Iconify 图标集网络加载器 │ │ ├── iconSizeHelper.ts # 图标尺寸辅助工具 │ │ ├── pageTitle.ts # 页面标题工具 │ │ ├── progressBar.ts # 进度条工具 │ │ └── router/ # 路由相关工具 │ │ ├── dynamicRoute.ts # 动态路由注册与管理 │ │ ├── helper.ts # 路由辅助函数 │ │ ├── lock.ts # 路由锁定管理器 │ │ ├── menuFilter.ts # 路由菜单过滤器 │ │ └── menuInterface.ts # 菜单数据接口模拟 │ ├── views/ # 页面视图目录 │ │ ├── 404/ # 404 错误页面 │ │ ├── dashboard/ # 仪表盘页面 │ │ ├── login/ # 登录页面 │ │ ├── project_description/ # 项目描述页面 │ │ ├── nested/ # 嵌套路由示例页面 │ │ │ └── nested_menu_1/ │ │ │ ├── nested_menu_1_1/ │ │ │ ├── nested_menu_1_2/ │ │ │ │ ├── nested_menu_1_2_1/ │ │ │ │ └── nested_menu_1_2_2/ │ │ │ └── nested_menu_1_3/ │ │ └── example/ # 组件示例页面 │ │ ├── smart_dialog_example/ # SmartDialog 示例 │ │ ├── smart_drawer_example/ # SmartDrawer 示例 │ │ ├── smart_echarts_example/ # ECharts 图表示例 │ │ ├── smart_form_example/ # SmartForm 示例 │ │ ├── smart_js_tree_example/ # JSON 树形查看器示例 │ │ ├── smart_table_example/ # SmartTable 示例 │ │ └── visualization_form_example/ # 可视化表单设计器示例 │ ├── App.vue # 根组件 │ ├── main.ts # 应用入口文件 │ └── permission.ts # 路由权限守卫 ├── .cursor/ # Cursor IDE 配置目录 │ └── skills/ # AI 辅助编码技能规则 ├── .gitattributes # Git 属性配置 ├── .gitignore # Git 忽略文件配置 ├── .prettierrc.json # Prettier 格式化配置 ├── .vscode/ # VSCode/Cursor 编辑器配置 │ └── extensions.json # 推荐扩展列表 ├── env.d.ts # 环境变量与第三方模块类型声明 ├── index.html # HTML 模板 ├── package.json # 项目依赖配置 ├── package-lock.json # 依赖锁定文件 ├── README.md # 项目说明文档 ├── tsconfig.json # TypeScript 主配置（项目引用） ├── tsconfig.app.json # TypeScript 应用配置 ├── tsconfig.node.json # TypeScript Node 配置 ├── tsconfig.vitest.json # TypeScript 测试配置 ├── vite.config.ts # Vite 构建配置 └── vitest.config.ts # Vitest 测试配置 ``` ## 开发规范 ### 代码风格 - 所有代码必须使用 **Prettier** 进行格式化 - 函数定义优先使用**箭头函数** - 条件判断应保持**积极语义**，避免逻辑取反 - 同一逻辑的代码块应**集中放置**，确保高内聚 ### 命名规范 #### 页面目录 - `views` 目录下新增页面时，需先创建目录 - 目录名使用对应的**英文单词**（禁止使用拼音或中文） - 目录名使用**下划线连接**（如 `user_profile`） - 在该目录内创建 `index.vue` 文件 #### 组件命名 - `components` 目录下新增的业务组件，名称必须以 **`Smart`** 开头 - 采用**大驼峰命名法**（如 `SmartForm`、`SmartTable`、`SmartCard`） - 通用组件可使用其他命名（如 `SmartIconifyIcon`） #### 样式类名 - 自定义 CSS 类名使用**下划线连接**（如 `.module_container`） - 禁止在自定义类名中使用连字符（`-`） ### 样式开发规范 #### 优先级 1. **Element Plus** 组件自带样式与官方变量 2. **SCSS** 自定义样式（组件内 scoped 优先） 3. **全局样式模块**（仅用于基础重置或跨页面复用） #### SCSS 书写规范 - 使用 SCSS 变量统一颜色、间距、阴影、圆角等 - 需要跨组件共享的变量放入 `src/styles/index.scss` - 避免过深选择器；控制在 3 层以内 - 使用父选择器 `&` 书写伪类、伪元素与状态 ### 函数注释规范 所有导出函数、公共方法及关键内部函数必须添加标准注释： ```typescript /** * @author zed * @date YYYY-MM-DD * @description 用一到两句话准确描述函数职责、输入输出与副作用 * @param paramName 参数中文描述（类型：Type，是否可选：是/否，默认值：xxx） * @param anotherParam 另一参数描述（类型：Type） * @returns 返回值中文描述（类型：ReturnType，空则写 void/undefined） * @throws 可能抛出的异常/错误场景说明（没有可省略） * @example * // 简要示例（可选） * const result = yourFunctionName(arg1, arg2) * console.log(result) */ export const yourFunctionName = (paramName: Type, anotherParam: Type): ReturnType => { // 函数体 }; ``` ### TypeScript 规范 - 明确定义接口和类型，严格避免滥用 `any` 类型 - 使用类型推断时确保类型安全 - 组件类型定义放在组件目录的 `types.ts` 或 `type.ts` 文件中 ### Smart 组件库 项目内置了丰富的 Smart 系列组件，提供统一的 API 和交互体验： - **SmartForm**：智能表单组件，支持多种表单项类型，自动布局和验证 - **SmartTable**：智能表格组件，支持排序、筛选、分页、选择等功能 - **SmartCard**：智能卡片组件，提供统一的卡片样式和布局 - **SmartDialog**：智能对话框组件，封装常用对话框场景 - **SmartDrawer**：智能抽屉组件，提供侧边滑出式内容展示 - **SmartImgPuzzle**：拼图验证码组件，提供安全的用户验证 - **SmartLanguageToggle**：语言切换组件，支持中英文切换 - **SmartQuickTools**：快捷工具组件，提供常用快捷操作 - **SmartTagsViews**：标签页视图组件，支持多标签页管理 - **SmartThemeToggle**：主题切换组件，支持明暗主题切换 所有 Smart 组件已全局注册，可在任意模板中直接使用，无需手动导入。组件使用示例请参考 `src/modules/example/views/` 目录下的示例页面。 ## 构建配置说明 ### Vite 配置特性 - **路径别名**：`@` 指向 `src` 目录 - **代理配置**：开发环境支持 API 代理（配置在 `vite.config.ts` 的 `server.proxy`） - **代码分割**：自动将 Vue、Element Plus、工具库分离为独立 chunk - **生产优化**：自动移除 `console` 和 `debugger`，启用代码压缩 ### 构建产物 - **输出目录**：`dist` - **静态资源目录**：`dist/assets` - **文件命名**：使用 hash 确保缓存更新 ## 测试 ### 运行测试 ```bash npm run test:unit ``` ### 测试框架 - **Vitest**：基于 Vite 的单元测试框架，支持 ESM 和 HMR - **@vue/test-utils**：Vue 组件测试工具 - **jsdom**：提供 DOM 环境模拟 ### 测试文件位置 测试文件位于 `src/__tests__/` 目录，命名格式为 `*.spec.ts`。 ## 部署 ### 构建生产版本 ```bash npm run build ``` ### 部署注意事项 1. 确保 `VITE_BASE_URL` 环境变量与部署路径匹配 2. 如果部署在子路径下，需要配置正确的 `base` 路径 3. 生产环境建议启用 HTTPS 4. 配置适当的缓存策略（静态资源使用长期缓存，HTML 使用协商缓存） ## 常见问题 ### 端口被占用 修改 `.env.development` 文件中的 `VITE_PORT` 环境变量，或直接修改 `vite.config.ts` 中的端口配置。 ### 图标不显示 确保网络环境可访问 `https://api.iconify.design`，并且图标名称拼写正确（格式：`collection:icon-name`）。 ### 样式不生效 1. 确认 SCSS 文件是否正确导入（`src/styles/index.scss`） 2. 检查组件内 `scoped` 样式是否被覆盖 3. 检查 Element Plus 样式是否已导入 ### TypeScript 类型错误 运行 `npm run type-check` 检查类型错误，确保所有类型定义正确。 ## 许可证 本项目为私有项目，未经授权不得使用。 ## 更新日志 ### v1.0.0 (2025-11-27) - 初始版本发布 - 集成 Vue 3 + TypeScript + Vite - 集成路由、状态管理、国际化 - 集成 Element Plus + SCSS 样式体系 - 支持主题切换、语言切换 - 集成单元测试框架 --- **项目维护者**: zed 😊 **最后更新**: 2026-02-09