WXProgram/API_SPECIFICATION.md

仓库管理系统 - API 接口规范

概述

本文档定义了仓库管理系统后端需要提供的RESTful API接口。前端采用桥接模式，支持模拟数据和真实API的无缝切换。

基础信息

• 基础URL: http://localhost:3000/api
• 认证方式: JWT Bearer Token
• 数据格式: JSON

认证接口

2. 用户登出

POST /user/logout

请求头:

Authorization: Bearer <token>

用户接口

3. 获取用户信息

GET /user/info

请求头:

Authorization: Bearer <token>

响应: 同登录接口的用户信息格式

仓库接口

4. 获取所有仓库列表

GET /warehouses

响应:

[
  {
    "id": 1,
    "name": "瓦尔塔蓄电池昆明总店",
    "address": "昆明市五华区二环西路599号",
    "contact": "刘经理",
    "phone": "0871-65123456",
    "description": "瓦尔塔蓄电池云南总代理，提供全系列蓄电池产品",
    "status": "open",
    "capacity": 2000
  }
]

5. 获取指定仓库详情

GET /warehouses/{id}

响应: 单个仓库对象

6. 获取仓库相关订单

GET /warehouses/{id}/orders

响应: 订单数组

货运人员接口

7. 获取所有货运人员

GET /delivery-persons

响应:

[
  {
    "id": 1,
    "name": "张三",
    "phone": "13800138001",
    "vehicleType": "电动三轮车",
    "currentLocation": {
      "longitude": 102.712345,
      "latitude": 25.043210
    },
    "status": "available",
    "currentOrders": []
  }
]

8. 获取指定货运人员详情

GET /delivery-persons/{id}

响应: 单个货运人员对象

9. 更新货运人员位置

PUT /delivery-persons/{id}/location

请求体:

{
  "longitude": 102.712345,
  "latitude": 25.043210
}

10. 批量更新货运人员位置

POST /delivery-persons/locations/batch

请求体:

{
  "locations": [
    {
      "deliveryPersonId": 1,
      "longitude": 102.712345,
      "latitude": 25.043210,
      "timestamp": 1640995200000
    }
  ]
}

11. 获取位置历史记录

GET /delivery-persons/{id}/location-history?limit=50

响应:

[
  {
    "timestamp": 1640995200000,
    "longitude": 102.712345,
    "latitude": 25.043210,
    "speed": 25.5,
    "accuracy": 5.2
  }
]

12. 实时位置订阅

POST /delivery-persons/locations/subscribe

请求体:

{
  "deliveryPersonIds": [1, 2, 3]
}

响应:

{
  "subscriptionId": "sub_123456",
  "expiresAt": 1641081600000
}

13. 取消位置订阅

POST /delivery-persons/locations/unsubscribe/{subscriptionId}

订单接口

14. 获取待指派订单

GET /orders/pending

响应: 订单数组

15. 指派订单给货运人员

POST /orders/{orderId}/assign

请求体:

{
  "deliveryPersonId": 1
}

16. 获取货运人员当前订单

GET /delivery-persons/{id}/orders

响应: 订单数组

统计接口

17. 获取系统统计信息

GET /stats/system

响应:

{
  "totalWarehouses": 10,
  "totalDeliveryPersons": 25,
  "pendingOrders": 8,
  "activeOrders": 32
}

18. 获取订单统计信息

GET /stats/orders?timeRange=today

参数:

• timeRange: today | week | month

响应:

{
  "totalOrders": 156,
  "completedOrders": 128,
  "inProgressOrders": 28,
  "averageDeliveryTime": 2.5
}

系统接口

19. 健康检查

GET /health

响应:

{
  "status": "ok",
  "message": "系统运行正常",
  "timestamp": 1640995200000
}

20. 上传错误日志

POST /logs/error

请求体:

{
  "error": "错误信息",
  "stack": "错误堆栈",
  "timestamp": 1640995200000,
  "userAgent": "Mozilla/5.0..."
}

错误处理

所有接口都应返回标准的错误格式：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {}
  }
}

模拟数据模式

当后端不可用时，前端会自动切换到模拟数据模式。在此模式下：

1. 所有API调用会抛出包含 MOCK_MODE 消息的错误
2. 桥接服务会捕获这些错误并提供模拟数据
3. 用户可以在设置中手动切换模式

开发建议

1. 接口版本化: 建议在URL中包含版本号，如 /api/v1/warehouses
2. 分页支持: 列表接口应支持分页参数 ?page=1&limit=20
3. 字段过滤: 支持 ?fields=id,name,status 参数来限制返回字段
4. 排序支持: 支持 ?sort=name,-createdAt 参数来指定排序
5. 搜索过滤: 支持 ?search=keyword 参数来进行全文搜索

前端集成

前端已经实现了完整的桥接层，支持：

• 自动模式切换（模拟数据 ↔ 真实API）
• 统一的错误处理
• 接口测试工具
• 详细的调试信息

后端只需要按照此规范实现API接口，前端即可无缝集成。