forked from erp-dev/erp
97 lines
2.4 KiB
Markdown
97 lines
2.4 KiB
Markdown
# Agent API: 开版订单统计
|
||
|
||
## 概述
|
||
|
||
此 API 供 AI Agent 查询开版订单统计数据，按客户分组显示今日和本月订单数量。
|
||
|
||
## 认证
|
||
|
||
使用 `X-AGENT-SECRET` 请求头进行认证，无需 JWT Token。
|
||
|
||
## 端点
|
||
|
||
```
|
||
GET /api/v1/settlement/plate-orders/summary/
|
||
```
|
||
|
||
## 请求头
|
||
|
||
| Header | Value | Required |
|
||
|--------|-------|----------|
|
||
| X-AGENT-SECRET | RCYH_BOT_0083 | Yes |
|
||
|
||
## 查询参数
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| date | string | Yes | 统计日期，格式: YYYY-MM-DD |
|
||
|
||
## 响应格式
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"client_id": 1,
|
||
"client_name": "客户名称",
|
||
"plate_order_count": [
|
||
{
|
||
"type": "首版-匹布",
|
||
"today": 5,
|
||
"current_month": 120
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| client_id | integer | 客户ID |
|
||
| client_name | string | 客户名称 |
|
||
| plate_order_count | array | 订单统计数组 |
|
||
| plate_order_count[].type | string | 订单类型，格式: `{版型}-{做货方式}` |
|
||
| plate_order_count[].today | integer | 今日订单数 |
|
||
| plate_order_count[].current_month | integer | 本月累计订单数（从月初到查询日期） |
|
||
|
||
### 订单类型 (type) 可能值
|
||
|
||
- `首版-匹布`: 首版订单，匹布方式
|
||
- `首版-做货`: 首版订单，做货方式
|
||
- `复版-匹布`: 复版订单，匹布方式
|
||
- `复版-做货`: 复版订单，做货方式
|
||
- `修改单-匹布`: 修改订单，匹布方式
|
||
- `修改单-做货`: 修改订单，做货方式
|
||
|
||
## 错误响应
|
||
|
||
| Status | Response |
|
||
|--------|----------|
|
||
| 400 | `{"error": "缺少 date 参数"}` |
|
||
| 400 | `{"error": "日期格式错误，请使用 YYYY-MM-DD 格式"}` |
|
||
| 403 | `{"error": "日期不存在"}` |
|
||
| 401 | `{"detail": "身份认证信息未提供。"}` (secret 错误) |
|
||
|
||
## cURL 调用示例
|
||
|
||
```bash
|
||
curl -X GET \
|
||
-H "X-AGENT-SECRET: RCYH_BOT_0083" \
|
||
"http://localhost:8100/api/v1/settlement/plate-orders/summary/?date=2026-02-24"
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
1. **查询今日开版统计**: 使用当天日期
|
||
2. **查询历史日期统计**: 使用指定日期
|
||
3. **对比不同客户订单量**: 遍历 data 数组
|
||
|
||
## 注意事项
|
||
|
||
- 返回数据仅包含有订单的客户（today 或 current_month > 0）
|
||
- current_month 统计范围：月初第一天到查询日期
|
||
- 此 API 仅限 Agent 调用，普通用户需使用 JWT 认证
|