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
• 响应:

[
  {
    "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
• 响应:

[
  {
    "id": 101,
    "name": "张师傅",
    "phone": "13812345678",
    "avatarUrl": "/images/truck.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
• 请求体:

{
  "longitude": 102.714585,
  "latitude": 25.046321
}

4. 订单接口

4.1 获取待指派订单

• URL: /orders/pending
• 方法: GET
• 响应:

[
  {
    "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
• 请求体:

{
  "deliveryPersonId": 101
}

4.3 获取货运人员当前订单

• URL: /delivery-persons/{id}/orders
• 方法: GET
• 响应: 订单列表

数据格式说明

用户信息 (UserInfo)

interface UserInfo {
  id: number;
  name: string;
  role: 'admin' | 'delivery_person';
  avatarUrl: string;
  phone: string;
}

仓库信息 (WarehouseInfo)

interface WarehouseInfo {
  id: number;
  name: string;
  address: string;
  contact: string;
  phone: string;
  description: string;
  status: 'open' | 'closed' | 'maintenance';
  capacity: number;
}

货运人员 (DeliveryPerson)

interface DeliveryPerson {
  id: number;
  name: string;
  phone: string;
  avatarUrl: string;
  status: 'idle' | 'busy';
  currentLocation: {
    longitude: number;
    latitude: number;
  };
  currentOrders: Order[];
}

订单 (Order)

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: 服务器内部错误

错误响应格式：

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

联系方式

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