WMS仓库管理系统 - API接口文档

API概述

WMS（Warehouse Management System）仓库管理系统提供完整的RESTful API接口，支持基础数据管理、仓储管理、业务流程管理和报表分析等核心功能。

技术规范

协议: HTTP/HTTPS
数据格式: JSON
字符编码: UTF-8
认证方式: JWT Token
API版本: v1.0

基础信息

Base URL: http://localhost:8801/api
API文档: http://localhost:8801/swagger-ui.html
健康检查: http://localhost:8801/actuator/health

统一响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-10-15T10:30:00"
}

错误响应

{
  "success": false,
  "code": 400,
  "message": "参数验证失败",
  "data": null,
  "timestamp": "2024-10-15T10:30:00"
}

分页响应

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "records": [
      // 数据列表
    ],
    "total": 100,
    "size": 20,
    "current": 1,
    "pages": 5
  },
  "timestamp": "2024-10-15T10:30:00"
}

1. 基础数据管理 API

1.1 仓库管理

查询仓库列表

GET /api/basic/warehouses

查询参数:

参数	类型	必填	描述
name	String	否	仓库名称
type	String	否	仓库类型
status	String	否	仓库状态
current	Integer	否	当前页码(默认1)
size	Integer	否	每页数量(默认20)

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "warehouseCode": "WH001",
        "warehouseName": "上海中心仓库",
        "warehouseType": "NORMAL",
        "address": "上海市浦东新区张江高科技园区",
        "contactPerson": "张三",
        "contactPhone": "13800138001",
        "totalArea": 10000.00,
        "maxCapacity": 50000.000,
        "currentCapacity": 25680.000,
        "utilizationRate": 51.36,
        "status": "ACTIVE"
      }
    ],
    "total": 1
  }
}

创建仓库

POST /api/basic/warehouses

请求参数:

{
  "warehouseCode": "WH002",
  "warehouseName": "北京分仓",
  "warehouseType": "NORMAL",
  "address": "北京市朝阳区",
  "contactPerson": "李四",
  "contactPhone": "13800138002",
  "totalArea": 8000.00,
  "maxCapacity": 40000.000
}

2. 入库管理 API

2.1 入库单管理

分页查询入库单

POST /api/inbound-order/page

请求参数:

{
  "current": 1,
  "size": 10,
  "noticeNo": "RK202412150001",
  "inboundType": "purchase",
  "status": "draft",
  "supplierId": 1,
  "warehouseId": 1,
  "startDate": "2024-12-01",
  "endDate": "2024-12-31"
}

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "noticeNo": "RK202412150001",
        "inboundType": "purchase",
        "supplierId": 1,
        "supplierName": "苹果公司",
        "warehouseId": 1,
        "warehouseName": "主仓库",
        "expectedDate": "2024-12-15",
        "status": "in_progress",
        "totalQty": 1000,
        "receivedQty": 800,
        "qualifiedQty": 750,
        "putawayQty": 700,
        "createTime": "2024-12-12T09:00:00Z"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 10
  }
}

创建入库单

POST /api/inbound-order

请求参数:

{
  "inboundType": "purchase",
  "supplierId": 1,
  "warehouseId": 1,
  "expectedDate": "2024-12-15",
  "remark": "采购入库",
  "items": [
    {
      "productId": 1,
      "plannedQty": 100,
      "batchNo": "B20241215001",
      "productionDate": "2024-12-01",
      "expiryDate": "2026-12-01"
    }
  ]
}

确认入库单

POST /api/inbound-order/{id}/confirm

开始入库

POST /api/inbound-order/{id}/start

完成入库

POST /api/inbound-order/{id}/complete

取消入库单

POST /api/inbound-order/{id}/cancel

请求参数:

{
  "reason": "取消原因"
}

2.2 收货管理

收货确认

POST /api/inbound-order/receive

请求参数:

{
  "itemId": 1,
  "receivedQty": 100,
  "batchNo": "B20241215001",
  "productionDate": "2024-12-01",
  "expiryDate": "2026-12-01",
  "remark": "收货正常"
}

2.3 质检管理

质检通过

POST /api/inbound-order/item/{itemId}/pass-quality

请求参数:

{
  "remark": "质检通过"
}

质检不通过

POST /api/inbound-order/item/{itemId}/fail-quality

请求参数:

{
  "remark": "质检不通过原因"
}

3. 出库管理 API

3.1 出库单管理

分页查询出库单

POST /api/outbound-order/page

创建出库单

POST /api/outbound-order

确认出库单

POST /api/outbound-order/{id}/confirm

开始拣货

POST /api/outbound-order/{id}/start-picking

完成拣货

POST /api/outbound-order/{id}/complete-picking

开始复核

POST /api/outbound-order/{id}/start-checking

完成复核

POST /api/outbound-order/{id}/complete-checking

发货确认

POST /api/outbound-order/{id}/ship

4. 库存管理 API

4.1 库存查询

分页查询库存

POST /api/inventory/page

请求参数:

{
  "current": 1,
  "size": 10,
  "productCode": "P001",
  "warehouseId": 1,
  "locationId": 1,
  "batchNo": "B20241215001"
}

获取库存统计

GET /api/inventory/stats

获取库存预警

POST /api/inventory/alerts/page

4.2 库存调整

创建库存调整

POST /api/inventory/adjustments

请求参数:

{
  "adjustmentType": "INCREASE",
  "reason": "盘盈",
  "items": [
    {
      "inventoryId": 1,
      "adjustmentQty": 10,
      "remark": "盘点发现多出10件"
    }
  ]
}

5. 认证授权 API

5.1 用户认证

用户登录

POST /api/auth/login

请求参数:

{
  "username": "admin",
  "password": "123456"
}

响应示例:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "管理员",
      "email": "admin@example.com"
    }
  }
}

用户登出

POST /api/auth/logout

请求头:

Authorization: Bearer {token}

刷新令牌

POST /api/auth/refresh

请求参数:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

6. 测试用例

6.1 入库流程测试

# 1. 用户登录
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456"
  }'

# 2. 创建入库单
curl -X POST http://localhost:8080/api/inbound-order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "inboundType": "purchase",
    "supplierId": 1,
    "warehouseId": 1,
    "expectedDate": "2024-12-15",
    "items": [
      {
        "productId": 1,
        "plannedQty": 100,
        "batchNo": "B20241215001"
      }
    ]
  }'

# 3. 确认入库单
curl -X POST http://localhost:8080/api/inbound-order/1/confirm \
  -H "Authorization: Bearer {token}"

# 4. 开始入库
curl -X POST http://localhost:8080/api/inbound-order/1/start \
  -H "Authorization: Bearer {token}"

# 5. 收货确认
curl -X POST http://localhost:8080/api/inbound-order/receive \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "itemId": 1,
    "receivedQty": 100,
    "batchNo": "B20241215001"
  }'

6.2 库存查询测试

# 查询库存列表
curl -X POST http://localhost:8080/api/inventory/page \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "current": 1,
    "size": 10,
    "warehouseId": 1
  }'

# 获取库存统计
curl -X GET http://localhost:8080/api/inventory/stats \
  -H "Authorization: Bearer {token}"

7. 错误码说明

错误码	说明	解决方案
400	请求参数错误	检查请求参数格式和必填字段
401	未授权	检查Token是否有效
403	禁止访问	检查用户权限
404	资源不存在	检查请求的资源ID是否正确
409	业务冲突	检查业务状态是否允许当前操作
422	业务逻辑错误	检查业务规则是否满足
500	服务器错误	联系系统管理员

8. 开发指南

8.1 认证方式

所有API请求都需要在请求头中携带JWT Token：

Authorization: Bearer {token}

8.2 分页参数

分页查询统一使用以下参数：

current: 当前页码，从1开始
size: 每页大小，默认10，最大100

8.3 日期格式

所有日期字段统一使用ISO 8601格式：

日期: YYYY-MM-DD
日期时间: YYYY-MM-DDTHH:mm:ssZ

8.4 状态枚举

入库单状态

draft: 草稿
confirmed: 已确认
in_progress: 进行中
completed: 已完成
cancelled: 已取消

出库单状态

draft: 草稿
confirmed: 已确认
picking: 拣货中
picked: 已拣货
checking: 复核中
checked: 已复核
shipped: 已发货
cancelled: 已取消

文档版本: v1.0.0 更新时间: 2024-12-15 维护团队: WMS开发团队

请求体:

{
  "warehouseCode": "WH005",
  "warehouseName": "广州南沙仓库",
  "warehouseType": "NORMAL",
  "address": "广州市南沙区物流园区1号",
  "contactPerson": "李四",
  "contactPhone": "13800138005",
  "contactEmail": "lisi@example.com",
  "totalArea": 8000.00,
  "storageArea": 6400.00,
  "maxCapacity": 40000.000
}

更新仓库

PUT /api/basic/warehouses/{id}

删除仓库

DELETE /api/basic/warehouses/{id}

1.2 商品管理

查询商品列表

GET /api/basic/products

查询参数:

参数	类型	必填	描述
productName	String	否	商品名称
categoryId	Long	否	分类ID
brand	String	否	品牌
abcCategory	String	否	ABC分类
status	String	否	商品状态

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "productCode": "P001001",
        "productName": "iPhone 15 Pro 256GB 深空黑色",
        "categoryId": 2,
        "categoryName": "手机数码",
        "brand": "Apple",
        "model": "A3108",
        "specification": "256GB存储/6.1英寸屏幕",
        "unit": "台",
        "productType": "SERIAL",
        "abcCategory": "A",
        "purchasePrice": 7999.00,
        "salePrice": 9999.00,
        "minStock": 10.000,
        "maxStock": 100.000,
        "safetyStock": 20.000,
        "currentStock": 73.000,
        "availableStock": 68.000,
        "reservedStock": 5.000,
        "status": "ACTIVE"
      }
    ],
    "total": 20
  }
}

创建商品

POST /api/basic/products

请求体:

{
  "productCode": "P007001",
  "productName": "MacBook Air M3芯片 13英寸 8GB+256GB",
  "categoryId": 3,
  "brand": "Apple",
  "model": "MRXN3CH/A",
  "specification": "M3芯片/8GB内存/256GB固态硬盘",
  "unit": "台",
  "productType": "SERIAL",
  "abcCategory": "A",
  "purchasePrice": 8999.00,
  "salePrice": 10999.00,
  "costPrice": 9200.00,
  "minStock": 5.000,
  "maxStock": 50.000,
  "safetyStock": 10.000,
  "length": 30.41,
  "width": 21.24,
  "height": 1.13,
  "weight": 1.240,
  "supplierId": 105,
  "barcode": "195949123456",
  "description": "MacBook Air M3芯片，轻薄便携笔记本电脑"
}

1.3 供应商管理

查询供应商列表

GET /api/basic/suppliers

供应商绩效评估

GET /api/basic/suppliers/{id}/performance

响应示例:

{
  "success": true,
  "data": {
    "supplierId": 101,
    "supplierName": "华为技术有限公司",
    "evaluationPeriod": "2024Q3",
    "overallScore": 95.80,
    "qualityScore": 96.5,
    "deliveryScore": 94.8,
    "serviceScore": 96.2,
    "priceScore": 95.6,
    "cooperationLevel": "STRATEGIC",
    "totalOrders": 45,
    "onTimeDeliveryRate": 94.8,
    "qualityPassRate": 96.5,
    "averageLeadTime": 15,
    "recommendations": [
      "继续保持高质量标准",
      "优化物流配送时效",
      "加强技术支持服务"
    ]
  }
}

1.4 客户管理

客户价值分析

GET /api/basic/customers/{id}/value-analysis

响应示例:

{
  "success": true,
  "data": {
    "customerId": 101,
    "customerName": "天猫旗舰店",
    "customerLevel": "DIAMOND",
    "valueScore": 96.8,
    "rfmAnalysis": {
      "recency": 5,
      "frequency": 95,
      "monetary": 98,
      "rfmScore": "555",
      "segment": "冠军客户"
    },
    "transactionSummary": {
      "totalAmount": 12500000.00,
      "totalOrders": 2850,
      "averageOrderValue": 4385.96,
      "lastOrderDate": "2024-10-10",
      "customerLifetime": 1250
    },
    "growthTrend": "+15.6%",
    "predictedValue": 14500000.00,
    "recommendations": [
      "提供VIP专属服务",
      "优先配货保障",
      "定制化产品推荐"
    ]
  }
}

2. 仓储管理 API

2.1 库存管理

实时库存查询

GET /api/warehouse/inventory

查询参数:

参数	类型	必填	描述
warehouseId	Long	否	仓库ID
productId	Long	否	商品ID
locationId	Long	否	货位ID
batchNo	String	否	批次号
inventoryStatus	String	否	库存状态
abcCategory	String	否	ABC分类
lowStock	Boolean	否	是否低库存

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "warehouseId": 1,
        "warehouseName": "上海中心仓库",
        "locationId": 1,
        "locationCode": "A-01-01-01",
        "productId": 1,
        "productCode": "P001001",
        "productName": "iPhone 15 Pro 256GB 深空黑色",
        "batchNo": "IP15P001",
        "supplierName": "苹果电脑贸易（上海）有限公司",
        "inventoryStatus": "AVAILABLE",
        "qualityStatus": "QUALIFIED",
        "availableQuantity": 45.000,
        "reservedQuantity": 0.000,
        "allocatedQuantity": 0.000,
        "totalQuantity": 45.000,
        "unitCost": 8200.00,
        "totalValue": 369000.00,
        "daysInInventory": 47,
        "turnoverRate": 8.5,
        "abcCategory": "A",
        "expiryDate": null,
        "lastMovementDate": "2024-10-01T16:30:00"
      }
    ],
    "total": 50,
    "summary": {
      "totalProducts": 20,
      "totalQuantity": 1250.000,
      "totalValue": 15680000.00,
      "lowStockItems": 8,
      "expiringItems": 3
    }
  }
}

库存调整

POST /api/warehouse/inventory/adjustment

请求体:

{
  "adjustmentNo": "ADJ20241015001",
  "warehouseId": 1,
  "adjustmentType": "MANUAL",
  "reasonCode": "INVENTORY_COUNT",
  "reasonDescription": "月度盘点调整",
  "items": [
    {
      "inventoryId": 1,
      "productId": 1,
      "locationId": 1,
      "batchNo": "IP15P001",
      "adjustmentQuantity": -2.000,
      "adjustmentReason": "盘点发现短缺"
    }
  ],
  "operatorId": 3,
  "operatorName": "仓库操作员"
}

库存预警查询

GET /api/warehouse/inventory/alerts

响应示例:

{
  "success": true,
  "data": {
    "alerts": [
      {
        "alertType": "LOW_STOCK",
        "priority": "HIGH",
        "productId": 1,
        "productName": "iPhone 15 Pro 256GB 深空黑色",
        "currentStock": 8.000,
        "minStock": 10.000,
        "shortfall": 2.000,
        "warehouseName": "上海中心仓库",
        "alertTime": "2024-10-15T09:00:00",
        "recommendation": "紧急补货"
      },
      {
        "alertType": "EXPIRING_SOON",
        "priority": "MEDIUM",
        "productId": 20,
        "productName": "伊利纯牛奶 250ml*16盒装",
        "quantity": 80.000,
        "expiryDate": "2024-10-25",
        "remainingDays": 10,
        "recommendation": "促销清仓"
      }
    ],
    "summary": {
      "totalAlerts": 25,
      "highPriorityAlerts": 8,
      "mediumPriorityAlerts": 12,
      "lowPriorityAlerts": 5
    }
  }
}

2.2 货位管理

货位查询

GET /api/warehouse/locations

货位利用率分析

GET /api/warehouse/locations/utilization

响应示例:

{
  "success": true,
  "data": {
    "overallUtilization": 76.8,
    "utilizationByArea": [
      {
        "areaId": 2,
        "areaName": "A区存储区",
        "totalLocations": 500,
        "occupiedLocations": 420,
        "utilizationRate": 84.0,
        "efficiency": "HIGH"
      }
    ],
    "utilizationTrend": [
      {
        "date": "2024-10-01",
        "utilization": 74.2
      },
      {
        "date": "2024-10-15",
        "utilization": 76.8
      }
    ],
    "recommendations": [
      "A区利用率较高，建议扩容",
      "C区利用率偏低，可优化货位分配"
    ]
  }
}

2.3 库存移库

创建移库任务

POST /api/warehouse/transfers

请求体:

{
  "transferNo": "TRF20241015001",
  "warehouseId": 1,
  "transferType": "INTERNAL",
  "fromLocationId": 1,
  "toLocationId": 5,
  "productId": 15,
  "batchNo": "SFJ001",
  "plannedQuantity": 50.000,
  "transferReason": "货位优化调整",
  "priority": "NORMAL",
  "assignedTo": "王五",
  "specialInstructions": "小心搬运，避免包装破损"
}

3. 入库管理 API

3.1 入库单管理

查询入库单列表

GET /api/inbound/orders

查询参数:

参数	类型	必填	描述
orderNo	String	否	入库单号
orderType	String	否	入库类型
warehouseId	Long	否	仓库ID
supplierId	Long	否	供应商ID
orderStatus	String	否	单据状态
startDate	String	否	开始日期
endDate	String	否	结束日期

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "orderNo": "IN20241001001",
        "orderType": "PURCHASE",
        "warehouseId": 1,
        "warehouseName": "上海中心仓库",
        "supplierId": 105,
        "supplierName": "苹果电脑贸易（上海）有限公司",
        "sourceOrderNo": "PO20241001001",
        "plannedDate": "2024-09-15",
        "actualDate": "2024-09-15",
        "orderStatus": "COMPLETED",
        "priority": "HIGH",
        "totalQuantity": 50.000,
        "receivedQuantity": 50.000,
        "totalAmount": 499950.00,
        "receiveProgress": 100.00,
        "qualityInspection": true,
        "inspectionStatus": "PASSED",
        "createdBy": "warehouse_manager",
        "createTime": "2024-09-14T10:30:00"
      }
    ],
    "total": 8
  }
}

创建入库单

POST /api/inbound/orders

请求体:

{
  "orderType": "PURCHASE",
  "warehouseId": 1,
  "supplierId": 106,
  "sourceOrderNo": "PO20241015002",
  "plannedDate": "2024-10-20",
  "expectedArrivalTime": "2024-10-20T09:00:00",
  "priority": "NORMAL",
  "transportMode": "汽运",
  "vehicleNo": "沪A12345",
  "driverName": "张师傅",
  "driverPhone": "13800138888",
  "qualityInspection": true,
  "batchManagement": true,
  "notes": "联想笔记本电脑采购入库",
  "items": [
    {
      "lineNo": 1,
      "productId": 8,
      "plannedQuantity": 60.000,
      "unitPrice": 12999.00,
      "unitCost": 10500.00,
      "inspectionRequired": true
    }
  ]
}

入库收货

POST /api/inbound/orders/{id}/receive

请求体:

{
  "receiverId": 2,
  "receiverName": "仓库经理",
  "receiveTime": "2024-10-20T10:30:00",
  "dockDoor": "月台1",
  "items": [
    {
      "itemId": 15,
      "receivedQuantity": 58.000,
      "damagedQuantity": 2.000,
      "damageReason": "包装破损",
      "batchNo": "TP20241020001",
      "manufactureDate": "2024-10-01",
      "qualityStatus": "PENDING"
    }
  ]
}

3.2 质检管理

质检任务列表

GET /api/inbound/quality-inspections

执行质检

POST /api/inbound/quality-inspections

请求体:

{
  "orderId": 6,
  "orderItemId": 15,
  "productId": 8,
  "batchNo": "TP20241020001",
  "inspectionType": "INCOMING",
  "inspectionMethod": "抽检",
  "sampleSize": 5.000,
  "inspectionQuantity": 5.000,
  "qualifiedQuantity": 5.000,
  "unqualifiedQuantity": 0.000,
  "overallResult": "QUALIFIED",
  "inspectorId": 4,
  "inspectorName": "质检员",
  "inspectionDate": "2024-10-20",
  "inspectionLocation": "质检区A",
  "standardsApplied": "GB/T 9813-2000",
  "remarks": "外观完好，功能正常，质量合格"
}

4. 出库管理 API

4.1 出库单管理

查询出库单列表

GET /api/outbound/orders

响应示例:

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "orderNo": "OUT20241002001",
        "orderType": "SALE",
        "warehouseId": 1,
        "warehouseName": "上海中心仓库",
        "customerId": 101,
        "customerName": "天猫旗舰店",
        "sourceOrderNo": "SO20241002001",
        "plannedDate": "2024-10-01",
        "actualDate": "2024-10-01",
        "orderStatus": "SHIPPED",
        "priority": "HIGH",
        "totalQuantity": 5.000,
        "pickedQuantity": 5.000,
        "shippedQuantity": 5.000,
        "totalAmount": 49995.00,
        "pickingProgress": 100.00,
        "shippingMethod": "EXPRESS",
        "trackingNo": "YT2024100100001",
        "deliveryAddress": "杭州市余杭区文一西路969号天猫大厦",
        "deliveryContact": "李经理"
      }
    ],
    "total": 8
  }
}

创建出库单

POST /api/outbound/orders

确认出库单

POST /api/outbound/orders/{id}/confirm

开始拣货

POST /api/outbound/orders/{id}/start-picking

4.2 拣货管理

拣货任务列表

GET /api/outbound/picking-tasks

创建拣货任务

POST /api/outbound/picking-tasks

请求体:

{
  "orderId": 6,
  "waveNo": "W20241015001",
  "pickingMethod": "DISCRETE",
  "assignedTo": "张三",
  "pickingArea": "A区",
  "containerType": "CART",
  "containerId": "CART001",
  "priority": "NORMAL",
  "items": [
    {
      "orderItemId": 20,
      "productId": 10,
      "locationId": 5,
      "inventoryId": 15,
      "sequenceNo": 1,
      "requestedQuantity": 25.000,
      "allocatedQuantity": 25.000,
      "pickMethod": "PIECE"
    }
  ]
}

完成拣货

POST /api/outbound/picking-tasks/{id}/complete

请求体:

{
  "completedTime": "2024-10-15T14:30:00",
  "pickingResults": [
    {
      "itemId": 25,
      "pickedQuantity": 24.000,
      "shortageQuantity": 1.000,
      "shortageReason": "货位库存不足",
      "itemStatus": "SHORT"
    }
  ],
  "totalDistance": 150.5,
  "actualDuration": 45,
  "notes": "1件货位缺货，已申请补货"
}

4.3 包装管理

包装任务列表

GET /api/outbound/packing-tasks

完成包装

POST /api/outbound/packing-tasks/{id}/complete

4.4 发货管理

创建发货记录

POST /api/outbound/shipments

请求体:

{
  "orderId": 1,
  "carrierName": "顺丰速运",
  "shippingMethod": "EXPRESS",
  "serviceType": "STANDARD",
  "trackingNo": "SF1234567890123",
  "vehicleNo": "沪A98765",
  "driverName": "刘师傅",
  "driverPhone": "13900000001",
  "shipmentDate": "2024-10-01",
  "shipmentTime": "2024-10-01T16:00:00",
  "estimatedDeliveryTime": "2024-10-02T18:00:00",
  "totalPackages": 2,
  "totalWeight": 1.5,
  "totalVolume": 0.008,
  "freightAmount": 15.00,
  "signatureRequired": true,
  "specialInstructions": "贵重物品，请小心搬运"
}

5. 报表分析 API

5.1 库存报表

库存汇总报表

GET /api/reports/inventory/summary

查询参数:

参数	类型	必填	描述
warehouseId	Long	否	仓库ID
startDate	String	是	开始日期
endDate	String	是	结束日期

响应示例:

{
  "success": true,
  "data": {
    "reportType": "库存汇总报表",
    "warehouseId": 1,
    "dateRange": "2024-09-01 至 2024-10-15",
    "generateTime": "2024-10-15 14:30:00",
    "summary": {
      "totalProducts": 1250,
      "totalQuantity": 25680.50,
      "totalValue": 12850320.75,
      "averageValue": 10280.26,
      "activeProducts": 1180,
      "inactiveProducts": 70
    },
    "categoryStatistics": [
      {
        "category": "电子产品",
        "products": 450,
        "value": 8650320.50,
        "percentage": "68.1%"
      }
    ],
    "abcAnalysis": {
      "A": {
        "products": 125,
        "valuePercentage": "80.2%",
        "strategy": "重点管理，严格控制"
      }
    },
    "alertStatistics": {
      "lowStock": 45,
      "overstock": 12,
      "expiringSoon": 8,
      "deadStock": 23
    }
  }
}

库存周转率报表

GET /api/reports/inventory/turnover

查询参数:

参数	类型	必填	描述
warehouseId	Long	否	仓库ID
period	String	否	统计周期(默认MONTHLY)
topN	Integer	否	返回前N个商品(默认10)

ABC分析报表

GET /api/reports/inventory/abc-analysis

5.2 业务报表

入库业务报表

GET /api/reports/business/inbound

出库业务报表

GET /api/reports/business/outbound

供应商绩效报表

GET /api/reports/business/supplier-performance

响应示例:

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "supplierName": "华为技术",
      "supplierCode": "SUP001",
      "orderCount": 45,
      "totalAmount": 580320.50,
      "onTimeRate": "94.8%",
      "qualityRate": "96.5%",
      "overallScore": 95.80,
      "cooperationLevel": "金牌供应商"
    }
  ]
}

5.3 财务报表

库存成本报表

GET /api/reports/finance/inventory-cost

运营成本报表

GET /api/reports/finance/operation-cost

5.4 综合分析

仪表板数据

GET /api/reports/dashboard

响应示例:

{
  "success": true,
  "data": {
    "warehouseId": 1,
    "updateTime": "2024-10-15 14:30:00",
    "kpiMetrics": {
      "totalOrders": 1456,
      "todayOrders": 45,
      "pendingOrders": 12,
      "inventoryValue": 12850320.75,
      "inventoryTurnover": "4.2",
      "utilizationRate": "85.6%",
      "accuracyRate": "99.2%",
      "onTimeDelivery": "96.8%"
    },
    "realTimeStatus": {
      "activeStaff": 28,
      "runningEquipment": 15,
      "processingOrders": 18,
      "systemStatus": "正常"
    },
    "alerts": [
      {
        "alertType": "库存不足",
        "message": "iPhone 15 Pro库存仅剩5台",
        "priority": "high"
      }
    ]
  }
}

通用报表查询

POST /api/reports/query

请求体:

{
  "reportType": "INVENTORY_SUMMARY",
  "params": {
    "warehouseId": 1,
    "startDate": "2024-09-01T00:00:00",
    "endDate": "2024-10-15T23:59:59"
  }
}

5.5 报表导出

导出报表

POST /api/reports/export

查询参数:

参数	类型	必填	描述
reportType	String	是	报表类型
format	String	否	导出格式(默认EXCEL)

请求体:

{
  "warehouseId": 1,
  "startDate": "2024-09-01",
  "endDate": "2024-10-15",
  "includeDetails": true
}

响应示例:

{
  "success": true,
  "data": {
    "fileName": "INVENTORY_SUMMARY_20241015_143000.xlsx",
    "fileSize": "2.5MB",
    "downloadUrl": "/api/reports/download/INVENTORY_SUMMARY_20241015_143000.xlsx",
    "expiryTime": "2024-10-16 14:30:00",
    "status": "success"
  }
}

6. 系统管理 API

6.1 用户管理

用户登录

POST /api/auth/login

请求体:

{
  "username": "admin",
  "password": "admin123"
}

响应示例:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImlhdCI6MTY5NzM1MjAwMCwiZXhwIjoxNjk3NDM4NDAwfQ.xxxxx",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "userInfo": {
      "id": 1,
      "username": "admin",
      "realName": "系统管理员",
      "email": "admin@wms.com",
      "roles": ["SUPER_ADMIN"],
      "permissions": ["*:*:*"]
    }
  }
}

用户登出

POST /api/auth/logout

获取当前用户信息

GET /api/auth/userinfo

修改密码

POST /api/auth/change-password

6.2 系统配置

获取系统配置

GET /api/system/configs

更新系统配置

PUT /api/system/configs/{key}

6.3 操作日志

查询操作日志

GET /api/system/operation-logs

查询参数:

参数	类型	必填	描述
module	String	否	业务模块
operationType	String	否	操作类型
operatorName	String	否	操作人
startDate	String	否	开始时间
endDate	String	否	结束时间

错误码说明

错误码	说明	处理建议
200	操作成功	-
400	参数错误	检查请求参数格式和内容
401	未授权	请先登录或检查Token
403	权限不足	联系管理员分配权限
404	资源不存在	检查资源ID是否正确
409	数据冲突	检查数据唯一性约束
500	服务器内部错误	联系技术支持
1001	库存不足	检查库存数量
1002	货位被占用	选择其他可用货位
1003	单据状态不允许操作	检查单据当前状态
1004	商品已过期	处理过期商品
1005	供应商不可用	检查供应商状态

接口认证

JWT Token使用

请求头设置:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImlhdCI6MTY5NzM1MjAwMCwiZXhwIjoxNjk3NDM4NDAwfQ.xxxxx
Content-Type: application/json

Token刷新:

POST /api/auth/refresh-token
Authorization: Bearer [current_token]

接口限流

通用接口: 100请求/分钟/IP
查询接口: 200请求/分钟/用户
写操作接口: 50请求/分钟/用户
报表导出: 10请求/小时/用户

开发调试

Swagger UI

访问 http://localhost:8801/swagger-ui.html 可以：

查看完整API文档
在线测试接口
生成API客户端代码

Postman集合

提供完整的Postman接口集合文件，包含：

所有API接口定义
示例请求和响应
环境变量配置
自动化测试脚本

Mock数据

所有接口都提供Mock数据支持，便于前端开发和测试。

文档版本: v1.0.0 最后更新: 2024年10月15日 技术支持: 如有API使用问题，请联系开发团队

FilesExpand file tree

API_DOCS.md

Latest commit

History

API_DOCS.md

File metadata and controls

WMS仓库管理系统 - API接口文档

API概述

技术规范

基础信息

统一响应格式

成功响应

错误响应

分页响应

1. 基础数据管理 API

1.1 仓库管理

查询仓库列表

创建仓库

2. 入库管理 API

2.1 入库单管理

分页查询入库单

创建入库单

确认入库单

开始入库

完成入库

取消入库单

2.2 收货管理

收货确认

2.3 质检管理

质检通过

质检不通过

3. 出库管理 API

3.1 出库单管理

分页查询出库单

创建出库单

确认出库单

开始拣货

完成拣货

开始复核

完成复核

发货确认

4. 库存管理 API

4.1 库存查询

分页查询库存

获取库存统计

获取库存预警

4.2 库存调整

创建库存调整

5. 认证授权 API

5.1 用户认证

用户登录

用户登出

刷新令牌

6. 测试用例

6.1 入库流程测试

6.2 库存查询测试

7. 错误码说明

8. 开发指南

8.1 认证方式

8.2 分页参数

8.3 日期格式

8.4 状态枚举

入库单状态

出库单状态

更新仓库

删除仓库

1.2 商品管理

查询商品列表

创建商品

1.3 供应商管理

查询供应商列表

供应商绩效评估

1.4 客户管理

客户价值分析

2. 仓储管理 API

2.1 库存管理

实时库存查询

库存调整

库存预警查询

2.2 货位管理