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
```

**响应**:
```json
[
  {
    "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
```

**响应**:
```json
[
  {
    "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
```

**请求体**:
```json
{
  "longitude": 102.712345,
  "latitude": 25.043210
}
```

### 10. 批量更新货运人员位置
```
POST /delivery-persons/locations/batch
```

**请求体**:
```json
{
  "locations": [
    {
      "deliveryPersonId": 1,
      "longitude": 102.712345,
      "latitude": 25.043210,
      "timestamp": 1640995200000
    }
  ]
}
```

### 11. 获取位置历史记录
```
GET /delivery-persons/{id}/location-history?limit=50
```

**响应**:
```json
[
  {
    "timestamp": 1640995200000,
    "longitude": 102.712345,
    "latitude": 25.043210,
    "speed": 25.5,
    "accuracy": 5.2
  }
]
```

### 12. 实时位置订阅
```
POST /delivery-persons/locations/subscribe
```

**请求体**:
```json
{
  "deliveryPersonIds": [1, 2, 3]
}
```

**响应**:
```json
{
  "subscriptionId": "sub_123456",
  "expiresAt": 1641081600000
}
```

### 13. 取消位置订阅
```
POST /delivery-persons/locations/unsubscribe/{subscriptionId}
```

## 订单接口

### 14. 获取待指派订单
```
GET /orders/pending
```

**响应**: 订单数组

### 15. 指派订单给货运人员
```
POST /orders/{orderId}/assign
```

**请求体**:
```json
{
  "deliveryPersonId": 1
}
```

### 16. 获取货运人员当前订单
```
GET /delivery-persons/{id}/orders
```

**响应**: 订单数组

## 统计接口

### 17. 获取系统统计信息
```
GET /stats/system
```

**响应**:
```json
{
  "totalWarehouses": 10,
  "totalDeliveryPersons": 25,
  "pendingOrders": 8,
  "activeOrders": 32
}
```

### 18. 获取订单统计信息
```
GET /stats/orders?timeRange=today
```

**参数**:
- `timeRange`: today | week | month

**响应**:
```json
{
  "totalOrders": 156,
  "completedOrders": 128,
  "inProgressOrders": 28,
  "averageDeliveryTime": 2.5
}
```

## 系统接口

### 19. 健康检查
```
GET /health
```

**响应**:
```json
{
  "status": "ok",
  "message": "系统运行正常",
  "timestamp": 1640995200000
}
```

### 20. 上传错误日志
```
POST /logs/error
```

**请求体**:
```json
{
  "error": "错误信息",
  "stack": "错误堆栈",
  "timestamp": 1640995200000,
  "userAgent": "Mozilla/5.0..."
}
```

## 错误处理

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

```json
{
  "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接口，前端即可无缝集成。