forked from erp-dev/erp
103 lines
2.4 KiB
Markdown
103 lines
2.4 KiB
Markdown
# 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` |