أعد هيكلة منطق استطلاع المهام للتعامل مع حمولات الأخطاء المنظمة وتحسين رسائل الخطأ

frontend/src/hooks/useTaskPolling.test.ts

@@ -3,9 +3,13 @@ import { renderHook, act } from '@testing-library/react';
 import { useTaskPolling } from './useTaskPolling';
 
 // ── mock the api module ────────────────────────────────────────────────────
-vi.mock('@/services/api', () => ({
-  getTaskStatus: vi.fn(),
-}));
+vi.mock('@/services/api', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/services/api')>();
+  return {
+    ...actual,
+    getTaskStatus: vi.fn(),
+  };
+});
 
 import { getTaskStatus } from '@/services/api';
 const mockGetStatus = vi.mocked(getTaskStatus);
@@ -122,6 +126,33 @@ describe('useTaskPolling', () => {
     expect(onError).toHaveBeenCalledWith('Ghostscript not found.');
   });
 
+  it('prefers a structured task error payload when SUCCESS contains a failed result', async () => {
+    mockGetStatus.mockResolvedValueOnce({
+      task_id: 'task-4b',
+      state: 'SUCCESS',
+      error: {
+        error_code: 'OPENROUTER_MISSING_API_KEY',
+        user_message: 'AI features are temporarily unavailable. Our team has been notified.',
+        task_id: 'task-4b',
+      },
+      result: { status: 'failed' },
+    });
+
+    const onError = vi.fn();
+    const { result } = renderHook(() =>
+      useTaskPolling({ taskId: 'task-4b', intervalMs: 500, onError })
+    );
+
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    expect(result.current.isPolling).toBe(false);
+    expect(result.current.result).toBeNull();
+    expect(result.current.error).toBe('AI features are temporarily unavailable. Our team has been notified.');
+    expect(onError).toHaveBeenCalledWith('AI features are temporarily unavailable. Our team has been notified.');
+  });
+
   // ── FAILURE state ──────────────────────────────────────────────────────
   it('stops polling and sets error on FAILURE state', async () => {
     mockGetStatus.mockResolvedValueOnce({
@@ -144,6 +175,31 @@ describe('useTaskPolling', () => {
     expect(onError).toHaveBeenCalledWith('Worker crashed.');
   });
 
+  it('normalizes a structured FAILURE payload into a safe string message', async () => {
+    mockGetStatus.mockResolvedValueOnce({
+      task_id: 'task-5b',
+      state: 'FAILURE',
+      error: {
+        error_code: 'TASK_FAILURE',
+        user_message: 'Task processing failed. Please retry.',
+        task_id: 'task-5b',
+      },
+    });
+
+    const onError = vi.fn();
+    const { result } = renderHook(() =>
+      useTaskPolling({ taskId: 'task-5b', intervalMs: 500, onError })
+    );
+
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    expect(result.current.isPolling).toBe(false);
+    expect(result.current.error).toBe('Task processing failed. Please retry.');
+    expect(onError).toHaveBeenCalledWith('Task processing failed. Please retry.');
+  });
+
   // ── network error ──────────────────────────────────────────────────────
   it('stops polling and sets error on network/API exception', async () => {
     mockGetStatus.mockRejectedValueOnce(new Error('Network error.'));

frontend/src/hooks/useTaskPolling.ts

@@ -1,7 +1,12 @@
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { toast } from 'sonner';
 import i18n from '@/i18n';
-import { getTaskStatus, type TaskStatus, type TaskResult } from '@/services/api';
+import {
+  getTaskStatus,
+  getTaskErrorMessage,
+  type TaskStatus,
+  type TaskResult,
+} from '@/services/api';
 import { trackEvent } from '@/services/analytics';
 
 interface UseTaskPollingOptions {
@@ -54,6 +59,7 @@ export function useTaskPolling({
         if (taskStatus.state === 'SUCCESS') {
           stopPolling();
           const taskResult = taskStatus.result;
+          const fallbackError = i18n.t('common.errors.processingFailed');
 
           if (taskResult?.status === 'completed') {
             setResult(taskResult);
@@ -63,7 +69,10 @@ export function useTaskPolling({
             trackEvent('task_completed', { task_id: taskId });
             onComplete?.(taskResult);
           } else {
-            const errMsg = taskResult?.error || i18n.t('common.errors.processingFailed');
+            const errMsg = getTaskErrorMessage(
+              taskStatus.error ?? taskResult?.user_message ?? taskResult?.error,
+              fallbackError
+            );
             setError(errMsg);
             toast.error(errMsg);
             trackEvent('task_failed', { task_id: taskId, reason: 'result_failed' });
@@ -71,7 +80,10 @@ export function useTaskPolling({
           }
         } else if (taskStatus.state === 'FAILURE') {
           stopPolling();
-          const errMsg = taskStatus.error || i18n.t('common.errors.processingFailed');
+          const errMsg = getTaskErrorMessage(
+            taskStatus.error,
+            i18n.t('common.errors.processingFailed')
+          );
           setError(errMsg);
           toast.error(errMsg);
           trackEvent('task_failed', { task_id: taskId, reason: 'state_failure' });

frontend/src/services/api.ts

@@ -187,12 +187,22 @@ export interface TaskResponse {
   message: string;
 }
 
+export interface TaskErrorPayload {
+  error_code?: string;
+  user_message?: string;
+  task_id?: string;
+  trace_id?: string;
+  message?: string;
+  error?: string;
+  detail?: string;
+}
+
 export interface TaskStatus {
   task_id: string;
   state: 'PENDING' | 'PROCESSING' | 'SUCCESS' | 'FAILURE';
   progress?: string;
   result?: TaskResult;
-  error?: string;
+  error?: string | TaskErrorPayload;
 }
 
 export interface TaskResult {
@@ -200,6 +210,10 @@ export interface TaskResult {
   download_url?: string;
   filename?: string;
   error?: string;
+  error_code?: string;
+  user_message?: string;
+  task_id?: string;
+  trace_id?: string;
   original_size?: number;
   compressed_size?: number;
   reduction_percent?: number;
@@ -229,6 +243,33 @@ export interface TaskResult {
   tables_found?: number;
 }
 
+function isTaskErrorPayload(value: unknown): value is TaskErrorPayload {
+  return Boolean(value) && typeof value === 'object';
+}
+
+export function getTaskErrorMessage(error: unknown, fallback: string): string {
+  if (typeof error === 'string' && error.trim()) {
+    return error.trim();
+  }
+
+  if (isTaskErrorPayload(error)) {
+    const candidates = [
+      error.user_message,
+      error.message,
+      error.error,
+      error.detail,
+    ];
+
+    for (const candidate of candidates) {
+      if (typeof candidate === 'string' && candidate.trim()) {
+        return candidate.trim();
+      }
+    }
+  }
+
+  return fallback;
+}
+
 export interface AuthUser {
   id: number;
   email: string;