feat(ops): 运维监控新增 OpenAI Token 请求统计表

- 新增管理端接口 /api/v1/admin/ops/dashboard/openai-token-stats，按模型聚合统计 gpt% 请求 - 支持 time_range=30m|1h|1d|15d|30d（默认 30d），支持 platform/group_id 过滤 - 支持分页（page/page_size）或 TopN（top_n）互斥查询 - 前端运维监控页新增统计表卡片，包含空态/错误态与分页/TopN 交互 - 补齐后端与前端测试
2026-02-12 14:20:14 +08:00
parent ed2eba9028
commit 65661f24e2
15 changed files with 1335 additions and 0 deletions
--- a/backend/internal/handler/admin/admin_helpers_test.go
+++ b/backend/internal/handler/admin/admin_helpers_test.go
@@ -58,6 +58,96 @@ func TestParseOpsDuration(t *testing.T) {
 	require.False(t, ok)
 }

+func TestParseOpsOpenAITokenStatsDuration(t *testing.T) {
+	tests := []struct {
+		input string
+		want  time.Duration
+		ok    bool
+	}{
+		{input: "30m", want: 30 * time.Minute, ok: true},
+		{input: "1h", want: time.Hour, ok: true},
+		{input: "1d", want: 24 * time.Hour, ok: true},
+		{input: "15d", want: 15 * 24 * time.Hour, ok: true},
+		{input: "30d", want: 30 * 24 * time.Hour, ok: true},
+		{input: "7d", want: 0, ok: false},
+	}
+
+	for _, tt := range tests {
+		got, ok := parseOpsOpenAITokenStatsDuration(tt.input)
+		require.Equal(t, tt.ok, ok, "input=%s", tt.input)
+		require.Equal(t, tt.want, got, "input=%s", tt.input)
+	}
+}
+
+func TestParseOpsOpenAITokenStatsFilter_Defaults(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+
+	before := time.Now().UTC()
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	after := time.Now().UTC()
+
+	require.NoError(t, err)
+	require.NotNil(t, filter)
+	require.Equal(t, "30d", filter.TimeRange)
+	require.Equal(t, 1, filter.Page)
+	require.Equal(t, 20, filter.PageSize)
+	require.Equal(t, 0, filter.TopN)
+	require.Nil(t, filter.GroupID)
+	require.Equal(t, "", filter.Platform)
+	require.True(t, filter.StartTime.Before(filter.EndTime))
+	require.WithinDuration(t, before.Add(-30*24*time.Hour), filter.StartTime, 2*time.Second)
+	require.WithinDuration(t, after, filter.EndTime, 2*time.Second)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_WithTopN(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(
+		http.MethodGet,
+		"/?time_range=1h&platform=openai&group_id=12&top_n=50",
+		nil,
+	)
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	require.NoError(t, err)
+	require.Equal(t, "1h", filter.TimeRange)
+	require.Equal(t, "openai", filter.Platform)
+	require.NotNil(t, filter.GroupID)
+	require.Equal(t, int64(12), *filter.GroupID)
+	require.Equal(t, 50, filter.TopN)
+	require.Equal(t, 0, filter.Page)
+	require.Equal(t, 0, filter.PageSize)
+}
+
+func TestParseOpsOpenAITokenStatsFilter_InvalidParams(t *testing.T) {
+	tests := []string{
+		"/?time_range=7d",
+		"/?group_id=0",
+		"/?group_id=abc",
+		"/?top_n=0",
+		"/?top_n=101",
+		"/?top_n=10&page=1",
+		"/?top_n=10&page_size=20",
+		"/?page=0",
+		"/?page_size=0",
+		"/?page_size=101",
+	}
+
+	gin.SetMode(gin.TestMode)
+	for _, rawURL := range tests {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, rawURL, nil)
+
+		_, err := parseOpsOpenAITokenStatsFilter(c)
+		require.Error(t, err, "url=%s", rawURL)
+	}
+}
+
 func TestParseOpsTimeRange(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	w := httptest.NewRecorder()
--- a/backend/internal/handler/admin/ops_dashboard_handler.go
+++ b/backend/internal/handler/admin/ops_dashboard_handler.go
@@ -1,6 +1,7 @@
 package admin

 import (
+	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
@@ -218,6 +219,115 @@ func (h *OpsHandler) GetDashboardErrorDistribution(c *gin.Context) {
 	response.Success(c, data)
 }

+// GetDashboardOpenAITokenStats returns OpenAI token efficiency stats grouped by model.
+// GET /api/v1/admin/ops/dashboard/openai-token-stats
+func (h *OpsHandler) GetDashboardOpenAITokenStats(c *gin.Context) {
+	if h.opsService == nil {
+		response.Error(c, http.StatusServiceUnavailable, "Ops service not available")
+		return
+	}
+	if err := h.opsService.RequireMonitoringEnabled(c.Request.Context()); err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+
+	filter, err := parseOpsOpenAITokenStatsFilter(c)
+	if err != nil {
+		response.BadRequest(c, err.Error())
+		return
+	}
+
+	data, err := h.opsService.GetOpenAITokenStats(c.Request.Context(), filter)
+	if err != nil {
+		response.ErrorFrom(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func parseOpsOpenAITokenStatsFilter(c *gin.Context) (*service.OpsOpenAITokenStatsFilter, error) {
+	if c == nil {
+		return nil, fmt.Errorf("invalid request")
+	}
+
+	timeRange := strings.TrimSpace(c.Query("time_range"))
+	if timeRange == "" {
+		timeRange = "30d"
+	}
+	dur, ok := parseOpsOpenAITokenStatsDuration(timeRange)
+	if !ok {
+		return nil, fmt.Errorf("invalid time_range")
+	}
+	end := time.Now().UTC()
+	start := end.Add(-dur)
+
+	filter := &service.OpsOpenAITokenStatsFilter{
+		TimeRange: timeRange,
+		StartTime: start,
+		EndTime:   end,
+		Platform:  strings.TrimSpace(c.Query("platform")),
+	}
+
+	if v := strings.TrimSpace(c.Query("group_id")); v != "" {
+		id, err := strconv.ParseInt(v, 10, 64)
+		if err != nil || id <= 0 {
+			return nil, fmt.Errorf("invalid group_id")
+		}
+		filter.GroupID = &id
+	}
+
+	topNRaw := strings.TrimSpace(c.Query("top_n"))
+	pageRaw := strings.TrimSpace(c.Query("page"))
+	pageSizeRaw := strings.TrimSpace(c.Query("page_size"))
+	if topNRaw != "" && (pageRaw != "" || pageSizeRaw != "") {
+		return nil, fmt.Errorf("invalid query: top_n cannot be used with page/page_size")
+	}
+
+	if topNRaw != "" {
+		topN, err := strconv.Atoi(topNRaw)
+		if err != nil || topN < 1 || topN > 100 {
+			return nil, fmt.Errorf("invalid top_n")
+		}
+		filter.TopN = topN
+		return filter, nil
+	}
+
+	filter.Page = 1
+	filter.PageSize = 20
+	if pageRaw != "" {
+		page, err := strconv.Atoi(pageRaw)
+		if err != nil || page < 1 {
+			return nil, fmt.Errorf("invalid page")
+		}
+		filter.Page = page
+	}
+	if pageSizeRaw != "" {
+		pageSize, err := strconv.Atoi(pageSizeRaw)
+		if err != nil || pageSize < 1 || pageSize > 100 {
+			return nil, fmt.Errorf("invalid page_size")
+		}
+		filter.PageSize = pageSize
+	}
+	return filter, nil
+}
+
+func parseOpsOpenAITokenStatsDuration(v string) (time.Duration, bool) {
+	switch strings.TrimSpace(v) {
+	case "30m":
+		return 30 * time.Minute, true
+	case "1h":
+		return time.Hour, true
+	case "1d":
+		return 24 * time.Hour, true
+	case "15d":
+		return 15 * 24 * time.Hour, true
+	case "30d":
+		return 30 * 24 * time.Hour, true
+	default:
+		return 0, false
+	}
+}
+
 func pickThroughputBucketSeconds(window time.Duration) int {
 	// Keep buckets predictable and avoid huge responses.
 	switch {