# Citrus Platform - Cursor Rules

## Proje Genel Kuralları

### Dil ve Lokalizasyon
- Tüm metinler Laravel Localization kullanmalı
- Türkçe ve İngilizce dil desteği zorunlu
- Dil dosyaları `lang/tr/` ve `lang/en/` klasörlerinde
- Çeviri anahtarları kebab-case formatında: `module_name.key_name`
- Blade template'lerde `{{ __('module.key') }}` kullan
- Controller'larda `__('module.key')` kullan

### Modül Yapısı
- Her modül için aşağıdaki yapıyı takip et:
```
app/Filament/Admin/Resources/ModuleName/
├── ModuleNameResource.php
├── Pages/
│   ├── ListModuleName.php
│   ├── CreateModuleName.php
│   └── EditModuleName.php
├── Schemas/
│   └── ModuleNameForm.php
└── Tables/
    └── ModuleNameTable.php
```

### Filament Resource Oluşturma
- Yeni modül oluştururken Filament'in kendi komutunu kullan:
```bash
php artisan make:filament-resource ModelName --generate --model --migration --factory
```
- Bu komut otomatik olarak tüm gerekli dosyaları oluşturur
- Manuel dosya oluşturma yerine bu komutu tercih et
- Komut çalıştırıldıktan sonra model ve migration'ları ihtiyaca göre düzenle

### Resource Sınıfı Kuralları
- `getNavigationLabel()`, `getModelLabel()`, `getPluralModelLabel()` metodlarını implement et
- Tüm metinler için localization kullan
- Navigation icon için Heroicon kullan

### Page Sınıfları Kuralları
- `getTitle()` metodunu implement et ve localization kullan
- Action butonları için `->label(__('module.action_name'))` kullan
- Notification mesajları için localization kullan
- `getRedirectUrl()` metodunu implement et

### Form ve Table Kuralları
- Form field'ları için label'ları localization'dan al
- Table column'ları için header'ları localization'dan al
- Validation mesajları için localization kullan

### Filament 4.x Import Kuralları (ÖNEMLİ!)

#### **Table Actions (DOĞRU):**
```php
// Table Actions için
use Filament\Actions\EditAction;
use Filament\Actions\DeleteAction;
use Filament\Actions\RestoreAction;
use Filament\Actions\ForceDeleteAction;

// Bulk Actions için
use Filament\Actions\BulkActionGroup;
use Filament\Actions\DeleteBulkAction;
use Filament\Actions\ForceDeleteBulkAction;
use Filament\Actions\RestoreBulkAction;

// Filters için
use Filament\Tables\Filters\TrashedFilter;
use Filament\Tables\Filters\SelectFilter;

// Columns için
use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Columns\IconColumn;
use Filament\Tables\Columns\ImageColumn;

// Table metodları
$table
    ->recordActions([      // ✅ Doğru
        EditAction::make(),
    ])
    ->toolbarActions([     // ✅ Doğru
        BulkActionGroup::make([
            DeleteBulkAction::make(),
        ]),
    ]);
```

#### **Form & Schema Components (DOĞRU):**
```php
// Form input components
use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\Checkbox;
use Filament\Forms\Components\Toggle;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\DateTimePicker;
use Filament\Forms\Components\FileUpload;

// Layout components (ÖNEMLİ: Schemas namespace!)
use Filament\Schemas\Components\Section;   // ✅ Doğru
use Filament\Schemas\Components\Grid;      // ✅ Doğru
use Filament\Schemas\Components\Tabs;      // ✅ Doğru
use Filament\Schemas\Components\Fieldset;  // ✅ Doğru
```

#### **YANLIŞ KULLANIM (Eski Filament 3.x):**
```php
// ❌ YANLIŞ - Bu namespace'ler Filament 4'te YOK!
use Filament\Tables\Actions\EditAction;      // ❌
use Filament\Forms\Components\Section;       // ❌
use Filament\Forms\Components\Grid;          // ❌

// ❌ YANLIŞ - Eski metod adları
$table
    ->actions([...])      // ❌ Kullanma!
    ->bulkActions([...])  // ❌ Kullanma!
```

#### **ÖZET:**
- ✅ **Table Actions:** `Filament\Actions\` namespace
- ✅ **Table Columns:** `Filament\Tables\Columns\` namespace
- ✅ **Table Filters:** `Filament\Tables\Filters\` namespace
- ✅ **Form Inputs:** `Filament\Forms\Components\` namespace
- ✅ **Layout Components:** `Filament\Schemas\Components\` namespace (Section, Grid, Tabs)
- ✅ **Table Methods:** `->recordActions()` ve `->toolbarActions()`

### Dil Dosyası Yapısı
<?php

return [
    'title' => 'Modül Başlığı',
    'navigation_label' => 'Navigasyon Etiketi',
    'model_label' => 'Tekil Model Etiketi',
    'plural_model_label' => 'Çoğul Model Etiketi',
    
    // Actions
    'create' => 'Oluştur',
    'edit' => 'Düzenle',
    'delete' => 'Sil',
    'restore' => 'Geri Yükle',
    'force_delete' => 'Kalıcı Olarak Sil',
    
    // Form fields
    'field_name' => 'Alan Etiketi',
    
    // Messages
    'created_successfully' => 'Başarıyla oluşturuldu.',
    'updated_successfully' => 'Başarıyla güncellendi.',
    'deleted_successfully' => 'Başarıyla silindi.',
    
    // Table columns
    'table_column_name' => 'Sütun Başlığı',
    
    // Validation messages
    'field_required' => 'Bu alan zorunludur.',
    'field_unique' => 'Bu değer zaten kullanılıyor.',
];


### Model Kuralları
- `$fillable` array'ini tanımla
- `$casts` array'ini kullan
- Soft delete için `SoftDeletes` trait'ini kullan
- `$dates` array'ini kullan

### Migration Kuralları
- Tablo adları çoğul olmalı
- Column adları snake_case
- Foreign key'ler için `_id` suffix'i kullan
- Timestamps için `created_at` ve `updated_at` kullan
- Soft delete için `deleted_at` kullan
- Mevcut tablolar için migration oluştururken `if (!Schema::hasTable())` kontrolü kullanma
- Soft delete hatası alındığında `deleted_at` sütununu ekleyen ayrı migration oluştur

### Test Kuralları
- Her modül için test dosyaları oluştur
- Feature test'leri yaz
- Unit test'leri yaz
- Localization test'leri yaz

### Kod Stili
- PSR-12 standartlarına uy
- Type hinting kullan
- Return type'ları belirt
- DocBlock'ları yaz
- Kısa ve açıklayıcı metod isimleri kullan

### Güvenlik
- CSRF koruması aktif
- Validation kuralları uygula
- Authorization kontrolü yap
- SQL injection koruması
- XSS koruması

### Performans
- Eager loading kullan
- Database index'leri ekle
- Cache kullan
- Query optimization yap

## Pages Modülü Örnek Yapısı

Pages modülü bu kuralların uygulandığı örnek modüldür. Yeni modül oluştururken bu yapıyı referans al.

### Dosya Yapısı
- `PageResource.php` - Ana resource sınıfı
- `Pages/ListPages.php` - Liste sayfası
- `Pages/CreatePage.php` - Oluşturma sayfası  
- `Pages/EditPage.php` - Düzenleme sayfası
- `Schemas/PageForm.php` - Form şeması
- `Tables/PagesTable.php` - Tablo şeması
- `lang/tr/pages.php` - Türkçe çeviriler
- `lang/en/pages.php` - İngilizce çeviriler

### Özellikler
- ✅ Localization desteği
- ✅ Soft delete
- ✅ Form validation
- ✅ Table filtering
- ✅ Action buttons
- ✅ Notifications
- ✅ Redirect handling

## Universal Translation System

### Translation System Kullanımı
Platform, dinamik ve evrensel bir çeviri sistemi içerir. Herhangi bir modele çeviri desteği eklemek için:

```php
use App\Traits\HasTranslations;

class YourModel extends Model
{
    use HasTranslations;
    
    protected $translatable = [
        'title',
        'content',
        'description',
        'meta_title',
        'meta_description',
    ];
}
```

### Translation Kuralları
- ✅ Çevrilecek alanlar `$translatable` array'inde tanımlanmalı
- ✅ `HasTranslations` trait'i kullanılmalı
- ✅ Trait'te `$translatable` property tanımlama (conflict oluşur)
- ✅ Her model kendi `$translatable` array'ini tanımlar
- ✅ Slug, ID, FK gibi alanlar çevrilmemeli

### Translation Metodları
```php
// Çeviri kaydet
$model->setTranslation('field_name', 'en', 'Translation', 'published');

// Çeviri oku
$model->translate('field_name'); // Mevcut dilde
$model->translate('field_name', 'en'); // Belirli dilde
$model->translate('field_name', 'en', false); // Fallback olmadan

// Çeviri kontrolü
$model->hasTranslation('field_name', 'en');

// İlerleme takibi
$model->getTranslationProgress(); // ['tr' => 100, 'en' => 75]
$model->getMissingTranslations('en'); // ['meta_description']
```

### Translation Workflow
- `draft` → `review` → `approved` → `published`
- Sadece `published` çeviriler son kullanıcıya görünür
- User-language permissions ile kontrol edilir

### Helper Functions
```php
current_language(); // Mevcut dil objesi
available_languages(); // Aktif diller
translate_model($model, 'field', 'en'); // Model çevirisi
user_can_manage_language('en'); // Kullanıcı yetkisi
switch_language('en'); // Dil değiştir
```

### Dokümantasyon
- `docs/TRANSLATION_SYSTEM.md` - Tam sistem dokümantasyonu
- `docs/TRANSLATION_QUICK_START.md` - Hızlı başlangıç rehberi
