# 📦 İhracat Takip Sistemi — v1 Proje Dokümanı

## Genel Bakış

Bu proje, ihracat satışlarını, tahsilatları ve müşteri vadelerini takip etmek için geliştirilmiş iki bileşenli bir sistemdir:

- **Mobil Uygulama** → Flutter (iOS & Android)
- **Web Paneli** → PHP + PDO (MySQL)

---

## Teknoloji Kararları

### Web (Backend & Panel)
- Dil: **PHP**
- Veritabanı erişimi: **PDO** — [`phpr.org/pdo-mysql-veritabani-sinifi`](https://www.phpr.org/pdo-mysql-veritabani-sinifi/) adresindeki statik singleton DB sınıfı kullanılacak
- Veritabanı: **MySQL**

#### DB Sınıfı Kullanımı (Özet)
```php
// Tek değer
$count = DB::getVar('SELECT COUNT(id) FROM sales');

// Tek satır
$customer = DB::getRow('SELECT * FROM customers WHERE id = ?', [$id]);

// Çoklu satır
$sales = DB::get('SELECT * FROM sales ORDER BY sale_date DESC');

// Insert → last insert ID döner
$id = DB::insert('INSERT INTO sales (customer_id, amount) VALUES (?, ?)', [$cId, $amount]);

// Update / Delete → etkilenen satır sayısı döner
$affected = DB::exec('UPDATE sales SET status = ? WHERE id = ?', [$status, $id]);

// Hata kontrolü
if ($error = DB::getLastError()) {
    echo $error[2];
}
```

> Sınıf **statik + singleton** yapıdadır. İhtiyaç anında bağlanır, tekrar bağlantı açmaz.  
> Tüm sorgular **binding** ile çalışır → SQL Injection riski yoktur.  
> Sonuçlar **obje** olarak döner: `$row->field_name`

### Mobil
- Framework: **Flutter** (Dart)
- REST API üzerinden web backend ile haberleşir
- JWT veya session token ile kimlik doğrulama

---

## Modüller

### 1. Kullanıcı & Yetki Yönetimi

| Rol | Açıklama |
|---|---|
| `admin` | Tüm sisteme tam erişim |
| `exporter` | Kendi müşterilerini ve satışlarını görür |
| `operation` | Operasyon ile ilgili kayıtlara erişir |
| `finance` | Tahsilat ve raporlama modüllerine erişir |

- Rol bazlı veri görünürlüğü uygulanır (aynı tablo, farklı WHERE koşulları)
- Kullanıcı-rol ilişkisi `users.role` enum alanıyla tutulur

---

### 2. Müşteri Yönetimi

Her müşteri kaydında şu bilgiler bulunur:

- Firma adı
- Ülke
- İletişim bilgileri (telefon, e-posta, yetkili kişi)
- Çalışılan para birimi: `USD` veya `EUR`
- Vade süresi (gün cinsinden — örn: 30, 60, 90)
- Sorumlu ihracatçı (`users` tablosuna FK)
- Sorumlu operasyoncu (`users` tablosuna FK)

---

### 3. Satış Kayıt Modülü

Her satış kaydında:

- Satış tarihi
- Müşteri (FK)
- Ülke (müşteriden otomatik dolar, override edilebilir)
- Tutar
- Para birimi: `USD` / `EUR`
- Vade tarihi (satış tarihi + müşteri vade süresi — otomatik hesaplanır, manuel düzenlenebilir)
- Dosya ekleme: PDF / evrak (sunucuda saklanır, yol DB'de tutulur)

---

### 4. Dashboard

Anlık özet ekranı:

- Toplam açık satış tutarı: USD ayrı / EUR ayrı
- Ülke bazlı toplam satış (tablo veya harita)
- Son 6 aylık satış trendi (çizgi grafik)
- Ülke bazlı müşteri dağılımı (pasta / bar grafik)

---

### 5. Tahsilat & Gecikme Takibi

- Müşteri bazlı vade durumu görünümü
- Gecikme günü = `CURDATE() - due_date` (sadece ödenmemişler için)
- Gecikme segmentasyonu:

| Segment | Koşul |
|---|---|
| Güncel | Vadesi geçmemiş |
| 30+ | 1–59 gün gecikme |
| 60+ | 60–89 gün gecikme → **Uyarı tetiklenir** |
| 90+ | 90+ gün gecikme → Kritik |

- 60+ günde sistem uyarısı üretir (bildirim veya dashboard flag)
- Gecikme hesabı müşterinin vade süresine göre yapılır

---

### 6. Temel Raporlama

| Rapor | Açıklama |
|---|---|
| Ülke bazlı satış | Ülke → toplam tutar (USD/EUR ayrı) |
| Müşteri bazlı satış | Müşteri → dönemsel satış özeti |
| Açık bakiye raporu | Ödenmemiş satışlar, vade durumu ile birlikte |

Raporlar filtrelenebilir: tarih aralığı, para birimi, ülke, müşteri.

---

## Dosya & Medya Yönetimi

- Satışa eklenen belgeler sunucuda `uploads/sales/{sale_id}/` dizininde saklanır
- DB'de sadece dosya yolu (`file_path`) tutulur
- İzin verilen türler: PDF, JPG, PNG, DOCX
- Mobil taraftan da dosya yükleme desteklenecek (multipart/form-data)

---

## API Mimarisi (Web ↔ Mobil)

- RESTful JSON API
- Endpoint'ler: `/api/v1/customers`, `/api/v1/sales`, `/api/v1/reports` vb.
- Auth: Bearer token (JWT önerilir)
- Rol kontrolü her endpoint'te server-side yapılır

---

## Veritabanı

Ayrıca `schema.sql` dosyasına bakınız.

### Temel Tablolar

| Tablo | Açıklama |
|---|---|
| `users` | Kullanıcılar ve roller |
| `customers` | Müşteri firmaları |
| `sales` | Satış kayıtları |
| `sale_files` | Satışa eklenen dosyalar |
| `collections` | Tahsilat kayıtları (v2 için genişletilebilir) |

---

## Geliştirme Öncelikleri (v1 Scope)

1. Kullanıcı girişi & rol yönetimi
2. Müşteri CRUD
3. Satış CRUD + dosya ekleme
4. Vade & gecikme hesaplama
5. Dashboard özet
6. Temel raporlar

> v1'de tahsilat girişi (kısmi ödeme takibi) kapsam dışıdır. Satışlar `paid` / `unpaid` olarak işaretlenir.

---

## Klasör Yapısı Önerisi (Web)

```
/project
  /config
    config.php       ← DB sabitleri (MYSQL_HOST, MYSQL_DB, vb.)
    db.php           ← phpr.org DB sınıfı
  /api
    customers.php
    sales.php
    reports.php
    auth.php
  /uploads
    /sales
  /panel             ← Web arayüzü (PHP view dosyaları)
  index.php
```