寄车带货功能接口文档

功能概述

寄车带货功能基于固定多站点路线，司机发车时生成专属二维码，用户扫码后可直接填写起始站点创建寄货订单，司机端实时查看货物状态。

数据库表结构

1. 司机发车任务表 (tbl_dzbc_driver_trip)

id: 编号
trip_no: 任务编号（唯一）
path_id: 路线ID
path_name: 路线名称
driver_id: 司机ID
driver_name: 司机姓名
driver_phone: 司机电话
car_id: 车辆ID
car_plate: 车牌号
start_time: 出发时间
end_time: 到达时间
status: 状态（0-待发车，1-运行中，2-已完成，3-已取消）
qr_code: 二维码内容
current_site_id: 当前站点ID
current_site_name: 当前站点名称
cargo_count: 货物数量
cargo_total_price: 货物总价（分）
remark: 备注
ext1, ext2: 扩展字段

2. 货物订单表 (tbl_dzbc_cargo_order)

id: 编号
order_no: 订单编号（唯一）
trip_id: 司机任务ID
trip_no: 任务编号
user_id: 用户ID
user_name: 用户姓名
user_phone: 用户电话
sender_name: 发货人姓名
sender_phone: 发货人电话
receiver_name: 收货人姓名
receiver_phone: 收货人电话
from_site_id: 起始站点ID
from_site_name: 起始站点名称
to_site_id: 送达站点ID
to_site_name: 送达站点名称
price: 价格（分）
pay_status: 支付状态（0-待支付，1-已支付）
pay_time: 支付时间
pay_trade_no: 支付交易号
status: 订单状态（0-待发货，1-已取货，2-运输中，3-已送达，4-已取消）
cargo_count: 货物数量
cargo_weight: 货物重量
cargo_value: 货物价值
remark: 备注
ext1, ext2: 扩展字段

3. 货物详情表 (tbl_dzbc_cargo_item)

id: 编号
order_id: 订单ID
order_no: 订单编号
cargo_name: 货物名称
cargo_type: 货物类型
quantity: 数量
unit: 单位
weight: 重量
length: 长度
width: 宽度
height: 高度
value: 价值
image_urls: 图片地址
remark: 备注
ext1, ext2: 扩展字段

业务流程

司机端流程

创建发车任务
- 司机选择路线、车辆
- 设置出发时间
- 生成唯一任务编号和二维码
开始发车
- 更新任务状态为"运行中"
- 二维码开始有效
到达站点
- 更新当前站点
- 标记该站点的订单为"已取货"
完成任务
- 更新任务状态为"已完成"
- 二维码失效

用户端流程

扫码下单
- 扫描司机生成的二维码
- 自动获取任务信息（路线、站点列表）
填写订单信息
- 选择起始站点、送达站点（从路线站点中选择）
- 填写发货人、收货人信息
- 填写货物详情（名称、数量、重量等）
- 上传货物图片
确认价格
- 系统根据站点价格自动计算费用
- 用户确认并支付
等待取货和配送
- 实时查看订单状态
- 司机到达起始站点后标记为"已取货"
- 货物到达目的地后标记为"已送达"

接口列表

司机任务管理

1. 创建发车任务

POST /system/dzbc/driverTrip

请求体：

{
  "pathId": 1,
  "driverId": 10,
  "carId": 1,
  "startTime": "2024-02-20 08:00:00"
}

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "tripNo": "TRIP20240220080001234",
    "pathId": 1,
    "pathName": "福州市区环线",
    "driverId": 10,
    "driverName": "张司机",
    "driverPhone": "13800138000",
    "carId": 1,
    "carPlate": "闽A12345",
    "startTime": "2024-02-20 08:00:00",
    "status": 0,
    "qrCode": "https://xxx.com/qr/TRIP20240220080001234",
    "cargoCount": 0,
    "cargoTotalPrice": 0,
    "sites": [
      {
        "id": 1,
        "siteId": 1,
        "siteName": "火车站",
        "siteOrder": 1
      },
      {
        "id": 2,
        "siteId": 2,
        "siteName": "市政府",
        "siteOrder": 2
      },
      {
        "id": 3,
        "siteId": 3,
        "siteName": "仓山万达",
        "siteOrder": 3
      }
    ]
  }
}

2. 开始发车

POST /system/dzbc/driverTrip/start/{id}

{
  "code": 200,
  "msg": "操作成功"
}

3. 到达站点

POST /system/dzbc/driverTrip/arrive/{id}?siteId=2

{
  "code": 200,
  "msg": "操作成功"
}

4. 完成任务

POST /system/dzbc/driverTrip/complete/{id}

5. 取消任务

POST /system/dzbc/driverTrip/cancel/{id}

6. 查询任务列表

GET /system/dzbc/driverTrip/list

查询参数：

pathId: 路线ID
driverId: 司机ID
tripNo: 任务编号（模糊查询）
status: 状态
pageNum: 页码
pageSize: 每页大小

7. 查询任务详情

GET /system/dzbc/driverTrip/{id}

8. 根据二维码查询任务（用户扫码）

GET /system/dzbc/driverTrip/qr/{tripNo}

说明：用户扫描二维码后，前端获取 tripNo 调用此接口，返回任务信息和路线站点列表。

返回示例：

{
  "code": 200,
  "data": {
    "id": 1,
    "tripNo": "TRIP20240220080001234",
    "pathId": 1,
    "pathName": "福州市区环线",
    "driverId": 10,
    "driverName": "张司机",
    "driverPhone": "13800138000",
    "carId": 1,
    "carPlate": "闽A12345",
    "startTime": "2024-02-20 08:00:00",
    "status": 1,
    "currentSiteId": 1,
    "currentSiteName": "火车站",
    "cargoCount": 5,
    "cargoTotalPrice": 5000,
    "sites": [
      {
        "id": 1,
        "siteId": 1,
        "siteName": "火车站",
        "siteOrder": 1
      },
      {
        "id": 2,
        "siteId": 2,
        "siteName": "市政府",
        "siteOrder": 2
      },
      {
        "id": 3,
        "siteId": 3,
        "siteName": "仓山万达",
        "siteOrder": 3
      }
    ],
    "cargoOrders": [
      {
        "id": 1,
        "orderNo": "CARGO20240220081500001",
        "fromSiteName": "火车站",
        "toSiteName": "市政府",
        "price": 500,
        "status": 1
      }
    ]
  }
}

货物订单管理

1. 提交货物订单

POST /system/dzbc/cargoOrder/submit

请求体：

{
  "tripNo": "TRIP20240220080001234",
  "fromSiteId": 1,
  "toSiteId": 2,
  "senderName": "张三",
  "senderPhone": "13800138001",
  "receiverName": "李四",
  "receiverPhone": "13800138002",
  "items": [
    {
      "cargoName": "电脑",
      "cargoType": "电子产品",
      "quantity": 1,
      "unit": "台",
      "weight": 2.5,
      "length": 40,
      "width": 30,
      "height": 10,
      "value": 5000,
      "images": ["http://xxx.com/image1.jpg"],
      "remark": "小心轻放"
    }
  ],
  "remark": "请尽快送达"
}

{
  "code": 200,
  "data": {
    "id": 1,
    "orderNo": "CARGO20240220081500001",
    "tripId": 1,
    "tripNo": "TRIP20240220080001234",
    "userId": 1,
    "userName": "王五",
    "userPhone": "13800138003",
    "senderName": "张三",
    "senderPhone": "13800138001",
    "receiverName": "李四",
    "receiverPhone": "13800138002",
    "fromSiteId": 1,
    "fromSiteName": "火车站",
    "toSiteId": 2,
    "toSiteName": "市政府",
    "price": 500,
    "payStatus": 0,
    "status": 0,
    "cargoCount": 1,
    "cargoWeight": 2.5,
    "cargoValue": 5000,
    "items": [...]
  }
}

2. 查询我的订单

GET /system/dzbc/cargoOrder/my/list

说明：获取当前登录用户的货物订单列表。

3. 查询任务的订单列表

GET /system/dzbc/cargoOrder/trip/{tripId}

说明：司机端查看某个任务的所有货物订单。

4. 更新订单状态

POST /system/dzbc/cargoOrder/status/{id}?status=1

状态说明：

0: 待发货
1: 已取货（司机到达起始站点）
2: 运输中（货物运输中）
3: 已送达（到达目的地）

5. 查询订单列表（管理员/司机）

GET /system/dzbc/cargoOrder/list

查询参数：

tripId: 任务ID
userId: 用户ID
status: 订单状态
payStatus: 支付状态
pageNum: 页码
pageSize: 每页大小

6. 查询订单详情

GET /system/dzbc/cargoOrder/{id}

价格计算规则

价格从 tbl_dzbc_site_price 表中查询，规则如下：

查询条件：
- pathId: 任务对应的路线ID
- fromSiteId: 用户选择的起始站点ID
- toSiteId: 用户选择的送达站点ID
返回结果：
- 如果找到匹配记录，直接使用该价格
- 如果没有找到，提示用户无法配送该线路
单位说明：
- 数据库存储的价格单位为"分"
- 前端显示时转换为"元"

订单状态流转

待发货 (0)
    ↓ [司机到达起始站点，取货]
已取货 (1)
    ↓ [开始运输]
运输中 (2)
    ↓ [到达目的地]
已送达 (3)
    ↓
已取消 (4) [用户或管理员取消]

二维码说明

生成时机：创建发车任务时自动生成
内容格式：https://xxx.com/qr/{tripNo} 或直接使用 tripNo
有效期：从"开始发车"到"完成任务"期间有效
使用方式：
- 前端生成二维码图片供司机展示
- 用户扫码后获取 tripNo
- 调用 GET /system/dzbc/driverTrip/qr/{tripNo} 获取任务信息

司机端显示内容

司机端需要实时显示：

当前任务信息（路线、车辆、状态）
当前站点
货物订单列表：
- 订单编号
- 起始站点 → 送达站点
- 发货人、收货人信息
- 订单状态
- 货物数量、重量
统计信息：
- 总订单数
- 总金额
- 各站点待取货数量

注意事项

站点限制：
- 用户只能从任务对应的路线站点中选择
- 不能选择路线外的站点
时间限制：
- 只能在"运行中"状态下扫码下单
- "待发车"和"已完成"状态不能下单
价格设置：
- 需要预先在 tbl_dzbc_site_price 表中设置价格
- 建议为任意两个站点都设置价格
- 包括相邻站点和跨站点
图片上传：
- 支持上传货物图片
- 图片存储到 OSS
- 多个图片用逗号分隔存储
订单限制：
- 同一用户可以提交多个订单
- 订单取消后不能恢复

CARGO_README.md 10 KB История Исходник

寄车带货功能接口文档

功能概述

数据库表结构

1. 司机发车任务表 (tbl_dzbc_driver_trip)

2. 货物订单表 (tbl_dzbc_cargo_order)

3. 货物详情表 (tbl_dzbc_cargo_item)

业务流程

司机端流程

用户端流程

接口列表

司机任务管理

1. 创建发车任务

2. 开始发车

3. 到达站点

4. 完成任务

5. 取消任务

6. 查询任务列表

7. 查询任务详情

8. 根据二维码查询任务（用户扫码）

货物订单管理

1. 提交货物订单

2. 查询我的订单

3. 查询任务的订单列表

4. 更新订单状态

5. 查询订单列表（管理员/司机）

6. 查询订单详情

价格计算规则

订单状态流转

二维码说明

司机端显示内容

注意事项

CARGO_README.md 10 KB

История Исходник