# 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 认证