> ## Documentation Index
> Fetch the complete documentation index at: https://support.zonely.gen.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Modül Geliştirme Rehberi

> Zonely için modül geliştirirken kullanılacak temel kurallar, örnek yapı ve yayın akışı.

Bu belge, Zonely için modül geliştiren ekiplerin uyması gereken genel standartları açıklar.
Amaç; temiz paketler hazırlamak, paketleri doğru şablonlara uygulamak ve güvenli şekilde yayınlamaktır.

## Modül Mantığı

Zonely modülleri ZIP paketi olarak yüklenir.
Panel paketi doğrular ve geçerliyse seçilen alan adına uygular.

Genel akış:

1. Modülü ZIP dosyası olarak hazırlayın.
2. Panel ZIP içeriğini doğrular.
3. Modül seçilen alan adına uygulanır.
4. Gerekirse şablon değişiklikleri etkinleştirilir.
5. `Public` etkinse modül topluluk listesinde görünür.

## Güncelleme Mantığı

Mevcut bir modülü güncellemek için modül kimliği (`id`) aynı kalmalıdır.

* Aynı `id` yüklenirse panel bunu güncelleme olarak işler.
* Yayın takibi için `version` değerini artırın.
* Yazar, açıklama ve sürüm bilgileri paket yapılandırmasından okunur.

## ZIP Yapısı

ZIP içinde en az bir yapılandırma dosyası bulunmalıdır:

```txt theme={null}
config.json
module.json
manifest.json
manifest/config.json
```

Şablon, varlık ve API dosyaları tutarlı bir klasör yapısını izlemelidir.
Paket içinde ilgisiz veya gereksiz dosya bulundurmayın.

## Şablon Kuralları

* Şablonlar için `.tpl` formatını kullanın.
* Tema yollarını doğru ve tutarlı tutun.
* Yeni şablon ekliyorsanız bunları tema uyumlu yolların altına yerleştirin.

Örnek:

```txt theme={null}
templates/Views/Themes/Norix/Pages/Store/main.campaigns.tpl
templates/Views/Themes/Norix/Navigations/campaigns.menu.tpl
admincp_templates/Drawers/main.campaigns.tpl
```

## Rota Eşleştirme

Yeni eklenen bir şablon otomatik olarak rotaya bağlanmaz. Rota üzerinden çağrılması gerekir.

Örnek frontend rotası:

```apache theme={null}
RewriteRule ^campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=MainHandlers&route=main.campaigns [L,QSA,NC]
```

Örnek yönetici rotası:

```apache theme={null}
RewriteRule ^admin/campaigns/?$ /Files/Controllers/ControllersAll.php?main=Handlers&container=AdminHandlers&route=main.campaigns [L,QSA,NC]
```

## Mevcut Dosya Değiştirme Stratejisi

Kararlı modül güncellemeleri için:

1. Hedef dosyayı modülünüzde aynı göreli yol ile ekleyin.
2. Yalnızca gerekli kısımları değiştirin.
3. Geniş kapsamlı ve gereksiz düzenlemelerden kaçının.

Bu yaklaşım bakımı kolaylaştırır ve fark takibini daha temiz hale getirir.

## API Kuralları (Genel)

Modül API dosyaları modül paketi içinde tanımlanmalı ve işlem adları üzerinden kullanılmalıdır.

Temel ilkeler:

* Her işlem açıkça tanımlanmalıdır.
* İzin verilen yöntemler (GET/POST vb.) net olmalıdır.
* Yanıtlar tutarlı bir JSON formatını izlemelidir.
* Hatalar açık ve tutarlı mesajlar döndürmelidir.

## API Çağrıları İçin Gereksinimler

Bir modül işlem isteği için:

1. `module_id` ve `action` gönderilmelidir.
2. İşlem modül yapılandırmasında tanımlanmış olmalıdır.
3. Modül mevcut alan adı için aktif olmalıdır.
4. İstek yöntemi izin verilen yöntemlerle eşleşmelidir.
5. Özel işlemler kimliği doğrulanmış bir oturum gerektirir.

## Örnek Modül Yerleşimi

```txt theme={null}
campaign-module.zip
|- config.json
|- preview.png
|- templates/
|  `- Views/
|     `- Themes/
|        `- Norix/
|           `- Pages/
|              `- Widgets/
|                 `- campaign.widget.tpl
|- template_changes/
|  `- Views/
|     `- Themes/
|        `- Norix/
|           `- Pages/
|              `- Main/
|                 `- main.home.tpl
`- api/
   `- campaign/
      `- list.php
```

## Örnek config.json

```json theme={null}
{
  "id": "campaign-module",
  "name": "Campaign Module",
  "version": "1.0.0",
  "author": "Zonely Team",
  "description": "Adds a campaign widget to the homepage.",
  "image": "preview.png",
  "targetThemes": ["Norix"],
  "api": {
    "campaign.list": { "public": true, "methods": ["GET"] }
  }
}
```

## Örnek Widget Dosyası

```html theme={null}
<div class="campaign-widget">
  <h3>Campaigns</h3>
  <div id="campaign-list"></div>
</div>
```

## Örnek API Dosyası

```php theme={null}
<?php
$stmt = $db->prepare("SELECT id, title FROM campaigns WHERE domain = ? ORDER BY id DESC LIMIT 5");
$stmt->execute([$moduleDomain]);
$rows = $stmt->fetchAll(PDO::FETCH_ASSOC);

$moduleRespond([
    "status" => "success",
    "data" => $rows
], 200);
return;
```

## Frontend API Çağrısı Örneği

```js theme={null}
const base = '/Files/Controllers/ControllersAll.php?main=Handlers&container=TemplatesModulesApiController';
const url = new URL(base, window.location.origin);
url.searchParams.set('module_id', 'campaign-module');
url.searchParams.set('action', 'campaign.list');

fetch(url.toString(), {
  method: 'GET',
  credentials: 'same-origin'
})
  .then((r) => r.json())
  .then((payload) => {
    console.log(payload.data);
  });
```

## Hata Yanıtı Alanları

Yükleme sırasında veya çalışma zamanında oluşan panel hataları genellikle şunları içerir:

```txt theme={null}
message
errors[]
errorType
```

## Hızlı Kontrol Listesi

Yayından önce:

* Yapılandırma dosyası mevcut.
* Modül kimliği ve sürüm doğru.
* Şablon yolları tema yapısıyla eşleşiyor.
* API işlem tanımları eksiksiz.
* JSON yanıt formatı geçerli.
* Modül doğru alan adı ve tema üzerinde test edildi.

## Son Not

En kararlı modüller; temiz paketler, açık işlem tanımları ve kontrollü şablon değişiklikleriyle oluşturulur.