# Section Types

## قواعد مشترک

```json
{
  "id": "home-section-id",
  "type": "registered_section_type",
  "data": {}
}
```

| فیلد | قانون |
| --- | --- |
| `id` | یکتا، حداکثر ۱۰۰ کاراکتر، الگوی `^[a-z0-9][a-z0-9-]{0,99}$` |
| `type` | یکی از typeهای ثبت‌شده |
| `data` | object strict مخصوص همان type |
| تعداد سکشن‌ها | حداکثر ۳۰ |

فیلد ناشناخته باید با `422` رد شود.

## اشیای مشترک

### Media

```json
{
  "url": "https://cdn.example.com/home/banner.webp",
  "width": 1600,
  "height": 500,
  "alt": "بنر فروش ویژه"
}
```

- `width` و `height`: عدد صحیح مثبت، حداکثر `10000`
- `alt`: حداکثر ۲۰۰ کاراکتر

### Link

```json
{
  "label": "مشاهده همه",
  "href": "/shop?sort=best_selling"
}
```

- `label`: ۱ تا ۱۶۰ کاراکتر
- `href`: path داخلی، حداکثر ۵۰۰ کاراکتر

## فهرست سکشن‌ها

| Type | Data | محدودیت |
| --- | --- | --- |
| `hero_slider` | `autoplayMs?`, `slides[]` | ۱ تا ۸ اسلاید |
| `image_banner` | `link`, `desktopMedia`, `mobileMedia` | هر دو تصویر اجباری |
| `banner_grid` | `variant`, `items[]` | ۱ تا ۶ آیتم |
| `ranked_product_list` | `title`, `action?`, `products[]` | ۱ تا ۱۲ محصول |
| `compact_deals` | `title`, `subtitle?`, `action?`, `products[]` | ۱ تا ۱۶ محصول |
| `product_carousel` | `title`, `action?`, `variant`, `products[]` | ۱ تا ۲۰ محصول |
| `category_grid` | `title`, `action?`, `variant`, `items[]` | ۱ تا ۱۶ آیتم |
| `category_panels` | `eyebrow?`, `title`, `action?`, `items[]` | ۱ تا ۸ پنل |
| `brand_grid` | `title`, `action?`, `items[]` | ۱ تا ۱۸ برند |
| `article_grid` | `title`, `action?`, `variant`, `items[]` | ۱ تا ۸ مقاله |

## مقادیر enum

| فیلد | مقادیر مجاز |
| --- | --- |
| `banner_grid.variant` | `two_equal`, `three_equal`, `featured_start` |
| `product_carousel.variant` | `default`, `flash_sale`, `compact` |
| `category_grid.variant` | `mosaic`, `equal` |
| `category_grid.items[].size` | `small`, `medium`, `large` |
| `article_grid.variant` | `featured_with_list` |
| `seo.robots` | `index,follow`, `noindex,follow` |

## ساختار آیتم‌ها

### `hero_slider.slides[]`

```json
{
  "id": "hero-mobile",
  "link": { "label": "مشاهده", "href": "/category/mobile" },
  "desktopMedia": {
    "url": "https://cdn.example.com/home/hero-desktop.webp",
    "width": 1600,
    "height": 500,
    "alt": "پیشنهاد ویژه موبایل"
  },
  "mobileMedia": {
    "url": "https://cdn.example.com/home/hero-mobile.webp",
    "width": 900,
    "height": 900,
    "alt": "پیشنهاد ویژه موبایل"
  }
}
```

`autoplayMs` اختیاری و بین `3000` تا `12000` است.

### `banner_grid.items[]`

```json
{
  "id": "mobile",
  "link": { "label": "مشاهده موبایل‌ها", "href": "/category/mobile" },
  "media": {
    "url": "https://cdn.example.com/home/mobile-banner.webp",
    "width": 720,
    "height": 310,
    "alt": "پیشنهادهای موبایل"
  }
}
```

### `category_grid.items[]`

```json
{
  "id": "mobile",
  "title": "موبایل",
  "href": "/category/mobile",
  "media": {
    "url": "https://cdn.example.com/categories/mobile.webp",
    "width": 600,
    "height": 600,
    "alt": "موبایل"
  },
  "size": "large"
}
```

### `category_panels.items[]`

```json
{
  "id": "mobile",
  "title": "موبایل",
  "subtitle": "منتخب این هفته",
  "href": "/category/mobile",
  "media": [
    {
      "url": "https://cdn.example.com/categories/mobile.webp",
      "width": 600,
      "height": 600,
      "alt": "موبایل"
    }
  ]
}
```

هر پنل باید ۱ تا ۴ media داشته باشد.

### `brand_grid.items[]`

```json
{
  "id": "apple",
  "name": "اپل",
  "englishName": "Apple",
  "productCount": 126,
  "href": "/brand/apple",
  "logo": {
    "url": "https://cdn.example.com/brands/apple.webp",
    "width": 320,
    "height": 180,
    "alt": "اپل"
  }
}
```

### `article_grid.items[]`

```json
{
  "id": "481",
  "slug": "phone-buying-guide",
  "title": "راهنمای خرید گوشی",
  "excerpt": "راهنمای کوتاه انتخاب گوشی.",
  "href": "/blog/phone-buying-guide",
  "image": {
    "url": "https://cdn.example.com/articles/phone-guide.webp",
    "width": 1200,
    "height": 800,
    "alt": "راهنمای خرید گوشی"
  },
  "authorName": "تحریریه",
  "publishedAt": "2026-09-13T09:00:00+03:30",
  "readingMinutes": 8,
  "commentsCount": 12
}
```

## Product

محصول باید با `CatalogProductSchema` storefront هماهنگ باشد. نمونه:

```json
{
  "id": "14919",
  "slug": "xiaomi-poco-x6-pro",
  "sku": "20420312",
  "title": "گوشی شیائومی Poco X6 Pro",
  "brand": {
    "id": "11",
    "title": "شیائومی",
    "slug": "xiaomi"
  },
  "image": {
    "url": "https://cdn.example.com/products/14919.webp",
    "width": 800,
    "height": 800,
    "alt": "گوشی شیائومی Poco X6 Pro"
  },
  "price": 28500000,
  "previousPrice": 31000000,
  "currency": "IRT",
  "inStock": true,
  "stockStatus": "in_stock",
  "badges": [],
  "rating": 4.6,
  "reviewCount": 83,
  "productUrl": "/product/xiaomi-poco-x6-pro"
}
```

پنل محصول را انتخاب می‌کند؛ بک‌اند تمام فیلدهای تجاری محصول را از منبع اصلی تولید می‌کند و نباید قیمت یا موجودی ارسال‌شده از مرورگر را معتبر بداند.