fix: added merchant_id to printing_order and plate_order

2026-01-14 14:26:03 +08:00
parent 3e75328156
commit fae667c965
20 changed files with 1049 additions and 17 deletions
--- a/docs/shipment_api.md
+++ b/docs/shipment_api.md
@@ -0,0 +1,157 @@
+# Shipment API 文档
+
+出货管理模块 API 文档，包含出货单和销售品相关接口。
+
+## 目录
+
+- [通过生产订单查询销售品](#通过生产订单查询销售品)
+
+---
+
+## 通过生产订单查询销售品
+
+查询与指定生产订单（PrintingOrder）关联的所有销售品（SalesItem）。
+
+### 接口信息
+
+- **URL**: `/api/v1/shipment/sales-items/by-printing-order/<printing_order_id>/`
+- **Method**: `GET`
+- **认证**: 需要登录（JWT Token）
+
+### 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| printing_order_id | int | 是 | 生产订单ID |
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| include_already_has_shipment | bool | 否 | false | 是否包含已关联出货单的销售品 |
+
+### 业务逻辑
+
+1. 根据 `printing_order_id` 获取该生产订单下所有 `PrintingJob` 的 ID
+2. 查询 `SalesItem`，过滤 `printing_job_id` 在这些 job ID 中的记录
+3. 根据 `include_already_has_shipment` 参数决定是否过滤已关联出货单的销售品：
+   - `false`（默认）：只返回 `shipment` 为空的销售品（待出货）
+   - `true`：返回所有销售品（包含已出货的）
+
+### 响应格式
+
+```json
+{
+    "count": 2,
+    "results": [
+        {
+            "id": 1,
+            "name": "产品A - 红色",
+            "quantity": "100.00",
+            "unit": 1,
+            "unit_display": "米",
+            "position": "A1-01",
+            "remark": "加急处理",
+            "printing_job_id": 123,
+            "customer_id": null,
+            "shipment_id": null,
+            "shipment_date": null,
+            "created_at": "2026-01-14T10:00:00Z",
+            "created_by_id": 1,
+            "created_by_name": "张三"
+        },
+        {
+            "id": 2,
+            "name": "产品B - 蓝色",
+            "quantity": "50.50",
+            "unit": 1,
+            "unit_display": "米",
+            "position": "",
+            "remark": "",
+            "printing_job_id": 124,
+            "customer_id": 10,
+            "shipment_id": 5,
+            "shipment_date": "2026-01-13",
+            "created_at": "2026-01-13T15:30:00Z",
+            "created_by_id": 2,
+            "created_by_name": "李四"
+        }
+    ]
+}
+```
+
+### 响应字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| count | int | 结果总数 |
+| results | array | 销售品列表 |
+| results[].id | int | 销售品ID |
+| results[].name | string | 销售品名称 |
+| results[].quantity | string | 数量（Decimal，保留2位小数） |
+| results[].unit | int | 单位编码（1=米, 2=件, 3=码, 4=个） |
+| results[].unit_display | string | 单位显示名称 |
+| results[].position | string | 货位（可能为空） |
+| results[].remark | string | 备注（可能为空） |
+| results[].printing_job_id | int/null | 关联的生产任务ID |
+| results[].customer_id | int/null | 销售品级别的客户ID |
+| results[].shipment_id | int/null | 关联的出货单ID，null 表示未出货 |
+| results[].shipment_date | string/null | 出货日期（YYYY-MM-DD），null 表示未出货 |
+| results[].created_at | string | 创建时间（ISO 8601） |
+| results[].created_by_id | int/null | 创建人ID |
+| results[].created_by_name | string/null | 创建人名称 |
+
+### 错误响应
+
+#### 404 Not Found - 生产订单不存在
+
+```json
+{
+    "detail": "生产订单 999 不存在"
+}
+```
+
+#### 401 Unauthorized - 未登录
+
+```json
+{
+    "detail": "Authentication credentials were not provided."
+}
+```
+
+### 使用示例
+
+#### 查询待出货的销售品（默认）
+
+```bash
+curl -X GET \
+  'https://api.example.com/api/v1/shipment/sales-items/by-printing-order/123/' \
+  -H 'Authorization: Bearer <token>'
+```
+
+#### 查询所有销售品（包含已出货）
+
+```bash
+curl -X GET \
+  'https://api.example.com/api/v1/shipment/sales-items/by-printing-order/123/?include_already_has_shipment=true' \
+  -H 'Authorization: Bearer <token>'
+```
+
+---
+
+## 单位编码对照表
+
+| 编码 | 名称 |
+|------|------|
+| 1 | 米 |
+| 2 | 件 |
+| 3 | 码 |
+| 4 | 个 |
+
+---
+
+## 相关模块
+
+- `shipment/services.py`: 业务逻辑层
+- `api_v1/views/shipment/`: API 视图层
+- `shipment/models.py`: 数据模型（SalesItem, Shipment）