forked from erp-dev/erp
feat: mes module
This commit is contained in:
@@ -24,70 +24,266 @@ curl -X GET \
|
||||
|
||||
## 查询未进入送货单的出货单
|
||||
|
||||
- **URL**: `/api/v2/ai/shipments/unshipped/`
|
||||
- **Method**: `GET`
|
||||
# API v2 Agent 接口文档
|
||||
|
||||
### 查询参数
|
||||
本文档面向 AI Agent 及外部自动化调用方，描述 `/api/v2/ai/` 前缀下的所有接口。
|
||||
|
||||
## 基本约定
|
||||
|
||||
- Base URL: `/api/v2/ai`
|
||||
- 认证：所有接口使用固定 API Key，通过 `Authorization` 请求头直接传入，无 `Bearer` 前缀
|
||||
- 多商户隔离：每个接口均需传入 `merchant_id` 查询参数，后端以此确定数据范围
|
||||
|
||||
### 认证方式
|
||||
|
||||
```text
|
||||
Authorization: <AGENT_ACCESS_KEY>
|
||||
```
|
||||
|
||||
`AGENT_ACCESS_KEY` 由后端部署时通过同名环境变量配置。未配置时所有请求均返回 `401`。
|
||||
|
||||
---
|
||||
|
||||
## 数据结构
|
||||
|
||||
### TransportVehicle
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"merchant_id": 10,
|
||||
"name": "大卡车",
|
||||
"license_plate": "粤A12345",
|
||||
"material_capacities": [
|
||||
{"id": 1, "material_name": "坯布", "capacity": 500},
|
||||
{"id": 2, "material_name": "成品", "capacity": 300}
|
||||
],
|
||||
"created_at": "2026-04-01T08:00:00+08:00",
|
||||
"updated_at": "2026-04-01T08:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Shipment
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 100,
|
||||
"merchant_id": 10,
|
||||
"customer": 5,
|
||||
"customer_name": "客户A",
|
||||
"fabric": "棉布 40S",
|
||||
"order_description": "滚筒预警",
|
||||
"shipment_date": "2026-04-14",
|
||||
"address": "广州市天河区",
|
||||
"contact_name": "张三",
|
||||
"contact_phone": "13800000000",
|
||||
"area": "华东",
|
||||
"remark": "备注",
|
||||
"status": "pending",
|
||||
"status_display": "待出货",
|
||||
"external_id": null,
|
||||
"geo_coordinates": {"lat": 23.1291, "lng": 113.2644},
|
||||
"delivery_id": null,
|
||||
"delivery": null,
|
||||
"sales_items": [
|
||||
{
|
||||
"id": 201,
|
||||
"name": "销售品甲",
|
||||
"quantity": "50.00",
|
||||
"unit": 1,
|
||||
"unit_display": "件",
|
||||
"position": "A-01",
|
||||
"remark": "",
|
||||
"printing_job_id": 88,
|
||||
"printing_job_width": "150cm"
|
||||
}
|
||||
],
|
||||
"created_at": "2026-04-14T10:00:00+08:00",
|
||||
"updated_at": "2026-04-14T10:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
### MesDevice
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"merchant": 10,
|
||||
"category": {
|
||||
"id": 2,
|
||||
"merchant": 10,
|
||||
"name": "打印机",
|
||||
"created_at": "2026-05-01T08:00:00+08:00",
|
||||
"updated_at": "2026-05-01T08:00:00+08:00"
|
||||
},
|
||||
"name": "A-01",
|
||||
"peak_capacity": 120,
|
||||
"capacity_unit": 1,
|
||||
"capacity_unit_label": "米",
|
||||
"extra": {"capacity": {"per_hour": 120}},
|
||||
"created_at": "2026-05-01T08:00:00+08:00",
|
||||
"updated_at": "2026-05-01T08:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
### MesProductionAssignment
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 100,
|
||||
"merchant": 10,
|
||||
"device": {
|
||||
"id": 1,
|
||||
"merchant": 10,
|
||||
"category": {
|
||||
"id": 2,
|
||||
"merchant": 10,
|
||||
"name": "打印机",
|
||||
"created_at": "2026-05-01T08:00:00+08:00",
|
||||
"updated_at": "2026-05-01T08:00:00+08:00"
|
||||
},
|
||||
"name": "A-01",
|
||||
"peak_capacity": 120,
|
||||
"capacity_unit": 1,
|
||||
"capacity_unit_label": "米",
|
||||
"extra": null,
|
||||
"created_at": "2026-05-01T08:00:00+08:00",
|
||||
"updated_at": "2026-05-01T08:00:00+08:00"
|
||||
},
|
||||
"content_type": 45,
|
||||
"object_id": 9001,
|
||||
"assigner": {"id": 20, "name": "张三", "merchant_id": 10},
|
||||
"assignee": {"id": 21, "name": "李四", "merchant_id": 10},
|
||||
"production_quantity": 300,
|
||||
"status": 2,
|
||||
"status_label": "已发布",
|
||||
"extra": {"batch": "A1"},
|
||||
"created_at": "2026-05-02T10:00:00+08:00",
|
||||
"updated_at": "2026-05-02T10:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 运输车辆列表
|
||||
|
||||
- URL: `/api/v2/ai/transport-vehicles/`
|
||||
- Method: `GET`
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `merchant_id` | int | 是 | 商户 ID |
|
||||
| `area` | string | 是 | 地区，精确匹配 |
|
||||
| `limit` | int | 否 | 分页大小 |
|
||||
| `offset` | int | 否 | 分页偏移 |
|
||||
| `limit` | int | 否 | 分页每页数量 |
|
||||
| `offset` | int | 否 | 分页偏移量 |
|
||||
|
||||
### 业务定义
|
||||
说明：
|
||||
|
||||
这里的“未出货”定义为：
|
||||
- `material_capacities` 表示该车辆对不同物料的最大装载量
|
||||
- 只返回 `merchant_id` 对应商户的车辆
|
||||
|
||||
- `Shipment.delivery_id is null`
|
||||
响应为分页结构，`results` 中每条为 `TransportVehicle`。
|
||||
|
||||
也就是该出货单尚未进入送货单。
|
||||
## 运输车辆详情
|
||||
|
||||
### 响应示例
|
||||
- URL: `/api/v2/ai/transport-vehicles/<license_plate>/`
|
||||
- Method: `GET`
|
||||
|
||||
```json
|
||||
{
|
||||
"count": 1,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 101,
|
||||
"merchant_id": 1,
|
||||
"customer": 12,
|
||||
"customer_name": "客户A",
|
||||
"shipment_date": "2026-04-14",
|
||||
"address": "",
|
||||
"contact_name": "张三",
|
||||
"contact_phone": "13800000000",
|
||||
"area": "华东",
|
||||
"remark": "目标记录",
|
||||
"status": 1,
|
||||
"status_display": "草稿(未发布)",
|
||||
"external_id": null,
|
||||
"delivery": null,
|
||||
"created_at": "2026-04-14T10:00:00Z",
|
||||
"updated_at": "2026-04-14T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
路径参数：
|
||||
|
||||
### 错误响应
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `license_plate` | 车牌号码 |
|
||||
|
||||
#### 401 Unauthorized
|
||||
查询参数：
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "AGENT_ACCESS_KEY 无效"
|
||||
}
|
||||
```
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `merchant_id` | int | 是 | 商户 ID |
|
||||
|
||||
#### 400 Bad Request
|
||||
说明：
|
||||
|
||||
```json
|
||||
{
|
||||
"merchant_id": ["This field is required."]
|
||||
}
|
||||
```
|
||||
- 同一商户内 `license_plate` 唯一
|
||||
- 不同商户可能存在相同车牌号，`merchant_id` 是必须的
|
||||
- 车辆不存在时返回 `404`
|
||||
|
||||
## 未出货出货单列表
|
||||
|
||||
- URL: `/api/v2/ai/shipments/unshipped/`
|
||||
- Method: `GET`
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `merchant_id` | int | 是 | 商户 ID |
|
||||
| `area` | string | 是 | 地区筛选，精确匹配 |
|
||||
| `limit` | int | 否 | 分页每页数量 |
|
||||
| `offset` | int | 否 | 分页偏移量 |
|
||||
|
||||
说明：
|
||||
|
||||
- “未出货”定义：`delivery` 为空，即尚未关联送货单
|
||||
- `delivery_id` 未关联时返回 `null`
|
||||
- 结果按 `created_at` 降序排列
|
||||
- 只返回 `merchant_id` 对应商户的数据
|
||||
|
||||
响应为分页结构，`results` 中每条为 `Shipment`。
|
||||
|
||||
## MES 设备列表
|
||||
|
||||
- URL: `/api/v2/ai/mes/devices/`
|
||||
- Method: `GET`
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `merchant_id` | int | 是 | 商户 ID |
|
||||
| `limit` | int | 否 | 分页每页数量 |
|
||||
| `offset` | int | 否 | 分页偏移量 |
|
||||
|
||||
说明：
|
||||
|
||||
- 使用与其他 agent API 相同的 `AGENT_ACCESS_KEY` 鉴权，不走 JWT
|
||||
- 返回当前商户下全部 MES 设备
|
||||
- 每条设备记录都带完整的设备分类信息
|
||||
|
||||
响应为分页结构，`results` 中每条为 `MesDevice`。
|
||||
|
||||
## MES 生产安排列表
|
||||
|
||||
- URL: `/api/v2/ai/mes/production-assignments/`
|
||||
- Method: `GET`
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `merchant_id` | int | 是 | 商户 ID |
|
||||
| `start_date` | date | 是 | 开始日期，格式 `YYYY-MM-DD` |
|
||||
| `end_date` | date | 是 | 结束日期，格式 `YYYY-MM-DD` |
|
||||
| `device_id` | int | 否 | 设备 ID，可选筛选 |
|
||||
| `status` | int | 否 | 生产安排状态，可选筛选 |
|
||||
| `limit` | int | 否 | 分页每页数量 |
|
||||
| `offset` | int | 否 | 分页偏移量 |
|
||||
|
||||
说明：
|
||||
|
||||
- 当前模型没有单独的“计划生产日期”字段
|
||||
- 因此该接口当前按 `created_at` 所在日期做范围过滤
|
||||
- 也就是“查询指定日期范围内创建的生产安排”
|
||||
- `device_id` 和 `status` 都是可选筛选条件
|
||||
|
||||
状态值：
|
||||
|
||||
| 值 | 显示值 |
|
||||
|------|------|
|
||||
| `1` | `Draft` |
|
||||
| `2` | `已发布` |
|
||||
| `3` | `已接收` |
|
||||
| `4` | `已取消` |
|
||||
| `5` | `已完工` |
|
||||
|
||||
响应为分页结构，`results` 中每条为 `MesProductionAssignment`。
|
||||
|
||||
Reference in New Issue
Block a user