---
name: excel-worker
description: "Lojistik ERP projesindeki Excel/CSV import ve export süreçlerini yönetir. getMapping, normalizeRow ve Excel servislerinin kullanımı için standartlar sunar."
---

# Excel Worker Skill

## Amaç
Lojistik ERP sistemindeki verilerin Excel/CSV formatında dışa aktarılması (Export) ve sisteme toplu veri girişi (Import) süreçlerini standartlaştırmak.

## 1. Temel Servisler

| Servis | Görev | Namespace |
| :--- | :--- | :--- |
| `ExcelImportService` | Dosya okuma, CSV/XLSX ayrıştırma, temel normalizasyon. | `App\Excel\Services` |
| `ExportService` | CSV/XML stream oluşturma, dosya adı temizleme. | `App\Core\Services` |

---

## 2. Tasarım Kalıbı: Mapping & Normalization

İthalat ve ihracat süreçlerinde UI etiketleri ile veritabanı alanlarını eşleştirmek için Controller seviyesinde şu metodlar kullanılmalıdır:

### `getMapping()` Metodu
Excel başlıklarını (UI Label) veritabanı sütunlarıyla eşleştirir.
```php
protected function getMapping(): array
{
    return [
        'Plaka' => 'plate_number',
        'Şase No' => 'chassis_number',
        'Marka' => 'brand',
        'Model Yılı' => 'model_year',
        'Durum' => 'is_active',
    ];
}
```

### `normalizeRow()` Metodu
Excel'den gelen ham veriyi (örn: "Aktif") uygulama diline (örn: `1`) çevirir.
```php
protected function normalizeRow(array $row): array
{
    $mapping = $this->getMapping();
    $normalized = [];

    foreach ($mapping as $label => $column) {
        $value = $row[$label] ?? null;

        // Özel dönüşümler
        if ($column === 'is_active') {
            $value = (strtolower($value) === 'aktif' || $value == '1') ? 1 : 0;
        }

        $normalized[$column] = $value;
    }

    return $normalized;
}
```

---

## 3. Workflow / İş Akışları

### A. Export (Dışa Aktar) Ekleme
1. **Controller:** `ExportService`'i inject et.
2. **Data:** `getMapping()`'deki sırayla veriyi array'e dök.
3. **Response:** `$exportService->csv($headers, $rows, 'dosya_adi')` döndür.

### B. Import (İçer Aktar) Ekleme
1. **Controller:** `ExcelImportService`'i inject et.
2. **Read:** `$excelService->readFileWithHeaders($path)` ile veriyi al.
3. **Process:** Her satır için `normalizeRow()` çalıştır ve Model'i kaydet/güncelle.
4. **Validation:** Hata varsa `notify()` veya custom error log ile kullanıcıyı bilgilendir.

---

## 4. Kritik Kurallar & İpuçları

1. **Title Matching:** Excel başlıkları, Blade view'lardaki `<label>` metinleriyle **birebir aynı** olmalıdır.
2. **UTF-8 BOM:** CSV işlemlerinde Türkçe karakter sorunu yaşanmaması için `ExcelImportService` içindeki BOM temizleme mekanizması korunmalıdır.
3. **Büyük Veri:** 1000+ satırlık import işlemlerinde `ProcessExcelJob` kullanarak işlemi kuyruğa (Queue) atın.
4. **Tarih Formatı:** Excel'den gelen tarihleri `Carbon::parse()` veya `PhpSpreadsheet` helper'ları ile normalize edin.

---

## Örnek Kullanım (Controller)

```php
public function export(ExportService $service)
{
    $items = Vehicle::all();
    $mapping = $this->getMapping();
    $headers = array_keys($mapping);
    
    $rows = $items->map(fn($v) => [
        $v->plate_number,
        $v->chassis_number,
        $v->brand,
        $v->model_year,
        $v->is_active ? 'Aktif' : 'Pasif'
    ])->toArray();

    return $service->csv($headers, $rows, 'vehicles');
}
```