From 341b54b18560dd86f58924bac789867d79c544fd Mon Sep 17 00:00:00 2001
From: RC-CHN <1051989940@qq.com>
Date: Thu, 8 Jan 2026 16:31:34 +0800
Subject: [PATCH] docs(api): add ModelMetricsMap type and improve breakdown
 field documentation

Extract ModelMetricsMap as a named type with documentation comments
explaining the map structure and providing examples. Update the
TrafficBucket.Breakdown field to use the new type and enhance the
GetTrafficChart endpoint description with detailed breakdown field
documentation including example usage.
---
 internal/api/log_handler.go | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/internal/api/log_handler.go b/internal/api/log_handler.go
index 6aec9d9..0c0a32a 100644
--- a/internal/api/log_handler.go
+++ b/internal/api/log_handler.go
@@ -616,13 +616,18 @@ type TrafficMetrics struct {
 	TokensOut int64 `json:"tokens_out"`
 }
 
+// ModelMetricsMap is a map from model name to TrafficMetrics.
+// Keys are model names (e.g. "gpt-4", "claude-3-opus") or "other" for aggregated remaining models.
+// Example: {"gpt-4": {"count": 10, "tokens_in": 1000, "tokens_out": 500}, "other": {"count": 3, "tokens_in": 200, "tokens_out": 100}}
+type ModelMetricsMap map[string]TrafficMetrics
+
 // TrafficBucket represents one time bucket with model breakdown
 type TrafficBucket struct {
 	Time      string `json:"time"`
 	Timestamp int64  `json:"timestamp"`
-	// Breakdown contains per-model metrics, keyed by model name (e.g. "gpt-4", "claude-3-opus", "other")
-	Breakdown map[string]TrafficMetrics `json:"breakdown" swaggertype:"object,object" example:"{\"gpt-4\":{\"count\":10,\"tokens_in\":1000,\"tokens_out\":500},\"claude-3-opus\":{\"count\":5,\"tokens_in\":800,\"tokens_out\":400},\"other\":{\"count\":3,\"tokens_in\":200,\"tokens_out\":100}}"`
-	Total     TrafficMetrics            `json:"total"`
+	// Breakdown is a map from model name (e.g. "gpt-4", "claude-3-opus", "other") to its metrics
+	Breakdown ModelMetricsMap `json:"breakdown"`
+	Total     TrafficMetrics  `json:"total"`
 }
 
 // TrafficChartResponse is the response for traffic chart API
@@ -641,7 +646,7 @@ const (
 
 // GetTrafficChart godoc
 // @Summary      Traffic chart data (admin)
-// @Description  Get time × model aggregated data for stacked traffic charts. Returns time buckets with per-model breakdown.
+// @Description  Get time × model aggregated data for stacked traffic charts. Returns time buckets with per-model breakdown. The 'breakdown' field in each bucket is a map where keys are model names (e.g. "gpt-4", "claude-3-opus") and values are TrafficMetrics objects. Models outside top_n are aggregated under the key "other". Example: {"gpt-4": {"count": 10, "tokens_in": 1000, "tokens_out": 500}, "other": {"count": 3, "tokens_in": 200, "tokens_out": 100}}
 // @Tags         admin
 // @Produce      json
 // @Security     AdminAuth