first commit

API_SPECIFICATION.md

@@ -0,0 +1,315 @@
+# 仓库管理系统 - 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接口，前端即可无缝集成。