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