واجهة التأكيدات الجديدة

من الحلقات اللانهائية إلى العافية الفورية: أُعيد بناء واجهة التأكيدات لتقديم إيجابية يومية مخصّصة دون أي عوائق. أصبح كل تأكيد الآن يأتي بمعرّف ثابت وبيانات نظيفة منسّقة ومخطط غني — إلى جانب البحث وترقيم الصفحات والنهايات المجمّعة واليومية، ومجموعة أدوات عافية متكاملة، واستجابات نصية عادية للرسائل النصية والمساعدات الصوتية.

🚀 ما الجديد

• معرّفات ثابتة – يحمل كل تأكيد id متسقًا قائمًا على التجزئة، لتبقى الودجات والإشعارات والذاكرات المؤقتة متزامنة.
• بيانات نظيفة تلقائيًا – تُنقّى حقول النص والفئة من المسافات الزائدة قبل وصولها إلى تطبيقك.
• فئات ذكية – تُشتق الفئات الـ 19 مباشرةً من مجموعة البيانات وتُرتَّب دون أي انحراف ناتج عن القيم المكتوبة يدويًا.
• أخطاء مفيدة – تُعيد الفئات غير المعروفة 404 واضحًا بدلًا من التعليق أو الدخول في حلقة.
• مخطط أغنى – يُعيد كل تأكيد id وtext وcategory وmood وlang وlength.
• اعثر على ما تحتاجه – بحث وترقيم صفحات في نهاية القائمة، إضافةً إلى نهاية مجمّعة قابلة للضبط.
• اختيارات يومية حتمية – تُعيد /today التأكيد نفسه ليوم معيّن لكل المستخدمين.
• مجموعة أدوات العافية – خصّص بالاسم، وأعد صياغة الأفكار السلبية، واقرن التأكيدات بتمارين التنفس.

🛠 نهايات الواجهة

1. قائمة التأكيدات

GET /v1/affirmations

المعاملات:

• category (اختياري): تصفية القائمة حسب الفئة، مثل confidence أو self-love.
• search (اختياري): بحث نصي كامل في نص التأكيد.
• page (الافتراضي: 1): رقم الصفحة لترقيم الصفحات.
• limit (الافتراضي: 10): عدد النتائج في الصفحة، بحد أقصى 50.
• lang (الافتراضي: en): رمز اللغة. يُعاد المحتوى الإنجليزي في هذا الإصدار.

2. تأكيد عشوائي

GET /v1/affirmations/random

المعاملات:

• category (اختياري): إعادة تأكيد عشوائي من فئة محددة.
• lang (الافتراضي: en): رمز اللغة. يُعاد المحتوى الإنجليزي في هذا الإصدار.
• format (الافتراضي: json): استخدم json للحصول على الكائن الكامل أو text للحصول على استجابة نصية عادية.

3. تأكيد عشوائي حسب الفئة

GET /v1/affirmations/categories/{category}/random

المعاملات:

• category (مطلوب): الفئة التي تُختار منها، مثل sleep. الفئات غير المعروفة تُعيد 404 واضحًا.

4. قائمة الفئات

GET /v1/affirmations/categories

يُعيد القائمة الكاملة المرتّبة للفئات — من anxiety-relief وcalm إلى confidence وfocus وgratitude وparenting وresilience وself-love وsleep وsuccess وغيرها.

5. تأكيدات مجمّعة

GET /v1/affirmations/batch

المعاملات:

• category (اختياري): تصفية المجموعة حسب الفئة.
• limit (الافتراضي: 10): عدد التأكيدات المُعادة، بحد أقصى 50.
• lang (الافتراضي: en): رمز اللغة. يُعاد المحتوى الإنجليزي في هذا الإصدار.

6. تأكيد اليوم

GET /v1/affirmations/today

المعاملات:

• category (اختياري): إعادة الاختيار اليومي الحتمي ضمن فئة معيّنة.
• lang (الافتراضي: en): رمز اللغة. يُعاد المحتوى الإنجليزي في هذا الإصدار.

يعيد الاسم البديل /daily تأكيد اليوم نفسه.

7. التخصيص

POST /v1/affirmations/personalize

النص:

• mood (اختياري): المزاج أو الفئة المستخدمة للاستقاء، مثل confidence. الافتراضي هو happiness.
• goal (اختياري): النية الكامنة وراء التأكيد.
• name (اختياري): اسم ليُدمج في التأكيد، على سبيل المثال “I am confident, Ava.”

8. إعادة صياغة فكرة سلبية

POST /v1/affirmations/reframe

النص:

• negativeThought (مطلوب): الفكرة المطلوب إعادة صياغتها، على سبيل المثال “I always fail”.

يُعيد عبارة معاد صياغتها إلى جانب تأكيد مرونة مطابق.

9. حزمة التأكيد + التنفس

GET /v1/affirmations/bundle

المعاملات:

• category (اختياري): الفئة المستخدمة للاستقاء. تُعيد فئة sleep تمرين التنفس 4-7-8؛ وتُعيد جميع الفئات الأخرى التنفس الصندوقي.

10. الجدول المقترح

GET /v1/affirmations/schedule

المعاملات:

• timezone (اختياري): وسم المنطقة الزمنية للفترات المقترحة، على سبيل المثال Europe/Berlin. الافتراضي هو UTC.

📦 أمثلة الاستجابات

تأكيد عشوائي:

{
  "id": 1874329517,
  "text": "I am confident, capable, and ready for today.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 42
}

تأكيد مخصّص:

{
  "id": 55123874,
  "text": "I am confident, Ava.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 20
}

فكرة معاد صياغتها:

{
  "reframe": "Even though \"I always fail\", I choose to believe: I am learning and growing every day.",
  "affirmation": {
    "id": 912345678,
    "text": "I am learning and growing every day.",
    "category": "resilience",
    "mood": "resilience",
    "lang": "en",
    "length": 36
  }
}

حزمة العافية:

{
  "affirmation": {
    "id": 44556677,
    "text": "I release the day and welcome rest.",
    "category": "sleep",
    "mood": "sleep",
    "lang": "en",
    "length": 36
  },
  "breathing": {
    "name": "4-7-8",
    "steps": ["Inhale 4s", "Hold 7s", "Exhale 8s"]
  }
}

الجدول المقترح:

{
  "morning": "08:00 Europe/Berlin",
  "evening": "21:00 Europe/Berlin",
  "timezone": "Europe/Berlin"
}

✨ استجابات متعددة الصيغ

تتحدث نهاية التأكيد العشوائي لغتي JSON والنص العادي. استخدم ?format=json (الافتراضي) للحصول على الكائن الكامل المنظّم في تطبيقات الويب والجوال، أو ?format=text للحصول على سلسلة جاهزة للإرسال في تدفقات الرسائل النصية والمساعدات الصوتية والودجات.

🎯 مصمّم لأجل

• المطوّرين الذين يبنون تطبيقات العافية وروبوتات المحادثة وميزات التحفيز ويبحثون عن واجهة مستقرة وموثّقة جيدًا.
• مديري المنتجات الذين يرفعون التفاعل عبر الإشعارات اليومية والتتابعات والمحتوى اليومي الحتمي.
• منشئي تطبيقات العافية الذين يحتاجون إلى محتوى تأكيدات موثوق ومصنّف على نطاق واسع.
• فرق المؤسسات التي تتوقّع نهايات قابلة للتوسّع بأسلوب حزم SDK مع تهيئة جاهزة عبر Postman.

🌟 لماذا تختار واجهة التأكيدات؟

• موثوقة بالتصميم: المعرّفات الثابتة والبيانات المنقّاة واستجابات 404 الواضحة تعني مفاجآت أقل في بيئة الإنتاج.
• عمق حين تحتاجه: 19 فئة تغطي كل شيء من تخفيف القلق إلى حب الذات.
• أكثر من مجرد استدعاء واحد: تخصيص وإعادة صياغة وحزم تنفس وجدولة في واجهة واحدة.
• صديقة للمطوّرين: بحث وترقيم صفحات وتجميع واستجابات متعددة الصيغ ومقتطفات جاهزة للاستخدام.
• جاهزة للعافية: وقت تشغيل بنسبة 99.99% مع استجابات منخفضة التأخير للحظات الإيجابية اليومية.

🚀 ابدأ الآن

• مجموعة Postman: استورد docs/affirmations-postman.json لاستكشاف كل نهاية بنقرة واحدة.
• مقتطفات الشيفرة: انسخ أمثلة جاهزة للتشغيل بلغات cURL و JavaScript و Python من docs/affirmations-snippets.md.
• جاهزة للنماذج اللغوية: يمنح docs/llms.txt وكلاء الذكاء الاصطناعي ملخصًا منظّمًا للواجهة.

ابدأ ببناء لحظات إيجابية اليوم — استدعِ نهاية today للحصول على تأكيد يومي حتمي، ثم أضف التخصيص وحزم التنفس لإكمال تجربة العافية.