admin123
/
shop-front-end
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
shop-front-end/doc/API接口文档.md

10 KiB
Raw Blame History

API 接口文档

概述

本文档详细描述了智能柜管理系统前端项目的所有 API 接口，按业务模块分类。

通用接口

登录认证

1. 获取配置信息

  • 接口: GET /api/common/login/config
  • 描述: 获取系统配置信息
  • 返回:
{
  serverHost: string
  // 其他配置信息
}

2. 密码登录

  • 接口: POST /api/common/login/password
  • 描述: 使用用户名密码登录
  • 参数:
{
  username: string
  password: string
}
  • 返回:
{
  token: string
  userInfo: User
}

3. 企业微信登录

  • 接口: POST /api/common/login/wechat
  • 描述: 企业微信扫码登录
  • 参数:
{
  corpid: string
  code: string
  state?: string
}

智能柜管理模块

智能柜设备管理

1. 获取智能柜列表

  • 接口: GET /api/cabinet/smart-cabinet/list
  • 描述: 获取智能柜设备列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
  status?: string
}
  • 返回:
{
  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
  • 描述: 获取柜体格口列表
  • 参数:
{
  cabinetId?: number
  page?: number
  size?: number
  status?: string
}
  • 返回:
{
  list: CabinetCell[]
  total: number
}

2. 格口操作

  • 接口: POST /api/cabinet/cell-operation/{operation}
  • 描述: 执行格口操作（开门、关门等）
  • 参数:
{
  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
  • 描述: 获取店铺列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
}
  • 返回:
{
  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
  • 描述: 获取商品列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
  categoryId?: number
  status?: string
}
  • 返回:
{
  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
  • 描述: 获取订单列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
  status?: string
  startTime?: string
  endTime?: string
}
  • 返回:
{
  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
  • 描述: 更新订单状态
  • 参数:
{
  status: string
}

审批管理

1. 获取审批列表

  • 接口: GET /api/shop/approval/list
  • 描述: 获取审批列表
  • 参数:
{
  page?: number
  size?: number
  type?: string
  status?: string
}
  • 返回:
{
  list: Approval[]
  total: number
}

2. 审批操作

  • 接口: POST /api/shop/approval/{id}/action
  • 描述: 执行审批操作
  • 参数:
{
  action: 'approve' | 'reject'
  remark?: string
}

数据统计

1. 获取统计数据

  • 接口: GET /api/shop/stats
  • 描述: 获取系统统计数据
  • 参数:
{
  corpid: string
}
  • 返回:
{
  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
  • 描述: 获取企业用户列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
}
  • 返回:
{
  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
  • 描述: 绑定汇邦云会员账号
  • 参数:
{
  qyUserId: number
  name: string
  idNum: string
}

系统管理模块

用户管理

1. 获取用户列表

  • 接口: GET /api/system/user/list
  • 描述: 获取系统用户列表
  • 参数:
{
  page?: number
  size?: number
  keyword?: string
}
  • 返回:
{
  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}
  • 描述: 删除用户

数据类型定义

通用类型

// 分页响应
type PaginationResponse<T> = {
  list: T[]
  total: number
}

// 基础实体
interface BaseEntity {
  id: number
  createTime: string
  updateTime: string
}

智能柜相关

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
}

店铺相关

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
}

统计相关

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
}

企业用户相关

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