# 寄车带货功能接口文档

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

## 数据库表结构

### 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. **创建发车任务**
   - 司机选择路线、车辆
   - 设置出发时间
   - 生成唯一任务编号和二维码

2. **开始发车**
   - 更新任务状态为"运行中"
   - 二维码开始有效

3. **到达站点**
   - 更新当前站点
   - 标记该站点的订单为"已取货"

4. **完成任务**
   - 更新任务状态为"已完成"
   - 二维码失效

### 用户端流程

1. **扫码下单**
   - 扫描司机生成的二维码
   - 自动获取任务信息（路线、站点列表）

2. **填写订单信息**
   - 选择起始站点、送达站点（从路线站点中选择）
   - 填写发货人、收货人信息
   - 填写货物详情（名称、数量、重量等）
   - 上传货物图片

3. **确认价格**
   - 系统根据站点价格自动计算费用
   - 用户确认并支付

4. **等待取货和配送**
   - 实时查看订单状态
   - 司机到达起始站点后标记为"已取货"
   - 货物到达目的地后标记为"已送达"

## 接口列表

### 司机任务管理

#### 1. 创建发车任务
```
POST /system/dzbc/driverTrip
```

请求体：
```json
{
  "pathId": 1,
  "driverId": 10,
  "carId": 1,
  "startTime": "2024-02-20 08:00:00"
}
```

返回：
```json
{
  "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}
```

返回：
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

#### 3. 到达站点
```
POST /system/dzbc/driverTrip/arrive/{id}?siteId=2
```

返回：
```json
{
  "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 调用此接口，返回任务信息和路线站点列表。

返回示例：
```json
{
  "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
```

请求体：
```json
{
  "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": "请尽快送达"
}
```

返回：
```json
{
  "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` 表中查询，规则如下：

1. **查询条件**：
   - pathId: 任务对应的路线ID
   - fromSiteId: 用户选择的起始站点ID
   - toSiteId: 用户选择的送达站点ID

2. **返回结果**：
   - 如果找到匹配记录，直接使用该价格
   - 如果没有找到，提示用户无法配送该线路

3. **单位说明**：
   - 数据库存储的价格单位为"分"
   - 前端显示时转换为"元"

## 订单状态流转

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

## 二维码说明

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

## 司机端显示内容

司机端需要实时显示：
1. 当前任务信息（路线、车辆、状态）
2. 当前站点
3. 货物订单列表：
   - 订单编号
   - 起始站点 → 送达站点
   - 发货人、收货人信息
   - 订单状态
   - 货物数量、重量
4. 统计信息：
   - 总订单数
   - 总金额
   - 各站点待取货数量

## 注意事项

1. **站点限制**：
   - 用户只能从任务对应的路线站点中选择
   - 不能选择路线外的站点

2. **时间限制**：
   - 只能在"运行中"状态下扫码下单
   - "待发车"和"已完成"状态不能下单

3. **价格设置**：
   - 需要预先在 `tbl_dzbc_site_price` 表中设置价格
   - 建议为任意两个站点都设置价格
   - 包括相邻站点和跨站点

4. **图片上传**：
   - 支持上传货物图片
   - 图片存储到 OSS
   - 多个图片用逗号分隔存储

5. **订单限制**：
   - 同一用户可以提交多个订单
   - 订单取消后不能恢复