shop-front-end/doc/API接口文档.md

# 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