docs: 添加项目文档和配置文件
- 新增项目说明文档，包含技术架构和核心功能 - 添加开发指南文档，规范开发流程 - 创建API接口文档，详细描述各模块接口 - 编写部署和维护指南，提供生产环境配置 - 添加.claude配置文件，设置权限规则
This commit is contained in:
dzq
parent
d69e6540e3
commit
864ef9a1fa
|
|
@ -0,0 +1,9 @@
|
||||||
|
{
|
||||||
|
"permissions": {
|
||||||
|
"allow": [
|
||||||
|
"Bash(mkdir:*)"
|
||||||
|
],
|
||||||
|
"deny": [],
|
||||||
|
"ask": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,594 @@
|
||||||
|
# API 接口文档
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
本文档详细描述了智能柜管理系统前端项目的所有 API 接口，按业务模块分类。
|
||||||
|
|
||||||
|
## 通用接口
|
||||||
|
|
||||||
|
### 登录认证
|
||||||
|
|
||||||
|
#### 1. 获取配置信息
|
||||||
|
- **接口**: `GET /api/common/login/config`
|
||||||
|
- **描述**: 获取系统配置信息
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
serverHost: string
|
||||||
|
// 其他配置信息
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 密码登录
|
||||||
|
- **接口**: `POST /api/common/login/password`
|
||||||
|
- **描述**: 使用用户名密码登录
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
username: string
|
||||||
|
password: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
token: string
|
||||||
|
userInfo: User
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 企业微信登录
|
||||||
|
- **接口**: `POST /api/common/login/wechat`
|
||||||
|
- **描述**: 企业微信扫码登录
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
corpid: string
|
||||||
|
code: string
|
||||||
|
state?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 智能柜管理模块
|
||||||
|
|
||||||
|
### 智能柜设备管理
|
||||||
|
|
||||||
|
#### 1. 获取智能柜列表
|
||||||
|
- **接口**: `GET /api/cabinet/smart-cabinet/list`
|
||||||
|
- **描述**: 获取智能柜设备列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
status?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: SmartCabinet[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 创建智能柜
|
||||||
|
- **接口**: `POST /api/cabinet/smart-cabinet`
|
||||||
|
- **描述**: 创建新的智能柜设备
|
||||||
|
- **参数**: `SmartCabinet`
|
||||||
|
- **返回**: `SmartCabinet`
|
||||||
|
|
||||||
|
#### 3. 更新智能柜
|
||||||
|
- **接口**: `PUT /api/cabinet/smart-cabinet/{id}`
|
||||||
|
- **描述**: 更新智能柜信息
|
||||||
|
- **参数**: `Partial<SmartCabinet>`
|
||||||
|
- **返回**: `SmartCabinet`
|
||||||
|
|
||||||
|
#### 4. 删除智能柜
|
||||||
|
- **接口**: `DELETE /api/cabinet/smart-cabinet/{id}`
|
||||||
|
- **描述**: 删除智能柜设备
|
||||||
|
|
||||||
|
### 柜体格口管理
|
||||||
|
|
||||||
|
#### 1. 获取格口列表
|
||||||
|
- **接口**: `GET /api/cabinet/cabinet-cell/list`
|
||||||
|
- **描述**: 获取柜体格口列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
cabinetId?: number
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
status?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: CabinetCell[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 格口操作
|
||||||
|
- **接口**: `POST /api/cabinet/cell-operation/{operation}`
|
||||||
|
- **描述**: 执行格口操作（开门、关门等）
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
cellId: number
|
||||||
|
operation: 'open' | 'close' | 'reset'
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### MQTT 服务器管理
|
||||||
|
|
||||||
|
#### 1. 获取 MQTT 服务器列表
|
||||||
|
- **接口**: `GET /api/cabinet/mqtt-server/list`
|
||||||
|
- **描述**: 获取 MQTT 服务器配置列表
|
||||||
|
- **返回**: `MqttServer[]`
|
||||||
|
|
||||||
|
#### 2. 测试 MQTT 连接
|
||||||
|
- **接口**: `POST /api/cabinet/mqtt-server/test`
|
||||||
|
- **描述**: 测试 MQTT 服务器连接
|
||||||
|
- **参数**: `MqttServer`
|
||||||
|
|
||||||
|
## 店铺管理模块
|
||||||
|
|
||||||
|
### 店铺管理
|
||||||
|
|
||||||
|
#### 1. 获取店铺列表
|
||||||
|
- **接口**: `GET /api/shop/shop/list`
|
||||||
|
- **描述**: 获取店铺列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: Shop[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 创建店铺
|
||||||
|
- **接口**: `POST /api/shop/shop`
|
||||||
|
- **描述**: 创建新店铺
|
||||||
|
- **参数**: `Shop`
|
||||||
|
- **返回**: `Shop`
|
||||||
|
|
||||||
|
#### 3. 更新店铺
|
||||||
|
- **接口**: `PUT /api/shop/shop/{id}`
|
||||||
|
- **描述**: 更新店铺信息
|
||||||
|
- **参数**: `Partial<Shop>`
|
||||||
|
- **返回**: `Shop`
|
||||||
|
|
||||||
|
#### 4. 删除店铺
|
||||||
|
- **接口**: `DELETE /api/shop/shop/{id}`
|
||||||
|
- **描述**: 删除店铺
|
||||||
|
|
||||||
|
### 商品管理
|
||||||
|
|
||||||
|
#### 1. 获取商品列表
|
||||||
|
- **接口**: `GET /api/shop/goods/list`
|
||||||
|
- **描述**: 获取商品列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
categoryId?: number
|
||||||
|
status?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: Goods[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 获取商品详情
|
||||||
|
- **接口**: `GET /api/shop/goods/{id}`
|
||||||
|
- **描述**: 获取商品详细信息
|
||||||
|
- **返回**: `Goods`
|
||||||
|
|
||||||
|
#### 3. 创建商品
|
||||||
|
- **接口**: `POST /api/shop/goods`
|
||||||
|
- **描述**: 创建新商品
|
||||||
|
- **参数**: `Goods`
|
||||||
|
- **返回**: `Goods`
|
||||||
|
|
||||||
|
#### 4. 更新商品
|
||||||
|
- **接口**: `PUT /api/shop/goods/{id}`
|
||||||
|
- **描述**: 更新商品信息
|
||||||
|
- **参数**: `Partial<Goods>`
|
||||||
|
- **返回**: `Goods`
|
||||||
|
|
||||||
|
#### 5. 删除商品
|
||||||
|
- **接口**: `DELETE /api/shop/goods/{id}`
|
||||||
|
- **描述**: 删除商品
|
||||||
|
|
||||||
|
### 分类管理
|
||||||
|
|
||||||
|
#### 1. 获取分类列表
|
||||||
|
- **接口**: `GET /api/shop/category/list`
|
||||||
|
- **描述**: 获取商品分类列表
|
||||||
|
- **返回**: `Category[]`
|
||||||
|
|
||||||
|
#### 2. 创建分类
|
||||||
|
- **接口**: `POST /api/shop/category`
|
||||||
|
- **描述**: 创建新分类
|
||||||
|
- **参数**: `Category`
|
||||||
|
- **返回**: `Category`
|
||||||
|
|
||||||
|
#### 3. 更新分类
|
||||||
|
- **接口**: `PUT /api/shop/category/{id}`
|
||||||
|
- **描述**: 更新分类信息
|
||||||
|
- **参数**: `Partial<Category>`
|
||||||
|
- **返回**: `Category`
|
||||||
|
|
||||||
|
#### 4. 删除分类
|
||||||
|
- **接口**: `DELETE /api/shop/category/{id}`
|
||||||
|
- **描述**: 删除分类
|
||||||
|
|
||||||
|
### 订单管理
|
||||||
|
|
||||||
|
#### 1. 获取订单列表
|
||||||
|
- **接口**: `GET /api/shop/order/list`
|
||||||
|
- **描述**: 获取订单列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
status?: string
|
||||||
|
startTime?: string
|
||||||
|
endTime?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: Order[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 获取订单详情
|
||||||
|
- **接口**: `GET /api/shop/order/{id}`
|
||||||
|
- **描述**: 获取订单详细信息
|
||||||
|
- **返回**: `Order`
|
||||||
|
|
||||||
|
#### 3. 创建订单
|
||||||
|
- **接口**: `POST /api/shop/order`
|
||||||
|
- **描述**: 创建新订单
|
||||||
|
- **参数**: `Order`
|
||||||
|
- **返回**: `Order`
|
||||||
|
|
||||||
|
#### 4. 更新订单状态
|
||||||
|
- **接口**: `PUT /api/shop/order/{id}/status`
|
||||||
|
- **描述**: 更新订单状态
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
status: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 审批管理
|
||||||
|
|
||||||
|
#### 1. 获取审批列表
|
||||||
|
- **接口**: `GET /api/shop/approval/list`
|
||||||
|
- **描述**: 获取审批列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
type?: string
|
||||||
|
status?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: Approval[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 审批操作
|
||||||
|
- **接口**: `POST /api/shop/approval/{id}/action`
|
||||||
|
- **描述**: 执行审批操作
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
action: 'approve' | 'reject'
|
||||||
|
remark?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据统计
|
||||||
|
|
||||||
|
#### 1. 获取统计数据
|
||||||
|
- **接口**: `GET /api/shop/stats`
|
||||||
|
- **描述**: 获取系统统计数据
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
corpid: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
shopCount: number
|
||||||
|
goodsCount: number
|
||||||
|
orderCount: number
|
||||||
|
goodsTotalAmount: number
|
||||||
|
unReturnedGoodsCount: number
|
||||||
|
unReturnedOrderCount: number
|
||||||
|
unReturnedAmount: number
|
||||||
|
cabinetCount: number
|
||||||
|
cellCount: number
|
||||||
|
linkedCellCount: number
|
||||||
|
unmanagedCellCount: number
|
||||||
|
gatewayCount: number
|
||||||
|
topGoods: TopGoodsDTO[]
|
||||||
|
todayLatestOrderGoods: TodayLatestOrderGoodsDTO[]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 企业管理模块
|
||||||
|
|
||||||
|
### 企业用户管理
|
||||||
|
|
||||||
|
#### 1. 获取企业用户列表
|
||||||
|
- **接口**: `GET /api/qy/qy-user/list`
|
||||||
|
- **描述**: 获取企业用户列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: QyUser[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 获取企业用户详情
|
||||||
|
- **接口**: `GET /api/qy/qy-user/{id}`
|
||||||
|
- **描述**: 获取企业用户详细信息
|
||||||
|
- **返回**: `QyUser`
|
||||||
|
|
||||||
|
#### 3. 更新企业用户
|
||||||
|
- **接口**: `PUT /api/qy/qy-user/{id}`
|
||||||
|
- **描述**: 更新企业用户信息
|
||||||
|
- **参数**: `Partial<QyUser>`
|
||||||
|
- **返回**: `QyUser`
|
||||||
|
|
||||||
|
#### 4. 绑定汇邦云账号
|
||||||
|
- **接口**: `POST /api/ab98/user/bind`
|
||||||
|
- **描述**: 绑定汇邦云会员账号
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
qyUserId: number
|
||||||
|
name: string
|
||||||
|
idNum: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 系统管理模块
|
||||||
|
|
||||||
|
### 用户管理
|
||||||
|
|
||||||
|
#### 1. 获取用户列表
|
||||||
|
- **接口**: `GET /api/system/user/list`
|
||||||
|
- **描述**: 获取系统用户列表
|
||||||
|
- **参数**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
- **返回**:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
list: SystemUser[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 创建用户
|
||||||
|
- **接口**: `POST /api/system/user`
|
||||||
|
- **描述**: 创建新用户
|
||||||
|
- **参数**: `SystemUser`
|
||||||
|
- **返回**: `SystemUser`
|
||||||
|
|
||||||
|
#### 3. 更新用户
|
||||||
|
- **接口**: `PUT /api/system/user/{id}`
|
||||||
|
- **描述**: 更新用户信息
|
||||||
|
- **参数**: `Partial<SystemUser>`
|
||||||
|
- **返回**: `SystemUser`
|
||||||
|
|
||||||
|
#### 4. 删除用户
|
||||||
|
- **接口**: `DELETE /api/system/user/{id}`
|
||||||
|
- **描述**: 删除用户
|
||||||
|
|
||||||
|
## 数据类型定义
|
||||||
|
|
||||||
|
### 通用类型
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 分页响应
|
||||||
|
type PaginationResponse<T> = {
|
||||||
|
list: T[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
|
||||||
|
// 基础实体
|
||||||
|
interface BaseEntity {
|
||||||
|
id: number
|
||||||
|
createTime: string
|
||||||
|
updateTime: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 智能柜相关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface SmartCabinet extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
code: string
|
||||||
|
status: 'online' | 'offline' | 'maintenance'
|
||||||
|
location: string
|
||||||
|
ipAddress: string
|
||||||
|
mqttServerId: number
|
||||||
|
}
|
||||||
|
|
||||||
|
interface CabinetCell extends BaseEntity {
|
||||||
|
cabinetId: number
|
||||||
|
cellNo: string
|
||||||
|
status: 'empty' | 'occupied' | 'fault'
|
||||||
|
goodsId?: number
|
||||||
|
}
|
||||||
|
|
||||||
|
interface MqttServer extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
host: string
|
||||||
|
port: number
|
||||||
|
username?: string
|
||||||
|
password?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 店铺相关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface Shop extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
code: string
|
||||||
|
address: string
|
||||||
|
contact: string
|
||||||
|
phone: string
|
||||||
|
status: 'active' | 'inactive'
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Goods extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
code: string
|
||||||
|
categoryId: number
|
||||||
|
price: number
|
||||||
|
stock: number
|
||||||
|
coverImg: string
|
||||||
|
description?: string
|
||||||
|
status: 'available' | 'sold_out' | 'disabled'
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Category extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
parentId?: number
|
||||||
|
sort: number
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Order extends BaseEntity {
|
||||||
|
orderNo: string
|
||||||
|
userId: number
|
||||||
|
totalAmount: number
|
||||||
|
status: 'pending' | 'processing' | 'completed' | 'cancelled'
|
||||||
|
goodsList: OrderGoods[]
|
||||||
|
}
|
||||||
|
|
||||||
|
interface OrderGoods extends BaseEntity {
|
||||||
|
orderId: number
|
||||||
|
goodsId: number
|
||||||
|
quantity: number
|
||||||
|
price: number
|
||||||
|
totalAmount: number
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Approval extends BaseEntity {
|
||||||
|
type: string
|
||||||
|
applicantId: number
|
||||||
|
targetId: number
|
||||||
|
status: 'pending' | 'approved' | 'rejected'
|
||||||
|
remark?: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 统计相关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface TopGoodsDTO {
|
||||||
|
goodsId: number
|
||||||
|
goodsName: string
|
||||||
|
coverImg: string
|
||||||
|
occurrenceCount: number
|
||||||
|
}
|
||||||
|
|
||||||
|
interface TodayLatestOrderGoodsDTO {
|
||||||
|
orderGoodsId: number
|
||||||
|
goodsName: string
|
||||||
|
coverImg: string
|
||||||
|
quantity: number
|
||||||
|
totalAmount: number
|
||||||
|
buyerName: string
|
||||||
|
createTimeStr: string
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 企业用户相关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface QyUser extends BaseEntity {
|
||||||
|
name: string
|
||||||
|
userId: string
|
||||||
|
department?: string
|
||||||
|
position?: string
|
||||||
|
mobile?: string
|
||||||
|
email?: string
|
||||||
|
avatar?: string
|
||||||
|
ab98UserId?: number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 错误码说明
|
||||||
|
|
||||||
|
| 错误码 | 说明 | 处理建议 |
|
||||||
|
|--------|------|----------|
|
||||||
|
| 401 | 未授权 | 检查 token 是否有效 |
|
||||||
|
| 403 | 禁止访问 | 检查用户权限 |
|
||||||
|
| 404 | 资源不存在 | 检查请求路径 |
|
||||||
|
| 500 | 服务器内部错误 | 联系系统管理员 |
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. 所有接口都需要在请求头中携带 token
|
||||||
|
2. 分页参数 page 从 1 开始
|
||||||
|
3. 时间参数使用 ISO 8601 格式
|
||||||
|
4. 文件上传使用 multipart/form-data
|
||||||
|
5. 接口返回统一使用 JSON 格式
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文档版本**: 1.0
|
||||||
|
**最后更新**: 2025-10-15
|
||||||
|
|
@ -0,0 +1,69 @@
|
||||||
|
# 项目文档目录
|
||||||
|
|
||||||
|
本目录包含智能柜管理系统前端项目的完整技术文档。
|
||||||
|
|
||||||
|
## 文档列表
|
||||||
|
|
||||||
|
### 📋 核心文档
|
||||||
|
|
||||||
|
1. **[项目说明文档.md](./项目说明文档.md)**
|
||||||
|
- 项目概述和技术架构
|
||||||
|
- 项目结构和核心功能
|
||||||
|
- 技术栈和开发环境
|
||||||
|
|
||||||
|
2. **[开发指南.md](./开发指南.md)**
|
||||||
|
- 开发环境搭建
|
||||||
|
- 代码规范和最佳实践
|
||||||
|
- API 开发规范
|
||||||
|
- 组件开发指南
|
||||||
|
|
||||||
|
3. **[API接口文档.md](./API接口文档.md)**
|
||||||
|
- 完整的 API 接口说明
|
||||||
|
- 按业务模块分类
|
||||||
|
- 数据类型定义
|
||||||
|
- 错误码说明
|
||||||
|
|
||||||
|
4. **[部署和维护指南.md](./部署和维护指南.md)**
|
||||||
|
- 生产环境部署流程
|
||||||
|
- 系统维护操作
|
||||||
|
- 故障排除指南
|
||||||
|
- 性能优化配置
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 开发人员
|
||||||
|
|
||||||
|
1. 阅读 **[项目说明文档.md](./项目说明文档.md)** 了解项目概况
|
||||||
|
2. 按照 **[开发指南.md](./开发指南.md)** 搭建开发环境
|
||||||
|
3. 参考 **[API接口文档.md](./API接口文档.md)** 进行接口开发
|
||||||
|
|
||||||
|
### 运维人员
|
||||||
|
|
||||||
|
1. 阅读 **[部署和维护指南.md](./部署和维护指南.md)**
|
||||||
|
2. 按照文档进行生产环境部署
|
||||||
|
3. 了解日常维护操作和故障排除方法
|
||||||
|
|
||||||
|
## 文档维护
|
||||||
|
|
||||||
|
### 更新流程
|
||||||
|
|
||||||
|
1. 项目有重大变更时，及时更新相关文档
|
||||||
|
2. 新增功能模块时，补充相应的 API 文档
|
||||||
|
3. 技术栈升级时，更新开发指南
|
||||||
|
|
||||||
|
### 版本控制
|
||||||
|
|
||||||
|
- 文档版本与项目版本保持一致
|
||||||
|
- 每次更新记录变更内容和日期
|
||||||
|
- 重要变更需要在文档中标注
|
||||||
|
|
||||||
|
## 联系我们
|
||||||
|
|
||||||
|
如有文档相关问题，请联系：
|
||||||
|
- 项目维护团队
|
||||||
|
- 技术负责人
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**最后更新**: 2025-10-15
|
||||||
|
**文档版本**: 1.0
|
||||||
|
|
@ -0,0 +1,639 @@
|
||||||
|
# 开发指南
|
||||||
|
|
||||||
|
## 开发环境搭建
|
||||||
|
|
||||||
|
### 1. 环境准备
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装 Node.js (版本 16.0+)
|
||||||
|
# 下载地址: https://nodejs.org/
|
||||||
|
|
||||||
|
# 安装 pnpm
|
||||||
|
npm install -g pnpm
|
||||||
|
|
||||||
|
# 验证安装
|
||||||
|
node --version
|
||||||
|
pnpm --version
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 项目初始化
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
git clone <repository-url>
|
||||||
|
cd shop-front-end
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 启动开发服务器
|
||||||
|
pnpm dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 开发工具配置
|
||||||
|
|
||||||
|
推荐使用 VSCode 并安装以下插件：
|
||||||
|
- Vue Language Features (Volar)
|
||||||
|
- TypeScript Vue Plugin (Volar)
|
||||||
|
- ESLint
|
||||||
|
- Prettier
|
||||||
|
- Stylelint
|
||||||
|
|
||||||
|
## 代码规范
|
||||||
|
|
||||||
|
### 1. 命名规范
|
||||||
|
|
||||||
|
#### 文件命名
|
||||||
|
- 组件文件: `PascalCase.vue`
|
||||||
|
- 工具文件: `camelCase.ts`
|
||||||
|
- 配置文件: `kebab-case.ts`
|
||||||
|
- 样式文件: `kebab-case.scss`
|
||||||
|
|
||||||
|
#### 变量命名
|
||||||
|
```typescript
|
||||||
|
// 正确
|
||||||
|
const userName = '张三'
|
||||||
|
const MAX_COUNT = 100
|
||||||
|
const userList = []
|
||||||
|
|
||||||
|
// 避免
|
||||||
|
const username = '张三' // 驼峰
|
||||||
|
const max_count = 100 // 下划线
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 组件命名
|
||||||
|
```vue
|
||||||
|
<!-- 正确 -->
|
||||||
|
<template>
|
||||||
|
<UserProfile />
|
||||||
|
<GoodsList />
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<!-- 避免 -->
|
||||||
|
<template>
|
||||||
|
<user-profile />
|
||||||
|
<goods-list />
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 代码结构
|
||||||
|
|
||||||
|
#### Vue 组件结构
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<!-- 模板内容 -->
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<script setup lang="ts">
|
||||||
|
// 导入
|
||||||
|
import { ref, onMounted } from 'vue'
|
||||||
|
import { getUserInfo } from '@/api/user'
|
||||||
|
|
||||||
|
// 类型定义
|
||||||
|
interface User {
|
||||||
|
id: number
|
||||||
|
name: string
|
||||||
|
}
|
||||||
|
|
||||||
|
// 响应式数据
|
||||||
|
const userInfo = ref<User>()
|
||||||
|
const loading = ref(false)
|
||||||
|
|
||||||
|
// 方法
|
||||||
|
const fetchUser = async () => {
|
||||||
|
loading.value = true
|
||||||
|
try {
|
||||||
|
const { data } = await getUserInfo()
|
||||||
|
userInfo.value = data
|
||||||
|
} catch (error) {
|
||||||
|
console.error(error)
|
||||||
|
} finally {
|
||||||
|
loading.value = false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 生命周期
|
||||||
|
onMounted(() => {
|
||||||
|
fetchUser()
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<style scoped lang="scss">
|
||||||
|
/* 样式 */
|
||||||
|
</style>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. TypeScript 规范
|
||||||
|
|
||||||
|
#### 类型定义
|
||||||
|
```typescript
|
||||||
|
// 接口定义
|
||||||
|
interface Goods {
|
||||||
|
id: number
|
||||||
|
name: string
|
||||||
|
price: number
|
||||||
|
stock: number
|
||||||
|
}
|
||||||
|
|
||||||
|
// 类型别名
|
||||||
|
type GoodsStatus = 'available' | 'sold_out' | 'disabled'
|
||||||
|
|
||||||
|
// 枚举
|
||||||
|
enum OrderStatus {
|
||||||
|
PENDING = 1,
|
||||||
|
PROCESSING = 2,
|
||||||
|
COMPLETED = 3
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 函数定义
|
||||||
|
```typescript
|
||||||
|
// 带类型的函数
|
||||||
|
const formatPrice = (price: number): string => {
|
||||||
|
return `¥${price.toFixed(2)}`
|
||||||
|
}
|
||||||
|
|
||||||
|
// 异步函数
|
||||||
|
const fetchGoodsList = async (params: SearchParams): Promise<Goods[]> => {
|
||||||
|
const { data } = await getGoodsList(params)
|
||||||
|
return data
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## API 开发规范
|
||||||
|
|
||||||
|
### 1. API 文件结构
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/api/shop/goods.ts
|
||||||
|
import request from '@/utils/request'
|
||||||
|
|
||||||
|
export interface Goods {
|
||||||
|
id: number
|
||||||
|
name: string
|
||||||
|
price: number
|
||||||
|
stock: number
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface GoodsParams {
|
||||||
|
page?: number
|
||||||
|
size?: number
|
||||||
|
keyword?: string
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface GoodsListResponse {
|
||||||
|
list: Goods[]
|
||||||
|
total: number
|
||||||
|
}
|
||||||
|
|
||||||
|
// 获取商品列表
|
||||||
|
export const getGoodsList = (params: GoodsParams) => {
|
||||||
|
return request.get<GoodsListResponse>('/api/goods/list', { params })
|
||||||
|
}
|
||||||
|
|
||||||
|
// 创建商品
|
||||||
|
export const createGoods = (data: Partial<Goods>) => {
|
||||||
|
return request.post<Goods>('/api/goods', data)
|
||||||
|
}
|
||||||
|
|
||||||
|
// 更新商品
|
||||||
|
export const updateGoods = (id: number, data: Partial<Goods>) => {
|
||||||
|
return request.put<Goods>(`/api/goods/${id}`, data)
|
||||||
|
}
|
||||||
|
|
||||||
|
// 删除商品
|
||||||
|
export const deleteGoods = (id: number) => {
|
||||||
|
return request.delete(`/api/goods/${id}`)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 请求封装
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/request.ts
|
||||||
|
import axios from 'axios'
|
||||||
|
import { ElMessage } from 'element-plus'
|
||||||
|
|
||||||
|
const request = axios.create({
|
||||||
|
baseURL: import.meta.env.VITE_API_BASE_URL,
|
||||||
|
timeout: 10000
|
||||||
|
})
|
||||||
|
|
||||||
|
// 请求拦截器
|
||||||
|
request.interceptors.request.use(
|
||||||
|
config => {
|
||||||
|
// 添加 token
|
||||||
|
const token = localStorage.getItem('token')
|
||||||
|
if (token) {
|
||||||
|
config.headers.Authorization = `Bearer ${token}`
|
||||||
|
}
|
||||||
|
return config
|
||||||
|
},
|
||||||
|
error => {
|
||||||
|
return Promise.reject(error)
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
// 响应拦截器
|
||||||
|
request.interceptors.response.use(
|
||||||
|
response => {
|
||||||
|
return response.data
|
||||||
|
},
|
||||||
|
error => {
|
||||||
|
// 统一错误处理
|
||||||
|
ElMessage.error(error.response?.data?.message || '请求失败')
|
||||||
|
return Promise.reject(error)
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
export default request
|
||||||
|
```
|
||||||
|
|
||||||
|
## 组件开发规范
|
||||||
|
|
||||||
|
### 1. 组件设计原则
|
||||||
|
|
||||||
|
#### 单一职责
|
||||||
|
每个组件只负责一个特定的功能。
|
||||||
|
|
||||||
|
#### 可复用性
|
||||||
|
组件应该设计为可复用的，通过 props 接收配置。
|
||||||
|
|
||||||
|
#### 组合优于继承
|
||||||
|
通过组合多个小组件来构建复杂功能。
|
||||||
|
|
||||||
|
### 2. Props 定义
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
interface Props {
|
||||||
|
// 必填属性
|
||||||
|
title: string
|
||||||
|
// 可选属性
|
||||||
|
size?: 'small' | 'medium' | 'large'
|
||||||
|
// 带默认值
|
||||||
|
disabled?: boolean
|
||||||
|
// 复杂对象
|
||||||
|
data?: Record<string, any>
|
||||||
|
}
|
||||||
|
|
||||||
|
// 定义 props
|
||||||
|
const props = withDefaults(defineProps<Props>(), {
|
||||||
|
size: 'medium',
|
||||||
|
disabled: false,
|
||||||
|
data: () => ({})
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Emits 定义
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
interface Emits {
|
||||||
|
(e: 'update:modelValue', value: string): void
|
||||||
|
(e: 'submit', data: Record<string, any>): void
|
||||||
|
(e: 'cancel'): void
|
||||||
|
}
|
||||||
|
|
||||||
|
// 定义 emits
|
||||||
|
const emit = defineEmits<Emits>()
|
||||||
|
|
||||||
|
const handleSubmit = () => {
|
||||||
|
emit('submit', formData)
|
||||||
|
}
|
||||||
|
|
||||||
|
const handleCancel = () => {
|
||||||
|
emit('cancel')
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 状态管理规范
|
||||||
|
|
||||||
|
### 1. Store 定义
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/store/modules/user.ts
|
||||||
|
import { defineStore } from 'pinia'
|
||||||
|
|
||||||
|
export interface UserState {
|
||||||
|
userInfo: User | null
|
||||||
|
token: string | null
|
||||||
|
}
|
||||||
|
|
||||||
|
export const useUserStore = defineStore('user', {
|
||||||
|
state: (): UserState => ({
|
||||||
|
userInfo: null,
|
||||||
|
token: null
|
||||||
|
}),
|
||||||
|
|
||||||
|
getters: {
|
||||||
|
isLogin: state => !!state.token,
|
||||||
|
userName: state => state.userInfo?.name || ''
|
||||||
|
},
|
||||||
|
|
||||||
|
actions: {
|
||||||
|
setUserInfo(userInfo: User) {
|
||||||
|
this.userInfo = userInfo
|
||||||
|
},
|
||||||
|
|
||||||
|
setToken(token: string) {
|
||||||
|
this.token = token
|
||||||
|
},
|
||||||
|
|
||||||
|
async login(credentials: LoginParams) {
|
||||||
|
const { data } = await loginApi(credentials)
|
||||||
|
this.setToken(data.token)
|
||||||
|
this.setUserInfo(data.user)
|
||||||
|
},
|
||||||
|
|
||||||
|
logout() {
|
||||||
|
this.userInfo = null
|
||||||
|
this.token = null
|
||||||
|
}
|
||||||
|
},
|
||||||
|
|
||||||
|
persist: {
|
||||||
|
enabled: true,
|
||||||
|
strategies: [
|
||||||
|
{
|
||||||
|
key: 'user',
|
||||||
|
storage: localStorage
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Store 使用
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
import { useUserStore } from '@/store/modules/user'
|
||||||
|
|
||||||
|
const userStore = useUserStore()
|
||||||
|
|
||||||
|
// 使用状态
|
||||||
|
const userName = computed(() => userStore.userName)
|
||||||
|
const isLogin = computed(() => userStore.isLogin)
|
||||||
|
|
||||||
|
// 调用 action
|
||||||
|
const handleLogin = async () => {
|
||||||
|
try {
|
||||||
|
await userStore.login(loginForm)
|
||||||
|
// 登录成功处理
|
||||||
|
} catch (error) {
|
||||||
|
// 错误处理
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 路由开发规范
|
||||||
|
|
||||||
|
### 1. 路由定义
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/router/modules/shop.ts
|
||||||
|
export default {
|
||||||
|
path: '/shop',
|
||||||
|
name: 'Shop',
|
||||||
|
redirect: '/shop/goods',
|
||||||
|
meta: {
|
||||||
|
title: '店铺管理',
|
||||||
|
icon: 'shop',
|
||||||
|
rank: 10
|
||||||
|
},
|
||||||
|
children: [
|
||||||
|
{
|
||||||
|
path: '/shop/goods',
|
||||||
|
name: 'Goods',
|
||||||
|
component: () => import('@/views/shop/goods/index.vue'),
|
||||||
|
meta: {
|
||||||
|
title: '商品管理',
|
||||||
|
roles: ['admin', 'shop_manager']
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: '/shop/orders',
|
||||||
|
name: 'Orders',
|
||||||
|
component: () => import('@/views/shop/orders/index.vue'),
|
||||||
|
meta: {
|
||||||
|
title: '订单管理',
|
||||||
|
roles: ['admin', 'shop_manager']
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
} as RouteConfigsTable
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 路由守卫
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 在路由守卫中检查权限
|
||||||
|
router.beforeEach((to, from, next) => {
|
||||||
|
const userStore = useUserStore()
|
||||||
|
|
||||||
|
// 检查登录状态
|
||||||
|
if (!userStore.isLogin && to.path !== '/login') {
|
||||||
|
next('/login')
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
// 检查页面权限
|
||||||
|
if (to.meta.roles && !hasPermission(to.meta.roles)) {
|
||||||
|
next('/error/403')
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
next()
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## 样式开发规范
|
||||||
|
|
||||||
|
### 1. SCSS 规范
|
||||||
|
|
||||||
|
```scss
|
||||||
|
// 变量定义
|
||||||
|
$primary-color: #409eff;
|
||||||
|
$success-color: #67c23a;
|
||||||
|
$warning-color: #e6a23c;
|
||||||
|
$danger-color: #f56c6c;
|
||||||
|
|
||||||
|
// 混入
|
||||||
|
@mixin flex-center {
|
||||||
|
display: flex;
|
||||||
|
align-items: center;
|
||||||
|
justify-content: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 组件样式
|
||||||
|
.goods-card {
|
||||||
|
border: 1px solid #ebeef5;
|
||||||
|
border-radius: 4px;
|
||||||
|
padding: 20px;
|
||||||
|
|
||||||
|
&__header {
|
||||||
|
@include flex-center;
|
||||||
|
margin-bottom: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
&__title {
|
||||||
|
font-size: 16px;
|
||||||
|
font-weight: bold;
|
||||||
|
color: $primary-color;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. CSS 类命名
|
||||||
|
|
||||||
|
使用 BEM 命名规范：
|
||||||
|
```scss
|
||||||
|
.block {}
|
||||||
|
.block__element {}
|
||||||
|
.block--modifier {}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 测试规范
|
||||||
|
|
||||||
|
### 1. 单元测试
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// tests/unit/utils/format.spec.ts
|
||||||
|
import { formatPrice } from '@/utils/format'
|
||||||
|
|
||||||
|
describe('formatPrice', () => {
|
||||||
|
it('should format price correctly', () => {
|
||||||
|
expect(formatPrice(100)).toBe('¥100.00')
|
||||||
|
expect(formatPrice(99.9)).toBe('¥99.90')
|
||||||
|
})
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 组件测试
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// tests/unit/components/GoodsCard.spec.ts
|
||||||
|
import { mount } from '@vue/test-utils'
|
||||||
|
import GoodsCard from '@/components/GoodsCard.vue'
|
||||||
|
|
||||||
|
describe('GoodsCard', () => {
|
||||||
|
it('should render goods info', () => {
|
||||||
|
const wrapper = mount(GoodsCard, {
|
||||||
|
props: {
|
||||||
|
goods: {
|
||||||
|
id: 1,
|
||||||
|
name: '测试商品',
|
||||||
|
price: 100
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
expect(wrapper.text()).toContain('测试商品')
|
||||||
|
expect(wrapper.text()).toContain('¥100.00')
|
||||||
|
})
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
## 提交规范
|
||||||
|
|
||||||
|
### 1. Commit Message 格式
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>(<scope>): <subject>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 类型说明
|
||||||
|
|
||||||
|
- `feat`: 新功能
|
||||||
|
- `fix`: 修复 bug
|
||||||
|
- `docs`: 文档更新
|
||||||
|
- `style`: 代码格式调整
|
||||||
|
- `refactor`: 代码重构
|
||||||
|
- `test`: 测试相关
|
||||||
|
- `chore`: 构建过程或辅助工具变动
|
||||||
|
|
||||||
|
### 3. 示例
|
||||||
|
|
||||||
|
```
|
||||||
|
feat(shop): 添加商品批量导入功能
|
||||||
|
|
||||||
|
- 支持 Excel 文件导入商品
|
||||||
|
- 添加导入进度显示
|
||||||
|
- 优化导入错误处理
|
||||||
|
|
||||||
|
Closes #123
|
||||||
|
```
|
||||||
|
|
||||||
|
## 性能优化
|
||||||
|
|
||||||
|
### 1. 代码分割
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 路由懒加载
|
||||||
|
const GoodsList = () => import('@/views/shop/goods/index.vue')
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 组件优化
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
// 使用 defineAsyncComponent 异步加载组件
|
||||||
|
const AsyncComponent = defineAsyncComponent(() =>
|
||||||
|
import('@/components/HeavyComponent.vue')
|
||||||
|
)
|
||||||
|
|
||||||
|
// 使用 computed 缓存计算结果
|
||||||
|
const filteredList = computed(() => {
|
||||||
|
return list.value.filter(item => item.status === 'active')
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 图片优化
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<!-- 使用懒加载 -->
|
||||||
|
<el-image
|
||||||
|
:src="imageUrl"
|
||||||
|
lazy
|
||||||
|
:preview-src-list="[imageUrl]"
|
||||||
|
/>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### 1. 类型错误
|
||||||
|
|
||||||
|
如果遇到 TypeScript 类型错误，检查：
|
||||||
|
- 是否正确导入类型定义
|
||||||
|
- 是否正确定义接口
|
||||||
|
- 是否使用正确的类型注解
|
||||||
|
|
||||||
|
### 2. 样式不生效
|
||||||
|
|
||||||
|
检查：
|
||||||
|
- 是否使用了正确的 scoped
|
||||||
|
- 是否正确定义了样式类名
|
||||||
|
- 是否引入了必要的样式文件
|
||||||
|
|
||||||
|
### 3. 路由跳转问题
|
||||||
|
|
||||||
|
检查：
|
||||||
|
- 路由路径是否正确
|
||||||
|
- 路由守卫是否阻止了跳转
|
||||||
|
- 组件是否正确定义
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文档版本**: 1.0
|
||||||
|
**最后更新**: 2025-10-15
|
||||||
|
|
@ -0,0 +1,482 @@
|
||||||
|
# 部署和维护指南
|
||||||
|
|
||||||
|
## 部署流程
|
||||||
|
|
||||||
|
### 1. 环境准备
|
||||||
|
|
||||||
|
#### 服务器要求
|
||||||
|
- **操作系统**: Linux (推荐 Ubuntu 20.04+ 或 CentOS 7+)
|
||||||
|
- **Web 服务器**: Nginx 1.18+
|
||||||
|
- **Node.js**: 16.0+
|
||||||
|
- **内存**: 至少 2GB
|
||||||
|
- **存储**: 至少 10GB 可用空间
|
||||||
|
|
||||||
|
#### 软件安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装 Node.js (使用 NodeSource 仓库)
|
||||||
|
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
|
||||||
|
sudo apt-get install -y nodejs
|
||||||
|
|
||||||
|
# 安装 pnpm
|
||||||
|
npm install -g pnpm
|
||||||
|
|
||||||
|
# 安装 Nginx
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 项目部署
|
||||||
|
|
||||||
|
#### 构建项目
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
git clone <repository-url>
|
||||||
|
cd shop-front-end
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 构建生产版本
|
||||||
|
pnpm build
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 配置 Nginx
|
||||||
|
|
||||||
|
创建 Nginx 配置文件 `/etc/nginx/sites-available/shop-frontend`:
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name your-domain.com;
|
||||||
|
root /path/to/shop-front-end/dist;
|
||||||
|
index index.html;
|
||||||
|
|
||||||
|
# 启用 gzip 压缩
|
||||||
|
gzip on;
|
||||||
|
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
|
||||||
|
|
||||||
|
# SPA 路由支持
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 静态资源缓存
|
||||||
|
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
|
||||||
|
expires 1y;
|
||||||
|
add_header Cache-Control "public, immutable";
|
||||||
|
}
|
||||||
|
|
||||||
|
# API 代理
|
||||||
|
location /api/ {
|
||||||
|
proxy_pass http://backend-server:8080;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
启用站点配置:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo ln -s /etc/nginx/sites-available/shop-frontend /etc/nginx/sites-enabled/
|
||||||
|
sudo nginx -t # 测试配置
|
||||||
|
sudo systemctl reload nginx # 重新加载配置
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 配置 SSL (可选)
|
||||||
|
|
||||||
|
使用 Let's Encrypt 配置 HTTPS:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装 Certbot
|
||||||
|
sudo apt install certbot python3-certbot-nginx
|
||||||
|
|
||||||
|
# 获取证书
|
||||||
|
sudo certbot --nginx -d your-domain.com
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 环境配置
|
||||||
|
|
||||||
|
#### 环境变量
|
||||||
|
|
||||||
|
创建 `.env.production` 文件:
|
||||||
|
|
||||||
|
```env
|
||||||
|
VITE_API_BASE_URL=https://your-api-domain.com
|
||||||
|
VITE_ROUTER_HISTORY=history
|
||||||
|
VITE_PUBLIC_PATH=/
|
||||||
|
VITE_HIDE_HOME=false
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 服务器配置文件
|
||||||
|
|
||||||
|
在 `public/` 目录下创建 `serverConfig.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"Title": "智能柜管理系统",
|
||||||
|
"FixedHeader": true,
|
||||||
|
"HiddenSideBar": false,
|
||||||
|
"MultiTagsCache": false,
|
||||||
|
"KeepAlive": true,
|
||||||
|
"Locale": "zh",
|
||||||
|
"Layout": "vertical",
|
||||||
|
"Theme": "default",
|
||||||
|
"DarkMode": false,
|
||||||
|
"Grey": false,
|
||||||
|
"Weak": false,
|
||||||
|
"HideTabs": false,
|
||||||
|
"HideFooter": false,
|
||||||
|
"SidebarStatus": true,
|
||||||
|
"EpThemeColor": "#409EFF",
|
||||||
|
"ShowLogo": true,
|
||||||
|
"ShowModel": "smart",
|
||||||
|
"MenuArrowIconNoTransition": false,
|
||||||
|
"CachingAsyncRoutes": false,
|
||||||
|
"ResponsiveStorageNameSpace": "responsive-"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 维护操作
|
||||||
|
|
||||||
|
### 1. 日常维护
|
||||||
|
|
||||||
|
#### 日志监控
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看 Nginx 访问日志
|
||||||
|
tail -f /var/log/nginx/access.log
|
||||||
|
|
||||||
|
# 查看 Nginx 错误日志
|
||||||
|
tail -f /var/log/nginx/error.log
|
||||||
|
|
||||||
|
# 查看系统日志
|
||||||
|
journalctl -u nginx -f
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 性能监控
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看系统资源使用
|
||||||
|
top
|
||||||
|
htop
|
||||||
|
|
||||||
|
# 查看磁盘使用
|
||||||
|
df -h
|
||||||
|
|
||||||
|
# 查看内存使用
|
||||||
|
free -h
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 备份策略
|
||||||
|
|
||||||
|
#### 代码备份
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 备份项目代码
|
||||||
|
tar -czf shop-frontend-backup-$(date +%Y%m%d).tar.gz /path/to/shop-front-end
|
||||||
|
|
||||||
|
# 备份 Nginx 配置
|
||||||
|
tar -czf nginx-config-backup-$(date +%Y%m%d).tar.gz /etc/nginx/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 自动化备份脚本
|
||||||
|
|
||||||
|
创建备份脚本 `/opt/scripts/backup.sh`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# 备份目录
|
||||||
|
BACKUP_DIR="/opt/backups"
|
||||||
|
DATE=$(date +%Y%m%d)
|
||||||
|
|
||||||
|
# 创建备份目录
|
||||||
|
mkdir -p $BACKUP_DIR/$DATE
|
||||||
|
|
||||||
|
# 备份项目代码
|
||||||
|
tar -czf $BACKUP_DIR/$DATE/shop-frontend.tar.gz /path/to/shop-front-end
|
||||||
|
|
||||||
|
# 备份 Nginx 配置
|
||||||
|
tar -czf $BACKUP_DIR/$DATE/nginx-config.tar.gz /etc/nginx/
|
||||||
|
|
||||||
|
# 删除 30 天前的备份
|
||||||
|
find $BACKUP_DIR -type d -mtime +30 -exec rm -rf {} \;
|
||||||
|
|
||||||
|
echo "Backup completed: $BACKUP_DIR/$DATE"
|
||||||
|
```
|
||||||
|
|
||||||
|
设置定时任务:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 编辑 crontab
|
||||||
|
crontab -e
|
||||||
|
|
||||||
|
# 添加每天凌晨 2 点执行备份
|
||||||
|
0 2 * * * /opt/scripts/backup.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 更新流程
|
||||||
|
|
||||||
|
#### 手动更新
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 进入项目目录
|
||||||
|
cd /path/to/shop-front-end
|
||||||
|
|
||||||
|
# 拉取最新代码
|
||||||
|
git pull origin master
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 构建新版本
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# 重启 Nginx
|
||||||
|
sudo systemctl reload nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 自动化更新脚本
|
||||||
|
|
||||||
|
创建更新脚本 `/opt/scripts/update.sh`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# 项目目录
|
||||||
|
PROJECT_DIR="/path/to/shop-front-end"
|
||||||
|
LOG_FILE="/var/log/shop-frontend-update.log"
|
||||||
|
|
||||||
|
# 记录开始时间
|
||||||
|
echo "$(date): Starting update process" >> $LOG_FILE
|
||||||
|
|
||||||
|
# 进入项目目录
|
||||||
|
cd $PROJECT_DIR
|
||||||
|
|
||||||
|
# 拉取最新代码
|
||||||
|
echo "$(date): Pulling latest code" >> $LOG_FILE
|
||||||
|
git pull origin master
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
echo "$(date): Installing dependencies" >> $LOG_FILE
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# 构建项目
|
||||||
|
echo "$(date): Building project" >> $LOG_FILE
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# 重启 Nginx
|
||||||
|
echo "$(date): Reloading Nginx" >> $LOG_FILE
|
||||||
|
sudo systemctl reload nginx
|
||||||
|
|
||||||
|
echo "$(date): Update completed successfully" >> $LOG_FILE
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 故障排除
|
||||||
|
|
||||||
|
#### 常见问题及解决方案
|
||||||
|
|
||||||
|
**问题 1: 页面显示空白**
|
||||||
|
- **原因**: 资源加载失败或路由配置错误
|
||||||
|
- **解决**:
|
||||||
|
1. 检查浏览器控制台错误信息
|
||||||
|
2. 确认静态资源路径正确
|
||||||
|
3. 检查 Nginx 配置中的 try_files 指令
|
||||||
|
|
||||||
|
**问题 2: API 请求失败**
|
||||||
|
- **原因**: 代理配置错误或后端服务不可用
|
||||||
|
- **解决**:
|
||||||
|
1. 检查 Nginx 代理配置
|
||||||
|
2. 确认后端服务正常运行
|
||||||
|
3. 检查网络连接
|
||||||
|
|
||||||
|
**问题 3: 页面刷新 404**
|
||||||
|
- **原因**: SPA 路由未正确配置
|
||||||
|
- **解决**:
|
||||||
|
1. 确认 Nginx 配置中包含 `try_files $uri $uri/ /index.html;`
|
||||||
|
2. 检查 Vue Router 的 history 模式配置
|
||||||
|
|
||||||
|
**问题 4: 静态资源加载慢**
|
||||||
|
- **原因**: 未启用压缩或缓存
|
||||||
|
- **解决**:
|
||||||
|
1. 启用 Nginx gzip 压缩
|
||||||
|
2. 配置静态资源缓存头
|
||||||
|
3. 考虑使用 CDN
|
||||||
|
|
||||||
|
#### 性能优化
|
||||||
|
|
||||||
|
**Nginx 性能优化配置:**
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
# /etc/nginx/nginx.conf
|
||||||
|
http {
|
||||||
|
# 基础优化
|
||||||
|
sendfile on;
|
||||||
|
tcp_nopush on;
|
||||||
|
tcp_nodelay on;
|
||||||
|
keepalive_timeout 65;
|
||||||
|
types_hash_max_size 2048;
|
||||||
|
|
||||||
|
# Gzip 压缩
|
||||||
|
gzip on;
|
||||||
|
gzip_vary on;
|
||||||
|
gzip_min_length 1024;
|
||||||
|
gzip_proxied any;
|
||||||
|
gzip_comp_level 6;
|
||||||
|
gzip_types
|
||||||
|
application/atom+xml
|
||||||
|
application/javascript
|
||||||
|
application/json
|
||||||
|
application/ld+json
|
||||||
|
application/manifest+json
|
||||||
|
application/rss+xml
|
||||||
|
application/vnd.geo+json
|
||||||
|
application/vnd.ms-fontobject
|
||||||
|
application/x-font-ttf
|
||||||
|
application/x-web-app-manifest+json
|
||||||
|
application/xhtml+xml
|
||||||
|
application/xml
|
||||||
|
font/opentype
|
||||||
|
image/bmp
|
||||||
|
image/svg+xml
|
||||||
|
image/x-icon
|
||||||
|
text/cache-manifest
|
||||||
|
text/css
|
||||||
|
text/plain
|
||||||
|
text/vcard
|
||||||
|
text/vnd.rim.location.xloc
|
||||||
|
text/vtt
|
||||||
|
text/x-component
|
||||||
|
text/x-cross-domain-policy;
|
||||||
|
|
||||||
|
# 静态资源缓存
|
||||||
|
open_file_cache max=1000 inactive=20s;
|
||||||
|
open_file_cache_valid 30s;
|
||||||
|
open_file_cache_min_uses 2;
|
||||||
|
open_file_cache_errors on;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. 安全配置
|
||||||
|
|
||||||
|
#### Nginx 安全配置
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
# 隐藏 Nginx 版本信息
|
||||||
|
server_tokens off;
|
||||||
|
|
||||||
|
# 安全头设置
|
||||||
|
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||||
|
add_header X-XSS-Protection "1; mode=block" always;
|
||||||
|
add_header X-Content-Type-Options "nosniff" always;
|
||||||
|
add_header Referrer-Policy "no-referrer-when-downgrade" always;
|
||||||
|
add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
|
||||||
|
|
||||||
|
# 限制请求大小
|
||||||
|
client_max_body_size 10m;
|
||||||
|
|
||||||
|
# 限制请求速率
|
||||||
|
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
|
||||||
|
|
||||||
|
location /api/ {
|
||||||
|
limit_req zone=api burst=20 nodelay;
|
||||||
|
# ... 其他配置
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 防火墙配置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 启用防火墙
|
||||||
|
sudo ufw enable
|
||||||
|
|
||||||
|
# 允许 SSH
|
||||||
|
sudo ufw allow ssh
|
||||||
|
|
||||||
|
# 允许 HTTP/HTTPS
|
||||||
|
sudo ufw allow 80
|
||||||
|
sudo ufw allow 443
|
||||||
|
|
||||||
|
# 查看防火墙状态
|
||||||
|
sudo ufw status
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. 监控和告警
|
||||||
|
|
||||||
|
#### 基础监控脚本
|
||||||
|
|
||||||
|
创建健康检查脚本 `/opt/scripts/health-check.sh`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# 检查 Nginx 服务状态
|
||||||
|
if ! systemctl is-active --quiet nginx; then
|
||||||
|
echo "Nginx is not running" | mail -s "Nginx Alert" admin@example.com
|
||||||
|
sudo systemctl restart nginx
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 检查磁盘空间
|
||||||
|
DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
|
||||||
|
if [ $DISK_USAGE -gt 90 ]; then
|
||||||
|
echo "Disk usage is over 90%" | mail -s "Disk Alert" admin@example.com
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 检查内存使用
|
||||||
|
MEM_USAGE=$(free | awk 'NR==2{printf "%.2f", $3*100/$2}')
|
||||||
|
if (( $(echo "$MEM_USAGE > 90" | bc -l) )); then
|
||||||
|
echo "Memory usage is over 90%" | mail -s "Memory Alert" admin@example.com
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
设置定时监控:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 每 5 分钟执行一次健康检查
|
||||||
|
*/5 * * * * /opt/scripts/health-check.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## 附录
|
||||||
|
|
||||||
|
### 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Nginx 相关
|
||||||
|
sudo systemctl status nginx # 查看状态
|
||||||
|
sudo systemctl start nginx # 启动
|
||||||
|
sudo systemctl stop nginx # 停止
|
||||||
|
sudo systemctl restart nginx # 重启
|
||||||
|
sudo systemctl reload nginx # 重新加载配置
|
||||||
|
|
||||||
|
# 日志相关
|
||||||
|
sudo journalctl -u nginx -f # 查看 Nginx 日志
|
||||||
|
sudo tail -f /var/log/nginx/access.log # 访问日志
|
||||||
|
sudo tail -f /var/log/nginx/error.log # 错误日志
|
||||||
|
|
||||||
|
# 系统监控
|
||||||
|
top # 系统资源使用
|
||||||
|
htop # 增强版 top
|
||||||
|
df -h # 磁盘使用
|
||||||
|
free -h # 内存使用
|
||||||
|
```
|
||||||
|
|
||||||
|
### 配置文件位置
|
||||||
|
|
||||||
|
- **Nginx 主配置**: `/etc/nginx/nginx.conf`
|
||||||
|
- **站点配置**: `/etc/nginx/sites-available/`
|
||||||
|
- **启用站点**: `/etc/nginx/sites-enabled/`
|
||||||
|
- **Nginx 日志**: `/var/log/nginx/`
|
||||||
|
- **项目目录**: `/path/to/shop-front-end/`
|
||||||
|
- **构建输出**: `/path/to/shop-front-end/dist/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文档版本**: 1.0
|
||||||
|
**最后更新**: 2025-10-15
|
||||||
|
|
@ -0,0 +1,330 @@
|
||||||
|
# 智能柜管理系统 - 前端项目说明文档
|
||||||
|
|
||||||
|
## 项目概述
|
||||||
|
|
||||||
|
本项目是一个基于 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
|
||||||
Loading…
Reference in New Issue