# 寄车带货功能实现总结

## 已完成的文件

### 1. 数据库表
- `script/sql/cargo.sql` - 建表 SQL（3张表）
  - tbl_dzbc_driver_trip（司机发车任务表）
  - tbl_dzbc_cargo_order（货物订单表）
  - tbl_dzbc_cargo_item（货物详情表）

### 2. 实体类
- `TblDzbcDriverTrip.java` - 司机任务实体
- `TblDzbcCargoOrder.java` - 货物订单实体
- `TblDzbcCargoItem.java` - 货物详情实体

### 3. 业务对象
- `TblDzbcDriverTripBo.java` - 司机任务业务对象
- `CargoOrderSubmitBo.java` - 订单提交请求对象
- `CargoItemBo.java` - 货物项业务对象

### 4. 视图对象
- `TblDzbcDriverTripVo.java` - 司机任务视图对象
- `TblDzbcCargoOrderVo.java` - 货物订单视图对象
- `TblDzbcCargoItemVo.java` - 货物详情视图对象

### 5. Mapper 接口
- `TblDzbcDriverTripMapper.java` - 司机任务 Mapper
- `TblDzbcCargoOrderMapper.java` - 货物订单 Mapper
- `TblDzbcCargoItemMapper.java` - 货物详情 Mapper

### 6. Service 接口
- `ITblDzbcDriverTripService.java` - 司机任务服务接口
- `ITblDzbcCargoOrderService.java` - 货物订单服务接口
- `ITblDzbcCargoItemService.java` - 货物详情服务接口

### 7. Service 实现
- `TblDzbcDriverTripServiceImpl.java` - 司机任务服务实现（已完成）

### 8. Controller
- `TblDzbcDriverTripController.java` - 司机任务控制器
- `TblDzbcCargoOrderController.java` - 货物订单控制器

### 9. 文档
- `script/sql/CARGO_README.md` - 完整接口文档

## 需要补充的代码

由于代码量较大，以下 Service 实现类可以根据需要补充：

### 1. TblDzbcCargoOrderServiceImpl

核心功能：
- 提交订单（计算价格、保存订单和货物详情）
- 更新订单状态
- 查询订单列表

### 2. TblDzbcCargoItemServiceImpl

核心功能：
- 保存货物详情（支持多图片上传）
- 查询订单的货物列表
- 删除货物详情

### 3. Mapper XML 文件

需要创建的 XML 文件：
- `TblDzbcDriverTripMapper.xml`
- `TblDzbcCargoOrderMapper.xml`
- `TblDzbcCargoItemMapper.xml`

## 主要功能模块

### 司机端功能

1. **创建发车任务**
   - 选择路线、车辆、司机
   - 设置出发时间
   - 生成任务编号和二维码

2. **任务管理**
   - 开始发车
   - 到达站点（更新当前站点）
   - 完成任务
   - 取消任务

3. **订单查看**
   - 查看任务的所有货物订单
   - 实时显示货物状态
   - 更新订单状态（取货、送达）

### 用户端功能

1. **扫码下单**
   - 扫描司机二维码
   - 自动获取任务和站点信息
   - 从站点列表选择起始、送达站点

2. **填写订单**
   - 填写发货人、收货人信息
   - 填写货物详情（名称、数量、重量等）
   - 上传货物图片
   - 查看价格

3. **订单管理**
   - 查看我的订单列表
   - 查看订单详情
   - 实时跟踪订单状态

## 数据流

### 1. 订单创建流程

```
用户扫码
  ↓
获取任务信息（tripNo）
  ↓
选择站点（fromSiteId, toSiteId）
  ↓
填写订单信息
  ↓
系统计算价格（从 tbl_dzbc_site_price）
  ↓
保存订单（tbl_dzbc_cargo_order）
  ↓
保存货物详情（tbl_dzbc_cargo_item）
  ↓
返回订单信息
```

### 2. 司机配送流程

```
创建任务（status=0）
  ↓
开始发车（status=1）← 二维码生效
  ↓
到达站点1（更新 currentSiteId）
  ↓
取货（更新订单 status=1）
  ↓
到达站点2（更新 currentSiteId）
  ↓
送货（更新订单 status=2）
  ↓
完成任务（status=2）← 二维码失效
```

## 价格计算

价格存储在 `tbl_dzbc_site_price` 表中：

```sql
SELECT price 
FROM tbl_dzbc_site_price 
WHERE path_id = ? 
  AND from_site_id = ? 
  AND to_site_id = ?
```

如果查询不到价格，提示用户无法配送该线路。

## 二维码实现方案

### 方案一：前端生成二维码

1. 后端返回 `tripNo`
2. 前端使用二维码库（如 qrcode.js）生成二维码图片
3. 二维码内容：`https://你的域名/qr/{tripNo}`

### 方案二：后端生成二维码图片

1. 使用 Java 二维码库（如 ZXing）生成二维码图片
2. 上传到 OSS
3. 返回图片 URL

## 接口清单

### 司机任务接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /driverTrip | POST | 创建发车任务 |
| /driverTrip/start/{id} | POST | 开始发车 |
| /driverTrip/arrive/{id} | POST | 到达站点 |
| /driverTrip/complete/{id} | POST | 完成任务 |
| /driverTrip/cancel/{id} | POST | 取消任务 |
| /driverTrip/list | GET | 查询任务列表 |
| /driverTrip/{id} | GET | 查询任务详情 |
| /driverTrip/qr/{tripNo} | GET | 扫码查询任务 |

### 货物订单接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /cargoOrder/submit | POST | 提交货物订单 |
| /cargoOrder/my/list | GET | 查询我的订单 |
| /cargoOrder/trip/{tripId} | GET | 查询任务的订单 |
| /cargoOrder/list | GET | 查询订单列表 |
| /cargoOrder/{id} | GET | 查询订单详情 |
| /cargoOrder/status/{id} | POST | 更新订单状态 |

## 部署步骤

1. **执行建表 SQL**
   ```bash
   mysql -u root -p khyznh < script/sql/cargo.sql
   ```

2. **补充缺失的 Service 实现**
   - TblDzbcCargoOrderServiceImpl
   - TblDzbcCargoItemServiceImpl

3. **创建 Mapper XML 文件**
   - TblDzbcDriverTripMapper.xml
   - TblDzbcCargoOrderMapper.xml
   - TblDzbcCargoItemMapper.xml

4. **配置价格**
   - 在 `tbl_dzbc_site_price` 表中设置路线价格
   - 为所有可能的站点组合设置价格

5. **测试接口**
   - 测试创建任务
   - 测试扫码查询
   - 测试提交订单
   - 测试订单状态流转

## 扩展建议

1. **支付功能**
   - 集成微信支付
   - 支付后更新订单支付状态

2. **消息通知**
   - 下单成功通知司机
   - 订单状态变更通知用户
   - 到达站点通知

3. **评价功能**
   - 用户对配送服务进行评价
   - 评分系统

4. **统计分析**
   - 订单量统计
   - 收入统计
   - 热门线路统计

5. **批量操作**
   - 批量更新订单状态
   - 批量打印订单

## 注意事项

1. **依赖关系**
   - 寄车带货功能依赖多站点路线功能（tbl_dzbc_multi_site_path）
   - 确保路线和站点已正确配置
   - 确保站点价格已设置

2. **状态管理**
   - 严格遵循订单状态流转规则
   - 不能跳过状态直接变更

3. **数据一致性**
   - 订单详情与订单主表保持一致
   - 任务状态与订单状态关联

4. **并发处理**
   - 防止同一订单重复操作
   - 使用事务保证数据一致性

详细接口文档请参考：`script/sql/CARGO_README.md`