WXProgram/backend-api.md

# 后端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. 提供详细的错误日志和调试信息

## 联系方式

如有接口相关问题，请联系前端开发团队。