# Modül Geliştirme Standardı

Bu belge, sistem genelindeki tüm opsiyonel, lisanslı ve çekirdek modüllerin geliştirilmesinde, paketlenmesinde ve yönetilmesinde uyulması gereken standartları ve kuralları belirler.

---

## 1. Modül Nedir?
Modül, çekirdek sistemin (Core) üzerine eklenen, belirli bir işlev grubunu (özelliği) yerine getiren, dinamik olarak aktif veya pasif edilebilen, gerektiğinde lisans kontrolüne tabi tutulabilen bağımsız yazılım bileşenidir.

## 2. Çekirdek Sistem ile Modül Farkı
- **Çekirdek Sistem (Core)**: Sistemin çalışması için zorunlu olan, kapatılması durumunda platformun temel işlevlerini yitireceği modüllerdir (örneğin: `core_catalog`, `core_orders`, `core_settings`). Çekirdek modüller admin panelden pasifleştirilemez.
- **Opsiyonel Modüller**: Çekirdek yapıyı bozmadan sonradan etkinleştirilebilen, lisans doğrulamasına tabi tutulabilen modüllerdir (örneğin: `advanced_orders`, `return_exchange_management`, `stock_count`). Pasifleştirildiklerinde veri silinmez, sadece ilgili rotalar ve servis metotları erişilemez olur.

## 3. Modül Key Standardı
Modül anahtarları (`key`) kesinlikle **snake_case** formatında olmalıdır. Büyük harf, tire, nokta veya boşluk içeremez.

- **Doğru**: `advanced_orders`, `return_exchange_management`, `woocommerce_xml_import`
- **Yanlış**: `AdvancedOrders`, `advanced-orders`, `advanced.orders`, `Advanced Orders`

## 4. Modül Kategori Standardı
Modüller sadece aşağıdaki Türkçe kategorilerden biriyle etiketlenmelidir:
- `Sipariş`
- `Ürün`
- `Stok`
- `Pazarlama`
- `Raporlama`
- `Entegrasyon`
- `Sistem`
- `Geliştirici`
- `Tema`
- `Güvenlik`

## 5. Modül Versiyon Standardı
Her modülün bir `version` alanı bulunmalıdır. Versiyonlama **Semantic Versioning (SemVer)** standardına uygun olarak `MAJOR.MINOR.PATCH` formatında olmalıdır.

- **Örnek**: `1.0.0`, `1.1.0`, `2.0.1`

## 6. Modül Bağımlılık Standardı
Modüllerin birbirine olan bağımlılıkları `metadata.depends_on` dizisi altında tanımlanmalıdır.
- Bir modülün canUse kontrolü, bağımlı olduğu tüm modüllerin de aktif ve kullanılabilir olmasını (`canUse = true`) gerektirir.
- Bağımlılık zincirlerinde döngüsel bağımlılık (Circular Dependency) oluşmaması için basit sonsuz döngü koruma algoritmaları kullanılır.

## 7. Modül Lisans ve Trial Davranışı
- **requires_license = true** olan modüllerin kullanılabilmesi için `license_status = 'valid'` olmalı veya aktif bir deneme süresi (`license_status = 'trial'` ve `trial_ends_at` gelecekte) bulunmalıdır.
- **license_status** değerleri: `valid`, `invalid`, `expired`, `trial`, `disabled`, `not_required` olmalıdır.
- **Trial (Deneme Süresi)**: Trial süresi bittiğinde modülün canUse durumu otomatik olarak `false` değerine düşer. Ancak hiçbir modül verisi silinmez.

## 8. Modül Aktif / Pasif Davranışı
- Modül pasifleştirildiğinde, modüle ait tüm rotalar (web/admin/customer), Livewire aksiyonları ve servis katmanı metotları erişilemez olmalıdır.
- Modülün kapatılması veri tabanından hiçbir tablonun veya kaydın silinmesine (DROP/DELETE) yol açmamalıdır.

## 9. Rotalar, Sidebar, Livewire ve Servis Standartları
- **Rotalar**: Modül rotaları `routes/web.php` veya `routes/admin.php` içinde `module` middleware'i ile korunmalıdır.
  ```php
  Route::middleware(['module:module_key'])->group(function () {
      // Modül rotaları
  });
  ```
- **Sidebar**: Menü linkleri Blade içinde `module_can_use('module_key')` kontrolü ile kaplanmalıdır.
  ```html
  @if(module_can_use('module_key'))
      <li><a href="...">Menü Elemanı</a></li>
  @endif
  ```
- **Livewire**: Sadece Blade'de gizlemek yeterli değildir. Livewire bileşenlerinin kritik metotlarında yetki ve servis kontrolleri yapılmalıdır.
- **Servis Katmanı**: Her modülün kendi iş mantığı servisi (`App\Services`) bulunmalı ve public kritik metotların başında modül canUse kontrolü yapılmalıdır.
  ```php
  if (!module_can_use('module_key')) {
      throw new \Exception('Bu modül aktif değil.');
  }
  ```

## 10. Modül Kapatıldığında Veri Davranışı
Modülün pasif konuma getirilmesi sadece erişim ve işlem yetkisini engeller. Hiçbir veri silinmez, tablolar boşaltılmaz. Modül tekrar açıldığında veriler kaldığı yerden kullanılmaya devam eder.

## 11. Uninstall Prensipleri
- Bu aşamada sistemde veri silen bir "Uninstall" (kaldırma) işlemi yapılmayacaktır.
- İleride eklenebilecek uninstall işlemleri ayrı, bilinçli ve kullanıcının onayını/yedekleme onayını gerektiren bir süreç olarak tasarlanmalıdır.

## 12. Yeni Modül Ekleme Kontrol Listesi
Yeni bir modül geliştirilirken sırasıyla aşağıdaki adımlar tamamlanmalıdır:
1. `config/modules.php` içerisine modül tanımı eklendi mi?
2. `ModuleKeys.php` içerisine modül key constant'ı eklendi mi?
3. `ModuleSeeder` ile veritabanı senkronizasyonu (idempotent) sağlandı mı?
4. Rotalar `module` middleware'i ile korundu mu?
5. Sidebar menüleri `module_can_use` ile şartlandı mı?
6. Servis sınıfı oluşturuldu ve metotlarda `module_can_use` kontrolü yapıldı mı?
7. Alt özellikler (features) tanımlandı mı?
8. Activity log standart event isimleriyle eklendi mi?
9. Değişikliklerde cache temizliği (`clearCache()`) tetiklendi mi?
10. Feature testleri yazıldı ve yeşillendi mi?