接口设计RESTful API5.1 接口设计规范5.1.1 URL 命名规范基础格式/api/{version}/{module}/{resource} 示例 GET /api/v1/warehouses # 查询仓库列表 GET /api/v1/warehouses/{id} # 查询单个仓库 POST /api/v1/warehouses # 创建仓库 PUT /api/v1/warehouses/{id} # 更新仓库 DELETE /api/v1/warehouses/{id} # 删除仓库 资源用复数名词避免动词 层级关系用嵌套/api/v1/warehouses/{id}/zones5.1.2 统一响应格式{ code: 200, message: success, data: {}, timestamp: 1753843200000, traceId: a1b2c3d4e5f6 }分页响应{ code: 200, message: success, data: { records: [], total: 150, page: 1, size: 20, pages: 8 } }5.1.3 HTTP 状态码状态码含义使用场景200成功GET/PUT 成功201已创建POST 创建资源成功204无内容DELETE 成功400请求错误参数校验失败401未认证Token 过期或无效403无权限没有操作权限404未找到资源不存在409冲突库存不足、单号重复500服务器错误系统异常5.2 基础数据 API5.2.1 仓库管理GET /api/v1/warehouses 参数: page, size, keyword, status 响应: 分页仓库列表 GET /api/v1/warehouses/{id} 响应: 仓库详情含库区列表 POST /api/v1/warehouses Body: { warehouseCode, warehouseName, address, contactPerson, contactPhone } PUT /api/v1/warehouses/{id} Body: { warehouseName, address, contactPerson, contactPhone } DELETE /api/v1/warehouses/{id} 限制: 仓库下有关联库存时禁止删除5.2.2 库区管理GET /api/v1/warehouses/{warehouseId}/zones GET /api/v1/zones/{id} POST /api/v1/warehouses/{warehouseId}/zones PUT /api/v1/zones/{id} DELETE /api/v1/zones/{id}5.2.3 库位管理GET /api/v1/zones/{zoneId}/locations 参数: locationType, status POST /api/v1/zones/{zoneId}/locations Body: { locationCode, locationType, maxVolume, maxWeight, maxQuantity } PUT /api/v1/locations/{id} Body: { maxVolume, maxWeight, maxQuantity, status } POST /api/v1/locations/batch Body: { zoneId, locations: [{locationCode, ...}, ...] } 说明: 批量创建库位如 A-01-01 到 A-01-20 DELETE /api/v1/locations/{id} 限制: 库位有库存时禁止删除5.2.4 商品管理GET /api/v1/skus 参数: page, size, keyword, category, ownerId, abcClass, status GET /api/v1/skus/{id} POST /api/v1/skus Body: { ownerId, skuCode, skuName, barcode, category, unit, specification, weight, volume, safetyStock, maxStock, abcClass, shelfLifeDays } PUT /api/v1/skus/{id} DELETE /api/v1/skus/{id}5.3 入库 API5.3.1 ASN 管理POST /api/v1/inbound/asns 权限: INBOUND:CREATE Body: { warehouseId: 1, ownerId: 1, orderType: PURCHASE, expectedArriveTime: 2026-08-01 10:00:00, details: [ { skuId: 1, expectedQuantity: 100, batchId: null }, { skuId: 2, expectedQuantity: 200, batchId: null } ] } 响应 201: { code: 201, data: { asnNo: ASN20260730001, id: 1 } } GET /api/v1/inbound/asns 参数: warehouseId, status, startTime, endTime, page, size GET /api/v1/inbound/asns/{id} 响应: ASN 详情 明细列表 PUT /api/v1/inbound/asns/{id}/cancel 说明: 取消未开始的 ASN POST /api/v1/inbound/asns/{id}/receive 权限: INBOUND:RECEIVE Body: { details: [ { detailId: 1, actualQuantity: 98, batchId: 10 }, { detailId: 2, actualQuantity: 200, batchId: 11 } ] } 说明: 确认收货actualQuantity expectedQuantity 则为部分收货5.3.2 上架GET /api/v1/inbound/recommend-locations 参数: skuId, quantity, warehouseId 响应: { locations: [{ id, locationCode, availableCapacity, zoneName }] } 说明: 获取系统推荐的 3 个上架库位 POST /api/v1/inbound/asns/{id}/putaway 权限: INBOUND:PUTAWAY Body: { details: [ { detailId: 1, locationId: 10 } ] } 说明: 确认上架更新库存5.4 出库 API5.4.1 出库订单POST /api/v1/outbound/orders 权限: OUTBOUND:CREATE Body: { warehouseId: 1, ownerId: 1, sourceOrderNo: OMS20260730001, carrier: SF, expectedShipTime: 2026-08-01 18:00:00, details: [ { skuId: 1, orderedQuantity: 5 }, { skuId: 2, orderedQuantity: 3 } ] } 响应 201: { orderNo: OUT20260730001, id: 1 } GET /api/v1/outbound/orders 参数: warehouseId, status, waveId, startTime, endTime, page, size GET /api/v1/outbound/orders/{id}5.4.2 波次管理POST /api/v1/outbound/waves/generate 权限: OUTBOUND:WAVE Body: { warehouseId: 1, waveType: ORDER_COUNT, params: { maxOrderCount: 20 } } 说明: 手动触发生成波次 GET /api/v1/outbound/waves 参数: warehouseId, status, page, size GET /api/v1/outbound/waves/{id} 响应: 波次详情 包含的订单列表 POST /api/v1/outbound/waves/{id}/allocate 说明: 为波次内所有订单分配库存预占5.4.3 拣货GET /api/v1/outbound/pick-tasks 参数: assigneeId, status, page, size 说明: 查询当前用户的拣货任务 GET /api/v1/outbound/pick-tasks/{id} 响应: { taskId, waveNo, items: [ { locationCode, skuCode, skuName, barcode, quantity, picked } ] } 说明: 已按拣货路径排序 POST /api/v1/outbound/pick-tasks/{id}/confirm-pick Body: { items: [ { detailId: 1, pickedQuantity: 5, locationId: 10 }, { detailId: 2, pickedQuantity: 3, locationId: 12 } ] } 说明: 确认拣货完成5.4.4 复核POST /api/v1/outbound/orders/{id}/check 权限: OUTBOUND:CHECK Body: { details: [ { detailId: 1, checkedQuantity: 5, result: OK }, { detailId: 2, checkedQuantity: 2, result: SHORTAGE, remark: 少1件 } ] }5.4.5 发货POST /api/v1/outbound/orders/{id}/ship 权限: OUTBOUND:SHIP Body: { trackingNo: SF1234567890, actualWeight: 5.2, actualVolume: 0.03 } 说明: 确认发货正式扣减库存5.5 库存 APIGET /api/v1/inventory 参数: warehouseId, skuId, locationId, batchId, status, page, size 响应: 库存分页列表 GET /api/v1/inventory/summary 参数: warehouseId, skuId 响应: { totalQuantity: 500, availableQuantity: 450, lockedQuantity: 30, frozenQuantity: 20 } POST /api/v1/inventory/move 权限: INVENTORY:MOVE Body: { inventoryId: 1, targetLocationId: 20, quantity: 50 } 说明: 库位间移动 POST /api/v1/inventory/adjust 权限: INVENTORY:ADJUST Body: { inventoryId: 1, adjustQuantity: -5, // 负数减少正数增加 reason: 盘点差异调整, referenceNo: ADJ20260730001 } POST /api/v1/inventory/freeze Body: { inventoryId: 1, reason: 质检冻结 } POST /api/v1/inventory/unfreeze Body: { inventoryId: 1 } GET /api/v1/inventory/logs 参数: skuId, warehouseId, changeType, startTime, endTime, page, size GET /api/v1/inventory/alerts 参数: warehouseId 响应: { lowStockItems: [...], highStockItems: [...] }5.6 盘点 APIPOST /api/v1/counts/plans 权限: COUNT:CREATE Body: { warehouseId: 1, countType: CYCLE, countMode: OPEN, zoneIds: [1, 2], plannedStartTime: 2026-07-30 09:00:00 } GET /api/v1/counts/plans/{id} POST /api/v1/counts/plans/{id}/start 说明: 开始盘点生成任务并锁定库位 GET /api/v1/counts/tasks 参数: planId, assigneeId, status, page, size POST /api/v1/counts/tasks/{id}/submit Body: { details: [ { skuId: 1, batchId: null, countQuantity: 98, locationId: 10 } ] } POST /api/v1/counts/tasks/{id}/recheck Body: { details: [...] } 说明: 复盘提交 POST /api/v1/counts/plans/{id}/audit-diff Body: { approved: true, remark: 差异确认调整库存 } 说明: 审核差异并调整库存 POST /api/v1/counts/plans/{id}/complete5.7 认证与权限 APIPOST /api/v1/auth/login Body: { username: admin, password: xxx } 响应: { token: eyJhbG..., refreshToken: ..., expiresIn: 7200 } POST /api/v1/auth/refresh Body: { refreshToken: ... } POST /api/v1/auth/logout GET /api/v1/users 权限: SYSTEM:USER:READ POST /api/v1/users 权限: SYSTEM:USER:CREATE PUT /api/v1/users/{id}/roles 权限: SYSTEM:USER:ASSIGN_ROLE Body: { roleIds: [1, 2] } GET /api/v1/roles GET /api/v1/permissions5.8 接口安全5.8.1 请求头要求Authorization: Bearer JWT_TOKEN Content-Type: application/json X-Request-Id: UUID // 请求追踪ID5.8.2 限流配置// 基于 Redis Lua 脚本实现令牌桶限流 RateLimiter(key login, permitsPerSecond 5) PostMapping(/auth/login) public Result login(RequestBody LoginDTO dto) { ... } RateLimiter(key api, permitsPerSecond 100) GetMapping(/inventory) public Result queryInventory() { ... }5.8.3 参数校验PostMapping(/asns) public Result createAsn(Valid RequestBody CreateAsnDTO dto) { ... } // DTO 中使用 JSR-303 注解 public class CreateAsnDTO { NotNull(message 仓库ID不能为空) private Long warehouseId; NotEmpty(message 明细不能为空) Size(min 1, max 100, message 明细数量1-100) private ListAsnDetailDTO details; }