# Service Landing Manager Development Guide

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

## هدف

- داشتن یک Page Builder قابل توسعه برای هر `Service`
- ذخیره محتوای هر سکشن به صورت `json` (بدون ساخت جدول جدا برای هر سکشن)
- پشتیبانی از ارث‌بری محتوا از `parent / grandparent / root`
- ثابت بودن سکشن هدر در ابتدای صفحه

## ساختار دیتابیس

جدول جدید: `service_landing_sections`

فایل migration:
- `database/migrations/2026_03_31_180000_create_service_landing_sections_table.php`
- `database/migrations/2026_03_31_190000_add_instance_key_to_service_landing_sections_table.php`

ستون‌های کلیدی:
- `service_id`
- `section_key`
- `instance_key` (برای سکشن‌های چندتایی)
- `sort_order`
- `inheritance_mode` (`self`, `parent`, `grandparent`, `root`)
- `content` (json)
- `is_active`

نکات:
- روی `(service_id, section_key, instance_key)` کلید یکتا داریم.
- ترتیب سکشن‌ها با `sort_order` مدیریت می‌شود.

## رجیستری سکشن‌ها (قلب توسعه‌پذیری)

فایل:
- `config/service_landing_sections.php`

هر سکشن در این رجیستری تعریف می‌شود. سکشن‌های فعال فعلی:
- `header`
- `success_path`
- `audio_player`
- `card_section`
- `account_charge`
- `left_right_description`
- `charge_plans`
- `honors`
- `success_path_v2`
- `card_section_v2`
- `growth`
- `specifications`
- `subscriptions`
- `map_address`
- `admob_income_calculator`
- `adsense_income_calculator`
- `compare_table`
- `customers`
- `contact_cta`
- `page_description`
- `service_types`
- `faq_section`
- `work_samples_section`
- `technologies_section`

هر سکشن این متادیتا را دارد:
- `label`
- `preview` (تصویر راهنما)
- `is_required`
- `is_sort_locked`
- `is_repeatable`
- `default_sort_order`
- `supports_inheritance`

### Helper های رجیستری

- `app/Helpers/ServiceLandingSectionKeys.php`
- `app/Helpers/ServiceLandingSectionsRegistry.php`

این دو کلاس کلیدها و دسترسی استاندارد به تنظیمات سکشن‌ها را فراهم می‌کنند.

## مدل و رابطه‌ها

- مدل جدید: `app/Models/ServiceLandingSection.php`
- رابطه در `Service`:
  - `landingSections()`

## سرویس بیزینس

فایل:
- `app/Services/ServiceLandingSectionService.php`

مسئولیت‌ها:
- ساخت خودکار سکشن‌های required (فعلاً Header)
- ارائه سکشن‌های قابل افزودن
- افزودن سکشن جدید به خدمت
- بروزرسانی محتوا (با DTO)
- مرتب‌سازی سکشن‌ها (به‌جز سکشن‌های lock شده)
- مدیریت فایل‌ها (تصویر/صوت) در مسیر:
  - `public/assets/uploads/service-landing`

## Controller, Request, DTO

### Controller
- `app/Http/Controllers/Admin/ServiceLandingSectionController.php`

متدها:
- `index` نمایش Landing Manager
- `store` افزودن سکشن
- `update` ذخیره تنظیمات سکشن
- `updateOrder` ذخیره ترتیب سکشن‌ها
- `destroy` حذف سکشن غیر اجباری

### Requestها
- `ServiceLandingSectionStoreRequest`
- `ServiceLandingSectionUpdateRequest`
- `ServiceLandingSectionOrderRequest`

### DTO
- `ServiceLandingSectionDTO`

## مسیرها (Routes)

فایل:
- `routes/admin.php`

Route names:
- `admin.services.landing.index`
- `admin.services.landing.store`
- `admin.services.landing.update`
- `admin.services.landing.order`
- `admin.services.landing.destroy`

## ساختار UI ادمین

فایل‌ها:
- `resources/views/admin/service/landing/index.blade.php`
- `resources/views/admin/service/landing/partials/form-fields.blade.php`

ویژگی‌ها:
- گالری افزودن سکشن با تصویر راهنما
- فرم‌های اختصاصی برای سکشن‌های پیاده‌سازی‌شده
- drag & drop برای مرتب‌سازی سکشن‌های قابل جابه‌جایی
- سکشن Header به صورت ثابت و غیرقابل جابه‌جایی

## ساختار JSON هر سکشن

### `header`

```json
{
  "title": "string|null",
  "short_description": "string|null",
  "image_primary": "filename|null",
  "image_secondary": "filename|null",
  "cta_buttons": [
    { "text": "string", "link": "url", "color": "green|black" }
  ]
}
```

### `success_path`

```json
{
  "section_title": "string|null",
  "steps": [
    { "title": "string", "description": "string", "sort_order": 1 }
  ]
}
```

### `audio_player`

```json
{
  "title": "string|null",
  "short_description": "string|null",
  "audio_file": "filename|null"
}
```

### `card_section`

```json
{
  "title": "string|null",
  "short_description": "string|null",
  "image": "filename|null",
  "cards": [
    { "title": "string", "description": "string" }
  ]
}
```

### `account_charge`

```json
{
  "title": "string|null",
  "short_description": "string|null"
}
```

### `left_right_description`

```json
{
  "title": "string|null",
  "description": "string|null",
  "image": "filename|null",
  "image_position": "left|right"
}
```

### `charge_plans`

```json
{
  "title": "string|null",
  "short_description": "string|null"
}
```

### `honors`

```json
{
  "title": "string|null",
  "short_description": "string|null"
}
```

### `success_path_v2`

```json
{
  "section_title": "string|null",
  "steps": [
    { "title": "string", "description": "string", "sort_order": 1 }
  ]
}
```

### `card_section_v2`

```json
{
  "section_title": "string|null",
  "cards": [
    {
      "title": "string",
      "description": "string",
      "image": "filename|null",
      "button_text": "string|null",
      "button_link": "url|null"
    }
  ]
}
```

### `growth`

```json
{
  "title": "string|null",
  "description": "string|null",
  "image": "filename|null",
  "buttons": [
    { "text": "string", "link": "url" }
  ]
}
```

### `specifications`

```json
{
  "title": "string|null",
  "image": "filename|null",
  "items": [
    { "title": "string", "description": "string|null" }
  ]
}
```

### `subscriptions`

```json
{}
```

### `map_address`

```json
{
  "title": "string|null",
  "description": "string|null",
  "image": "filename|null",
  "map_link": "url|null"
}
```

### `admob_income_calculator`

```json
{}
```

### `adsense_income_calculator`

```json
{}
```

### `compare_table`

```json
{
  "section_title": "string|null",
  "items": [
    { "title": "string", "image": "filename|null" }
  ],
  "features": [
    { "title": "string" }
  ],
  "matrix": {
    "0": { "0": 1, "1": 0 }
  }
}
```

### `customers`

```json
{
  "title": "string|null"
}
```

### `contact_cta`

```json
{}
```

### `page_description`

```json
{}
```

### `service_types`

```json
{
  "title": "string|null",
  "services_source": "children|siblings"
}
```

### `faq_section`

```json
{
  "title": "string|null",
  "items": [
    { "question": "string", "answer": "string" }
  ]
}
```

### `work_samples_section`

```json
{
  "title": "string|null",
  "items": [
    {
      "title": "string",
      "short_description": "string|null",
      "image": "filename|null",
      "link": "url|null"
    }
  ]
}
```

### `technologies_section`

```json
{
  "title": "string|null"
}
```

## نحوه اضافه کردن سکشن جدید

برای اضافه کردن سکشن جدید در آینده:

1. سکشن را در `config/service_landing_sections.php` اضافه کنید.
2. یک کلید ثابت در `ServiceLandingSectionKeys` اضافه کنید.
3. مقدار پیش‌فرض JSON را در `defaultContentForKey()` داخل `ServiceLandingSectionService` اضافه کنید.
4. قوانین ولیدیشن آن سکشن را در `ServiceLandingSectionUpdateRequest` اضافه کنید.
5. آماده‌سازی محتوای آن سکشن را در `ServiceLandingSectionService` اضافه کنید.
6. UI فرم آن سکشن را در `partials/form-fields.blade.php` اضافه کنید.
7. در صورت نیاز، نمایش فرانت‌اند آن سکشن را در لایه سایت اضافه کنید.

## وضعیت فعلی

نسخه فعلی Landing Manager شامل این سکشن‌ها است:
- هدر بالای صفحه
- مسیر موفقیت الو ادز
- فایل صوتی (Audio Player)
- سکشن Card ها
- بخش شارژ حساب
- بخش توضیحات و عکس (چپ و راست)
- بخش بسته های شارژی
- بخش افتخارات
- بخش استپی/مسیر (حالت دوم)
- بخش کاردی (حالت دوم)
- بخش رشد
- بخش ویژگی ها
- بخش اشتراک ها
- بخش آدرس و نقشه
- بخش محاسبه درآمد ادموب
- بخش محاسبه درآمد ادسنس
- بخش جدول مقایسه ای
- بخش مشتریان ما
- بخش CTA تماس باما/مشاوره
- بخش توضیحات صفحه
- بخش انواع خدمات
- سوالات متداول
- نمونه کارها
- تکنولوژی ها

این ساختار برای اضافه کردن بقیه سکشن‌ها آماده است.