first commit
This commit is contained in:
261
backend-api.md
Normal file
261
backend-api.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# 后端API接口文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档描述了前端小程序需要后端提供的RESTful API接口。系统支持双模式运行：
|
||||
- **模拟数据模式**：使用本地模拟数据进行开发和测试
|
||||
- **真实API模式**：连接真实后端服务进行联调和生产
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **基础URL**: `http://localhost:3000/api`
|
||||
- **认证方式**: JWT Token（Bearer Token）
|
||||
- **数据格式**: JSON
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. 用户相关接口
|
||||
|
||||
|
||||
|
||||
#### 1.2 获取用户信息
|
||||
- **URL**: `/user/info`
|
||||
- **方法**: GET
|
||||
- **认证**: 需要Token
|
||||
- **响应**: 同登录接口的用户信息格式
|
||||
|
||||
#### 1.3 用户登出
|
||||
- **URL**: `/user/logout`
|
||||
- **方法**: POST
|
||||
- **认证**: 需要Token
|
||||
|
||||
### 2. 仓库相关接口
|
||||
|
||||
#### 2.1 获取所有仓库列表
|
||||
- **URL**: `/warehouses`
|
||||
- **方法**: GET
|
||||
- **响应**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "瓦尔塔蓄电池昆明总店",
|
||||
"address": "昆明市五华区二环西路599号",
|
||||
"contact": "刘经理",
|
||||
"phone": "0871-65123456",
|
||||
"description": "瓦尔塔蓄电池云南总代理，提供全系列蓄电池产品",
|
||||
"status": "open",
|
||||
"capacity": 2000
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 2.2 获取指定仓库详情
|
||||
- **URL**: `/warehouses/{id}`
|
||||
- **方法**: GET
|
||||
- **响应**: 单个仓库对象
|
||||
|
||||
#### 2.3 获取仓库相关订单
|
||||
- **URL**: `/warehouses/{id}/orders`
|
||||
- **方法**: GET
|
||||
- **响应**: 订单列表（格式见订单接口）
|
||||
|
||||
### 3. 货运人员接口
|
||||
|
||||
#### 3.1 获取所有货运人员
|
||||
- **URL**: `/delivery-persons`
|
||||
- **方法**: GET
|
||||
- **响应**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 101,
|
||||
"name": "张师傅",
|
||||
"phone": "13812345678",
|
||||
"avatarUrl": "/images/trucks.png",
|
||||
"status": "idle",
|
||||
"currentLocation": {
|
||||
"longitude": 102.714585,
|
||||
"latitude": 25.046321
|
||||
},
|
||||
"currentOrders": []
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 3.2 获取指定货运人员详情
|
||||
- **URL**: `/delivery-persons/{id}`
|
||||
- **方法**: GET
|
||||
- **响应**: 单个货运人员对象
|
||||
|
||||
#### 3.3 更新货运人员位置
|
||||
- **URL**: `/delivery-persons/{id}/location`
|
||||
- **方法**: PUT
|
||||
- **请求体**:
|
||||
```json
|
||||
{
|
||||
"longitude": 102.714585,
|
||||
"latitude": 25.046321
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 订单接口
|
||||
|
||||
#### 4.1 获取待指派订单
|
||||
- **URL**: `/orders/pending`
|
||||
- **方法**: GET
|
||||
- **响应**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1001,
|
||||
"startPoint": {
|
||||
"id": 1,
|
||||
"name": "瓦尔塔蓄电池昆明总店",
|
||||
"longitude": 102.705745,
|
||||
"latitude": 25.055281
|
||||
},
|
||||
"endPoint": {
|
||||
"name": "昆明德众汽车销售服务有限公司",
|
||||
"longitude": 102.714686,
|
||||
"latitude": 25.047134
|
||||
},
|
||||
"status": "pending",
|
||||
"goodsType": "瓦尔塔AGM蓄电池",
|
||||
"goodsWeight": 50,
|
||||
"createTime": 1640995200000
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 4.2 指派订单给货运人员
|
||||
- **URL**: `/orders/{id}/assign`
|
||||
- **方法**: POST
|
||||
- **请求体**:
|
||||
```json
|
||||
{
|
||||
"deliveryPersonId": 101
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.3 获取货运人员当前订单
|
||||
- **URL**: `/delivery-persons/{id}/orders`
|
||||
- **方法**: GET
|
||||
- **响应**: 订单列表
|
||||
|
||||
## 数据格式说明
|
||||
|
||||
### 用户信息 (UserInfo)
|
||||
```typescript
|
||||
interface UserInfo {
|
||||
id: number;
|
||||
name: string;
|
||||
role: 'admin' | 'delivery_person';
|
||||
avatarUrl: string;
|
||||
phone: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 仓库信息 (WarehouseInfo)
|
||||
```typescript
|
||||
interface WarehouseInfo {
|
||||
id: number;
|
||||
name: string;
|
||||
address: string;
|
||||
contact: string;
|
||||
phone: string;
|
||||
description: string;
|
||||
status: 'open' | 'closed' | 'maintenance';
|
||||
capacity: number;
|
||||
}
|
||||
```
|
||||
|
||||
### 货运人员 (DeliveryPerson)
|
||||
```typescript
|
||||
interface DeliveryPerson {
|
||||
id: number;
|
||||
name: string;
|
||||
phone: string;
|
||||
avatarUrl: string;
|
||||
status: 'idle' | 'busy';
|
||||
currentLocation: {
|
||||
longitude: number;
|
||||
latitude: number;
|
||||
};
|
||||
currentOrders: Order[];
|
||||
}
|
||||
```
|
||||
|
||||
### 订单 (Order)
|
||||
```typescript
|
||||
interface Order {
|
||||
id: number;
|
||||
startPoint: {
|
||||
id: number;
|
||||
name: string;
|
||||
longitude: number;
|
||||
latitude: number;
|
||||
};
|
||||
endPoint: {
|
||||
name: string;
|
||||
longitude: number;
|
||||
latitude: number;
|
||||
};
|
||||
status: 'pending' | 'assigned' | 'in_transit' | 'delivered';
|
||||
goodsType: string;
|
||||
goodsWeight: number;
|
||||
createTime: number;
|
||||
assignTime?: number;
|
||||
deliveryTime?: number;
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
所有接口应返回标准的HTTP状态码：
|
||||
- 200: 成功
|
||||
- 400: 请求参数错误
|
||||
- 401: 未授权
|
||||
- 403: 禁止访问
|
||||
- 404: 资源不存在
|
||||
- 500: 服务器内部错误
|
||||
|
||||
错误响应格式：
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "错误描述信息"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 前端架构说明
|
||||
|
||||
前端采用双服务架构：
|
||||
|
||||
1. **桥接服务 (BridgeService)**: 统一的数据访问层，根据配置自动选择数据源
|
||||
2. **API服务 (ApiService)**: 真实后端API调用
|
||||
3. **模拟数据服务 (DataService/DeliveryService)**: 本地模拟数据提供
|
||||
|
||||
**切换模式**: 通过设置页面或代码配置可在两种模式间切换：
|
||||
- 模拟数据模式：`USE_MOCK_DATA = true`
|
||||
- 真实API模式：`USE_MOCK_DATA = false`
|
||||
|
||||
## 部署要求
|
||||
|
||||
1. 后端服务应运行在 `http://localhost:3000`
|
||||
2. 支持CORS跨域请求
|
||||
3. 提供稳定的API服务，响应时间控制在500ms以内
|
||||
4. 支持HTTPS（生产环境）
|
||||
|
||||
## 开发建议
|
||||
|
||||
1. 先使用模拟数据模式进行前端功能开发
|
||||
2. 开发完成后，切换到真实API模式进行联调测试
|
||||
3. 确保接口数据格式与模拟数据保持一致
|
||||
4. 提供详细的错误日志和调试信息
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有接口相关问题，请联系前端开发团队。
|
||||
Reference in New Issue
Block a user