erpnew/docs/api_v2_agent_api.md

API v2 Agent 接口文档

本文档面向 AI Agent 及外部自动化调用方，描述 /api/v2/ai/ 前缀下的所有接口。

基本约定

• Base URL: /api/v2/ai
• 认证：所有接口使用固定 API Key，通过 Authorization 请求头直接传入（无 Bearer 前缀）
• 多商户隔离：每个接口均需传入 merchant_id 查询参数，后端以此确定数据范围

认证方式

# 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

---

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

• URL: /api/v2/ai/shipments/unshipped/
• Method: GET

查询参数

参数	类型	必填	说明
merchant_id	int	是	商户 ID
area	string	是	地区，精确匹配
limit	int	否	分页大小
offset	int	否	分页偏移

错误响应

401 Unauthorized

{
  "detail": "AGENT_ACCESS_KEY 无效"
}

400 Bad Request

{
  "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 的日期范围过滤生产安排
• 也就是说，它查的是“这个时间范围内创建的生产安排”

说明：

• material_capacities 表示该车辆对不同物料的最大装载量（单位：条）
• 只返回 merchant_id 对应商户的车辆
• VehicleType（旧版车辆类型字典）和 VehicleTransportRecord（旧版司机车次记录）是已废弃的模型，不在此接口返回

运输车辆详情

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

路径参数：

参数	说明
license_plate	车牌号码（URL 编码，如 粤A12345 → %E7%B2%A4A12345）

查询参数：

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

说明：

• 同一商户内 license_plate 唯一（数据库 unique_together: merchant + license_plate），因此 merchant_id + license_plate 可精确定位一辆车
• 不同商户可能存在相同车牌号，merchant_id 参数是必须的
• 车辆不存在时返回 404

成功响应：TransportVehicle

---

未出货出货单列表

• URL: /api/v2/ai/shipments/unshipped/
• Method: GET

查询参数：

参数	类型	必填	说明
merchant_id	int	是	商户 ID
area	string	是	地区筛选（精确匹配）
limit	int	否	分页每页数量
offset	int	否	分页偏移量

说明：

• "未出货"定义：delivery 为空，即尚未关联送货单
• delivery_id 始终返回送货单ID；未关联时为 null
• fabric 来自该出货单所关联销售品对应生产订单的 fabric；若当前出货单没有销售品则返回 null
• order_description 当前来自该出货单所关联销售品对应生产订单的 rolling_warn；若当前出货单没有销售品则返回 null
• 结果按 created_at 降序排列
• 只返回 merchant_id 对应商户的数据
• sales_items 包含该出货单的所有销售品（软删除的条目自动排除）
• sales_items[].printing_job_width：对应 PrintingJob → PrintingOrder.width；若无关联印染任务则为 null

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