feat: /api/v1/shipment/sales-items/by-printing-order/KD20135142/

2026-03-31 19:46:53 +08:00
parent 72840b7277
commit d36d9c1d9c
4 changed files with 205 additions and 9 deletions
--- a/docs/shipment_api.md
+++ b/docs/shipment_api.md
@@ -8,6 +8,7 @@
 - [创建出货单](#创建出货单)
 - [查询有待出货销售品的客户](#查询有待出货销售品的客户)
 - [按客户查询销售品](#按客户查询销售品)
+- [查询销售品详情](#查询销售品详情)
 - [通过生产订单查询销售品](#通过生产订单查询销售品)

 ---
@@ -341,6 +342,7 @@
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | include_already_has_shipment | bool | 否 | false | 是否包含已关联出货单的销售品 |
+| external_order_id | string | 否 | - | 按生产订单外部订单号精确筛选 |
 | limit | int | 否 | 800 | 分页大小 |
 | offset | int | 否 | 0 | 偏移量 |

@@ -350,6 +352,7 @@
 2. 仅查询当前商户下、`customer_id` 匹配的销售品
 3. 默认只返回 `shipment` 为空的销售品（待出货）
 4. 可通过 `include_already_has_shipment=true` 包含已出货销售品
+5. 可通过 `external_order_id` 按关联生产订单的外部订单号精确筛选

 ### 响应格式

@@ -369,6 +372,7 @@
      "remark": "",
      "printing_job_id": 88,
      "printing_order_id": 23,
+      "external_order_id": "KD20135142",
      "customer_id": 12,
      "customer_name": "客户A",
      "shipment_id": null,
@@ -393,6 +397,97 @@

 ---

+## 查询销售品详情
+
+查询单个销售品详情，返回列表接口中的全部字段，并额外补充关联生产任务产品图片。
+
+### 接口信息
+
+- **URL**: `/api/v1/shipment/sales-items/<id>/`
+- **Method**: `GET`
+- **认证**: 需要登录（JWT Token）
+
+### 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | int | 是 | 销售品ID |
+
+### 业务逻辑
+
+1. 仅允许查询当前商户下的销售品
+2. 返回销售品基础信息、关联客户信息、关联出货信息
+3. 额外返回关联 `PrintingJob` 产品图 URL：`product_image_url`
+4. 若无关联图片，则 `product_image_url` 返回 `null`
+
+### 响应格式
+
+```json
+{
+  "id": 101,
+  "name": "赛扬 190g",
+  "quantity": "1200.00",
+  "unit": 1,
+  "unit_display": "米",
+  "position": "A1-01",
+  "remark": "",
+  "printing_job_id": 88,
+  "printing_order_id": 23,
+  "external_order_id": "KD20135142",
+  "customer_id": 12,
+  "customer_name": "客户A",
+  "shipment_id": null,
+  "shipment_date": null,
+  "created_at": "2026-03-28T10:00:00Z",
+  "created_by_id": 1,
+  "created_by_name": "张三",
+  "product_image_url": "https://cdn.example.com/products/88/main.jpg"
+}
+```
+
+### 响应字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int | 销售品ID |
+| name | string | 销售品名称 |
+| quantity | string | 数量（Decimal，保留2位小数） |
+| unit | int | 单位编码（1=米, 2=件, 3=码, 4=个） |
+| unit_display | string | 单位显示名称 |
+| position | string | 货位（可能为空） |
+| remark | string | 备注（可能为空） |
+| printing_job_id | int/null | 关联的生产任务ID |
+| printing_order_id | int/null | 关联的生产订单ID |
+| external_order_id | string/null | 关联生产订单的外部订单号 |
+| customer_id | int/null | 销售品关联客户ID |
+| customer_name | string/null | 销售品关联客户名称 |
+| shipment_id | int/null | 关联的出货单ID，null 表示未出货 |
+| shipment_date | string/null | 出货日期（YYYY-MM-DD），null 表示未出货 |
+| created_at | string | 创建时间（ISO 8601） |
+| created_by_id | int/null | 创建人ID |
+| created_by_name | string/null | 创建人名称 |
+| product_image_url | string/null | 关联产品主图 URL，无图时为 `null` |
+
+### 错误响应
+
+#### 404 Not Found - 销售品不存在或无权限
+
+```json
+{
+  "detail": "销售品 999 不存在"
+}
+```
+
+### 使用示例
+
+```bash
+curl -X GET \
+  'https://api.example.com/api/v1/shipment/sales-items/101/' \
+  -H 'Authorization: Bearer <token>'
+```
+
+---
+
 ## 通过生产订单查询销售品

 查询与指定生产订单（PrintingOrder）关联的所有销售品（SalesItem）。
@@ -407,7 +502,7 @@

 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| printing_order_id | int | 是 | 生产订单ID |
+| printing_order_id | string | 是 | 生产订单内部ID，或 `external_order_id` |

 ### 查询参数

@@ -417,9 +512,12 @@

 ### 业务逻辑

-1. 根据 `printing_order_id` 获取该生产订单下所有 `PrintingJob` 的 ID
-2. 查询 `SalesItem`，过滤 `printing_job_id` 在这些 job ID 中的记录
-3. 根据 `include_already_has_shipment` 参数决定是否过滤已关联出货单的销售品：
+1. 先尝试将路径参数按内部生产订单ID查询
+2. 若内部ID未命中，则按 `external_order_id` 查询生产订单
+3. 若 `external_order_id` 命中多条生产订单，则返回 `400 Bad Request`
+4. 获取该生产订单下所有 `PrintingJob` 的 ID
+5. 查询 `SalesItem`，过滤 `printing_job_id` 在这些 job ID 中的记录
+6. 根据 `include_already_has_shipment` 参数决定是否过滤已关联出货单的销售品：
   - `false`（默认）：只返回 `shipment` 为空的销售品（待出货）
   - `true`：返回所有销售品（包含已出货的）

@@ -502,6 +600,14 @@
 }
 ```

+#### 400 Bad Request - external_order_id 匹配多条生产订单
+
+```json
+{
+    "detail": "external_order_id KD20135142 匹配到多个生产订单，请改用内部ID查询"
+}
+```
+
 #### 401 Unauthorized - 未登录

 ```json
@@ -520,6 +626,14 @@ curl -X GET \
  -H 'Authorization: Bearer <token>'
 ```

+#### 使用 external_order_id 查询
+
+```bash
+curl -X GET \
+  'https://api.example.com/api/v1/shipment/sales-items/by-printing-order/KD20135142/' \
+  -H 'Authorization: Bearer <token>'
+```
+
 #### 查询所有销售品（包含已出货）

 ```bash