# Raf Gezgini Geliştirme Prensipleri

Bu dosya Raf Gezgini projesinde yapılacak her geliştirmeden önce okunmalı ve uygulanmalıdır.

## Dil ve kullanıcı mesajları

- Kullanıcıya görünen bütün mobil, web ve API mesajları Türkçe olmalıdır.
- Laravel doğrulama, kimlik doğrulama ve hata mesajları Türkçe döndürülmelidir.
- Teknik hata sınıfları, SQL metinleri, stack trace veya İngilizce framework mesajları doğrudan kullanıcıya gösterilmemelidir.
- Türkçe karakterler UTF-8 olarak doğru saklanmalı ve gösterilmelidir; bozuk karakter kodlaması kabul edilmez.
- Alan adları kullanıcıya anlaşılır Türkçe etiketlerle gösterilmelidir.

## Veritabanı ve SQL

- MySQL ana veritabanıdır; veritabanı adı `raf_gezgini` olarak korunmalıdır.
- Tablo ve alan adları Türkçe anlamlı, küçük harfli ve Türkçe karakter içermeyen adlardan oluşmalıdır.
- Para alanlarında kayan nokta yerine uygun `numeric` türleri ve kesin ondalık hesap kullanılmalıdır.
- Projede veritabanı seviyesinde foreign key (yabancı anahtar) kısıtları kullanılmaz; yeni SQL kodlarına `FOREIGN KEY` veya `REFERENCES` tanımı eklenmez.
- Tablolar arası ilişkiler ilgili kimlik alanlarıyla uygulama seviyesinde yönetilir. İlişki alanları için gerekli normal indeksler eklenmeli; kayıt varlığı, silme davranışı ve veri bütünlüğü servis/doğrulama katmanında açıkça kontrol edilmelidir.
- Kontrol kısıtları, benzersizlik kuralları ve gerekli indeksler korunmalıdır.
- Codex hiçbir veritabanı tablosunu veya alanını doğrudan oluşturmaz, değiştirmez ya da silmez; migration veya benzeri komutlarla şema değişikliği uygulamaz.
- Tablo/alan oluşturma ve değiştirme gerektiğinde Codex yalnızca MySQL uyumlu SQL kodunu hazırlayıp kullanıcıya verir. SQL kodunu veritabanında kullanıcı manuel olarak çalıştırır.
- INSERT, UPDATE ve kalıcı referans verisi değişiklikleri için de Codex yalnızca MySQL kodunu verir; veritabanındaki kalıcı veriyi kendisi değiştirmez.
- Hazırlanan SQL dosyaları tekrar çalıştırılabilir, transaction kullanan ve mükerrer kayıt üretmeyen yapıda olmalıdır.
- Veritabanı şemasında veya kalıcı referans verisinde değişiklik gerektiren bir özellikte çalışma iki ayrı aşamada yürütülmelidir. Birinci aşamada Codex yalnızca gerekli MySQL kodunu hazırlayıp kullanıcıya verir; aynı aşamada PHP, Laravel, Filament, Flutter, API veya arayüz kodu yazmaya başlamaz.
- Codex, hazırlanan MySQL kodunun kullanıcı tarafından veritabanına uygulandığı açıkça bildirilene kadar beklemelidir. Kullanıcı uygulamanın tamamlandığını bildirdikten sonra gerekirse şemayı salt okunur kontrollerle doğrulayıp ikinci aşama olan uygulama kodlamasına geçmelidir.
- Veritabanı değişikliği gerektirmeyen işlerde bu iki aşamalı bekleme kuralı uygulanmaz; uygulama kodu doğrudan geliştirilebilir.

## Yönetim paneli (admin)

- Bu çalışma alanı yalnızca Filament yönetim paneli içindir; mobil uygulama ve HTTP API bu projede kullanılmaz.
- Admin paneli MySQL (`raf_gezgini`) veritabanına Laravel Eloquent ile doğrudan bağlanır; arada ayrı bir API katmanı yoktur.
- Yönetici kimlik doğrulaması `User` modeli ve Filament oturumu (`admin` guard) ile yapılır.
- Şifreler yalnızca güvenli özet olarak saklanmalı ve hiçbir yanıtta gönderilmemelidir.
- Barkodu bulunmayan veya doğrulanmamış ürünler inceleme/onay sürecine alınmalı; doğrulanmamış veri güvenilir katalog verisi gibi sunulmamalıdır.

## Alışveriş ve fiyat hesapları

- Raf fiyatı, miktar, indirim, tahmini toplam, kasa toplamı ve fark ayrı alanlar olarak korunmalıdır.
- Kilogram, litre, adet gibi birim fiyat hesapları ölçü birimi dönüşümleri dikkate alınarak yapılmalıdır.
- Kasa karşılaştırmasında pozitif/negatif farkın anlamı kullanıcıya açık Türkçe metin ve renklerle gösterilmelidir.

## Kod kalitesi ve doğrulama

- Her değişiklikten sonra ilgili PHP sözdizimi, Laravel rota/testleri çalıştırılmalıdır.
- Testler mümkün olduğunda MySQL transaction veya izole SQLite içinde çalışmalı ve test verisini kalıcı bırakmamalıdır.
- Hata yakalandığında neden düzeltilmeden başarılı sonuç bildirilmemelidir.
- Mevcut kullanıcı verileri ve ilgisiz değişiklikler korunmalıdır; yıkıcı komutlardan kaçınılmalıdır.
- Yeni özellikler küçük, test edilebilir ve sırayla tamamlanan aşamalar halinde geliştirilmelidir.

## Yetki ve çalışma biçimi

- Kullanıcının açıkça verdiği görev kapsamı dışına çıkılmamalıdır.
- Proje kapsamındaki güvenli, geri alınabilir geliştirme ve test adımları kesintisiz yürütülmelidir.
- Kalıcı veri silme, şema yıkımı veya kapsamı belirsiz dış sistem değişikliklerinde kullanıcıdan ayrıca açık onay alınmalıdır.