Fan Yemek API

Best practice özeti

• Aktör başına ayrı token/scope: customer token'ı panel uçlarına geçemez. Access JWT claim'leri: act (customer | seller | tenant | system), roles[], satıcı için sellerId, tenant için tid, oturum için sid / jti / ver, hedef API için aud. Detaylı izinler token'da değil; rol → permission map sunucuda türetilir.
• En az ayrıcalık (least privilege): her rol yalnızca ihtiyaç duyduğu yetkiye sahip. Yeni rol eklenebilir olmalı (rol → izin eşlemesi konfigüratif). system aktörü çoklu rol destekler; super_admin implicit olarak tüm system endpoint'lerine erişir.
• Endpoint düzeyinde policy: yetki kontrolü gateway/filter + servis katmanında çift kademeli; ayrıca resource ownership kontrolü (satıcı X'in temsilcisi sadece X'in siparişlerini görür).
• Kısa ömürlü access + refresh token rotation; anında iptal için ver + Redis INCR auth:ver:{sub} birincil mekanizma; blacklist:access:{jti} yalnızca opsiyonel (tek cihaz logout, kalan access TTL kadar).
• Telefon OTP zorunlu (customer, seller, tenant, system): giriş ve kayıt phoneNumber ile; varsayılan kanal WhatsApp (app.monochat.ai), alternatif SMS (Twilio). TOTP/authenticator app kullanılmaz.
• Birincil kimlik: phoneNumber + actor birlikte unique — aynı numara farklı panellerde ayrı hesap olabilir.
• system aktörü hassas işlemleri audit-log'a yazılır.

Not: API ağacında ilgili uçlarda Gerekli rol rozetiyle hangi rolün erişebildiği işaretlenmiştir.

Token modeli

Access token claim şeması

{
  "sub": "user-uuid",
  "act": "customer | user | system",
  "roles": ["owner"],
  "sellerId": "seller-uuid",
  "sid": "session-family-uuid",
  "jti": "access-token-uuid",
  "ver": 3,
  "iss": "fan-yemek-auth",
  "aud": "customer-api | seller-api | system-api",
  "iat": 1710000000,
  "exp": 1710000900
}

JWT'ye koy / koyma

OTP + JWT akışı

Yetkilendirme katmanları

• Gateway/filter: JWT imza + TTL doğrula; act + aud route prefix ile eşleşsin; ardından ver Redis kontrolü (endpoint policy'sine göre fail-open / fail-closed).
• Servis katmanı: rol kontrolü + resource ownership (sellerId === order.sellerId).
• Aktör izolasyonu: customer token /v1/seller/* ve /v1/system/* uçlarına geçemez.

İptal mekanizmaları

Redis aynı VPS/local ağda round-trip ~1 ms; tek INCR ile blacklist'e göre çok daha az operasyon. OTP verify / refresh sırasında GET auth:ver:{sub} (yoksa 0) → JWT ver claim'ine yazılır.

Access token doğrulama (gateway middleware)

async function verifyAccessToken(req, policy = 'fail-open') {
  const decoded = jwt.verify(req.token, PUBLIC_KEY, { aud, iss });

  try {
    const current = await redis.get(`auth:ver:${decoded.sub}`);
    if (current !== null && parseInt(current, 10) !== decoded.ver) {
      throw unauthorized('TOKEN_STALE');
    }
  } catch (err) {
    if (err.code === 'TOKEN_STALE') throw err;
    // Redis erişilemez
    if (policy === 'fail-closed') {
      throw serviceUnavailable('AUTH_STORE_UNAVAILABLE');
    }
    // fail-open: log + devam
  }

  return decoded;
}

Korunan tüm route'larda standart auth hataları: 401 TOKEN_STALE (eski ver), 503 AUTH_STORE_UNAVAILABLE (fail-closed route + Redis down).

Redis erişilemezlik politikası

Global tek davranış yerine route metadata / guard seviyesinde securityPolicy: 'strict' | 'standard' ile ayrılır.

Redis anahtarları

• otp:{sessionId} → OtpChallenge (mevcut)
• auth:ver:{sub} → integer counter (TTL yok; kalıcı, ~8 byte/kullanıcı)
• refresh:{tokenHash} → { sub, act, sid, ver, expiresAt }
• blacklist:access:{jti} → opsiyonel, ver yaklaşımına göre ikincil; logout sonrası kalan access TTL kadar

Kimlik akışı (apiKey → JWT)

clientId + clientSecret → token → Bearer JWT → (refresh rotation)

1. System/partner onboarding sonrası entegratöre clientId + clientSecret verilir (secret hash'lenerek saklanır).
2. POST /v1/integration/auth/token — credential exchange.
3. Yanıt: accessToken (JWT) + refreshToken (opaque) — Bölüm 1b'deki rotation mantığı geçerlidir.
4. Sonraki istekler: Authorization: Bearer {accessToken}.
5. Süresi dolunca: POST /v1/integration/auth/refresh (Faz 2+).

Access JWT claim'leri: act=integration, aud=integration-api, scopes[]; isteğe bağlı sellerId / tenantId (client kaydına bağlı kapsam). OTP/telefon yok.

Token alma — endpoint (Faz 2+)

Ham clientSecret yalnızca token exchange'de gönderilir; her API isteğinde taşınmaz.

POST /v1/integration/auth/token
Body: { "clientId": "...", "clientSecret": "..." }

200 OK:
{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

401 — Geçersiz credential
403 — Client askıda / süresi dolmuş
429 — Rate limit

Filtreleme — her zaman queryParam

Filtreler gövdede değil, daima query parametresi olarak gelir. q tüm tablolar için ön tanımlı alanlarda serbest arama yapar.

GET /api/v1/products?q=makarna
GET /api/v1/orders?orderDate.gt=100&orderDate.lt=200
GET /api/v1/sellers?rating.gte=4&sort=-rating&page=2&limit=20

Operatör eki sözleşmesi: .gt .gte .lt .lte .in .ne · sıralama: sort=alan / sort=-alan (azalan).

Liste yanıtı — standart pagination zarfı

Tüm list endpoint'leri sayfalama bilgisini veri içinde döner:

{
  "results": [ /* ... */ ],
  "options": {
    "paginations": {
      "currentPage": 1,
      "pageItems": 10,
      "totalCount": 100,
      "totalPage": 10
    }
  }
}

Hata yanıtı — tutarlı format

Tüm hatalar aynı zarfta döner; istemciler tek bir şemaya göre işler:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Geçersiz istek",
    "details": [ { "field": "phoneNumber", "message": "Zorunlu" } ]
  }
}

Standart HTTP kodları kullanılır (2xx başarı, 4xx istemci, 5xx sunucu). Aynı standart her iki katmanda (customer ve seller/satıcı) ortak uygulanır.

Rakip platform özeti

Önerilen seed mutfak listesi (~30)

İlk deploy'da migration ile yüklenir; system panelden ekleme/çıkarma mümkün.

Ekip profili

Fan Yemek proje atamaları için bkz. Bölüm 9 · Proje Ekibi.

Neden NestJS?

• Ekip hızı: Faz 1 kapsamı geniş; çoğunluk Nest.js deneyimli — paralel modül geliştirme mümkün.
• Mimari uyum: NestJS modül/DI yapısı Spring'e benzer; modüler monolit disiplini kolay kurulur.
• Proje profili: Marketplace backend I/O ağırlıklı (DB, Redis, queue, harici API); Node.js yeterince güçlü.
• Ekosistem: Redis, BullMQ/Kafka, Elasticsearch, JWT/RBAC, OpenAPI — olgun entegrasyonlar mevcut.
• ORM: @nestjs/typeorm + TypeORM — entity/repository kalıbı Spring JPA'ya yakın; migration ve PostGIS desteği net.

TypeORM (NestJS ile)

• Entity tanımı: bu referanstaki modeller (DeliveryShipment, CourierProvider vb.) TypeORM entity olarak domain modüllerine map edilir.
• Migration: typeorm migration:generate/run — şema değişiklikleri versiyonlu ve CI'da uygulanır.
• PostGIS: geography(Point) / raw query ile satıcı ve adres mesafe sorguları.
• Transaction: sipariş + ödeme + outbox yazımları QueryRunner veya @Transactional() ile atomik tutulur.

Kotlin + Spring ne zaman mantıklı olurdu?

resto-maxi-app (Spring Boot + Kotlin) domain ve pattern kaynağı olarak kullanılır; birebir kod paylaşımı şart değildir.

Önerilen stack

Runtime:        Node.js LTS + TypeScript
Framework:      NestJS (modüler monolit)
ORM:            TypeORM (@nestjs/typeorm)
DB:             PostgreSQL + PostGIS
Cache:          Redis (ioredis)
Queue:          BullMQ / RabbitMQ (Kafka — trafik büyüdükçe)
Search:         Elasticsearch
Auth:           Telefon OTP (WhatsApp/MonoChat + Twilio SMS), JWT + refresh rotation, RBAC
API:            REST /v1 (bu referanstaki sözleşme)
Observability:  OpenTelemetry + structured logging
Deploy:         Docker + CI/CD

Faz 1 modül önerisi

Kaçınılması gerekenler

• Hibrit stack (bazı servisler Nest, bazıları Spring) — Faz 1'de operasyonel yük iki katına çıkar.
• Kotlin seçip ekibi hızla Kotlin'e çevirmek — 5–6 kişinin ramp-up süresi Faz 1'i geciktirir.
• Erken microservice — önce modüler monolit; trafik kanıtlandıkça modülleri ayırın.

Frontend

Yasin Karadeniz

Müşteri Mobil Müşteri Web Satıcı Web System Web

Backend

Recep Özen

Backend

Nuh Yılmaz Şentürk

Backend

Furkan Öğütçü

Backend

Kadir Belen

Backend

POC go/no-go kriterleri (kod POC sonraki adım)

Go: tüm kritik satırlar geçer (overdraft dahil); pending/capture patch kabul edilebilir. No-go: bütünlük, tenant izolasyonu, overdraft limit veya concurrency fail → custom ledger (Kart B).

Ödeme türüne göre dallanma

• card_online / meal_card_online: authorize (checkout) → capture (satıcı kabul) → komisyon SellerTenant.commissionRate ile tenant kapsamında hesaplanır; capture sonrası split transaction ledger'a yazılır (Bölüm 10).
• cash_on_delivery / meal_card_on_delivery: sipariş isPrepaid: false; teslimatta/satıcıda tahsil; komisyon yine tenant komisyon oranından.
• bank_transfer: tenant IBAN (TenantPaymentConfig.bankTransferIban) gösterilir; sipariş pending_payment — system/satıcı manuel onay (MVP).
• meal_card_online: tahsilat-app APM (Pluxee/Multinet vb.); tenant config'de aktif provider + satıcı üye iş yeri metadata gerekir.

Kritik kurallar

• Tenant scope: tüm tahsilat-app çağrıları aktif tenant'ın merchant ref'i ile yapılır; cross-tenant yönlendirme yasak.
• Idempotency: her ödeme isteği sipariş bazlı Idempotency-Key ile gönderilir; tekrar denemede çift çekim olmaz (Payment.externalRef).
• Başarısız authorize: sipariş 402 ile reddedilir, sipariş kaydı oluşmaz veya payment_failed işaretlenir.
• Capture edilmiş ama reddedildi/iptal: sistem otomatik Refund başlatır; tahsilat-app webhook'u ile refunded teyit edilir.
• PCI sınırı: kart verisi yalnızca tahsilat-app'te; Fan Yemek sadece token + işlem referansı tutar.
• Komisyon: SellerTenant.commissionRate → Tenant.defaultCommissionRate → SystemConfig.platformCommissionDefault.

Akış notları

• Otomatik dispatch: yalnızca delivery_to_address ve tribune_delivery — sipariş ready olunca connector createDelivery(orderSnapshot) çağırır (pickup hariç).
• Manuel tetik: satıcı panelden POST /orders/:id/dispatch ile yeniden gönderim veya gecikmeli dispatch.
• Inbound webhook: sağlayıcı POST /webhooks/courier/:provider ile durum bildirir; HMAC doğrulanır, statü normalize edilir.
• Müşteri tracking: trackingUrl varsa proxy/passthrough; yoksa normalize statü + ETA.
• Geri dönüş: delivery.failed veya timeout'ta satıcı/operasyona eskalasyon.

Sektör referansı (kısa)

• Trendyol Yemek: online kart + Pluxee/Multinet/Edenred/Setcard (üye satıcılarda); kapıda nakit/yemek kartı geçerli satıcılarda.
• Getir Yemek: platform kuryesinde dijital ödeme; kapıda ödeme yalnızca Satıcı Getirsin modelinde.
• Yemeksepeti: Gel Al + adrese teslim; ödeme checkout'ta teslimat türüne göre filtrelenir.
• Fan Yemek farkı: stadyum senaryosunda tribune_delivery (engelli tribününe teslim, tribün no).

Sektör referansı

• Getir Yemek: çoklu bölge, bölge bazlı min sepet + teslimat süresi, haritada H3 altıgen grid.
• Trendyol Yemek: "Alan Seç", "Mahalle Doldur", "Mahalle Ayarı" — bölge başına farklı sepet tutarı (ör. 300–2000 TL).
• Fan Yemek: Seller.minOrder / SystemConfig.minOrderAmount yalnız fallback; asıl min sepet DeliveryZone.minOrderAmount.

Örnek veri

{
  "province": { "id": "il_55", "name": "Samsun", "code": "55", "boundary": null },
  "district": { "id": "ilce_5502", "provinceId": "il_55", "name": "Atakum", "boundary": null },
  "neighborhood": {
    "id": "mah_mevlana", "districtId": "ilce_5502", "provinceId": "il_55",
    "name": "Mevlana", "pathString": "/il_55/ilce_5502/mah_mevlana/",
    "h3Resolution": 9, "cellCount": 98
  },
  "neighborhoodCell": { "neighborhoodId": "mah_mevlana", "h3Index": "891ec1a4d4bffff" },
  "deliveryZone": { "id": "z1", "sellerId": "r_123", "name": "Bölge 1", "minOrderAmount": 350, "etaMinMinutes": 15, "etaMaxMinutes": 25 },
  "deliveryZoneCell": { "zoneId": "z1", "h3Index": "891ec1a4d4bffff", "neighborhoodId": "mah_mevlana" }
}

Sorgu örnekleri

-- 1) Nokta → hücre → satıcıın uygulanan bölgesi (lookup, saf H3)
-- h3 = latLngToCell(lat, lng, 9)
SELECT z.* FROM delivery_zone_cell c
JOIN delivery_zone z ON z.id = c.zone_id
WHERE c.h3_index = :h3 AND z.seller_id = :sellerId AND z.is_active
ORDER BY z.priority LIMIT 1;

-- 2) "Mahalle Doldur"
INSERT INTO delivery_zone_cell (zone_id, h3_index, neighborhood_id)
SELECT :zoneId, nc.h3_index, nc.neighborhood_id
FROM neighborhood_cell nc WHERE nc.neighborhood_id = :neighborhoodId;

-- 2b) "İlçe Doldur" (FK join)
INSERT INTO delivery_zone_cell (zone_id, h3_index, neighborhood_id)
SELECT :zoneId, nc.h3_index, nc.neighborhood_id
FROM neighborhood_cell nc
JOIN neighborhood n ON n.id = nc.neighborhood_id
WHERE n.district_id = :districtId AND n.is_active;

-- 3) Yarıçap-sınırlı mahalleler (hardcut) + X/Y
-- haversine(centroid) <= maxServiceRadiusKm