From dab07caca2a7f311a216090b073db081fbb98cce Mon Sep 17 00:00:00 2001
From: zenfun <zenfun510@gmail.com>
Date: Wed, 31 Dec 2025 14:25:55 +0800
Subject: [PATCH] docs(api): add apikey-stats time range and internal alerts
 report endpoints

Document two new API endpoints:
- GET /admin/apikey-stats/summary with optional since/until params
  for querying statistics within a specific time range
- POST /internal/alerts/report for Data Plane to report alerts
  with fingerprint-based deduplication mechanism
---
 docs/api.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index 9e4e834..c758cfe 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -456,6 +456,72 @@ curl http://localhost:8080/admin/alerts/stats \
 }
 ```
 
+### 6.4 APIKey 成功率统计时间范围
+
+`GET /admin/apikey-stats/summary?since=<unix>&until=<unix>`
+
+**新增时间范围参数**：可选的 `since` 和 `until` 参数，用于获取特定时间段内的上游凭证统计。
+
+```bash
+# 获取今天的统计
+curl "http://localhost:8080/admin/apikey-stats/summary?since=1704067200&until=1704153600" \
+  -H "Authorization: Bearer <admin_token>"
+
+# 获取全量统计（不传时间参数）
+curl "http://localhost:8080/admin/apikey-stats/summary" \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+**响应示例**：
+```json
+{
+  "total_requests": 50000,
+  "success_requests": 48000,
+  "failure_requests": 2000,
+  "success_rate": 0.96,
+  "failure_rate": 0.04
+}
+```
+
+### 6.5 DP 告警上报 (内部接口)
+
+`POST /internal/alerts/report`
+
+**内部端点**：供 Data Plane 上报异常事件给 Control Plane，需要 `X-Internal-Token` 认证。
+
+**去重机制**：
+- 每个告警可携带 `fingerprint` 字段（如 `rate_limit:master:5`）
+- 若 5 分钟内存在相同 fingerprint 的活跃告警，新告警将被去重
+
+```bash
+curl -X POST http://localhost:8080/internal/alerts/report \
+  -H "X-Internal-Token: <internal_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "alerts": [
+      {
+        "type": "rate_limit",
+        "severity": "warning",
+        "title": "速率限制触发",
+        "message": "Master production 在1分钟内触发50次限流",
+        "related_id": 5,
+        "related_type": "master",
+        "related_name": "production",
+        "fingerprint": "rate_limit:master:5"
+      }
+    ]
+  }'
+```
+
+**响应示例**：
+```json
+{
+  "accepted": 1,
+  "deduplicated": 0,
+  "errors": []
+}
+```
+
 ---
 
 ## 7. 备注