# API v2 Agent 接口

本文档描述 `api/v2/ai/...` 下供内部 agent 调用的简化鉴权接口。

## 鉴权方式

- 使用请求头 `Authorization`
- 直接传入固定密钥
- 不使用 `Bearer` 前缀

示例：

```bash
curl -X GET \
  'https://api.example.com/api/v2/ai/shipments/unshipped/?merchant_id=1&area=华东' \
  -H 'Authorization: your-agent-access-key'
```

配置项：

- [`AGENT_ACCESS_KEY`](/home/f/coding/flower/flower/settings.py)

---

## 查询未进入送货单的出货单

# 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 |
| `limit` | int | 否 | 分页每页数量 |
| `offset` | int | 否 | 分页偏移量 |

说明：

- `material_capacities` 表示该车辆对不同物料的最大装载量
- 只返回 `merchant_id` 对应商户的车辆

响应为分页结构，`results` 中每条为 `TransportVehicle`。

## 运输车辆详情

- URL: `/api/v2/ai/transport-vehicles/<license_plate>/`
- Method: `GET`

路径参数：

| 参数 | 说明 |
|------|------|
| `license_plate` | 车牌号码 |

查询参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `merchant_id` | int | 是 | 商户 ID |

说明：

- 同一商户内 `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`。