8.3 KiB

Raw Permalink Blame History

智能柜管理系统 - 前端项目说明文档

项目概述

本项目是一个基于 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

开发命令

# 安装依赖
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

部署说明

生产环境部署

构建生产版本
```
pnpm build
```
部署到 Web 服务器
- 将 dist/ 目录内容部署到服务器
- 配置服务器支持 SPA 路由
- 配置反向代理 API 请求

环境配置

生产环境需要配置 serverConfig.json 文件，包含服务器地址等配置信息。

维护和更新

版本管理

使用 Git 进行版本控制
遵循语义化版本规范
使用 Conventional Commits 规范提交信息

问题排查

查看浏览器控制台错误信息
检查网络请求状态
查看应用日志输出
使用 Vue Devtools 调试

扩展开发

添加新功能模块

在 src/views/ 创建页面组件
在 src/api/ 添加接口定义
在路由配置中添加路由
在状态管理中添加相关状态

自定义组件开发

在 src/components/ 创建组件
遵循组件开发规范
提供 TypeScript 类型定义
编写组件文档

文档版本: 1.0 最后更新: 2025-10-15 维护者: Claude Code Assistant

8.3 KiB Raw Permalink Blame History