# 🛒 Sale Modülü Geliştirici Kılavuzu (sale/GUIDE.md)
Bu modül; sepet yönetimi, bölgesel kargo & desi hesaplaması, promosyon/kupon motoru, çoklu teslimat & fatura adresi seçimi (bireysel/kurumsal), ödeme adımı (checkout) ve sipariş oluşturma süreçlerini yönetir.
---
## 📌 1. Dosya Yapısı ve Sorumluluklar (Freedom Bağımsız Satış Mimarisi)
Bu modül `sale/services.php` çekirdeği ile **tamamen bağımsız (standalone)** bir e-ticaret, sepet, bölgesel kargo ve sipariş motoru olarak çalışır. `view/` katmanı olmadan da herhangi bir temada veya headless API projesinde kullanılabilir.
- **`services.php`**: Kendi veritabanı bağlantısı (`sale_db`), ayar okuyucusu (`sale_settings`), para birimi/kur çeviricisi (`sale_convert_currency`), bölgesel kargo & desi hesaplayıcısı (`sale_calculate_shipping`), `locations.json` konum motoru (`sale_get_locations`), kupon doğrulayıcısı (`sale_coupon_apply`) ve sepet yöneticisini (`sale_cart_get`, `sale_cart_add`, `sale_cart_update`, `sale_cart_remove`, `sale_cart_clear`) barındıran çekirdek servis kütüphanesidir.
- **`cart.php`**: Müşteri sepeti, varyantlı ürün ekleme/çıkarma/adet güncelleme (`itemId::variantSku` formatı), stok sınırı kontrolleri, kupon kodu uygulama, bölgesel kargo ön izleme ve ücretsiz kargo barı.
- **`checkout.php`**: Kayıtlı adresler arasından tek tıkla seçim, yeni teslimat adresi girişi, bireysel / kurumsal fatura seçimi, ayrı fatura adresi seçeneği, `sale/locations.json` üzerinden dinamik il/ilçe seçimi, ödeme yöntemi seçimi (Kredi Kartı / Taksit, Havale/EFT, Kapıda Ödeme, Mağazada Ödeme), sipariş öncesi varyant stok doğrulaması ve sipariş onaylama.
- **`locations.json`**: Türkiye'nin 81 ili, tüm ilçeleri ve 7 coğrafi bölge eşleştirmesini barındıran JSON veri kaynağı.
- **`order_success.php`**: Başarılı sipariş sonrası sipariş numarası, özet ve havale IBAN bilgilerini gösteren onay ekranı.
---
## 🛍️ 2. Sepet & Varyasyon Anahtarlama Mantığı
1. **Sepet Anahtarı (`cartKey`):**
- Varyantsız ürün: `it_xxx`
- Varyantlı ürün: `it_xxx::SKU-123` (veya `it_xxx::variant_key`)
2. **Stok Denetimi:**
- Eğer sistem ayarlarında `ecommerce.stock_tracking == 1` ise, sepete ekleme ve adet artırma sırasında ilgili varyantın veya ürünün `stock` limiti kontrol edilir.
- Stok yetersizse `is_out_of_stock` veya `stock_exceeded` bayrakları set edilir, kullanıcıya bilgilendirme uyarısı verilir.
3. **Çoklu Para Birimi & Çift Yönlü Dinamik Kur Çevrimi (Multi-Currency Engine):**
- **Ürün Para Birimi Bağımsızlığı:** Bir ürün panelde hangi para birimiyle girilmiş olursa olsun (Örn: `399 USD`), sepete eklendiğinde `sale_cart_get()` tarafından mağazanın/kullanıcının aktif para birimine (`sale_get_currency()`) anlık kurlarla (`settings.rates`) çevrilir.
- **Doğru Kur Çevrim Formülü:** Türk Lirası tabanlı kurlarda ($1\text{ USD} = 48.5437\text{ TL}$):
$$\text{Tutar (TRY)} = \text{Miktar} \times \text{fromRate}$$
$$\text{Hedef Para Birimi} = \frac{\text{Tutar (TRY)}}{\text{toRate}}$$
Örn: 399 USD bir ürün TL sepetinde $399 \times 48.5437 = 19.368,94\text{ TL}$ olarak hesaplanır. Kullanıcı üst barda USD seçerse 100 TL'lik bir ürün $100 / 48.5437 = 2.06\text{ USD}$ olarak gösterilir ve işlem görür.
- **Varyasyon Fiyatları:** Varyantların özel para birimi veya fiyatları varsa, her varyant da kendi para biriminden aktif sepete dinamik olarak çevrilir.
---
## 🏠 3. Çoklu Adres, Ülke ve Fatura Seçimi (Checkout Adımı - /odeme)
1. **Routing & Rota Kuralı:**
- `/odeme` ve `/checkout` adresleri kesinlikle statik bir CMS sayfası (`type=page`) olarak algılanmaz; `.htaccess` ve `index.php` seviyesinde doğrudan `sale/checkout.php` modülüne yönlendirilir.
2. **Uluslararası Ülke Seçimi (`country`):**
- Ödeme formunda en üstte **Ülke Seçicisi** yer alır (Varsayılan: `Türkiye`).
- **Türkiye Seçildiğinde:** 81 il ve bağlı ilçeler dinamik dropdown olarak listelenir.
- **Yurtdışı Seçildiğinde (Almanya, ABD, İngiltere vb.):** İl dropdown'ı gizlenir; serbest metin formatında **Şehir / Eyalet** (`intl_city`) ve **Posta Kodu** (`postal_code`) girişleri açılır.
3. **Şehir İsimlerinin Sadeliği Kuralı:**
- Şehir seçim kutusunda (`#citySelect`, `#billingCitySelect`) şehir isimlerinin yanına kesinlikle *"A Bölgesi"*, *"B Bölgesi"* veya coğrafi bölge adları **eklenemez**. Şehirler yalnızca yalın adlarıyla (`İstanbul`, `Ankara`, `İzmir` vb.) listelenir. Bölge tespiti arayüzde gizli `data-region` özniteliği üzerinden arka planda yürütülür.
4. **Kayıtlı Adres Seçimi (`saved-addresses-grid`):**
- Oturum açmış kullanıcının kayıtlı adresleri listelenir (`v_auth_get_addresses()`).
- Bir adrese tıklandığında alıcı adı, telefon, ülke, il, ilçe ve açık adres otomatik doldurulur ve kargo ücreti anında hesaplanır.
- Eğer seçilen adres kurumsal ise fatura tipi otomatik olarak "Kurumsal" moduna geçer ve vergi bilgileri doldurulur.
5. **Fatura Türü (Bireysel / Kurumsal):**
- **Bireysel Fatura:** TC Kimlik Numarası girilebilir. Eğer boş bırakılırsa mevzuat gereği otomatik olarak **`11111111111`** atanır.
- **Kurumsal Fatura:** Firma Tam Unvanı, Vergi Dairesi ve Vergi Numarası alanları zorunludur.
6. **Ayrı Fatura Adresi (`billing_same_as_shipping`):**
- Varsayılan olarak fatura adresi teslimat adresi ile aynıdır.
- Kutu işareti kaldırıldığında ayrı fatura ismi, telefonu, ili, ilçesi ve açık fatura adresi girilebilir.
7. **Hesaba Kaydetme (`save_to_account`):**
- Giriş yapmış müşteriler yeni girdikleri teslimat adresini tek tıkla profillerine kaydedebilirler.
---
## 🚚 4. Bölgesel & Uluslararası Kargo ve Desi Fiyatlandırması
Kargo hesaplaması hem yurtiçi 7 coğrafi bölgeyi hem de uluslararası taşıyıcıları destekler (`sale_calculate_shipping()`):
1. **Yurtiçi Gönderiler (Türkiye - 81 İl, 7 Bölge):**
- `sale/locations.json` üzerinden seçilen ilin coğrafi bölgesi tespit edilir (`marmara`, `ege`, `akdeniz`, `ic_anadolu`, `karadeniz`, `dogu_anadolu`, `guneydogu`).
- Desi dilimlerine (`1-2 Desi`, `3-5 Desi`, `6-10 Desi`, `10+ Desi ek birim`) göre kargo ücreti hesaplanır.
- Sepet ara toplamı `free_shipping_threshold` (Örn: 1.000 TL) değerini aştığında kargo bedeli `0.00 TL` (Ücretsiz) olur.
2. **Yurtdışı Gönderiler (ShipEntegra, Navlungo, DHL, FedEx, vb.):**
- Ülke kodu Türkiye harici olduğunda (`$country !== 'TR'`), sistem ülkeyi 4 uluslararası navlun bölgesine eşler:
- **Zone 1:** Avrupa (Almanya, Fransa, Hollanda, Birleşik Krallık, İtalya, İspanya, Avusturya, İsviçre vb.)
- **Zone 2:** Kuzey Amerika (ABD, Kanada)
- **Zone 3:** Körfez, Orta Doğu & Kafkaslar (BAE, Suudi Arabistan, Katar, Kuveyt, Azerbaycan, Kazakistan vb.)
- **Zone 4:** Dünya Geneli (Diğer tüm ülkeler)
- Kargo firmasındaki uluslararası matristen (`international_matrix`) desi adımlarına (`0.5kg`, `1kg`, `2kg`, `3kg`, `5kg`, `+ek kg`) göre navlun belirlenir.
- Uluslararası navlun bedeli (EUR/USD), aktif sepet para birimine dinamik olarak çevrilerek faturaya ve siparişe yansıtılır.
---
## 💳 5. Ödeme & Sanal POS Taksit Entegrasyonu
Checkout sayfası `payment/` modülü ile doğrudan haberleşir:
- Kartın ilk 6 hanesi (BIN) girildiğinde `/payment/ajax/saas.php?action=get_installments&bin=...` çağrılır.
- Seçilen bankanın taksit tablosu anında render edilir.
- Seçilen taksit vade farkı sepete dinamik eklenir ve `v_create_order()` çağrısına aktarılır.
---
## 📄 6. Yasal Sözleşme Onayları
Checkout adımında **Ön Bilgilendirme Koşulları** ve **Mesafeli Satış Sözleşmesi** modal olarak açılır:
```html
Ön Bilgilendirme Koşulları
Mesafeli Satış Sözleşmesi
```
---
## 🎨 7. Modüler CSS Mimarisi (`sale/assets/css/sale.css`)
> 💡 **Önemli Kural:** Satış, sepet ve ödeme ekranlarının tüm stilleri genel CSS dosyasına bağımlı kalmadan, doğrudan `sale/assets/css/sale.css` içinde tutulur. Böylece `sale/` modülü başka bir projeye taşındığında stilleriyle birlikte eksiksiz çalışır.
- `cart-layout-grid`, `cart-item-card`, `cart-qty-stepper`
- `checkout-layout-grid`, `saved-addresses-grid`, `saved-address-card`, `invoice-type-toggle`
- `payment-methods-grid`, `pay-method-card`
- Taksit ve banka seçim tabloları