erpnew/docs/shipment_api.md

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：返回所有销售品（包含已出货的）

响应格式

{
    "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 - 生产订单不存在

{
    "detail": "生产订单 999 不存在"
}

401 Unauthorized - 未登录

{
    "detail": "Authentication credentials were not provided."
}

使用示例

查询待出货的销售品（默认）

curl -X GET \
  'https://api.example.com/api/v1/shipment/sales-items/by-printing-order/123/' \
  -H 'Authorization: Bearer <token>'

查询所有销售品（包含已出货）

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）