feat: mes module

2026-05-11 21:37:41 +08:00
parent d7b388e935
commit 9359013b4c
20 changed files with 3232 additions and 133 deletions
--- a/docs/api_v2_agent_api.md
+++ b/docs/api_v2_agent_api.md
@@ -11,99 +11,103 @@
 ### 认证方式

 ```
-Authorization: <AGENT_ACCESS_KEY>
+# API v2 Agent 接口
+
+本文档描述 `api/v2/ai/...` 下供内部 agent 调用的简化鉴权接口。
+
+## 鉴权方式
+
+- 使用请求头 `Authorization`
+- 直接传入固定密钥
+- 不使用 `Bearer` 前缀
+
+示例：
+
+```bash
+curl -X GET \
+  'https://api.example.com/api/v2/ai/mes/devices/?merchant_id=1' \
+  -H 'Authorization: your-agent-access-key'
 ```

-`AGENT_ACCESS_KEY` 由后端部署时通过同名环境变量配置。未配置时所有请求均返回 `401`。
+配置项：
+
+- [`AGENT_ACCESS_KEY`](/home/f/coding/flower/flower/settings.py)

 ---

-## 数据结构
+## 查询未进入送货单的出货单

-### TransportVehicle
+- **URL**: `/api/v2/ai/shipments/unshipped/`
+- **Method**: `GET`

-```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"
-    },
-    {
-      "id": 202,
-      "name": "销售品乙",
-      "quantity": "10.00",
-      "unit": 1,
-      "unit_display": "件",
-      "position": "",
-      "remark": "",
-      "printing_job_id": null,
-      "printing_job_width": null
-    }
-  ],
-  "created_at": "2026-04-14T10:00:00+08:00",
-  "updated_at": "2026-04-14T10:00:00+08:00"
-}
-```
-
---
-
-## 运输车辆列表
-
- URL: `/api/v2/ai/transport-vehicles/`
- Method: `GET`
-
-查询参数：
+### 查询参数

 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `merchant_id` | int | 是 | 商户 ID |
-| `limit` | int | 否 | 分页每页数量（默认由服务端决定） |
-| `offset` | int | 否 | 分页偏移量 |
+| `area` | string | 是 | 地区，精确匹配 |
+| `limit` | int | 否 | 分页大小 |
+| `offset` | int | 否 | 分页偏移 |

-响应为分页结构，`results` 中每条为 `TransportVehicle`，包含该车辆的所有物料容量。
+### 错误响应
+
+#### 401 Unauthorized
+
+```json
+{
+  "detail": "AGENT_ACCESS_KEY 无效"
+}
+```
+
+#### 400 Bad Request
+
+```json
+{
+  "merchant_id": ["This field is required."]
+}
+```
+
+## 查询 MES 设备列表
+
+- **URL**: `/api/v2/ai/mes/devices/`
+- **Method**: `GET`
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `merchant_id` | int | 是 | 商户 ID |
+| `limit` | int | 否 | 分页大小 |
+| `offset` | int | 否 | 分页偏移 |
+
+### 说明
+
+- 返回当前商户下全部 MES 设备
+- 每条记录包含所属设备分类信息
+- 使用与其他 agent 接口相同的固定密钥鉴权方式，不走 JWT
+
+## 查询指定日期范围内的 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 | 否 | 分页偏移 |
+
+### 当前实现说明
+
+- 当前 MES 模型没有单独的排产日期字段
+- 所以本接口当前是按 `created_at` 的日期范围过滤生产安排
+- 也就是说，它查的是“这个时间范围内创建的生产安排”

 说明：