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

## 项目概述

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