# API v2 MES 模块接口文档

本文档面向前端和业务评审，描述当前已经开放的 `MES` 公开接口，以及每个接口当前真实可用的字段。

## 基本约定

- Base URL: `/api/v2/mes`
- 认证：所有接口都需要登录。
- 人员身份：后端使用 `request.user.employee` 作为当前员工身份。
- 多商户隔离：所有接口只允许访问当前员工所属商户的数据。
- 创建审计：`created_by` 由当前登录用户自动写入。
- 操作审计：`operator` 由当前登录员工自动写入。
- `extra`：自由结构 JSON 字段，后端不解释业务内容。

## 枚举定义

### 产能单位 `capacity_unit`

| 值 | 显示值 |
|------|------|
| `1` | `米` |
| `2` | `码` |

### 生产指派状态 `status`

| 值 | 显示值 |
|------|------|
| `1` | `Draft` |
| `2` | `已发布` |
| `3` | `已接收` |
| `4` | `已取消` |
| `5` | `已完工` |

## 返回对象

### DeviceCategory 对象

```json
{
  "id": 1,
  "merchant": 10,
  "name": "打印机",
  "created_by": {
    "id": 5,
    "username": "admin"
  },
  "operator": {
    "id": 20,
    "name": "张三",
    "merchant_id": 10
  },
  "created_at": "2026-05-08T12:00:00+08:00",
  "updated_at": "2026-05-08T12:00:00+08:00"
}
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | integer | 主键 |
| `merchant` | integer | 所属商户 ID |
| `name` | string | 设备分类名称 |
| `created_by` | object | 创建用户信息，包含 `id`、`username` |
| `operator` | object | 操作员工信息，包含 `id`、`name`、`merchant_id` |
| `created_at` | datetime string | 创建时间 |
| `updated_at` | datetime string | 更新时间 |

### Device 对象

```json
{
  "id": 100,
  "merchant": 10,
  "category": 1,
  "category_name": "打印机",
  "name": "A-01",
  "peak_capacity": 120,
  "capacity_unit": 1,
  "capacity_unit_label": "米",
  "extra": {
    "capacity": {
      "per_hour": 120
    }
  },
  "created_by": {
    "id": 5,
    "username": "admin"
  },
  "operator": {
    "id": 20,
    "name": "张三",
    "merchant_id": 10
  },
  "created_at": "2026-05-08T12:00:00+08:00",
  "updated_at": "2026-05-08T12:00:00+08:00"
}
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | integer | 主键 |
| `merchant` | integer | 所属商户 ID |
| `category` | integer | 设备分类 ID |
| `category_name` | string | 设备分类名称 |
| `name` | string | 设备名称 |
| `peak_capacity` | integer | 峰值产能，必须大于 `0` |
| `capacity_unit` | integer | 产能单位枚举值 |
| `capacity_unit_label` | string | 产能单位显示值 |
| `extra` | object/null | 自由结构 JSON 扩展字段 |
| `created_by` | object | 创建用户信息，包含 `id`、`username` |
| `operator` | object | 操作员工信息，包含 `id`、`name`、`merchant_id` |
| `created_at` | datetime string | 创建时间 |
| `updated_at` | datetime string | 更新时间 |

### ProductionAssignment 对象

```json
{
  "id": 200,
  "merchant": 10,
  "device": 100,
  "device_name": "A-01",
  "content_type": 45,
  "object_id": 9001,
  "assigner": {
    "id": 20,
    "name": "张三",
    "merchant_id": 10
  },
  "assignee": {
    "id": 21,
    "name": "李四",
    "merchant_id": 10
  },
  "production_quantity": 300,
  "status": 1,
  "status_label": "Draft",
  "extra": {
    "batch": "A1"
  },
  "created_by": {
    "id": 5,
    "username": "admin"
  },
  "operator": {
    "id": 20,
    "name": "张三",
    "merchant_id": 10
  },
  "created_at": "2026-05-08T12:00:00+08:00",
  "updated_at": "2026-05-08T12:00:00+08:00"
}
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | integer | 主键 |
| `merchant` | integer | 所属商户 ID |
| `device` | integer | 设备 ID |
| `device_name` | string | 设备名称 |
| `content_type` | integer | 关联业务对象类型 ID |
| `object_id` | integer | 关联业务对象主键 |
| `assigner` | object | 指派者员工信息，包含 `id`、`name`、`merchant_id` |
| `assignee` | object/null | 被指派人员工信息，包含 `id`、`name`、`merchant_id`，可空 |
| `production_quantity` | integer | 生产数量，必须大于 `0`，单位跟随设备 `capacity_unit` |
| `status` | integer | 状态枚举值 |
| `status_label` | string | 状态显示值 |
| `extra` | object/null | 自由结构 JSON 扩展字段 |
| `created_by` | object | 创建用户信息，包含 `id`、`username` |
| `operator` | object | 操作员工信息，包含 `id`、`name`、`merchant_id` |
| `created_at` | datetime string | 创建时间 |
| `updated_at` | datetime string | 更新时间 |

## 设备分类接口

### 设备分类列表

- URL: `/api/v2/mes/device-categories/`
- Method: `GET`

查询参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 否 | 按名称模糊匹配 |

### 创建设备分类

- URL: `/api/v2/mes/device-categories/`
- Method: `POST`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 设备分类名称 |

### 设备分类详情

- URL: `/api/v2/mes/device-categories/{category_id}/`
- Method: `GET`

### 更新设备分类

- URL: `/api/v2/mes/device-categories/{category_id}/`
- Method: `PATCH`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 否 | 设备分类名称 |

### 删除设备分类

- URL: `/api/v2/mes/device-categories/{category_id}/`
- Method: `DELETE`

错误示例：

```json
{
  "detail": "设备分类已被设备引用，不能删除"
}
```

## 设备接口

### 设备列表

- URL: `/api/v2/mes/devices/`
- Method: `GET`

查询参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 否 | 按设备名称模糊匹配 |
| `category` | integer | 否 | 按设备分类 ID 过滤 |
| `extra_path` | string | 否 | `extra` 中的 JSON 路径，使用 `.` 分隔，例如 `capacity.per_hour` |
| `extra_value` | string | 否 | 与 `extra_path` 配套使用，支持 JSON 字面量字符串，例如 `120`、`"A1"`、`true` |

说明：

- `extra_path` 和 `extra_value` 必须同时传入。
- 当前仅支持精确匹配。
- 后端不解释 `extra` 的业务语义，只按路径和值匹配。

### 创建设备

- URL: `/api/v2/mes/devices/`
- Method: `POST`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 设备名称 |
| `category` | integer | 是 | 设备分类 ID |
| `peak_capacity` | integer | 是 | 峰值产能，必须大于 `0` |
| `capacity_unit` | integer | 否 | 产能单位，省略时默认 `1=米` |
| `extra` | object/null | 否 | 自由结构 JSON 扩展字段 |

### 设备详情

- URL: `/api/v2/mes/devices/{device_id}/`
- Method: `GET`

### 更新设备

- URL: `/api/v2/mes/devices/{device_id}/`
- Method: `PATCH`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 否 | 设备名称 |
| `category` | integer | 否 | 设备分类 ID |
| `peak_capacity` | integer | 否 | 峰值产能，必须大于 `0` |
| `capacity_unit` | integer | 否 | 产能单位 |
| `extra` | object/null | 否 | 传 `null` 可清空扩展字段 |

补充说明：

- 模型层历史迁移曾使用一次性兼容默认值处理旧数据，但前端不应依赖省略 `peak_capacity` 让系统自动补值。

### 删除设备

- URL: `/api/v2/mes/devices/{device_id}/`
- Method: `DELETE`

- 成功返回 `204 No Content`

## 生产指派接口

### 生产指派列表

- URL: `/api/v2/mes/production-assignments/`
- Method: `GET`

查询参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `device` | integer | 否 | 按设备 ID 过滤 |
| `content_type` | integer | 否 | 按关联对象类型 ID 过滤 |
| `object_id` | integer | 否 | 按关联对象 ID 过滤 |
| `status` | integer | 否 | 按状态过滤 |

### 创建生产指派

- URL: `/api/v2/mes/production-assignments/`
- Method: `POST`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `device` | integer | 是 | 设备 ID |
| `content_type` | integer | 是 | 关联业务对象类型 ID |
| `object_id` | integer | 是 | 关联业务对象主键 |
| `assigner` | integer | 是 | 指派者员工 ID |
| `assignee` | integer/null | 否 | 被指派人员工 ID，可空 |
| `production_quantity` | integer | 是 | 生产数量，必须大于 `0` |
| `status` | integer | 否 | 状态，省略时默认 `1=Draft` |
| `extra` | object/null | 否 | 自由结构 JSON 扩展字段 |

说明：

- `device`、`assigner`、`assignee` 必须属于当前商户。
- `production_quantity` 单位跟随设备 `capacity_unit`。

### 生产指派详情

- URL: `/api/v2/mes/production-assignments/{assignment_id}/`
- Method: `GET`

### 更新生产指派

- URL: `/api/v2/mes/production-assignments/{assignment_id}/`
- Method: `PATCH`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `device` | integer | 否 | 设备 ID |
| `assignee` | integer/null | 否 | 被指派人员工 ID，可空 |
| `production_quantity` | integer | 否 | 生产数量，必须大于 `0` |
| `status` | integer | 否 | 目标状态 |
| `extra` | object/null | 否 | 扩展字段，传 `null` 可清空 |

状态流转说明：

- 主流程：`Draft -> 已发布 -> 已接收 -> 已完工`
- `Draft` 可以改为 `已取消`
- `已发布` 可以改为 `已取消`
- `已接收` 和 `已完工` 不能改为 `已取消`
- `已取消` 和 `已完工` 视为终态，不能回退

错误示例：

```json
{
  "detail": "当前状态不允许变更为目标状态"
}
```

### 删除生产指派

- URL: `/api/v2/mes/production-assignments/{assignment_id}/`
- Method: `DELETE`