# V1 Müşteri Kurulum Rehberi (Customer Installation Guide)

Bu doküman, yeni e-ticaret sisteminin canlı (production) veya test sunucularına sıfırdan kurulumunu adım adım açıklamaktadır. Kurulumu gerçekleştirecek teknik ekibin veya müşterinin bu rehberi sırasıyla uygulaması gerekir.

---

## 1. Sunucu Gereksinimleri
Sistemin kararlı ve yüksek performanslı çalışabilmesi için aşağıdaki sunucu gereksinimlerinin karşılanması zorunludur:

* **İşletim Sistemi:** Linux (Ubuntu 20.04+, Debian, AlmaLinux veya CentOS önerilir) veya uyumlu paylaşımlı hosting.
* **Web Sunucusu:** Apache, Nginx veya LiteSpeed (Nginx önerilir).
* **Veritabanı Sunucusu:** MySQL 8.0+ veya MariaDB 10.5+.
* **SSL Sertifikası:** HTTPS protokolü üzerinden güvenli haberleşme (API'ler, ödeme geçitleri ve lisans kontrolü için zorunludur).
* **SSH Erişimi & Composer:** (Yöntem A paketi ile kurulum yapılacaksa gereklidir).

---

## 2. PHP Gereksinimleri & PHP Extension Listesi
Uygulama, PHP'nin modern özelliklerini ve güvenlik standartlarını kullanır.
* **PHP Sürümü:** **PHP 8.2 veya üzeri** (PHP 8.3 önerilir).

### Zorunlu PHP Eklentileri (Extensions):
Aşağıdaki eklentilerin sunucu üzerinde aktif olduğundan emin olunmalıdır:
* `pdo` & `pdo_mysql` (Veritabanı bağlantısı için)
* `openssl` (Güvenli şifreleme ve imza doğrulama için)
* `mbstring` (Çoklu bayt karakter desteği için)
* `tokenizer` & `xml` & `ctype` & `json` (Laravel çekirdeği için)
* `curl` (Lisans sunucusu ve ödeme API entegrasyonları için)
* `gd` veya `imagick` (Ürün resimlerini yeniden boyutlandırma ve galeri yönetimi için)
* `zip` (Yedekleme ve güncelleme işlemleri için)
* `fileinfo` (Yüklenen medya dosyalarının MIME tiplerini güvenli doğrulamak için)

---

## 3. Web Root / Document Root Ayarı
Güvenlik nedeniyle, web sunucusunun public erişim kök dizini (Web Root) uygulamanın ana dizini değil, mutlaka **`public/`** alt dizini olarak ayarlanmalıdır.

* **Örnek Doğru Yapılandırma:** `/home/user/domains/example.com/public_html/public`
* **Nginx Sunucu Bloğu Örneği:**
  ```nginx
  root /var/www/yeni_eticaret/public;
  index index.php index.html;
  ```

### Paylaşımlı Hosting (Shared Hosting) İçin Alternatif Yöntem:
Eğer paylaşımlı hosting panelinizde Document Root'u `public/` olarak ayarlamanıza izin verilmiyorsa, aşağıdaki adımlarla kurulum yapabilirsiniz:
1. Proje kök dizinindeki tüm ana dosyaları ve klasörleri (`app/`, `bootstrap/`, `config/`, `vendor/` vb.) web üzerinden erişilemeyen bir üst dizine (örneğin `/home/kullanici/yeni_eticaret/`) yükleyin.
2. Sadece `public/` klasörünün içindekileri web kök dizinine (örneğin `/home/kullanici/public_html/`) taşıyın.
3. Web kök dizinine taşıdığınız `index.php` dosyasını açıp, üst dizindeki Laravel çekirdeğine giden yolları (`autoload.php` ve `app.php` yollarını) güncelleyin.
4. **Hayati Uyarı:** `.env` dosyası kesinlikle doğrudan web üzerinden erişilebilir (`public_html` altında) olmamalıdır. Aksi halde tüm şifreleriniz ve lisans anahtarınız çalınabilir.

---

## 4. Dosyaların Sunucuya Yüklenmesi
1. Hazırlanan V1 teslim paketini (ZIP formatında) sunucunuza yükleyin.
2. Dosyaları web kök dizinine veya belirlediğiniz dizine çıkartın.
3. Dosya izinlerini (Permission) Laravel standartlarına uygun olarak güncelleyin:
   * `storage/` ve `bootstrap/cache/` klasörleri ile alt klasörlerine web sunucusu yazma yetkisi verilmelidir:
     ```bash
     chmod -R 775 storage bootstrap/cache
     chown -R www-data:www-data storage bootstrap/cache (Ubuntu/Nginx için)
     ```

---

## 5. .env Hazırlığı
1. Proje ana dizininde bulunan `.env.example` veya `.env.production.example` dosyasının bir kopyasını oluşturarak adını **`.env`** yapın.
2. `.env` dosyasını düzenleyerek şu temel ayarları girin:
   * `APP_NAME` (Sitenizin Adı)
   * `APP_ENV=production`
   * `APP_DEBUG=false`
   * `APP_URL` (Sitenizin tam HTTPS adresi, örn: `https://www.example.com`)
3. `DB_` ile başlayan veritabanı bağlantı alanlarını şimdilik boş bırakabilir veya hazırladığınız veritabanı bilgilerini girebilirsiniz (Kurulum Sihirbazı bu alanları otomatik doldurabilir).
4. `LICENSE_SERVER_URL` ve lisans doğrulama bilgilerinin doğruluğunu teyit edin (Geliştirici tarafından verilen varsayılan lisans ayarları kalabilir).

---

## 6. Installer (Kurulum Sihirbazı) ile Kurulum
Tarayıcınızı açıp sitenizin adresine (`https://www.example.com`) gittiğinizde sistem henüz kurulmadığı için otomatik olarak **Kurulum Sihirbazı** (`install.php`) devreye girecektir.

### Kurulum Adımları:
1. **Gereksinim Kontrolü:** Sihirbaz, PHP sürümünüzü ve gerekli eklentileri (PDO, GD, vb.) denetler. Eksik eklenti varsa kurulumu durdurur.
2. **Veritabanı Bağlantısı:** 
   * Veritabanı Sunucusu (genelde `127.0.0.1` veya `localhost`), Veritabanı Adı, Kullanıcı Adı ve Şifre bilgilerini girin.
   * "Bağlantıyı Test Et" butonuyla bilgilerin doğruluğunu teyit edin. Sihirbaz veritabanına bağlanamazsa sonraki adıma geçmenize izin vermez.
3. **Migration & Şema Kurulumu:** 
   * Veritabanı tablolarını ve varsayılan sistem ayarlarını oluşturmak için "Veritabanını Kur" butonuna basın. Arka planda `php artisan migrate --force` komutu çalıştırılacaktır.
4. **İlk Admin (Süper Admin) Oluşturma:**
   * Yönetim paneline giriş yapabilmeniz için ilk Süper Yönetici hesabını (Ad Soyad, E-posta ve şifre) oluşturun.
5. **Lisans Aktivasyonu:**
   * Size tanımlanan **Lisans Anahtarını** ilgili alana girin. Sistem otomatik olarak merkezi lisans sunucusuyla iletişim kurarak lisansı doğrulayacak ve Pro özellikleri aktif edecektir.
6. **Storage Link Oluşturma:**
   * Ürün resimlerinin arayüzde görünebilmesi için sembolik link (`public/storage` -> `storage/app/public`) sihirbaz tarafından oluşturulur.
7. **Kurulumu Tamamlama:**
   * Kurulum bittiğinde sistem otomatik olarak `storage/app/installed.lock` dosyasını oluşturur. Bu kilit dosyası oluştuktan sonra kurulum sihirbazı dışarıdan erişime tamamen kapanır.

---

## 7. Cron / Scheduler Ayarı
Sistemdeki sipariş durumlarının takibi, lisans periyodik kontrolleri, e-posta gönderimleri ve sistem temizliği gibi zamanlanmış görevlerin çalışabilmesi için sunucuda **Cron** tanımı yapılmalıdır.

1. Sunucu terminalinde `crontab -e` komutunu çalıştırın.
2. Aşağıdaki satırı ekleyin (dosya yollarını kendi sunucunuza göre güncelleyin):
   ```cron
   * * * * * php /path/to/project/artisan schedule:run >> /dev/null 2>&1
   ```

---

## 8. Queue Worker (Kuyruk Yöneticisi) Ayarı
E-posta gönderimi ve sipariş faturalandırılması gibi işlemlerin kullanıcıyı bekletmeden arka planda asenkron çalışması için kuyruk sistemi aktiftir.

1. Arka planda işlerin işlenmesi için şu komutu çalıştırın:
   ```bash
   php artisan queue:work --sleep=3 --tries=3 --timeout=90
   ```
2. Bu işlemin sunucu kapansa bile sürekli çalışır durumda kalması için sunucuda **Supervisor** servisini kurmanız önerilir.
### Örnek Supervisor Konfigürasyonu (`/etc/supervisor/conf.d/yeni-eticaret.conf`):
```ini
[program:yeni-eticaret-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/yeni_eticaret/artisan queue:work --sleep=3 --tries=3 --timeout=90
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/yeni_eticaret/storage/logs/worker.log
```

---

## 9. Sistem Ayarları (Kurulum Sonrası Yapılması Gerekenler)

### Mail Ayarları:
Yönetici paneline giriş yapın. **Ayarlar -> E-Posta Ayarları** menüsünden SMTP bilgilerinizi (Sunucu, Port, Kullanıcı Adı, Şifre ve Şifreleme Tipi) girip kaydedin. Bir adet test e-postası göndererek çalıştığını doğrulayın.

### Öme Ayarları:
**Ayarlar -> Ödeme Yöntemleri** menüsünden anlaşmalı olduğunuz ödeme kuruluşu (örn: iyzico, Paytr) API anahtarlarını girin. Güvenlik için test modunda deneme siparişi verip ardından canlı moda geçiş yapın.

### Kargo Ayarları:
**Ayarlar -> Kargo Firmaları** menüsünden kargo fiyatlandırma politikalarını, ücretsiz kargo limitlerini ve API entegrasyonu bilgilerini tanımlayın.

---

## 10. Güvenlik Kontrolleri
Kurulum tamamlandıktan sonra aşağıdaki kritik güvenlik adımlarını mutlaka kontrol edin:

* [ ] `.env` dosyasında `APP_DEBUG=false` ve `APP_ENV=production` olduğunu doğrulayın.
* [ ] Proje ana dizininde `.env` dosyasının web üzerinden doğrudan erişilemediğini (HTTP 403 veya 404 döndüğünü) tarayıcıdan test edin.
* [ ] `storage/app/installed.lock` dosyasının oluştuğunu ve `/install` adresine gidildiğinde kurulum sihirbazının tekrar açılmayıp ana sayfaya yönlendirdiğini doğrulayın.
* [ ] `.env` dosyasındaki `LICENSE_RESPONSE_SECRET` değerinin lokal geliştirme değeri olmadığını, güçlü ve benzersiz bir random string olduğunu teyit edin.
* [ ] Sistem yedekleme veya log dosyalarının `public/` klasörü altında açıkta barındırılmadığından emin olun.

---

## 11. Sık Karşılaşılan Sorunlar (Troubleshooting)

#### 1. Sayfa Açıldığında 500 Internal Server Error Veriyor
* **Çözüm:** `storage/logs/laravel.log` dosyasını inceleyin. Genellikle `storage/` veya `bootstrap/cache/` klasörlerinin yazma izinlerinin (chmod/chown) eksik olmasından kaynaklanır.

#### 2. Görseller Yükleniyor Ama Sitede Kırık/Boş Görünüyor
* **Çözüm:** Sembolik link oluşturulamamıştır. SSH üzerinden `php artisan storage:link` komutunu el ile çalıştırın.

#### 3. Lisans Doğrulama Başarısız Hatası (License Validation Failed)
* **Çözüm:** Sunucunuzun dış dünyaya HTTPS bağlantısı yapabildiğinden ve curl eklentisinin kurulu olduğundan emin olun. Ayrıca `.env` içindeki `LICENSE_SERVER_URL` adresinin erişilebilir olduğunu kontrol edin.

---

## 12. Destek İçin Gerekli Bilgiler
Destek talebi oluştururken hızlı çözüm için aşağıdaki bilgileri hazır bulundurun:
1. Sunucu PHP Sürümü ve İşletim Sistemi bilgisi.
2. `storage/logs/laravel.log` dosyasındaki hata çıktıları.
3. Kullandığınız aktif PHP Extension listesi.
4. Lisans anahtarınızın son 4 hanesi.
