# 智能柜管理系统 - 前端项目说明文档 ## 项目概述 本项目是一个基于 Vue 3 + TypeScript + Element Plus 的智能柜管理系统前端应用，主要用于管理智能柜设备、商品库存、订单处理等业务功能。 ### 项目基本信息 - **项目名称**: agileboot-front-end-pure - **版本**: 1.0.0 - **技术栈**: Vue 3 + TypeScript + Element Plus + Vite + Pinia - **开发语言**: TypeScript - **包管理器**: pnpm - **构建工具**: Vite ## 技术架构 ### 核心技术栈 - **Vue 3**: 渐进式 JavaScript 框架 - **TypeScript**: 类型安全的 JavaScript 超集 - **Element Plus**: Vue 3 版本的 Element UI 组件库 - **Vite**: 下一代前端构建工具 - **Pinia**: Vue 官方状态管理库 - **Vue Router**: Vue 官方路由管理 ### 开发工具链 - **ESLint**: 代码质量检查 - **Prettier**: 代码格式化 - **Stylelint**: CSS/SCSS 代码检查 - **Husky**: Git hooks 管理 - **Commitlint**: 提交信息规范检查 ## 项目结构 ``` shop-front-end/ ├── src/ # 源代码目录 │ ├── api/ # API 接口 │ │ ├── ab98/ # 会员相关接口 │ │ ├── cabinet/ # 智能柜相关接口 │ │ ├── common/ # 通用接口 │ │ ├── qy/ # 企业用户相关接口 │ │ ├── shop/ # 店铺相关接口 │ │ └── system/ # 系统管理接口 │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ │ ├── QrCodeHover/ # 二维码悬浮组件 │ │ ├── ReAuth/ # 权限组件 │ │ ├── ReCol/ # 布局组件 │ │ ├── ReCropper/ # 图片裁剪组件 │ │ ├── ReDialog/ # 对话框组件 │ │ ├── ReIcon/ # 图标组件 │ │ ├── ReImageVerify/# 图片验证组件 │ │ ├── RePureTableBar/ # 表格工具栏 │ │ ├── ReQrcode/ # 二维码组件 │ │ ├── ReTypeit/ # 打字机效果组件 │ │ └── VDialog/ # 对话框组件 │ ├── config/ # 配置文件 │ ├── directives/ # 自定义指令 │ ├── layout/ # 布局组件 │ ├── plugins/ # 插件配置 │ ├── router/ # 路由配置 │ │ └── modules/ # 路由模块 │ ├── store/ # 状态管理 │ │ └── modules/ # store 模块 │ ├── style/ # 样式文件 │ ├── utils/ # 工具函数 │ └── views/ # 页面组件 │ ├── cabinet/ # 智能柜管理 │ ├── error/ # 错误页面 │ ├── login/ # 登录页面 │ ├── permission/ # 权限页面 │ ├── qy/ # 企业管理 │ ├── shop/ # 店铺管理 │ ├── system/ # 系统管理 │ ├── user/ # 用户管理 │ └── welcome/ # 首页 ├── build/ # 构建脚本 ├── dist/ # 构建输出 ├── public/ # 公共资源 └── doc/ # 项目文档 ``` ## 核心功能模块 ### 1. 智能柜管理 (cabinet) - **柜体管理**: 智能柜设备的管理和维护 - **格口管理**: 柜体格口的配置和状态监控 - **设备操作**: 柜体设备的远程控制 - **MQTT 服务器**: 设备通信服务管理 ### 2. 店铺管理 (shop) - **商品管理**: 商品信息、库存管理 - **分类管理**: 商品分类体系 - **订单管理**: 订单处理和状态跟踪 - **审批中心**: 业务审批流程 ### 3. 企业管理 (qy) - **企业用户管理**: 企业用户信息管理 - **余额管理**: 用户余额和消费记录 ### 4. 系统管理 (system) - **用户管理**: 系统用户管理 - **权限管理**: 角色和权限配置 - **个人中心**: 用户个人信息管理 ### 5. 会员管理 (ab98) - **会员信息**: 会员资料管理 - **会员详情**: 会员详细信息展示 ## API 接口结构 ### 智能柜相关 (api/cabinet/) - `smart-cabinet.ts`: 智能柜设备管理 - `cabinet-cell.ts`: 柜体格口管理 - `cell-operation.ts`: 格口操作 - `mainboards.ts`: 主板管理 - `mqttServer.ts`: MQTT 服务器管理 ### 店铺相关 (api/shop/) - `shop.ts`: 店铺管理 - `goods.ts`: 商品管理 - `category.ts`: 分类管理 - `order.ts`: 订单管理 - `approval.ts`: 审批管理 - `stats.ts`: 数据统计 ### 企业用户相关 (api/qy/) - `qyUser.ts`: 企业用户管理 ### 系统相关 (api/system/) - 系统管理接口 ## 路由配置 项目采用动态路由和静态路由结合的方式： - **静态路由**: 在 `src/router/modules/` 中定义 - **动态路由**: 根据用户权限动态生成 - **路由守卫**: 实现权限验证和登录状态检查 主要路由模块： - `global.ts`: 全局路由配置 - `home.ts`: 首页路由 - `error.ts`: 错误页面路由 - `remaining.ts`: 剩余路由处理 ## 状态管理 使用 Pinia 进行状态管理，主要模块包括： - **权限管理**: 用户权限状态 - **按钮权限**: 按钮级别权限控制 - **系统配置**: 系统配置信息 - **微信相关**: 企业微信集成状态 ## 开发环境配置 ### 环境要求 - **Node.js**: 16.0+ - **pnpm**: 6.0+ - **推荐环境**: Node.js 16 + pnpm 7.30.5 ### 开发命令 ```bash # 安装依赖 pnpm install # 启动开发服务器 pnpm dev # 构建生产版本 pnpm build # 代码检查 pnpm lint # 类型检查 pnpm typecheck ``` ### 开发工具配置 - **VSCode 配置**: `.vscode/` 目录下的配置文件 - **代码规范**: ESLint + Prettier + Stylelint - **Git hooks**: Husky + Commitlint ## 构建和部署 ### 构建配置 - **构建工具**: Vite - **输出目录**: `dist/` - **资源优化**: 图片压缩、代码分割 - **CDN 支持**: 支持 CDN 引入第三方库 ### 环境变量 项目使用环境变量配置： - `VITE_ROUTER_HISTORY`: 路由历史模式 - `VITE_HIDE_HOME`: 是否隐藏首页 - `VITE_PORT`: 开发服务器端口 - `VITE_PUBLIC_PATH`: 公共路径 ## 特色功能 ### 1. 企业微信集成 - 支持企业微信扫码登录 - 企业微信用户信息同步 - 企业微信回调处理 ### 2. 智能柜设备管理 - MQTT 协议设备通信 - 实时设备状态监控 - 远程设备控制 ### 3. 数据统计看板 - 实时数据统计展示 - 商品借还排行 - 今日订单数据 - 设备状态监控 ### 4. 权限管理系统 - 按钮级别权限控制 - 动态路由生成 - 角色权限分配 ## 代码规范 ### 命名规范 - 组件名: PascalCase - 文件名: kebab-case - 变量名: camelCase - 常量名: UPPER_SNAKE_CASE ### 文件组织 - 每个功能模块独立目录 - API 接口按业务模块划分 - 组件按功能分类 - 工具函数统一管理 ## 依赖管理 ### 主要依赖 - **Vue 生态**: vue@3.3.4, vue-router@4.2.2, pinia@2.1.4 - **UI 组件**: element-plus@2.3.6 - **工具库**: @vueuse/core@10.2.0, axios@1.4.0, dayjs@1.11.8 - **构建工具**: vite@4.3.9, typescript@5.0.4 ### 开发依赖 - **代码质量**: eslint@8.43.0, prettier@2.8.8, stylelint@15.9.0 - **类型检查**: vue-tsc@1.8.1 - **Git hooks**: husky@8.0.3, commitlint@17.6.6 ## 部署说明 ### 生产环境部署 1. 构建生产版本 ```bash pnpm build ``` 2. 部署到 Web 服务器 - 将 `dist/` 目录内容部署到服务器 - 配置服务器支持 SPA 路由 - 配置反向代理 API 请求 ### 环境配置 生产环境需要配置 `serverConfig.json` 文件，包含服务器地址等配置信息。 ## 维护和更新 ### 版本管理 - 使用 Git 进行版本控制 - 遵循语义化版本规范 - 使用 Conventional Commits 规范提交信息 ### 问题排查 - 查看浏览器控制台错误信息 - 检查网络请求状态 - 查看应用日志输出 - 使用 Vue Devtools 调试 ## 扩展开发 ### 添加新功能模块 1. 在 `src/views/` 创建页面组件 2. 在 `src/api/` 添加接口定义 3. 在路由配置中添加路由 4. 在状态管理中添加相关状态 ### 自定义组件开发 1. 在 `src/components/` 创建组件 2. 遵循组件开发规范 3. 提供 TypeScript 类型定义 4. 编写组件文档 --- **文档版本**: 1.0 **最后更新**: 2025-10-15 **维护者**: Claude Code Assistant