Numex E-Ticaret

MIT lisanslı e-ticaret başlangıç iskeleti — Numex AI tarafından geliştirildi.

Bu bir başlangıç iskeletidir, hazır mağaza değildir. Canlı satıştan önce ödeme ve güvenlik gözden geçirilmeli, yasal metinler ve örnek içerik kendi bilgilerinizle değiştirilmelidir.

Vitrin + ürün detay + sepet + kapıda ödeme + Stripe bağlantısı + yönetim paneli. Harici veritabanı sunucusu gerekmez, tek komutla ayağa kalkar.

---

İçindekiler

• Özellikler
• Hızlı başlangıç
• Ortam değişkenleri
• Ödeme (Stripe)
• Mimari
• Veri modeli
• HTTP uçları
• Mağaza görselleri
• Canlıya çıkış kontrol listesi
• Katkı
• Lisans

---

Özellikler

Vitrin

• Ana sayfa: hero, güven şeridi, öne çıkan ürünler, kategori vitrini, müşteri yorumları, bülten bloğu
• Ürün listesi: kategori filtresi, arama, sıralama
• Ürün detay: puan, stok durumu, teslimat bilgisi, atıf/kaynak kutusu, benzer ürünler
• Sipariş takibi: sipariş kodu ile durum sorgulama
• Duyarlı yerleşim: masaüstü, tablet ve 360 px'e kadar telefon

Sepet ve sipariş

• Oturum tabanlı sepet (giriş zorunlu değil), miktar güncelleme ve ürün çıkarma
• Adres bilgili sipariş formu, sunucu tarafı doğrulama
• Sipariş kodu üretimi (NMX-YYYYMMDD-XXXXXX)
• Sipariş sonrası başarı / iptal ekranları

Ödeme

| Yöntem | Durum | |---|---| | Kapıda ödeme | Çalışır, gerçek tıklama yoluyla denendi. Anahtar yoksa varsayılan; ALLOW_COD_FALLBACK=false ile kapanır | | Stripe Checkout | Kod ve imzalı webhook yazıldı, webhook imzası sahte anahtarla sınandı. Gerçek bir Stripe test hesabıyla uçtan uca denenmedi | | iyzico | Deneysel, henüz çalışmıyor. Yetki başlığı iyzico'nun beklediği biçimde değil, kimlik no ve IP alanları sabit değer. IYZICO_DENEYSEL=true olmadan ödeme sayfasında görünmez |

Stok düşümü tek noktada ve idempotenttir: aynı ödeme birkaç kez bildirilse de stok yalnız bir kez düşer.

Yönetim paneli (/admin)

• bcrypt ile hash'lenmiş yönetici girişi, oturum koruması
• Dashboard: ciro, sipariş/ürün sayıları, satış trendi grafiği, durum dağılımı, son işlemler
• Ürün yönetimi: ekleme, düzenleme, aktif/pasif, öne çıkan, stok ve fiyat
• Kategori yönetimi, sipariş listesi ve sipariş durumu güncelleme

Güvenlik

• Parametreli SQL sorguları (SQL enjeksiyonuna kapalı)
• bcrypt şifre hash'leme; düz metin şifre saklanmaz
• Yönetici rotalarında yetki kontrolü
• Stripe webhook imza doğrulaması (ham gövde üzerinden)
• Sırlar .env'de tutulur, .gitignore ile depo dışında bırakılır

---

Hızlı başlangıç

git clone <depo-adresi> numex-eticaret
cd numex-eticaret
npm install
cp ornek.env .env      # Windows PowerShell: Copy-Item ornek.env .env

.env içindeki SESSION_SECRET, ADMIN_EMAIL ve ADMIN_PASSWORD değerlerini düzenleyin, sonra:

npm start

| Adres | Açıklama | |---|---| | http://localhost:3000 | Mağaza vitrini | | http://localhost:3000/urunler | Ürün listesi | | http://localhost:3000/admin | Yönetim paneli |

İlk açılışta .env değerleriyle yönetici hesabı oluşturulur ve örnek katalog tohumlanır. .env'deki ADMIN_PASSWORD sonradan değiştirilirse, sunucu yeniden başlatıldığında veritabanındaki hash otomatik olarak yeni değerle eşitlenir.

Geliştirme modu (dosya değişiminde otomatik yeniden başlatma):

npm run dev

---

Linux notu: Hazır sqlite3 paketi glibc 2.38 ister (Debian 13, Ubuntu 24.04 ve üstü). Eski sistemde uygulama açılmazsa daha yeni bir sürüm kullanın.

Ortam değişkenleri

ornek.env dosyasını .env olarak kopyalayıp doldurun.

| Değişken | Zorunlu | Açıklama | |---|---|---| | PORT | — | Sunucu portu (varsayılan 3000) | | SESSION_SECRET | evet | Oturum imzalama anahtarı; canlıda uzun rastgele bir değer olmalı | | ADMIN_EMAIL | evet | Yönetici e-posta adresi | | ADMIN_PASSWORD | evet | Yönetici şifresi (yalnız ilk oluşturmada ve senkron için kullanılır) | | SITE_NAME | — | Vitrinde görünen mağaza adı | | STRIPE_SECRET_KEY | — | Stripe gizli anahtarı (sk_test_… / sk_live_…) | | STRIPE_PUBLISHABLE_KEY | — | Stripe açık anahtarı (pk_test_… / pk_live_…) | | STRIPE_WEBHOOK_SECRET | — | Webhook imza anahtarı (whsec_…) | | ALLOW_COD_FALLBACK | — | Stripe yokken kapıda ödemeye izin ver (varsayılan true) | | IYZICO_DENEYSEL | — | true olmadan iyzico görünmez; deneysel, henüz çalışmıyor | | DEMO_MODU | — | true ise demo şeridi çıkar, panel salt okunur olur | | DB_PATH | — | SQLite dosya yolu (varsayılan data/numex.db) | | CURRENCY | — | Para birimi (varsayılan try) |

STRIPE_SECRET_KEY ve SESSION_SECRET asla depoya girmez. .env dosyası .gitignore içindedir.

---

Ödeme (Stripe)

1. Stripe paneli → API anahtarları adresinden anahtarları alın.

2. .env içine yazın:

   STRIPE_SECRET_KEY=sk_test_...
   STRIPE_PUBLISHABLE_KEY=pk_test_...
   

3. Webhook'u yerelde dinleyin:

   stripe listen --forward-to localhost:3000/odeme/webhook
   

   Komutun verdiği whsec_... değerini STRIPE_WEBHOOK_SECRET olarak .env'e ekleyin.

4. Test kartı: 4242 4242 4242 4242 — gelecekte bir son kullanma tarihi, herhangi 3 haneli CVC.

Anahtar boşsa sipariş kapıda ödeme olarak kaydedilir. Canlıya çıkarken sk_live_… ve gerçek webhook uç noktası kullanılmalıdır.

---

Mimari

İstek
  │
  ├─ express.urlencoded / json      gövde ayrıştırma
  ├─ express.static                 public/ ve data/uploads/
  ├─ express-session                oturum (cookie tabanlı)
  ├─ connect-flash                  tek seferlik mesajlar
  ├─ attachCart                     sepeti oturuma bağlar
  ├─ res.locals                     siteName, currentUser, cartCount, biçimleyiciler
  │
  ├─ routes/magaza.js               /  /urunler  /urun/:slug  /siparis-takip  /hakkimizda
  ├─ routes/sepet.js                /sepet  (ekle, güncelle, çıkar)
  ├─ routes/odeme.js                /odeme  /odeme/basarili  /odeme/iptal  /odeme/webhook
  ├─ routes/admin.js                /admin (giriş + korumalı panel rotaları)
  │
  └─ hata yakalayıcı                404 ve 500 için EJS sayfası

src/
  server.js            uygulama girişi, ara katman sırası, rota bağlama
  db.js                SQLite bağlantısı, şema (idempotent), get/all/run sarmalayıcıları
  seed.js              örnek katalog + yönetici hesabı (kendi kendine yeterli)
  kapak.js             ürün görseli yoksa üretilen SVG kapak
  yardimci.js          TL/tarih biçimleyiciler, durum etiketleri
  middleware/
    auth.js            requireAdmin — oturum kontrolü
    cart.js            attachCart — sepeti oturuma bağlar
  routes/
    magaza.js  sepet.js  odeme.js  admin.js
  views/
    *.ejs              vitrin şablonları
    partials/          ust.ejs, alt.ejs, urun-kart.ejs
    admin/             panel şablonları ve panel partial'ı
public/
  css/stil.css         tek stil dosyası (tasarım token'ları :root içinde)
data/
  numex.db             SQLite veritabanı (git'e girmez)
  uploads/             yüklenen ürün görselleri (git'e girmez)

Tasarım kararları

• Sunucusuz veritabanı: SQLite — kurulum derdi yok, tek dosya yedeklenir. Trafik artınca db.js içindeki sarmalayıcılar korunarak PostgreSQL'e taşınabilir.
• Sunucu tarafı render (EJS): ilk boya hızlı, SEO bedava, istemci paketi yok.
• Ödeme mantığı ayrı rotada (routes/odeme.js): sağlayıcı değişirse yalnız bu dosya yeniden yazılır; imza doğrulaması ham gövde üzerinden yapılır.
• Tasarım token'ları: renk, boşluk, gölge :root altında; tema değişikliği tek yerden yapılır.

---

Veri modeli

users        id, email (unique), password_hash, name, role, created_at
categories   id, name, slug (unique), description, sort_order
products     id, name, slug (unique), category_id → categories,
             description, price, stock, image, reference,
             featured, active, created_at
orders       id, order_code (unique), customer_name, customer_email,
             customer_phone, address, city, note, total,
             status, payment_method, payment_status,
             stripe_session_id, created_at
order_items  id, order_id → orders (CASCADE), product_id → products,
             product_name, unit_price, quantity

Sipariş durumları: yeni → hazirlaniyor → kargoda → teslim (ve iptal). Ödeme durumları: bekliyor, odendi, basarisiz, iade.

reference alanı, ürünün kaynağını/atfını taşır ve ürün sayfasında ayrı kutuda gösterilir — açık kaynak ve akademik içerikte atıf bütünlüğü için.

---

HTTP uçları

| Yöntem | Yol | Açıklama | |---|---|---| | GET | / | Ana sayfa | | GET | /urunler | Ürün listesi (?kategori=, ?q=, ?sirala=) | | GET | /urun/:slug | Ürün detay | | GET | /sepet | Sepet | | POST | /sepet/ekle | Sepete ürün ekle | | POST | /sepet/guncelle | Miktar güncelle | | POST | /sepet/cikar | Üründen çıkar | | GET | /odeme | Sipariş formu | | POST | /odeme | Sipariş oluştur / Stripe oturumu aç | | GET | /odeme/basarili | Ödeme başarılı | | GET | /odeme/iptal | Ödeme iptal | | POST | /odeme/webhook | Stripe webhook (imza doğrulamalı) | | GET | /siparis-takip | Sipariş kodu ile sorgulama | | GET | /hakkimizda | Kurumsal sayfa | | GET | /admin/giris · POST | Yönetici girişi | | POST | /admin/cikis | Çıkış | | GET | /admin | Dashboard |

---

Mağaza görselleri

Ürüne panelden görsel yüklenmezse src/kapak.js devreye girer: kategoriye göre renklenen, ürün kısaltmasını taşıyan bir SVG kapak üretilir. Bu sayede katalog hiçbir zaman boş gri kutu göstermez; gerçek görsel yüklendiğinde otomatik olarak onun yerini alır.

---

Canlıya çıkış kontrol listesi

• [ ] Ödeme yöntemi seçildi ve kendi hesabınızla test ödemesiyle uçtan uca denendi
• [ ] Marka adı, logo ve alt bilgi (src/views/partials) kendi firmanızla değiştirildi
• [ ] /yasal sayfasındaki KVKK ve mesafeli satış metinleri bir hukukçu tarafından dolduruldu
• [ ] Ana sayfadaki örnek yorumlar, teslimat ve iade sözleri gerçek koşullarınıza göre düzenlendi
• [ ] Örnek ürünler silindi
• [ ] SESSION_SECRET uzun ve rastgele (en az 32 karakter)
• [ ] ADMIN_PASSWORD güçlü ve .env dışında hiçbir yerde yok
• [ ] NODE_ENV=production
• [ ] HTTPS arkasında çalışıyor; src/server.js içinde app.set('trust proxy', 1) ve cookie.secure: true eklendi
• [ ] Stripe sk_live_… + gerçek webhook uç noktası tanımlı
• [ ] data/numex.db için düzenli yedekleme kurulu
• [ ] ALLOW_COD_FALLBACK bilinçli olarak seçildi
• [ ] Oturum deposu kalıcı bir depoya alındı (varsayılan bellek deposu tek süreç içindir)
• [ ] Vekil sunucu arkasında giriş sınırı gerçek IP'yi görüyor (trust proxy)
• [ ] Sunucu logları ve hata izleme açık

---

Katkı

1. Dal açın: git checkout -b ozellik/kisa-ad
2. Değişikliği yapın, npm start ile ayağa kaldırıp gerçekten deneyin
3. Anlamlı bir commit mesajı yazın
4. Pull request açın; neyi neden değiştirdiğinizi kısaca anlatın

Hata bildirirken: beklenen davranış, gerçekleşen davranış ve yeniden üretme adımları yeterli.

---

Lisans

MIT — ayrıntı için LICENSE. Ticari kullanım, değiştirme ve yeniden dağıtım serbesttir; telif bildirimi korunmalıdır.

Geliştiren: Numex AI — https://www.numexai.com.tr

---

Numex ile geliştirildi

Bu iskelet, Numex kod ajanıyla yazıldı. Numex'i denemek için: https://www.numexai.com.tr