Geliştiriciler / Genişletme

Uygulama geliştirme

Entegrasyonlar çekirdeğin içine yazılmaz; her biri kendi paketinde, kendi kuyruğunda ve kendi süreçinde çalışan bir modüldür. Modül, sürümlü bir sözleşmeye (@platform/contracts) bağlanır; çekirdek değişse de kırılmaz.

module.json

modules/marketplace-ornek/module.json

{
  "key": "ornek",
  "name": "Örnek Pazaryeri",
  "version": "0.1.0",
  "type": "integration",
  "implements": ["MarketplaceAdapter"],
  "contracts": "^1.0.0",
  "tablePrefix": "mod_ornek_",
  "queues": ["ornek.product", "ornek.order", "ornek.stock"],
  "concurrency": { "default": 4, "ornek.order": 1 },
  "settingsSchema": "./settings.schema.json",
  "permissions": ["catalog:read", "stock:read", "order:write"],
  "requiresEntitlement": "marketplace.ornek"
}

requiresEntitlement modülün hangi planlarda açılabileceğini belirler. settingsSchema mağazadan istenecek alanları (API anahtarı, satıcı kimliği…) tanımlar; panel formu bundan üretilir.

Adaptör sözleşmeleri

Arayüz	Kullanım	Metotlar
`MarketplaceAdapter`	Pazaryeri (Trendyol, Hepsiburada…)	fetchCategoryTree, fetchAttributes, pushListings, syncStock, syncPrice, pullOrders, acknowledgeOrder, pushShipment, pullProducts?, health
`PaymentAdapter`	Ödeme sağlayıcısı (PayTR…)	methods, initiate, handleCallback, refund, health
`ShippingAdapter`	Kargo firması	quote, createLabel, cancelLabel, track, health
`StorageAdapter`	Görsel deposu (S3 uyumlu)	put, urlFor, deleteMany, health

src/adapter.ts

import { IntegrationError, type PaymentAdapter } from '@platform/contracts';

export const adapter: PaymentAdapter<{ apiKey: string }> = {
  key: 'ornek-odeme',

  async initiate(intent, ctx) {
    const res = await fetch('https://odeme.ornek.com/sessions', {
      method: 'POST',
      headers: { authorization: `Bearer ${ctx.settings.apiKey}` },
      body: JSON.stringify({ amount: intent.amount.amount.toString() }),
      signal: ctx.signal,
    });
    if (res.status === 401) {
      throw new IntegrationError('API anahtarı geçersiz', {
        moduleKey: 'ornek-odeme',
        retryable: false,
      });
    }
    const body = await res.json();
    return { redirectUrl: body.url, providerRef: body.id, expiresAt: new Date(body.expiresAt) };
  },

  // methods, handleCallback, refund, health…
};

Yaşam döngüsü

`register`	`module.json` okunur, sözleşme sürümü doğrulanır
`migrate`	Modül yalnızca kendi `mod_<key>_*` tablolarını oluşturur
`configure`	`settings.schema.json`dan panel formu üretilir; mağaza API anahtarını girer
`enable`	Yetki uygunsa kuyruklar bağlanır, zamanlanmış işler kaydolur
`observe`	Panelde modül kartı: son senkron, bekleyen iş, hata sayısı
`disable`	Tek tıkla kapatma; veriler korunur, mağaza satmaya devam eder

Yalıtım kuralları

Modül yalnızca kendi mod_<key>_* tablolarına yazar. Bu kural veritabanı rolüyle zorlanır.
Her modül kendi kuyruğunda ve kendi süreçinde çalışır; hiçbir entegrasyon HTTP istek yolunu bloklamaz.
Art arda hatalarda devre kesici modülü durdurur; tükenen işler ölü mektup kuyruğuna düşer, kaybolmaz.
Hatalar IntegrationError ile ve doğru retryable bayrağıyla fırlatılır: kimlik hatası tekrar denenmez, hız limiti denenir.
Sırlar asla günlüğe yazılmaz; ctx.logger merkezî günlüğe gider.

Uygulama marketi yol haritasında. Şimdilik modüller platform deposuna eklenir ve yönetici onayıyla dağıtılır.