# المهام غير المتزامنة

أرسل مهامًا طويلة التشغيل، واستعلم عن حالة المهمة، وتعامل مع الحالات النهائية، واسترجع النتائج.

تعيد بعض عمليات Felo `task_id` فورًا وتنتهي في الخلفية. النمط هو نفسه في كل مكان: أرسل، ثم استطلع، ثم استرجع النتيجة.

## عائلتا المهام

| العائلة | الإرسال | الاستطلاع |
|--------|--------|------|
| مسارات عمل Felo | `POST /v2/ppts` و`POST /v2/landing_page` و`POST /v2/mindmap` | `GET /v2/tasks/{task_id}/status` |
| توليد النماذج | `POST /api/v1/videos/generations` و`POST /api/v1/images/generations` | `GET /api/v1/videos/generations/{task_id}` و`GET /api/v1/images/generations/{task_id}` |

تصدير PPTX عملية غير متزامنة منفصلة: `POST /v2/ppts/{ppt_business_id}/export`، ثم `GET /v2/ppts/{ppt_business_id}/export`.

SuperAgent ليس API استطلاع. يعيد `stream_key` ويستخدم SSE؛ راجع [مرجع SuperAgent](https://openapi.felo.ai/ar/docs/api-reference/superagent.md).

## دورة الحياة

1. **الإرسال.** أرسل معاملات النموذج أو سير العمل. يعيد الإرسال الناجح `task_id` وحالة أولية.
2. **الاستطلاع.** اقرأ endpoint المهمة على فترات. أبقِ الفاصل الزمني وأقصى وقت انتظار في شيفرتك.
3. **الإنهاء.** عند النجاح، اقرأ عناوين URL للنتيجة أو حقول المخرجات. وعند الفشل، اقرأ الخطأ وقرر ما إذا كنت ستعيد الإرسال.

## قيم الحالة

تستخدم مهام سير عمل Felo قيمًا بأحرف كبيرة:

| الحالة | المعنى |
|--------|---------|
| `RUNNING` | قيد المعالجة |
| `COMPLETED` | اكتملت بنجاح |
| `FAILED` | فشل نهائي؛ اقرأ `error_message` |
| `PENDING` | نهائية في الاستجابة التاريخية؛ اقرأ `error_message` |
| `EXPIRED` | نهائية؛ المهمة لم تعد متاحة |
| `CANCELED` | نهائية؛ أُلغيت المهمة |

تستخدم مهام توليد النماذج قيمًا بأحرف صغيرة: `queued` و`running` و`succeeded` و`failed` و`interrupted`. وقد تتضمن المهمة الفاشلة كائن `error` فيه `message` و`type`.

قد تظهر قيم حالة غير معروفة مع تطور الواجهة الخلفية. تعامل مع القيمة غير المعروفة على أنها غير نهائية ما لم يذكر التوثيق خلاف ذلك.

## الاستطلاع

- مهام سير عمل Felo: استطلع كل 2–5 ثوانٍ.
- توليد الفيديو: استطلع كل 5–10 ثوانٍ.
- توليد الصور: ابدأ بـ2–5 ثوانٍ وتراجع تدريجيًا للمهام الطويلة.
- توقف عند حالة نهائية، أو عند مهلة تختارها، أو بعد حد أقصى لعدد المحاولات.
- أضف تشويشًا عشوائيًا عندما يستطلع عملاء كثيرون في الوقت نفسه.

حلقة Node.js بسيطة:

```javascript
async function pollStatus(taskId, { timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await fetch(`https://openapi.felo.ai/v2/tasks/${taskId}/status`, {
      headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}` },
    });
    if (!response.ok) throw new Error(`status ${response.status}`);
    const payload = await response.json();
    const status = payload.data?.status;
    if (status === "COMPLETED") return payload.data;
    if (["FAILED", "PENDING", "EXPIRED", "CANCELED"].includes(status)) {
      throw new Error(payload.data?.error_message || status);
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  throw new Error("task timed out");
}
```

## استرداد النتائج

| المهمة | النتيجة |
|------|--------|
| PPT | يعيد `GET /v2/tasks/{task_id}/historical` القيم `ppt_url` و`ppt_biz_id` و`live_doc_url` عند توفرها |
| صفحة الهبوط | تعيد الاستجابة التاريخية مخرجات الصفحة و`live_doc_url` عند توفرهما |
| فيديو / صورة | تعيد استجابة الاستطلاع `outputs`؛ وعند النجاح تكون الإدخالات عناوين URL وسائط موقّعة يمكن تنزيلها دون مصادقة. راجع [توليد الصور](https://openapi.felo.ai/ar/docs/guides/image-generation.md) لتفاصيل الانتهاء والتنزيل |
| تصدير PPTX | تعيد استجابة الاستطلاع `download_url` و`expires_at` فقط عندما تكون `status` هي `COMPLETED` |

تنتهي صلاحية عنوان URL الموقّع لتنزيل PPTX بعد 30 دقيقة من إصداره. استدعِ endpoint GET مجددًا للحصول على عنوان جديد؛ وهذا لا يعيد توليد الملف.

## معالجة الفشل

- اقرأ حقل خطأ المهمة قبل إعادة المحاولة. بعض حالات الفشل يسببها الطلب وستتكرر.
- لا تعد الإرسال عشوائيًا عند كل مهلة؛ تحقق أولًا مما إذا كانت المهمة لا تزال `RUNNING`.
- تعني `402` أرصدة غير كافية. وتعني `429` حد معدل. أعد المحاولة فقط بعد حل الحالة.
- يرفض توليد الفيديو حقول رد الاتصال برمز `400`، بينما يتجاهلها توليد الصور. استطلع endpoint المهمة بدلًا من انتظار webhook.

## ذو صلة

- [PPT Task API](https://openapi.felo.ai/ar/docs/api-reference/ppt-tasks.md)
- [Landing Page Task API](https://openapi.felo.ai/ar/docs/api-reference/landing-page.md)
- [مرجع Model API](https://openapi.felo.ai/ar/docs/model-api)
- [توليد الصور](https://openapi.felo.ai/ar/docs/guides/image-generation.md)
- [الأخطاء والحدود وإعادة المحاولة](https://openapi.felo.ai/ar/docs/guides/errors-and-limits.md)
