citrus-cms/README.md

<p align="center">
  <img src="assets/citrus-logos/citrus-dikey-dark.svg" width="50%" alt="Citrus CMS Logo">
</p>

# Citrus CMS - Geliştirici Dokümantasyonu

## İçindekiler
1. [Proje Genel Bakış](#proje-genel-bakış)
2. [Kurulum](#kurulum)
3. [Klasör Yapısı](#klasör-yapısı)
4. [Modül Sistemi](#modül-sistemi)
5. [Kimlik Doğrulama (Auth) Sistemi](#kimlik-doğrulama-auth-sistemi)
6. [Types Tablosu ve Kullanımı](#types-tablosu-ve-kullanımı)
7. [Controller Yapısı](#controller-yapısı)
8. [Helper Fonksiyonlar](#helper-fonksiyonlar)
9. [DevExtreme Entegrasyonu](#devextreme-entegrasyonu)
10. [Admin-AJAX Sistemi](#admin-ajax-sistemi)
11. [Şablonlar ve Bileşenler](#şablonlar-ve-bileşenler)
12. [Yeni Modül Geliştirme](#yeni-modül-geliştirme)
13. [Middleware ve İzin Sistemi](#middleware-ve-izin-sistemi)

## Proje Genel Bakış

Bu proje, Laravel framework'ü üzerine inşa edilmiş, Trunçgil Teknoloji tarafından geliştirilen Citrus CMS yönetim paneli uygulamasıdır. Temel olarak aşağıdaki özellikleri içermektedir:

- Modüler yapı
- Kullanıcı yetkilendirme ve rol bazlı izin sistemi
- DevExtreme ile gelişmiş kullanıcı arayüzü
- Excel import/export işlemleri
- Dinamik form ve alan yönetimi
- Çoklu dil desteği
- Çeşitli helper fonksiyonlar

## Kurulum

Projeyi yerel ortamınızda ayağa kaldırmak için aşağıdaki adımları izleyin:

1. **Bağımlılıkları Yükleyin:**
   ```bash
   composer install
   ```

2. **Yapılandırma Dosyasını Hazırlayın:**
   `.env.example` dosyasını `.env` olarak kopyalayın ve veritabanı bilgilerinizi düzenleyin.
   ```bash
   cp .env.example .env
   ```

3. **Uygulama Anahtarını Oluşturun:**
   ```bash
   php artisan key:generate
   ```

4. **Veritabanı Migrasyonlarını Çalıştırın:**
   ```bash
   php artisan migrate
   ```

### Admin Hesabı Oluşturma ve Şifre Üretme

Sisteme giriş yapabilmek için bir admin hesabı oluşturmanız veya mevcut admin hesabının şifresini sıfırlamanız gerekebilir. Bunun için özel bir Artisan komutu mevcuttur:

```bash
php artisan admin:create
```

Bu komutu çalıştırdığınızda:
- `admin@citrus.com` e-posta adresi ile bir kullanıcı oluşturulur (varsa şifresi sıfırlanır).
- 12 karakterli rastgele ve güvenli bir şifre üretilir.
- Kullanıcıya tam yetki (`ALL PRIVILEGES`) tanımlanır.
- Üretilen giriş bilgileri terminal ekranında görüntülenir.

> [!IMPORTANT]
> Güvenlik nedeniyle, üretim (production) ortamında admin şifresini oluşturduktan sonra bu bilgileri güvenli bir yerde saklamanız ve gerekirse panel üzerinden değiştirmeniz önerilir.

## Klasör Yapısı

Projenin ana klasör yapısı Laravel'in standart yapısına uygundur, ancak bazı özel klasör ve dosyalar eklenmiştir:

- **app/** - Uygulamanın ana kaynak kodu
  - **Functions/** - Özel fonksiyonlar
  - **Helpers/** - Yardımcı fonksiyonlar
  - **Models/** - Veritabanı modelleri
  - **DevExtreme/** - DevExtreme entegrasyonu için gerekli sınıflar
  - **Http/Controllers/** - Controller sınıfları
- **resources/** - Görünüm şablonları ve ön yüz varlıkları
- **routes/** - Uygulama rotaları
- **config/** - Yapılandırma dosyaları
- **public/** - Genel erişilebilir dosyalar
- **storage/** - Uygulama tarafından oluşturulan dosyalar için depolama alanı

## Modül Sistemi

Proje modüler bir yapıda geliştirilmiştir. Her bir modül (örneğin WeldLog, TestPackage, vb.) kendi Model, Controller ve View dosyalarına sahiptir. Modüller, `Types` tablosu üzerinden yönetilmektedir.

### Modül Yapısı

Tipik bir modül şu bileşenlerden oluşur:

1. **Model** - `app/Models/` altında
2. **Controller** - `app/Http/Controllers/` altında
3. **Views** - `resources/views/admin/` altında
4. **Routes** - `routes/web.php` içinde tanımlı

## Kimlik Doğrulama (Auth) Sistemi

Laravel'in varsayılan kimlik doğrulama sistemi kullanılmaktadır, ancak genişletilmiş yetkilendirme ve rol yönetimi uygulanmıştır.

### Kullanıcı Seviyeleri

Kullanıcılar farklı seviyelere (level) sahip olabilir:
- Admin
- Manager
- User
- vb.

Her seviye için farklı izin ayarları tanımlanabilir.

### Middleware

Uygulamada `PermissionControl` adlı özel bir middleware kullanılmakta, bu middleware kullanıcının erişim isteklerini kontrol etmektedir.

```php
// Middleware örneği
if(in_array($thisPath, $onlyAdminPath)) {
    if(!isAdmin()) {
        echo "Only admin can access this area.";
        exit();
    }
}
```

## Types Tablosu ve Kullanımı

`types` tablosu, sistemdeki modülleri tanımlamak için kullanılır. Bu tablo aşağıdaki alanları içerir:

- `id` - Benzersiz tanımlayıcı
- `title` - Modül başlığı
- `slug` - URL-dostu benzersiz string
- `fields` - Modülün içerdiği alanlar (virgülle ayrılmış liste)

Her modül için gerekli alanlar `Fields` tablosunda saklanır ve bu tablo aracılığıyla formlar ve tablolar dinamik olarak oluşturulur.

## Controller Yapısı

Projede controller'lar genellikle şu yapıda düzenlenmiştir:

### AdminController

`AdminController` temel CRUD işlemleri ve admin paneli yönetimi için kullanılır. Örnek metotlar:

- `index()` - Admin panel ana sayfası
- `action()` - İçerik ekleme, silme, güncelleme
- `importExcel()` - Excel'den veri içe aktarma
- `exportExcel()` - Veriyi Excel olarak dışa aktarma
- `delete()` - Kayıt silme

### Modül Controllerleri

Her modül genellikle kendi controller'ına sahiptir. Örneğin `WeldLogController`, `TestPackageController` vb.

## Helper Fonksiyonlar

Projede çeşitli yardımcı fonksiyonlar bulunmaktadır. Bunlar `app/Functions/` ve `app/Helpers/` dizinlerinde saklanır.

Sık kullanılan helper fonksiyonlardan bazıları:

- `u()` - Mevcut kullanıcıyı döndürür
- `db($table)` - Belirtilen tabloya erişim sağlar
- `setting($key)` - Sistem ayarlarına erişim
- `isAdmin()` - Kullanıcının admin olup olmadığını kontrol eder
- `userPermissions()` - Kullanıcı izinlerini döndürür

## DevExtreme Entegrasyonu

Proje, kullanıcı arayüzü için DevExtreme bileşenlerini kullanmaktadır. DevExtreme, veri tablolarını ve formları hızlı bir şekilde oluşturmak için kullanılan JavaScript tabanlı UI komponent kütüphanesidir.

### DevExtreme Bileşenleri ve Yapısı

DevExtreme entegrasyonu için özel sınıflar `app/DevExtreme/` klasöründe bulunur:

- `Utils` - Genel yardımcı fonksiyonlar
- `FilterHelper` - Filtreleme için yardımcı fonksiyonlar
- `DbSet` - Veritabanı sorguları için yardımcı sınıf

### CRUD İşlemleri

**Önemli Not**: Sistemdeki tüm modüllerin CRUD (Create, Read, Update, Delete) işlemleri `AdminController.php` üzerinden yürütülmektedir. Bu merkezi yaklaşım, kod tekrarını önler ve tutarlı bir API sağlar.

`AdminController` içindeki temel CRUD metotları:

- `tableToJson` - Veritabanı tablosunu JSON formatına dönüştürür (Read)
- `insertJson` - Yeni kayıt ekler (Create)
- `saveJson` - Mevcut kaydı günceller (Update)
- `removeJson` - Kaydı siler (Delete)

Tüm modüller, işlemlerini bu metotlar üzerinden gerçekleştirir ve özel bir controller geliştirmeye gerek kalmaz.

### DevExtreme DataGrid

DataGrid, veri tablosunu görüntülemek için kullanılan ana bileşendir. JavaScript tarafında aşağıdaki özellikleri destekler:

- Filtreleme ve sıralama
- Sayfalama
- Satır düzenleme
- Grup oluşturma
- Özet bilgileri
- Özel düğmeler ve işlemler

## Admin-AJAX Sistemi

Projede AJAX tabanlı istekler için özel bir sistem kullanılmaktadır. Bu sistem, `AdminAjaxController` tarafından yönetilir ve admin paneli içerisinde yapılan asenkron istekleri işler.

### URL Yapısı

Admin-AJAX istekleri için URL yapısı şu şekildedir:

```
/admin-ajax/{işlem_adı}
```

Burada `{işlem_adı}`, gerçekleştirilecek AJAX işlemini belirtir. Örneğin:

```
/admin-ajax/get-users
/admin-ajax/update-status
/admin-ajax/save-form
```

### Controller Yapısı

Admin-AJAX Controller'ı şu şekilde çalışır:

```php
// app/Http/Controllers/AdminAjaxController.php
public function index(Request $request, string $var) {
    $u = Auth::user();
    if(!isset($u->level)) {
        echo("permission error");
        exit();
    }
    
    $url = "admin-ajax.$var";
    
    return view($url, array(
        "request" => $request     
    ));
}
```

Bu yapı, AJAX isteğini uygun view dosyasına yönlendirir. View adı `admin-ajax.{işlem_adı}` formatında olmalıdır.

### View Dosyaları

AJAX view dosyaları `resources/views/admin-ajax/` dizininde bulunur. Her bir AJAX işlemi için ayrı bir blade dosyası oluşturulmalıdır:

```
resources/views/admin-ajax/get-users.blade.php
resources/views/admin-ajax/update-status.blade.php
resources/views/admin-ajax/save-form.blade.php
```

### Yeni AJAX İşlemi Ekleme

Yeni bir AJAX işlemi eklemek için:

1. İlgili view dosyasını oluşturun:

```php
// resources/views/admin-ajax/yeni-islem.blade.php
@php
// İsteği işleyin
$data = db('tablo_adi')->get();

// JSON formatında yanıt döndürün
echo json_encode([
    'status' => 'success',
    'data' => $data
]);
@endphp
```

2. View dosyasını çağıran JavaScript kodu:

```javascript
$.ajax({
    url: '/admin-ajax/yeni-islem',
    type: 'POST',
    data: {
        parametre1: deger1,
        parametre2: deger2,
        _token: csrf_token // CSRF koruması için gerekli
    },
    success: function(response) {
        // Başarılı yanıtı işleyin
    },
    error: function(error) {
        // Hatayı işleyin
    }
});
```

### Güvenlik Önlemleri

Admin-AJAX isteklerinde şu güvenlik önlemleri uygulanmaktadır:

- Tüm istekler için kimlik doğrulama kontrolü
- CSRF koruma tokeni
- Kullanıcı seviyesine göre yetkilendirme

## Şablonlar ve Bileşenler

Proje, birçok tekrar kullanılabilir şablon ve bileşen içerir. Bu bileşenler, modül geliştirme sürecini kolaylaştırır ve tutarlı bir kullanıcı arayüzü sağlar.

### Şablon Sistemi

Sistem içinde kullanılan ana şablonlar:

#### `sablon4.blade.php`

`resources/views/admin/type/sablon4.blade.php` dosyası, modül sayfalarını oluşturmak için kullanılan temel şablondur. Yeni bir modül geliştirirken, model ve migration oluşturduktan sonra bu şablonu kullanmak genellikle yeterlidir. Şablonun başında tanımlanan değişkenler ile özelleştirilebilir.

Temel özelleştirme değişkenleri:

```php
// Modül başlığı
$title = "Radiographic Test";
// Tabloyu oluşturmak için kullanılan model
$listDatas = RadiographicTest::orderBy("id","DESC")->paginate(setting('row_count'));
// Veritabanı tablo adı
$tableName = "radiographic_tests";
// Blok grupları - alanları kategorilere bölmek için
$blockGroup = [    
    'Info' => [
        'report_file',
        'contractor',
    ],
    // Diğer gruplar...
];
// Dosya yükleme klasörü
$firstUploadFolder = '004_QA/0001_RT/';
// Dosya yükleme başlığı
$firstUploadTitle = 'Upload PDF';
```

#### `module-block.blade.php`

`resources/views/components/blocks/module-block.blade.php` dosyası, modülün ana içeriğini oluşturan ve DataGrid'i görüntüleyen bileşendir. Bu bileşen, `sablon4.blade.php` içinde çağrılır ve aşağıdaki özellikleri içerir:

- Alan listesi oluşturma
- Alan tiplerini belirleme
- Sütun seçimini yönetme
- Excel içe/dışa aktarma işlemleri
- DataGrid entegrasyonu

```php
// Dışa aktarma, sütun seçimi ve diğer işlemler için temel ayarlar
$options = [
    'export' => $tableName,
];
// DataGrid dahil etme
@include("components.table.$tableType")
```

#### `datagrid.blade.php`

`resources/views/components/table/datagrid.blade.php` dosyası, DevExtreme DataGrid'i entegre eder ve aşağıdaki özellikleri sağlar:

- Sütun tiplendirme ve düzenleme
- Filtreleme ve sıralama
- Veri işleme (CRUD)
- Klavye kısayolları
- Özel stil ve davranışlar
- Validation işlemleri

Bu dosya, JavaScript kodunu da içerir ve DataGrid'in tüm davranışlarını yapılandırır:

```javascript
var dataGrid = $("#dataGrid").dxDataGrid({
    // DataGrid ayarları
    dataSource: dataSource,
    keyExpr: "{{$tableName}}",
    allowColumnResizing: true,
    // Diğer yapılandırmalar...
});
```

#### `upload.blade.php`

`resources/views/admin/type/document/upload.blade.php` dosyası, dosya yükleme işlemlerini yönetir. Özellikle PDF dosyalarını yüklemek için kullanılır. Aşağıdaki özellikleri içerir:

- Dropzone.js entegrasyonu
- Modal pencere ile yükleme arayüzü
- Birden fazla yükleme bölümü
- Özel klasörlere dosya yükleme

Bu bileşen, sablon4.blade.php içinde `@include("admin.type.document.upload")` ile dahil edilir.

### Form Elemanları ve Alan Tipleri

DataGrid içinde kullanılabilen farklı alan tipleri vardır:

- `text` - Standart metin girişi
- `date` - Tarih seçici
- `number` - Sayısal değer girişi
- `select` - Dropdown liste
- `auto-complete` - Otomatik tamamlama
- `link-search` - Bağlantı ve arama
- `decimal` - Ondalık sayı girişi
- `checkbox` - Onay kutusu

Her alan tipi için `components/table/datagrid/{tip}.blade.php` altında bir şablon vardır.

Örnek olarak select tipi için kullanım:

```php
$relationDatas = [
    'field_name' => [
        'type' => 'select',
        'datas' => [
            'option1' => 'Option 1',
            'option2' => 'Option 2'
        ]
    ]
];
```

## Yeni Modül Geliştirme

Citrus CMS'de yeni bir modül oluşturmak için iki yöntem bulunmaktadır: **Module Generator Wizard** (Önerilen) ve **Manuel Yöntem**.

### 1. Module Generator Wizard (Önerilen)

Sistemde bulunan "Module Generator" sihirbazı, bir modül için gerekli olan tüm dosyaları ve veritabanı işlemlerini otomatik olarak gerçekleştirir.

**Adımlar:**
1. Sol menüden **İçerik Yönetimi (Content Management) > Module Generator** sayfasına gidin.
2. **Temel Bilgiler:** Modül başlığını girin ve bir ikon (PNG) yükleyin.
3. **Veritabanı Sütunları:** Modülde yer alacak alanları tanımlayın:
   - Sütun adı, veri tipi (String, Integer, Long Text, Date, Boolean vb.) seçin.
   - Açılır menüler (Select) veya API bağlantılı listeler (API Dropdown) için gelişmiş ayarları yapın.
4. **Onay ve Oluştur:** "Generate Module Now" butonuna tıkladığınızda sistem şunları otomatik yapar:
   - Veritabanı Migration dosyasını oluşturur ve çalıştırır.
   - Eloquent Model dosyasını (`app/Models/`) oluşturur.
   - Gelişmiş Datagrid içeren Blade View dosyasını (`resources/views/admin/type/`) oluşturur.
   - `types` tablosuna gerekli kaydı ekler.

Bu işlemden sonra modülünüz hemen kullanıma hazır hale gelir.

### 2. Manuel Yöntem

Daha özel ihtiyaçlar için modülü manuel olarak da oluşturabilirsiniz:

1. **Model ve Migration Oluşturun**:
   ```php
   // app/Models/YeniModul.php
   namespace App\Models;
   
   use Illuminate\Database\Eloquent\Model;
   
   class YeniModul extends Model
   {
       protected $table = 'yeni_modul';
       protected $primaryKey = 'id';
       public $timestamps = true;
   }
   ```

   ```php
   // database/migrations/xxxx_create_yeni_modul_table.php
   public function up()
   {
       Schema::create('yeni_modul', function (Blueprint $table) {
           $table->id();
           $table->string('ad')->nullable();
           $table->text('aciklama')->nullable();
           $table->timestamps();
       });
   }
   ```

2. **Şablonu Kopyalayın ve Özelleştirin**:
   - `resources/views/admin/type/` dizini altında yeni bir blade dosyası oluşturun (Örn: `yeni-modul.blade.php`).
   - `datagrid-module-template.blade.php` veya `sablon4.blade.php` temel alınarak özelleştirme yapabilirsiniz.
   
3. **Type Tablosuna Kayıt Ekleyin**:
   - Admin panelinden **Modüller** sayfasına gidin ve yeni bir kayıt ekleyin.
   - `Slug` kısmına oluşturduğunuz blade dosyasının adını yazın.

**Önemli Not**: Tüm CRUD işlemleri otomatik olarak `AdminController.php` üzerinden yönetilir. Özel bir controller kodlamanıza genellikle gerek yoktur.

## Middleware ve İzin Sistemi

Uygulamada izin kontrolü şu şekilde yapılmaktadır:

1. **Kullanıcı Seviyeleri**: Her kullanıcı bir seviyeye sahiptir (level alanı)
2. **İzin Tanımları**: Her modül için okuma, yazma, tam kontrol izinleri tanımlanır
3. **Middleware Kontrolü**: Kullanıcının sahip olduğu seviyeye göre izin kontrolleri yapılır

```php
// İzin kontrolü örneği
if(isAuth($modulAdi, "read")) {
    // Okuma izni var, işleme devam et
} else {
    // İzin yok, erişim engellendi
}
```

### Kullanıcı İzin Kontrolü

`userPermissions()` fonksiyonu kullanıcının izinlerini döndürür ve `isAuth()` fonksiyonu belirli bir işlem için izin kontrolü yapar.

---

Bu dokümantasyon, projenin temel yapısını ve özelliklerini kapsamaktadır. Daha detaylı bilgi için ilgili kaynak kodları inceleyebilir veya ekip ile iletişime geçebilirsiniz.