feat: agent api

2026-04-14 18:05:56 +08:00
parent 0167478a25
commit 714d6287fe
6 changed files with 374 additions and 0 deletions
--- a/docs/api_v2_ai_api.md
+++ b/docs/api_v2_ai_api.md
@@ -0,0 +1,93 @@
+# 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)
+
+---
+
+## 查询未进入送货单的出货单
+
+- **URL**: `/api/v2/ai/shipments/unshipped/`
+- **Method**: `GET`
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `merchant_id` | int | 是 | 商户 ID |
+| `area` | string | 是 | 地区，精确匹配 |
+| `limit` | int | 否 | 分页大小 |
+| `offset` | int | 否 | 分页偏移 |
+
+### 业务定义
+
+这里的“未出货”定义为：
+
+- `Shipment.delivery_id is null`
+
+也就是该出货单尚未进入送货单。
+
+### 响应示例
+
+```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"
+    }
+  ]
+}
+```
+
+### 错误响应
+
+#### 401 Unauthorized
+
+```json
+{
+  "detail": "AGENT_ACCESS_KEY 无效"
+}
+```
+
+#### 400 Bad Request
+
+```json
+{
+  "merchant_id": ["This field is required."]
+}
+```