136 lines
4.8 KiB
Plaintext
136 lines
4.8 KiB
Plaintext
Ürün Gereksinim Belgesi (PRD)
|
||
Proje Adı: Stripe Ödeme Geçidi Ara Katmanı (Payment Gateway Middleware)
|
||
|
||
Versiyon: 1.0
|
||
|
||
Tarih: 15 Ocak 2026
|
||
|
||
Durum: Taslak
|
||
|
||
1. Proje Özeti
|
||
Bu proje, harici web sitelerinden (istemci) gelen ödeme taleplerini karşılayan, Stripe altyapısını kullanarak tahsilatı gerçekleştiren ve kullanıcıyı işlem sonucuna göre ilgili web sitesine geri yönlendiren merkezi bir ödeme sayfası ve yönetim panelidir.
|
||
|
||
Temel Amaç: Farklı projeler veya web siteleri için tek bir noktadan güvenli ödeme almak ve tüm işlemleri tek bir admin panelinden takip etmek.
|
||
|
||
2. Teknik Yığın (Tech Stack)
|
||
Frontend & Backend: Next.js 15 (App Router, Server Actions)
|
||
|
||
Veritabanı & Kimlik Doğrulama: Supabase (PostgreSQL, Auth)
|
||
|
||
Ödeme Altyapısı: Stripe (Stripe Elements & Webhooks)
|
||
|
||
UI Framework: Tailwind CSS + Shadcn/UI
|
||
|
||
Deployment: Vercel (Önerilen)
|
||
|
||
3. Kullanıcı Rolleri
|
||
Son Kullanıcı (Payer): Ödemeyi yapacak olan kişi.
|
||
|
||
Sistem Admini: Ödemeleri izleyen, iade (refund) işlemlerini yöneten ve raporları gören yetkili.
|
||
|
||
Entegre Sistem (Client): Kullanıcıyı ödeme sayfasına yönlendiren harici web sitesi.
|
||
|
||
4. Kullanıcı Akışları (User Flows)
|
||
4.1. Ödeme Akışı
|
||
|
||
Başlatma: Kullanıcı, harici siteden (örn: alisveris.com) "Öde" butonuna basar.
|
||
|
||
Yönlendirme: Kullanıcı şu parametrelerle sisteme gelir:
|
||
|
||
amount: Tutar (örn: 100)
|
||
|
||
currency: Para birimi (örn: TRY)
|
||
|
||
ref_id: Harici sitedeki sipariş no (örn: SIP-999)
|
||
|
||
callback_url: İşlem bitince dönülecek URL
|
||
|
||
client_secret (Opsiyonel/Güvenlik): Tutarlılığı doğrulamak için imza.
|
||
|
||
Ödeme Sayfası: Sistem parametreleri doğrular, Stripe üzerinde bir PaymentIntent oluşturur ve kullanıcıya kredi kartı formunu gösterir.
|
||
|
||
İşlem: Kullanıcı kart bilgilerini girer ve onaylar.
|
||
|
||
Sonuç:
|
||
|
||
Başarılı: Supabase güncellenir -> Kullanıcı callback_url?status=success&ref_id=... adresine yönlendirilir.
|
||
|
||
Başarısız: Hata mesajı gösterilir -> Kullanıcı tekrar denemeye veya callback_url?status=failed adresine yönlendirilir.
|
||
|
||
4.2. Admin Paneli Akışı
|
||
|
||
Admin, /admin rotasından Supabase Auth ile giriş yapar.
|
||
|
||
Dashboard'da günlük toplam ciro ve son işlemleri görür.
|
||
|
||
İşlem listesinde tarih, tutar, durum ve kaynak siteye göre filtreleme yapar.
|
||
|
||
5. Fonksiyonel Gereksinimler
|
||
5.1. Ödeme Arayüzü (Checkout Page)
|
||
|
||
Dinamik Tutar: URL parametresinden gelen tutarı ekranda göstermelidir.
|
||
|
||
Stripe Elements: Kart numarası, SKT ve CVC için Stripe'ın güvenli iframe (Elements) yapısı kullanılmalıdır.
|
||
|
||
Validasyon: Eksik parametre ile gelindiyse (örn: tutar yoksa) kullanıcıya "Geçersiz İşlem" hata sayfası gösterilmelidir.
|
||
|
||
Loading State: Ödeme işlenirken buton "İşleniyor..." durumuna geçmeli ve tekrar tıklama engellenmelidir.
|
||
|
||
5.2. Backend & API (Next.js Server Actions)
|
||
|
||
Create Payment Intent: Sayfa yüklendiğinde Stripe API ile iletişim kurup bir ödeme oturumu başlatmalıdır.
|
||
|
||
Webhook Listener: Stripe'tan gelen asenkron payment_intent.succeeded ve payment_intent.payment_failed olaylarını dinleyen bir API route (/api/webhooks/stripe) olmalıdır.
|
||
|
||
Kritik: Veritabanındaki ödeme durumu sadece Webhook'tan gelen bilgiye göre "Paid" olarak işaretlenmelidir (Kullanıcı tarayıcıyı kapatsa bile işlem kaydedilmelidir).
|
||
|
||
5.3. Admin Paneli
|
||
|
||
Oturum Yönetimi: Sadece belirli e-posta adreslerine sahip adminler giriş yapabilmelidir.
|
||
|
||
İşlem Listesi Tablosu:
|
||
|
||
Sütunlar: ID, Tutar, Para Birimi, Durum (Badge), Kaynak URL, Referans ID, Tarih.
|
||
|
||
Filtreler: Başarılı/Başarısız, Tarih Aralığı.
|
||
|
||
Dashboard Widgetları:
|
||
|
||
Toplam Ciro (Total Revenue)
|
||
|
||
Başarılı İşlem Sayısı
|
||
|
||
Başarısız İşlem Oranı
|
||
|
||
6. Veritabanı Şeması (Supabase)
|
||
Tablo Adı: transactions
|
||
|
||
Kolon Adı Veri Tipi Açıklama
|
||
id UUID (PK) Benzersiz işlem ID'si
|
||
created_at Timestamptz İşlem oluşturulma tarihi
|
||
amount Numeric Tutar (Örn: 150.50)
|
||
currency Text Para birimi (TRY, USD)
|
||
status Text pending, succeeded, failed
|
||
stripe_pi_id Text Stripe Payment Intent ID
|
||
source_ref_id Text Harici sitenin sipariş numarası
|
||
callback_url Text Geri dönüş URL'i
|
||
metadata JSONB Ekstra bilgiler (Müşteri IP, email vb.)
|
||
7. Güvenlik Gereksinimleri
|
||
SSL: Tüm sistem HTTPS üzerinden çalışmalıdır.
|
||
|
||
Environment Variables: Stripe Secret Key ve Supabase Key'leri asla client-side kodunda ifşa edilmemelidir.
|
||
|
||
CSRF Koruması: Next.js yerleşik korumaları aktif olmalıdır.
|
||
|
||
Basit Güvenlik (V1 için): Harici site ile backend arasında bir "Secret Key" belirlenip, URL manipülasyonunu önlemek için basit bir hash kontrolü eklenebilir (İleri fazda önerilir).
|
||
|
||
8. Geliştirme Yol Haritası (Fazlar)
|
||
Faz 1: Next.js kurulumu, Supabase bağlantısı ve Veritabanı tablosunun oluşturulması.
|
||
|
||
Faz 2: Stripe entegrasyonu ve Ödeme Sayfası (Checkout) tasarımı.
|
||
|
||
Faz 3: Webhook kurulumu (Ödemenin veritabanına işlenmesi).
|
||
|
||
Faz 4: Admin Paneli geliştirilmesi.
|
||
|
||
Faz 5: Test ve Canlıya Alım (Deployment). |