330 lines
8.3 KiB
Markdown
330 lines
8.3 KiB
Markdown
# 智能柜管理系统 - 前端项目说明文档
|
|
|
|
## 项目概述
|
|
|
|
本项目是一个基于 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 |