Merge remote-tracking branch 'origin/main' into feature/openapi-docs

# Conflicts:
#	apps/api/internal/httpapi/handlers.go

apps/api/internal/httpapi/handlers.go

@@ -953,7 +953,7 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 					status := statusFromRunError(runErr)
 					errorPayload := map[string]any{
 						"code":    runErrorCode(runErr),
-						"message": runErr.Error(),
+						"message": runErrorMessage(runErr),
 						"status":  status,
 					}
 					if result.Task.ID != "" {
@@ -962,6 +962,9 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 					if result.Task.RequestID != "" {
 						errorPayload["requestId"] = result.Task.RequestID
 					}
+					for key, value := range runErrorDetails(runErr) {
+						errorPayload[key] = value
+					}
 					sendSSE(w, "error", map[string]any{"error": errorPayload})
 					if flusher != nil {
 						flusher.Flush()
@@ -982,7 +985,7 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 				if !requestStillConnected(r) {
 					return
 				}
-				writeError(w, statusFromRunError(runErr), runErr.Error(), runErrorCode(runErr))
+				writeErrorWithDetails(w, statusFromRunError(runErr), runErrorMessage(runErr), runErrorDetails(runErr), runErrorCode(runErr))
 				return
 			}
 			if !requestStillConnected(r) {
@@ -1098,6 +1101,138 @@ func runErrorCode(err error) string {
 	return clients.ErrorCode(err)
 }
 
+func runErrorMessage(err error) string {
+	if err == nil {
+		return ""
+	}
+	if summary := rateLimitErrorSummary(err); summary != "" {
+		return err.Error() + "；" + summary
+	}
+	return err.Error()
+}
+
+func runErrorDetails(err error) map[string]any {
+	if detail := rateLimitErrorDetail(err); len(detail) > 0 {
+		return map[string]any{"rateLimit": detail}
+	}
+	return nil
+}
+
+func rateLimitErrorSummary(err error) string {
+	var limitErr *store.RateLimitExceededError
+	if !errors.As(err, &limitErr) {
+		return ""
+	}
+	scopeLabel := "限流对象"
+	switch limitErr.ScopeType {
+	case "user_group":
+		scopeLabel = "用户组"
+	case "platform_model":
+		scopeLabel = "平台模型"
+	}
+	scopeName := strings.TrimSpace(limitErr.ScopeName)
+	if scopeName == "" {
+		scopeName = strings.TrimSpace(limitErr.ScopeKey)
+	}
+	if groupKey := stringValue(limitErr.ScopeMetadata["groupKey"]); limitErr.ScopeType == "user_group" && groupKey != "" && groupKey != scopeName {
+		scopeName = fmt.Sprintf("%s(%s)", scopeName, groupKey)
+	}
+	projected := limitErr.Projected
+	if projected <= 0 {
+		projected = limitErr.Current + limitErr.Amount
+	}
+	parts := []string{
+		fmt.Sprintf("限流摘要：%s %s 的 %s 超限", scopeLabel, scopeName, limitErr.Metric),
+		fmt.Sprintf("当前 %s，本次 %s，预计 %s，限制 %s", formatRateLimitValue(limitErr.Current), formatRateLimitValue(limitErr.Amount), formatRateLimitValue(projected), formatRateLimitValue(limitErr.Limit)),
+	}
+	if limitErr.WindowSeconds > 0 {
+		parts = append(parts, fmt.Sprintf("窗口 %d 秒", limitErr.WindowSeconds))
+	}
+	if limitErr.RetryAfter > 0 {
+		parts = append(parts, fmt.Sprintf("约%s后可重试", formatRateLimitDuration(limitErr.RetryAfter)))
+	} else if !limitErr.Retryable {
+		parts = append(parts, "该请求超过单次限额，不能排队重试")
+	}
+	return strings.Join(parts, "，")
+}
+
+func rateLimitErrorDetail(err error) map[string]any {
+	var limitErr *store.RateLimitExceededError
+	if !errors.As(err, &limitErr) {
+		return nil
+	}
+	detail := map[string]any{
+		"scopeType":     limitErr.ScopeType,
+		"scopeKey":      limitErr.ScopeKey,
+		"scopeName":     limitErr.ScopeName,
+		"metric":        limitErr.Metric,
+		"limit":         limitErr.Limit,
+		"amount":        limitErr.Amount,
+		"current":       limitErr.Current,
+		"used":          limitErr.Used,
+		"reserved":      limitErr.Reserved,
+		"projected":     limitErr.Projected,
+		"windowSeconds": limitErr.WindowSeconds,
+		"retryable":     limitErr.Retryable,
+		"exceeded": map[string]any{
+			"metric":    limitErr.Metric,
+			"current":   limitErr.Current,
+			"amount":    limitErr.Amount,
+			"projected": limitErr.Projected,
+			"limit":     limitErr.Limit,
+		},
+	}
+	if limitErr.RetryAfter > 0 {
+		detail["retryAfterMs"] = limitErr.RetryAfter.Milliseconds()
+	}
+	if !limitErr.ResetAt.IsZero() {
+		detail["resetAt"] = limitErr.ResetAt.UTC().Format(time.RFC3339Nano)
+	}
+	if len(limitErr.Policy) > 0 {
+		detail["rateLimitPolicy"] = limitErr.Policy
+		if matchedRule := matchedRateLimitRule(limitErr.Policy, limitErr.Metric); len(matchedRule) > 0 {
+			detail["matchedRule"] = matchedRule
+		}
+	}
+	if len(limitErr.ScopeMetadata) > 0 {
+		detail["scopeMetadata"] = limitErr.ScopeMetadata
+	}
+	if limitErr.ScopeType == "user_group" {
+		userGroup := map[string]any{
+			"id":   limitErr.ScopeKey,
+			"name": limitErr.ScopeName,
+		}
+		if groupKey := stringValue(limitErr.ScopeMetadata["groupKey"]); groupKey != "" {
+			userGroup["groupKey"] = groupKey
+		}
+		detail["userGroup"] = userGroup
+	}
+	return detail
+}
+
+func formatRateLimitValue(value float64) string {
+	return strconv.FormatFloat(value, 'f', -1, 64)
+}
+
+func formatRateLimitDuration(duration time.Duration) string {
+	if duration < time.Second {
+		return strconv.FormatInt(duration.Milliseconds(), 10) + "毫秒"
+	}
+	seconds := duration.Seconds()
+	return strconv.FormatFloat(seconds, 'f', -1, 64) + "秒"
+}
+
+func matchedRateLimitRule(policy map[string]any, metric string) map[string]any {
+	rules, _ := policy["rules"].([]any)
+	for _, rawRule := range rules {
+		rule, _ := rawRule.(map[string]any)
+		if stringValue(rule["metric"]) == metric {
+			return rule
+		}
+	}
+	return nil
+}
+
 // listTasks godoc
 // @Summary 列出任务
 // @Description 按当前用户列出任务，支持关键字、模型类型、时间范围和分页过滤。