# API v2 Shipment Delivery Photo 文档

本文档说明司机按出货单上传送达照片的 API。

## 数据结构

```json
{
  "id": 1,
  "shipment_id": 100,
  "delivery_id": 20,
  "photo": "https://image.yuwen.cloud/media/shipment_delivery_photos/demo.jpg",
  "remark": "已送达并签收",
  "created_by": 8,
  "created_at": "2026-04-28T20:00:00+08:00",
  "updated_at": "2026-04-28T20:00:00+08:00"
}
```

说明：

- `photo` 使用项目现有七牛存储。
- `shipment_id` 与 `delivery_id` 都是必填。
- 同一个 `shipment_id + delivery_id` 组合允许多次写入，不做唯一性限制。
- 后端会校验 `shipment.delivery_id == delivery_id`，不一致时拒绝写入。

## 列表查询

- URL: `/api/v2/shipment-delivery-photos/`
- Method: `GET`

查询参数：

| 参数 | 类型 | 说明 |
|------|------|------|
| `shipment_id` | int | 可选，按出货单筛选 |
| `delivery_id` | int | 可选，按送货单筛选 |

说明：

- 支持只传 `shipment_id`
- 支持只传 `delivery_id`
- 支持同时传两者，按 AND 过滤

成功响应：`ShipmentDeliveryPhoto[]`

## 创建送达照片

- URL: `/api/v2/shipment-delivery-photos/`
- Method: `POST`
- Content-Type: `multipart/form-data`

请求参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `shipment` | int | 是 | 出货单 ID |
| `delivery` | int | 是 | 送货单 ID |
| `photo` | file | 是 | 送达照片 |
| `remark` | string | 否 | 备注 |

说明：

- `created_by` 由当前登录用户自动写入
- `shipment` 与 `delivery` 必须属于当前商户
- `delivery` 必须与 `shipment.delivery_id` 一致

成功响应：`201 Created`，返回 `ShipmentDeliveryPhoto`

## 详情查询

- URL: `/api/v2/shipment-delivery-photos/<photo_id>/`
- Method: `GET`

成功响应：`ShipmentDeliveryPhoto`

## 更新送达照片

- URL: `/api/v2/shipment-delivery-photos/<photo_id>/`
- Method: `PATCH` / `PUT`
- Content-Type: `multipart/form-data`

允许更新：

| 参数 | 类型 | 说明 |
|------|------|------|
| `shipment` | int | 出货单 ID |
| `delivery` | int | 送货单 ID |
| `photo` | file | 照片 |
| `remark` | string | 备注 |

说明：

- 更新时仍会执行 `shipment.delivery_id == delivery_id` 一致性校验
- `PATCH` 支持部分更新
- `PUT` 需要传完整字段

## 删除送达照片

- URL: `/api/v2/shipment-delivery-photos/<photo_id>/`
- Method: `DELETE`

成功响应：`204 No Content`