feat(usage): 错误请求全面对齐用量明细(UI/列序/排序/筛选/列设置/新列)

管理端(/admin/usage)与用户端(/usage)错误请求 tab 对齐用量明细:
- 表格重写到 DataTable 底座,列序/徽章体系/骨架屏/移动端视图对齐
- 服务端排序(created_at/model/status_code 白名单,id tiebreak)
- 新增列:IP(含地区获取)、分组、类型、User-Agent;管理端另增分类列
- 筛选:/usage 收进顶部筛选卡按 tab 切换;管理端错误 tab 专属 phase/状态码筛选
- 列设置:两端错误 tab 独立列设置(localStorage 独立存储)
- 管理端用户邮箱可点击进余额弹窗;用户端白名单放行 group/type/UA(产品决策对齐用量明细口径)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DaydreamCoding

backend/internal/handler/admin/ops_handler.go

@@ -73,6 +73,14 @@ func NewOpsHandler(opsService *service.OpsService) *OpsHandler {
 }
 
 // GetErrorLogs lists ops error logs.
+// applyOpsErrorSortParams reads sort_by/sort_order query params into the filter.
+// Column whitelist and order normalization live in the repository; unknown
+// values degrade to the default (created_at DESC), mirroring the usage list.
+func applyOpsErrorSortParams(c *gin.Context, filter *service.OpsErrorLogFilter) {
+	filter.SortBy = strings.TrimSpace(c.Query("sort_by"))
+	filter.SortOrder = strings.TrimSpace(c.Query("sort_order"))
+}
+
 // GET /api/v1/admin/ops/errors
 func (h *OpsHandler) GetErrorLogs(c *gin.Context) {
 	if h.opsService == nil {
@@ -187,6 +195,8 @@ func (h *OpsHandler) GetErrorLogs(c *gin.Context) {
 		filter.StatusCodes = out
 	}
 
+	applyOpsErrorSortParams(c, filter)
+
 	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
 	if err != nil {
 		response.ErrorFrom(c, err)
@@ -291,6 +301,8 @@ func (h *OpsHandler) ListRequestErrors(c *gin.Context) {
 		filter.StatusCodes = out
 	}
 
+	applyOpsErrorSortParams(c, filter)
+
 	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
 	if err != nil {
 		response.ErrorFrom(c, err)
@@ -377,6 +389,8 @@ func (h *OpsHandler) ListRequestErrorUpstreamErrors(c *gin.Context) {
 		filter.ClientRequestID = clientRequestID
 	}
 
+	applyOpsErrorSortParams(c, filter)
+
 	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
 	if err != nil {
 		response.ErrorFrom(c, err)
@@ -497,6 +511,8 @@ func (h *OpsHandler) ListUpstreamErrors(c *gin.Context) {
 		filter.StatusCodes = out
 	}
 
+	applyOpsErrorSortParams(c, filter)
+
 	result, err := h.opsService.GetErrorLogs(c.Request.Context(), filter)
 	if err != nil {
 		response.ErrorFrom(c, err)

backend/internal/handler/usage_handler.go

@@ -322,6 +322,10 @@ func (h *UsageHandler) ListErrors(c *gin.Context) {
 		filter.ErrorTypesAny = types
 	}
 
+	// 排序对齐用量明细:列白名单与方向归一在 repo 层,非法值回退 created_at DESC。
+	filter.SortBy = strings.TrimSpace(c.Query("sort_by"))
+	filter.SortOrder = strings.TrimSpace(c.Query("sort_order"))
+
 	result, err := h.opsService.ListUserErrorRequests(c.Request.Context(), subject.UserID, filter)
 	if err != nil {
 		response.ErrorFrom(c, err)

backend/internal/repository/ops_repo.go

@@ -177,6 +177,34 @@ func opsInsertErrorLogArgs(input *service.OpsInsertErrorLogInput) []any {
 	}
 }
 
+// opsErrorLogsOrderBy builds the ORDER BY clause from a whitelist, mirroring
+// usageLogOrderBy semantics. Unknown SortBy falls back to created_at; e.id is
+// always appended as tiebreaker for stable pagination.
+func opsErrorLogsOrderBy(filter *service.OpsErrorLogFilter) string {
+	sortBy := ""
+	sortOrder := ""
+	if filter != nil {
+		sortBy = strings.ToLower(strings.TrimSpace(filter.SortBy))
+		sortOrder = strings.ToLower(strings.TrimSpace(filter.SortOrder))
+	}
+
+	var column string
+	switch sortBy {
+	case "model":
+		column = "COALESCE(NULLIF(TRIM(e.requested_model), ''), e.model)"
+	case "status_code":
+		column = "e.status_code"
+	default:
+		column = "e.created_at"
+	}
+
+	dir := "DESC"
+	if sortOrder == "asc" {
+		dir = "ASC"
+	}
+	return fmt.Sprintf("%s %s, e.id %s", column, dir, dir)
+}
+
 func (r *opsRepository) ListErrorLogs(ctx context.Context, filter *service.OpsErrorLogFilter) (*service.OpsErrorLogList, error) {
 	if r == nil || r.db == nil {
 		return nil, fmt.Errorf("nil ops repository")
@@ -233,13 +261,14 @@ SELECT
   COALESCE(a.name, ''),
   e.group_id,
   COALESCE(g.name, ''),
-  CASE WHEN e.client_ip IS NULL THEN NULL ELSE e.client_ip::text END,
+  CASE WHEN e.client_ip IS NULL THEN NULL ELSE host(e.client_ip) END,
   COALESCE(e.request_path, ''),
   e.stream,
   COALESCE(e.inbound_endpoint, ''),
   COALESCE(e.upstream_endpoint, ''),
   COALESCE(e.requested_model, ''),
   COALESCE(e.upstream_model, ''),
+  COALESCE(e.user_agent, ''),
   e.request_type,
   COALESCE(ak.name, ''),
   ak.deleted_at,
@@ -251,7 +280,7 @@ LEFT JOIN users u ON e.user_id = u.id
 LEFT JOIN users u2 ON e.resolved_by_user_id = u2.id
 LEFT JOIN api_keys ak ON ak.id = e.api_key_id
 ` + where + `
-ORDER BY e.created_at DESC
+ORDER BY ` + opsErrorLogsOrderBy(filter) + `
 LIMIT $` + itoa(len(args)+1) + ` OFFSET $` + itoa(len(args)+2)
 
 	rows, err := r.db.QueryContext(ctx, selectSQL, argsWithLimit...)
@@ -311,6 +340,7 @@ LIMIT $` + itoa(len(args)+1) + ` OFFSET $` + itoa(len(args)+2)
 			&item.UpstreamEndpoint,
 			&item.RequestedModel,
 			&item.UpstreamModel,
+			&item.UserAgent,
 			&requestType,
 			&apiKeyName,
 			&apiKeyDeletedAt,
@@ -417,7 +447,7 @@ SELECT
   COALESCE(a.name, ''),
   e.group_id,
   COALESCE(g.name, ''),
-  CASE WHEN e.client_ip IS NULL THEN NULL ELSE e.client_ip::text END,
+  CASE WHEN e.client_ip IS NULL THEN NULL ELSE host(e.client_ip) END,
   COALESCE(e.request_path, ''),
   e.stream,
   COALESCE(e.inbound_endpoint, ''),

backend/internal/service/ops_models.go

@@ -65,6 +65,7 @@ type OpsErrorLog struct {
 	RequestedModel   string `json:"requested_model"`
 	UpstreamModel    string `json:"upstream_model"`
 	RequestType      *int16 `json:"request_type"`
+	UserAgent        string `json:"user_agent"`
 
 	// 关联 api_key 名称（LEFT JOIN api_keys 取得；软删只覆盖 key 列，name 保留，故已删 key 仍有原名）。
 	APIKeyName    string `json:"api_key_name,omitempty"`
@@ -75,7 +76,6 @@ type OpsErrorLogDetail struct {
 	OpsErrorLog
 
 	ErrorBody string `json:"error_body"`
-	UserAgent string `json:"user_agent"`
 
 	// Upstream context (optional)
 	UpstreamStatusCode   *int   `json:"upstream_status_code,omitempty"`
@@ -158,6 +158,12 @@ type OpsErrorLogFilter struct {
 
 	Page     int
 	PageSize int
+
+	// SortBy/SortOrder: server-side sorting aligned with the usage-log list.
+	// Repo whitelists columns (created_at/model/status_code); anything else
+	// falls back to created_at. SortOrder is "asc"/"desc" (default desc).
+	SortBy    string
+	SortOrder string
 }
 
 type OpsErrorLogList struct {

backend/internal/service/ops_user_error.go

@@ -3,9 +3,12 @@ package service
 import "time"
 
 // UserErrorRequest 是面向终端用户的"错误请求"精简脱敏视图（白名单）。
-// 严禁包含 client_ip / user_agent / account / api_key_prefix / upstream_endpoint /
-// user_email 等敏感或内部字段。注：message（网关标准化错误描述）与 key_name
+// 严禁包含 account / api_key_prefix / upstream_endpoint / user_email 等
+// 敏感或内部字段。注：message（网关标准化错误描述）与 key_name
 // （用户自有 API Key 名称，KeysView 中本就可见）经产品决策对该用户开放；
+// client_ip / user_agent / group_name / request_type / stream 均为该用户
+// 自己请求的属性，经产品决策（2026-07-03）开放，
+// 与用量明细已向用户展示自身 ip_address/user_agent/分组/类型 的口径对齐；
 // error_body 仅在详情接口（GetUserErrorRequestDetail）按归属校验后返回。
 type UserErrorRequest struct {
 	ID              int64     `json:"id"`
@@ -18,6 +21,11 @@ type UserErrorRequest struct {
 	Message         string    `json:"message"`
 	KeyName         string    `json:"key_name"`
 	KeyDeleted      bool      `json:"key_deleted"`
+	ClientIP        string    `json:"client_ip,omitempty"`
+	GroupName       string    `json:"group_name,omitempty"`
+	RequestType     *int16    `json:"request_type,omitempty"`
+	Stream          bool      `json:"stream"`
+	UserAgent       string    `json:"user_agent,omitempty"`
 }
 
 // UserErrorRequestList 是用户错误请求分页结果。
@@ -90,6 +98,10 @@ func ToUserErrorRequest(e *OpsErrorLog) *UserErrorRequest {
 	if model == "" {
 		model = e.Model
 	}
+	clientIP := ""
+	if e.ClientIP != nil {
+		clientIP = *e.ClientIP
+	}
 	return &UserErrorRequest{
 		ID:              e.ID,
 		CreatedAt:       e.CreatedAt,
@@ -101,6 +113,11 @@ func ToUserErrorRequest(e *OpsErrorLog) *UserErrorRequest {
 		Message:         e.Message,
 		KeyName:         e.APIKeyName,
 		KeyDeleted:      e.APIKeyDeleted,
+		ClientIP:        clientIP,
+		GroupName:       e.GroupName,
+		RequestType:     e.RequestType,
+		Stream:          e.Stream,
+		UserAgent:       e.UserAgent,
 	}
 }
 

backend/internal/service/ops_user_error_test.go

@@ -122,9 +122,11 @@ func TestToUserErrorRequestDetail_WhitelistAndRedacts(t *testing.T) {
 			UserEmail:        "secret@example.com",
 			ClientIP:         func() *string { s := "1.2.3.4"; return &s }(),
 			UpstreamEndpoint: "https://api.openai.com/v1/chat/completions",
+			UserAgent:        "codex_cli_rs/0.125.0",
+			GroupName:        "grp-a",
+			Stream:           true,
 		},
 		ErrorBody:          `{"error":{"message":"upstream failed","type":"server_error"}}`,
-		UserAgent:          "Mozilla/5.0 secret-agent",
 		UpstreamStatusCode: &upstreamStatus,
 	}
 
@@ -147,13 +149,27 @@ func TestToUserErrorRequestDetail_WhitelistAndRedacts(t *testing.T) {
 		t.Errorf("UpstreamStatusCode mismatch")
 	}
 
+	// client_ip / user_agent / group_name / stream 经产品决策开放（与用量明细口径对齐）
+	if out.ClientIP != "1.2.3.4" {
+		t.Errorf("want client_ip=1.2.3.4, got %q", out.ClientIP)
+	}
+	if out.UserAgent != "codex_cli_rs/0.125.0" {
+		t.Errorf("want user_agent=codex_cli_rs/0.125.0, got %q", out.UserAgent)
+	}
+	if out.GroupName != "grp-a" {
+		t.Errorf("want group_name=grp-a, got %q", out.GroupName)
+	}
+	if !out.Stream {
+		t.Errorf("want stream=true")
+	}
+
 	// 序列化后不含敏感字段
 	b, err := json.Marshal(out)
 	if err != nil {
 		t.Fatalf("json.Marshal failed: %v", err)
 	}
 	raw := string(b)
-	for _, forbidden := range []string{"user_email", "client_ip", "upstream_endpoint", "user_agent"} {
+	for _, forbidden := range []string{"user_email", "upstream_endpoint"} {
 		if strings.Contains(raw, forbidden) {
 			t.Errorf("sensitive field %q leaked in JSON output: %s", forbidden, raw)
 		}

frontend/src/__tests__/setup.ts

@@ -57,6 +57,20 @@ if (typeof globalThis.cancelIdleCallback === 'undefined') {
   }) as unknown as typeof cancelIdleCallback
 }
 
+// Mock matchMedia (jsdom 未实现;DataTable 等组件依赖它做桌面/移动分支)
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+  window.matchMedia = ((query: string) => ({
+    matches: true, // 测试默认按桌面视口渲染表格
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })) as unknown as typeof window.matchMedia
+}
+
 // Mock IntersectionObserver
 class MockIntersectionObserver {
   observe = vi.fn()

frontend/src/api/admin/ops.ts

@@ -930,11 +930,11 @@ export interface OpsErrorLog {
   requested_model?: string
   upstream_model?: string
   request_type?: number | null
+  user_agent?: string
 }
 
 export interface OpsErrorDetail extends OpsErrorLog {
   error_body: string
-  user_agent: string
 
   // Upstream context (optional; enriched by gateway services)
   upstream_status_code?: number | null
@@ -1106,6 +1106,10 @@ export type OpsErrorListQueryParams = {
   q?: string
   status_codes?: string
   status_codes_other?: string
+
+  // 服务端排序,列白名单见后端 opsErrorLogsOrderBy(created_at/model/status_code)
+  sort_by?: string
+  sort_order?: 'asc' | 'desc'
 }
 
 // Legacy unified endpoints

frontend/src/api/admin/usage.ts

@@ -86,6 +86,9 @@ export interface AdminUsageQueryParams extends UsageQueryParams {
   billing_mode?: string
   sort_by?: string
   sort_order?: 'asc' | 'desc'
+  // 错误请求 tab 专属筛选(仅传给错误列表接口;共用同一 filters 对象)
+  error_phase?: string | null
+  status_code?: number | null
 }
 
 // ==================== API Functions ====================