# Mail Sistemi

Bu belge, projedeki eposta yönetim sistemini açıklar.

## Genel Bakış

Sistem iki ana bileşenden oluşur:

1. **`emails` tablosu** — Company ve Person modellerine birden fazla eposta adresi atanmasını sağlayan polymorphic yapı
2. **`gmail_messages` tablosu** — Gmail'den gelen epostaların kayıtları

## Veri Yapısı

### `emails` Tablosu

Polymorphic bir tablodur. Hem `Company` hem `Person` modelleri ile ilişkilendirilebilir.

| Kolon            | Tip     | Açıklama                                                              |
| ---------------- | ------- | --------------------------------------------------------------------- |
| `id`             | bigint  | Primary key                                                           |
| `email`          | string  | Eposta adresi                                                         |
| `label`          | string? | Kategori etiketi (örn: "iş", "destek", "kişisel")                     |
| `is_primary`     | boolean | Birincil eposta işareti                                               |
| `emailable_type` | string  | İlişkili model sınıfı (`App\Models\Company` veya `App\Models\Person`) |
| `emailable_id`   | bigint  | İlişkili modelin ID'si                                                |
| `user_id`        | bigint  | Eposta adresinin ait olduğu kullanıcı                                 |

**İndeksler:**

- `['user_id', 'email']` — unique (aynı kullanıcı aynı epostayı iki kez ekleyemez)
- `['emailable_type', 'emailable_id']` — polymorphic ilişki indeksi

### `gmail_messages` Tablosu

Gmail API'den senkronize edilen eposta mesajları.

| Kolon             | Tip          | Açıklama                             |
| ----------------- | ------------ | ------------------------------------ |
| `id`              | bigint       | Primary key                          |
| `user_id`         | bigint       | Mesajın ait olduğu kullanıcı         |
| `message_id`      | string(64)   | Gmail message ID                     |
| `thread_id`       | string(64)?  | Gmail thread ID                      |
| `from_name`       | string?      | Gönderen adı                         |
| `from_email`      | string?      | Gönderen eposta adresi               |
| `subject`         | string(512)? | Konu                                 |
| `snippet`         | text?        | Eposta önizleme metni                |
| `received_at`     | timestamp?   | Alınma zamanı                        |
| `is_unread`       | boolean      | Okunmamış durumu (varsayılan: true)  |
| `label_ids`       | json?        | Gmail label ID'leri                  |
| `created_task_id` | bigint?      | Bu epostadan oluşturulan görev ID'si |

## İlişki Diyagramı

```
┌─────────────────┐       ┌─────────────────┐
│   gmail_messages │       │     emails      │
├─────────────────┤       ├─────────────────┤
│ from_email ──────────────► email           │
│ from_name      │       │ emailable_type  │
│ subject        │       │ emailable_id ────────┐
│ snippet        │       │ is_primary      │   │
│ received_at    │       │ label           │   │
│ is_unread      │       │ user_id         │   │
└─────────────────┘       └─────────────────┘   │
                                                 │
                        ┌────────────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
      ┌──────────────┐   ┌──────────────┐
      │   Company    │   │    Person    │
      ├──────────────┤   ├──────────────┤
      │ id           │   │ id           │
      │ name         │   │ name         │
      │ email (legacy)│  │ surname      │
      │ user_id      │   │ email (legacy)│
      │ ...          │   │ company_id   │
      └──────────────┘   │ user_id      │
                         │ ...          │
                         └──────────────┘
```

## Model Kullanımı

### `HasEmails` Trait

`App\Models\Traits\HasEmails` trait'i, bir modele çoklu eposta desteği ekler.

**Kullanılan Modeller:**

- `App\Models\Company`
- `App\Models\Person`

**Sağladığı Metodlar:**

```php
// Tüm eposta adreslerini döndür (Collection)
$model->emails;

// Birincil eposta adresini döndür (Email modeli veya null)
$model->primaryEmail();

// Birincil eposta adresini string olarak döndür
$model->primary_email_address; // accessor
```

### `Email` Modeli

```php
// Eposta sahibini döndür (Company veya Person)
$email->emailable;

// Eposta adresinin ait olduğu kullanıcı
$email->user;
```

## Eşleştirme Mantığı

Gmail'den gelen bir epostanın `from_email` alanı, `emails` tablosundaki kayıtlarla eşleştirilir:

```php
use App\Models\Email;

// Gelen epostayı Company veya Person ile eşleştir
$matchedEmail = Email::where('user_id', $userId)
    ->where('email', $fromEmail)
    ->first();

if ($matchedEmail) {
    if ($matchedEmail->emailable_type === \App\Models\Company::class) {
        $company = $matchedEmail->emailable;
        // Company bulundu
    } elseif ($matchedEmail->emailable_type === \App\Models\Person::class) {
        $person = $matchedEmail->emailable;
        // Person bulundu
    }
}
```

## Yeni Eposta Ekleme

```php
// Company'a eposta ekle
$company->emails()->create([
    'email' => 'destek@firma.com',
    'label' => 'destek',
    'is_primary' => false,
    'user_id' => $company->user_id,
]);

// Person'a eposta ekle
$person->emails()->create([
    'email' => 'kisi@firma.com',
    'label' => 'iş',
    'is_primary' => true,
    'user_id' => $person->user_id,
]);
```

## Migration Geçmişi

| Migration                                                   | Açıklama                                                                          |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `2026_08_31_000002_create_gmail_messages_table`             | Gmail mesajları tablosu                                                           |
| `2026_09_02_000001_create_emails_table`                     | Polymorphic eposta adresleri tablosu                                              |
| `2026_09_02_000002_migrate_existing_emails_to_emails_table` | Mevcut `companies.email` ve `persons.email` verilerini `emails` tablosuna aktardı |

## Notlar

- `companies.email` ve `persons.email` kolonları hâlâ mevcuttur (geriye uyumluluk için). Yeni eposta adresleri `emails` tablosuna eklenmelidir.
- Aynı eposta adresi bir kullanıcı için yalnızca bir kez kaydedilebilir (`user_id + email` unique kısıtı).
- `is_primary` ile her model için bir birincil eposta belirlenebilir.
- `label` alanı epostaları kategorize etmek için kullanılabilir (örn: "iş", "destek", "fatura").