feat: settlement lineup

docs/agent_api_settlement.md

@@ -0,0 +1,96 @@
+# 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 认证