# 📱 راهنمای 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)

#### 🚀 اندپوینت سبک و اختصاصی باز کردن مودال (On-Demand Modal API):
برای بهینه‌سازی و عدم بارگذاری سنگین در لیست‌ها، اندپوینت اختصاصی زیر ساخته شده تا هنگام باز شدن هر مودال، اطلاعات منبع (آدرس، لینک‌ها و تصاویر) را مستقیماً دریافت کنید:
* **اندپوینت:** `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` (بدون لینک):
```json
{
  "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` (همراه با لینک):
```json
{
  "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"
    }
  ]
}
```