forked from erp-dev/erp
249 lines
6.0 KiB
Markdown
249 lines
6.0 KiB
Markdown
# Shipment API 文档
|
||
|
||
出货管理模块 API 文档，包含出货单和销售品相关接口。
|
||
|
||
## 目录
|
||
|
||
- [创建出货单](#创建出货单)
|
||
- [通过生产订单查询销售品](#通过生产订单查询销售品)
|
||
|
||
---
|
||
|
||
## 创建出货单
|
||
|
||
创建出货单并关联销售品。
|
||
|
||
### 接口信息
|
||
|
||
- **URL**: `/api/v1/shipment/shipments/`
|
||
- **Method**: `POST`
|
||
- **认证**: 需要登录（JWT Token）
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| customer | int | 是 | 客户ID |
|
||
| shipment_date | string | 是 | 出货日期（YYYY-MM-DD） |
|
||
| remark | string | 否 | 备注 |
|
||
| sales_items | array[int] | 否 | 要关联的销售品ID列表 |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"customer": 1,
|
||
"shipment_date": "2026-01-14",
|
||
"remark": "备注信息",
|
||
"sales_items": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"customer": 1,
|
||
"customer_name": "客户A",
|
||
"shipment_date": "2026-01-14",
|
||
"remark": "备注信息",
|
||
"items_count": 3,
|
||
"created_by_id": 1,
|
||
"created_by_name": "张三",
|
||
"created_at": "2026-01-14T10:00:00Z",
|
||
"updated_at": "2026-01-14T10:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 出货单ID |
|
||
| customer | int | 客户ID |
|
||
| customer_name | string | 客户名称 |
|
||
| shipment_date | string | 出货日期 |
|
||
| remark | string | 备注 |
|
||
| items_count | int | 关联的销售品数量 |
|
||
| created_by_id | int | 创建人ID |
|
||
| created_by_name | string | 创建人名称 |
|
||
| created_at | string | 创建时间 |
|
||
| updated_at | string | 更新时间 |
|
||
|
||
### 错误响应
|
||
|
||
#### 400 Bad Request - 客户不存在
|
||
|
||
```json
|
||
{
|
||
"detail": "客户 999 不存在"
|
||
}
|
||
```
|
||
|
||
#### 400 Bad Request - 销售品不存在
|
||
|
||
```json
|
||
{
|
||
"detail": "以下销售品不存在: [999]"
|
||
}
|
||
```
|
||
|
||
#### 400 Bad Request - 销售品已关联其他出货单
|
||
|
||
```json
|
||
{
|
||
"detail": "以下销售品已关联到其他出货单: [1, 2]"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通过生产订单查询销售品
|
||
|
||
查询与指定生产订单（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）
|