> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.nodx.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Entegrasyon standardı

> Capability, action mapping, veri biçimi ve test kuralları

Bu rehber, özel entegrasyon eklerken bütün kategorilerde kullanacağın ortak kuralları anlatır.

## Capability ve action mapping farkı

**Capability**, Panel'in bildiği sabit işlem adıdır. **Action mapping** ise bu işlemin senin resource'unda nasıl gerçekleştirileceğini söyler.

| Panel isteği                | Capability örneği      | Resource içindeki karşılığı                     |
| --------------------------- | ---------------------- | ----------------------------------------------- |
| Marketleri listele          | `shops.list`           | Bir export veya SQL sorgusu                     |
| Oyuncuyu dirilt             | `ems.revive`           | Bir server/client event                         |
| Kapıyı aç veya kilitle      | `doorlock.toggle`      | Export veya event                               |
| Personel rütbesini değiştir | `management.grade.set` | Export, event veya desteklenen framework işlemi |

Capability adını resource'un kendi terminolojisine göre değiştirme. Örneğin paket “houses” kelimesini kullansa bile Panel'in **Ev Yönetimi** sayfası `housing.list` ister.

## Erişim seviyeleri

| Seviye | Anlamı                                                               | Örnek                  |
| ------ | -------------------------------------------------------------------- | ---------------------- |
| Okuma  | Veri getirir, oyun durumunu değiştirmez                              | `shops.list`           |
| Yazma  | Oyun veya veritabanı durumunu değiştirir                             | `character.job.set`    |
| Kritik | Para silme, ev devretme veya kayıt silme gibi yüksek riskli işlemdir | `banking.money.remove` |

<Warning>
  Önce okuma capability'sini çalıştır. Listeleme başarısızken oluşturma, düzenleme veya silme işlemlerini aktif etme.
</Warning>

## Action türleri

| Tür    | Ne zaman kullanılır?                         | Öneri                                            |
| ------ | -------------------------------------------- | ------------------------------------------------ |
| Export | Paket dışarıya hazır bir fonksiyon sunuyorsa | Okuma ve doğrulama işlemlerinde tercih et        |
| Event  | Paket işlemleri event ile yapıyorsa          | Özellikle oyuncuya uygulanan aksiyonlarda kullan |
| SQL    | Veri yalnızca veritabanında bulunuyorsa      | Öncelikle okuma için kullan                      |
| Custom | Standart yöntemler pakete yetmiyorsa         | Destek ekibiyle birlikte doğrula                 |

## Temel mapping alanları

| Alan          | Açıklama                                                       |
| ------------- | -------------------------------------------------------------- |
| `type`        | `export`, `event` veya `sql`                                   |
| `side`        | İşlemin `server` veya `client` tarafında çalışacağını belirtir |
| `resource`    | `server.cfg` içindeki resource adı                             |
| `name`        | Çağrılacak export veya event adı                               |
| `args`        | İşleme gönderilecek değerlerin sırası                          |
| `query`       | SQL action için kullanılacak sorgu                             |
| `result_path` | Dönen cevabın hangi alanından veri okunacağını belirtir        |

### Export örneği

```json theme={null}
{
  "shops.list": {
    "type": "export",
    "side": "server",
    "resource": "my-shops",
    "name": "GetPanelShops"
  }
}
```

### Event örneği

```json theme={null}
{
  "notify.send": {
    "type": "event",
    "side": "server",
    "resource": "my-notify",
    "name": "my-notify:server:send",
    "args": ["player_id", "payload.message", "payload.type"]
  }
}
```

### SQL okuma örneği

```json theme={null}
{
  "doorlock.list": {
    "type": "sql",
    "query": "SELECT id, name, locked, job FROM doorlocks ORDER BY id ASC",
    "result_path": "doors"
  }
}
```

<Warning>
  SQL action'larında önce salt okunur sorgular kullan. Yazma sorguları paket önbelleğini atlayabilir ve oyun içi durumla veritabanını farklı hale getirebilir.
</Warning>

## Liste cevabı nasıl olmalı?

Liste capability'leri boş olsa bile geçerli bir liste döndürmelidir. Bir paketin cevap alanı farklıysa **Sonuç yolu** alanını kullan.

```json theme={null}
{
  "ok": true,
  "items": [
    {
      "id": "example-1",
      "label": "Örnek kayıt"
    }
  ]
}
```

Bu cevapta liste `items` alanındaysa sonuç yolu `items` olarak ayarlanır.

## Test sonucunu okuma

| Adım                | Başarılı sonuç neyi gösterir?               |
| ------------------- | ------------------------------------------- |
| Resource bulundu    | Resource başlatılmış ve adı doğru           |
| Capability eşleşti  | Panel sayfası doğru işlem adını çağırabilir |
| Action bulundu      | Export, event veya SQL ayarı kullanılabilir |
| Cevap alındı        | İşlem zaman aşımına uğramadan döndü         |
| Veri biçimi geçerli | Panel cevabı okuyabilir                     |

`capability_not_synced` görürsen plugin'in son bağlantısını kontrol et, health check çalıştır ve entegrasyonu tekrar test et.

## Canlıya almadan önce kontrol listesi

* Doğru sunucu seçili.
* Resource adı `ensure` adıyla birebir aynı.
* Okuma action'ları veri döndürüyor.
* Boş listeler hata yerine boş liste olarak dönüyor.
* Yazma işlemi oyun içinde de doğrulandı.
* Silme ve para işlemleri yalnızca yetkili rollere açık.
* Paket restartlandıktan sonra tekrar test edildi.