5.8 KiB

Raw Permalink Blame History

📱 راهنمای API و مپینگ دیتا برای مودال‌های فلاتر (Source Details)

این مستند نحوه نمایش اطلاعات منبع در مودال‌های کلاینت فلاتر (Flutter) را مشخص می‌کند.

📌 قاعده کلی مودال‌ها

توجه: در مودال‌ها متن اصلی (Original Text) و ترجمه (Translation) قرار نمی‌گیرند (زیرا این دو مورد روی خود کارت در صفحه اصلی نمایش داده شده‌اند).
هدف اصلی این مودال‌ها نمایش اطلاعات و مستندات منبع (Source Details) است.

۱. تفکیک محتوای مودال‌ها بر اساس نوع ارگیومنت

نوع ارگیومنت (Source Type)	فیلدهای مورد نیاز در مودال	فیلدهای نادیده‌گرفته‌شده در مودال
`quote` (نقل‌قول / متن اصلی راوی)	آدرس‌ها (`address`) + عکس‌های کتاب (`images`)	فاقد لینک و متن تکراری
`fatwa` (فتوا)	آدرس‌ها (`address`) + لینک‌ها (`links`) + عکس‌های کتاب (`images`)	فاقد متن تکراری
`history` (تاریخ)	آدرس‌ها (`address`) + لینک‌ها (`links`) + عکس‌های کتاب (`images`)	فاقد متن تکراری
`interpretations` (تفاسیر)	آدرس‌ها (`address`) + لینک‌ها (`links`) + عکس‌های کتاب (`images`)	فاقد متن تکراری
`corrections` (تصحیحات)	آدرس‌ها (`address`) + لینک‌ها (`links`) + عکس‌های کتاب (`images`)	فاقد متن تکراری

۲. منابع دریافت دیتا (API Endpoints)

برای بهینه‌سازی و عدم بارگذاری سنگین در لیست‌ها، اندپوینت اختصاصی زیر ساخته شده تا هنگام باز شدن هر مودال، اطلاعات منبع (آدرس، لینک‌ها و تصاویر) را مستقیماً دریافت کنید:

اندپوینت: GET /api/hadis/<hadis_slug_or_id>/source-details/ (یا GET /api/hadis/<hadis_slug_or_id>/sources/)
ورودی: اسلاگ حدیث یا آی‌دی عددی آن.
خروجی: آبجکت کامل منبع شامل address (لیست رشته‌ها)، links (لیست لینک‌ها) و images (لیست تصاویر).

الف) تفاسیر و تصحیحات (Interpretations & Corrections):

حالت آفلاین (Sync):
- اندپوینت: GET /api/hadis/sync/hadis/
- تفاسیر: داخل آرایه interpretations هر آبجکت حدیث.
- تصحیحات: داخل آرایه corrections هر آبجکت حدیث.
حالت آنلاین:
- اندپوینت جزئیات تصحیح: GET /api/hadis/corrections/<correction_slug>/
- اندپوینت جزئیات تفسیر: GET /api/hadis/interpretations/<interpretation_slug>/

ب) متون اصلی راوی (Transmitter Original Texts / Quotes):

حالت آنلاین: GET /api/hadis/narrators/<narrator_slug>/original_texts/ یا GET /api/hadis/original-texts/<original_text_slug>/
حالت آفلاین (Sync): GET /api/hadis/sync/narrators/ $\rightarrow$ داخل آرایه original_texts هر آبجکت راوی.

ج) سایر ارگیومنت‌ها (فتاوا، تاریخ، نقل‌قول‌ها):

حالت آنلاین (درخواست مودال): GET /api/hadis/<hadis_slug_or_id>/source-details/
حالت آفلاین (Sync): GET /api/hadis/sync/hadis/ $\rightarrow$ فیلدهای detail.address، detail.links و detail.reference_images.

۳. جدول مپینگ فیلدها در UI مودال

فیلد در API	نوع داده	نحوه استفاده و رندر در مودال فلاتر
`title`	`String`	عنوان بالای مودال (مثلاً نام کتاب یا عنوان موضوع)
`address`	`List<String>` یا `String`	لیست خطوط آدرس، جلد، صفحه و چاپ منبع
`images`	`List<{ id, image, thumbnail }>`	گالری افقی بندانگشتی تصاویر نسخ خطی با قابلیت کلیک و نمایش تمام‌صفحه
`links`	`List<String>`	دکمه‌ها یا لیست لینک‌های وب‌سایت منبع (فقط در fatwa، history، interpretations و corrections)

📦 نمونه دیتای مپینگ برای فلاتر

۱. نمونه مودال برای `quote` (بدون لینک):

{
  "title": "رواية زرارة",
  "address": [
    "الکافی، ج ۱، ص ۲۵، طبع دارالحدیث",
    "التهذیب، ج ۲، ص ۱۰"
  ],
  "images": [
    {
      "id": 10,
      "image": "https://dovodi.newhorizonco.uk/media/hadis/book_references/kafi_p25.png",
      "thumbnail": "https://dovodi.newhorizonco.uk/media/hadis/book_references/kafi_p25.png"
    }
  ]
}

۲. نمونه مودال برای `fatwa` / `history` / `interpretations` / `corrections` (همراه با لینک):

{
  "title": "تفسیر آیه تطهیر",
  "address": [
    "التبیان فی تفسیر القرآن، ج ۲، ص ۴۵، طبع دار احیاء التراث العربی",
    "مجمع البیان، ج ۴، ص ۱۲"
  ],
  "links": [
    "https://shamela.ws/book/123/45",
    "https://lib.eshia.ir/12345/2/45"
  ],
  "images": [
    {
      "id": 25,
      "image": "https://dovodi.newhorizonco.uk/media/hadis/book_references/tibyan_p45.png",
      "thumbnail": "https://dovodi.newhorizonco.uk/media/hadis/book_references/tibyan_p45.png"
    }
  ]
}

5.8 KiB Raw Permalink Blame History