feat: prod clean

docs/api_v2_shipment_delivery_photo_api.md

@@ -0,0 +1,103 @@
+# 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`