🇳🇱  Fulfillment Platform — Müşteri Sunum Raporu

HollandaGida
MVP Teknik &
Operasyon Raporu

Çok satıcılı fulfillment operasyonunu tek platformda yönetmek için tasarlanan bu sistem; sipariş, stok, depo, faturalama ve webhook işlemlerini uçtan uca kapsar.

8
Tamamlanan Sprint
5
Kullanıcı Rolü
30+
API Endpoint
%100
Sıfır Vulnerability
Bu sayfa ziyaretçilere ürünü tanıtır. Operasyon için giriş yapın; yetkiye göre kendi panelinize yönlendirilirsiniz.
01

Projenin Amacı ve İş Değeri

Sistemi neden inşa ettik ve hangi problemi çözüyor?

Çekirdek 1.1
Merkezi Sipariş Yönetimi
Shopify, WooCommerce veya özel API'lerden gelen siparişleri tek noktada toplar. Siparişler otomatik stok rezervasyonu ile işleme alınır, durum geçişleri kural tabanlı kontrol edilir.
Çekirdek 1.2
Tutarlı Stok Yönetimi
Eş zamanlı siparişlerde stok çakışması (race condition) olmaz. FEFO mantığıyla gıda operasyonuna uygun lot seçimi yapılır. Her stok hareketi ledger formatında kayıt altına alınır.
Operasyon 1.3
Depo Operasyon Akışı
Picking → Packing → Shipping adımlarını buton bazlı yönetir. Kargo etiketi, takip kodu ve maliyet girişi entegre ekranda yapılır. Depocunun hata yapmaması için ürün görseli + SKU doğrulaması var.
Finans 1.4
Finansal Doğruluk
Aylık invoice run otomatik satıcı bazlı fatura üretir. Finans hareketleri değiştirilemez (immutable) ledger'da tutulur. Reconciliation servisi tutarsızlıkları erken tespit eder.
02

Sistem Mimarisi

Katmanlı yapı — her bileşen nerede durur?

UI Katmanı
Admin Paneli Satıcı Paneli Depo Ekranı Muhasebe Paneli Tedarik Modülü Next.js App Router
API Katmanı
/api/external — Dış API /api/internal — İç API /api/v1 — Versiyonlu Mirror API Key Auth JWT Middleware Role Guard Rate Limit Idempotency
İş Kuralı
order.service.ts invoice.service.ts state-policy.ts stock-ledger.ts financial-ledger.ts carrier.ts Distributed Lock Tenant Guard
Veri Katmanı
PostgreSQL Prisma ORM User / Seller / Order Shipment / Invoice / Payment ActivityLog / DomainEvent IdempotencyKey / StockLot
Asenkron
BullMQ + Redis webhook-events queue async-tasks queue dead-letter-events queue Retry + Backoff DLQ UI Failed Job Dashboard
03

Adım Adım: Ne Yapıldı, Neden?

Her geliştirme adımının iş gerekçesi ve teknik konumu

✓ Tamamlandı Adım 1
Veri Modeli & Şema Hizalaması
Mevcut şemaya eksik tablolar ve alanlar eklendi. Neden: Satıcı entegrasyonları, fatura kalemleri, ödemeler ve aktivite logları olmadan hiçbir iş akışı doğru kayıt tutamaz.
SellerIntegration InvoiceItem Payment ActivityLog schema.prisma
✓ Tamamlandı Adım 2
Admin CRUD Çekirdeği
Ürün/stok/satıcı/API key yönetimi endpoint ve form ekranları. Neden: Admin paneli sadece görüntüleme yapıyordu; sistemi gerçekten yönetebilmek için yazma aksiyonları şarttı.
POST /internal/products POST /internal/sellers POST /internal/api-keys admin-crud-panel.tsx
✓ Tamamlandı Adım 3
Depo Operasyon Akışı
NEW → PICKING → PACKED → SHIPPED geçiş butonları, takip no ve kargo maliyet girişi. Neden: Depocunun siparişi uçtan uca sevk etmesi için adım bazlı kontrol şarttır.
PATCH /warehouse/orders/[id] shipOrder() stock_movements tracking form UI
✓ Tamamlandı Adım 4
Satıcı Paneli Genişletme
Ürün seçim/toggle yönetimi, sipariş/kargo/fatura detay sayfaları. Neden: Satıcının kendi operasyonunu bağımsız takip etmesi hem güven hem de destek yükünü azaltır.
seller/orders seller/shipments seller/invoices SellerProductManager
✓ Tamamlandı Adım 5
Muhasebe — Invoice Run
Aylık dönem için satıcı bazlı otomatik fatura üretimi (PRODUCT + SHIPPING + SERVICE_FEE kalemleri), ödeme durumu güncelleme. Neden: Manuel hesaplama hem hata üretir hem zaman kaybettirir.
invoice.service.ts POST /accounting/invoice-runs financial-ledger.ts AccountingActionsPanel
✓ Tamamlandı Adım 6
Webhook + Kuyruk Sistemi
BullMQ + Redis ile retry/backoff, DLQ, idempotency. Neden: Webhook işleri API thread'ini bloklamamalı; geçici hatalar otomatik toparlanmalıdır.
queues.ts worker.ts webhook-processor.ts dead-letter queue
✓ Tamamlandı Adım 7
API Kapsamı Tamamlama
İptal, shipment lookup, versiyonlu API mirror, standart error formatı. Neden: Satıcı entegrasyonları tutarlı, güvenilir ve geriye uyumlu bir API sözleşmesine ihtiyaç duyar.
GET /products/[sku] POST /orders/[id]/cancel /api/v1/external/* api-response.ts
✓ Tamamlandı Adım 8
Test, Güvenlik, Stabilizasyon
Brute-force koruması, security header'ları, /api/health endpoint, dependency güncelleme, go-live:final-gate script. Neden: Canlıya çıkmadan önce sıfır vulnerability ve çalışır altyapı teyidi şarttır.
api/health npm audit: 0 go-live:final-gate security headers
04

Sistem Nasıl Çalıştırılır?

Yerel kurulumdan production gate'e — adım adım komutlar

ℹ️
Canlı ortam (deploy): Ziyaretçiler site köküne (/) girdiğinde bu sunum ekranı açılır; operasyon için kenar çubuğu veya kahraman alanındaki Panele giriş bağlantısı /auth/login sayfasına gider (tam sayfa, target=_top). Oturum açıldıktan sonra kullanıcı rolüne göre ilgili panele yönlendirilir. Aynı içerik ayrıca statik olarak /hollandagida-sunum.html adresinde de sunulur; build çıktısında public/ klasörüne kopyalanmalıdır.
Adım İşlem Komut / Açıklama
0 Sunum dosyası (opsiyonel senkron) Kök hollandagida-sunum.html dosyasını deploy öncesi public/hollandagida-sunum.html ile eşleştirin (cp hollandagida-sunum.html public/).
1 Ortam dosyasını oluştur cp .env.example .env
2 Zorunlu değişkenleri doldur DATABASE_URL  JWT_SECRET  REDIS_URL  CARRIER_WEBHOOK_TOKEN
3 Bağımlılıkları kur npm install
4 Prisma generate + migrate npm run db:generate  npm run db:migrate
5 Seed verisini yükle npm run db:seed
6 Uygulamayı başlat npm run dev (Terminal 1)  npm run queue:worker (Terminal 2)
7 Hızlı sağlık kontrolü GET /api/health → status: ok beklenir
8 Production öncesi final gate npm run go-live:final-gate (lint + build + test + smoke)
ℹ️
İki terminal şarttır: Uygulama (Terminal 1) ve BullMQ Worker (Terminal 2) ayrı ayrı çalışmalıdır. Worker olmadan webhook ve async işler birikir, işlenmez.
05

Kritik Dikkat Noktaları

Operasyonel, finansal ve güvenlik risklerini bilmek zorunludur

⚠️
Operasyonel Riskler
Worker durunca webhook ve async işler birikir — queue boyutunu izleyin.

Redis zayıflayınca queue gecikmeleri artar — sağlık endpoint'i günlük kontrol edin.

Failed job artış trendinde toplu retry yapmayın; önce kaynağı bulun.
💰
Finansal Riskler
Invoice run öncesi dönem ve kapsam doğrulayın — yanlış dönem çift fatura üretir.

Reconciliation düzenli kontrol edilmeli; gecikmiş tespit maliyeti arttırır.

Overdue ve credit limit bloğu manuel bypass edilmemeli; çift onay mekanizması gerekir.
🔒
Güvenlik Riskler
API key'ler güvenli kanalda saklanmalı ve periyodik rotasyona alınmalı.

JWT secret production'da güçlü ve uzun olmalı; test değeri bırakılmamalı.

Role/tenant kontrolü hiçbir public endpoint dışında kapatılamaz.
🚨
Stok Race Condition: Eş zamanlı yüksek trafikte sipariş gelirse sistem distributed lock kullanarak stok çakışmasını önler. Lock timeout alınırsa otomatik olarak 409 döner; manuel müdahale gerekmez.
06

Yönetim Rutini

Sistemi nasıl sağlıklı tutarsınız — günlük, haftalık, aylık

☀️ Günlük
  • GET /api/health → DB + Redis durumu kontrol
  • Failed jobs ve DLQ listesi kontrol
  • Açık siparişler ve shipping backlog izle
  • Kritik alarmlar: rate limit, lock timeout, webhook failed
  • Worker sürecinin ayakta olduğunu doğrula
📋 Haftalık
  • Reconciliation raporu al ve incele
  • Audit log üzerinden kritik aksiyonları gözden geçir
  • Satıcı bazlı gecikme ve risk trendleri
  • API key kullanım raporunu değerlendir
  • Rotasyon planı güncelle
📊 Aylık
  • Invoice run çalıştır (ay sonu)
  • Payment bağlantılarını doğrula
  • Finans ledger tutarlılığını kontrol et
  • SLA ve fee model performansını değerlendir
  • Dependency güvenlik taraması (npm audit)
07

Rol Bazlı Sorumluluk Matrisi

Kim neyi görür, yönetir, kararlar verir?

🛡️
Admin
Kullanıcı & rol yönetimi
Satıcı onboarding
Sistem sağlığı
Override kararlar
API key üretimi
Audit log görüntüleme
🏪
Satıcı
Ürün seçim/toggle
Sipariş takibi
Kargo durumu
Fatura listesi/detay
Entegrasyon anahtarları
📦
Depo
Picking / Packing
Shipping & tracking
Lot/expiry doğrulama
Hasar/eksik kaydı
Stok hareketi görüntüleme
📒
Muhasebe
Invoice run tetikleme
Payment durumu güncelleme
Reconciliation raporu
Finans blok kararları
Ledger görüntüleme
🚚
Tedarik
Tedarikçi yönetimi
Purchase Order takibi
Min stok / reorder
Tedarik süreci
Mal kabul kaydı
08

Sunum Demo Akışı

Toplantıda kullanabileceğiniz sıralı senaryo

1
Proje Girişi
Projenin amacını ve çözdüğü problemi kısaca anlatın. "Çok satıcılı fulfillment'ı manuel yönetmenin yarattığı kaos" ile başlayın.
2
Mimari Özet
UI → API → Service → Queue → DB katmanlarını tahtaya/ekrana çizin. Her katmanın sorumluluğunu tek cümleyle ifade edin.
3
Canlı Akış Demosu
Admin ile sisteme giriş → Satıcı API'siyle sipariş oluştur → Stok rezervasyonunu göster → Depo ekranında PICKING → PACKED → SHIP → Satıcı panelinde kargo takibi → Muhasebe'de invoice run tetikle.
4
Güvenlik ve Kontrol
Role guard'ı gösterin (başka rolde yanlış sayfaya erişilemiyor). API key brute-force blok mekanizmasını anlatın. Tenant izolasyonu prensibini açıklayın.
5
Operasyon Ekranları
Failed jobs listesi, DLQ, health endpoint (/api/health), reconciliation raporu ekranlarını gösterin. "Sistemi sadece izlemiyoruz, yönetiyoruz" mesajını verin.
6
Go-Live Hazırlık
npm run go-live:final-gate komutunu çalıştırın. Lint + build + test + smoke adımlarının hepsi yeşil göründüğünde "canlıya çıkmaya hazır" deyin.
7
Müşteri İşletim Planı
Günlük/haftalık/aylık rutin sorumlulukları paylaşın. Rol matrisini gösterin. "Sistemin sizden beklediği tek şey düzenli kontrol ve izleme" mesajıyla kapatın.
8
Soru-Cevap & Kapanış
Açık riskler (SLA, Sprint 5-8 konuları) dürüstçe paylaşın. Sonraki fazlar için sprint öncelikleri listesini gösterin.
09

Demo Hesapları

Sunum sırasında kullanılacak giriş bilgileri

🔑
Production'da bu şifreleri hemen değiştirin. Demo seed şifreler yalnızca geliştirme ortamı içindir. Canlı ortama geçilmeden önce tüm hesaplar güçlü şifreler ile güncellenmelidir.

Hızlı Komut Referansı

AmaçKomut
Geliştirme sunucusunpm run dev
Queue workernpm run queue:worker
Test suitenpm run test
Lint kontrolünpm run lint
Production buildnpm run build
E2E sipariş akışınpm run e2e:order-flow
Finans smoke testnpm run smoke:finance-guards
Reconciliation smokenpm run smoke:critical-flow-reconciliation
Production final gatenpm run go-live:final-gate