rust_imgapi/RULES.md

Admin Panel Geliştirme Kuralları

Bu doküman, mevcut Axum + Tokio backend için geliştirilecek admin panelin uyacağı teknik ve mimari kuralları tanımlar.

1. Genel İlkeler

• Kod mümkün olduğunca modüler olmalı
• Her component tek bir sorumluluk üstlenmeli
• Tekrarlı kodlar ortak utility ve component’lere taşınmalı
• UI, API client ve state yönetimi ayrıştırılmalı
• Üretim odaklı düşünülmeli
• Hatalar kullanıcı dostu şekilde gösterilmeli
• Hassas bilgiler loglanmamalı

2. Backend Uyum Kuralları

• Mevcut endpoint sözleşmeleri değiştirilmemeli
• Request/response shape varsayılmamalı
• Sadece dokümante edilmiş endpointler kullanılmalı
• Global error formatına uyulmalı
• Authorization gereken endpointlerde Bearer token kullanılmalı
• Image stream ve upload işlemlerinde uygun content-type korunmalı

3. Authentication Kuralları

• Login başarılı olursa access ve refresh token saklanmalı
• Access token süresi dolarsa refresh mekanizması denenmeli
• Refresh başarısız olursa kullanıcı login sayfasına atılmalı
• Logout sırasında tokenlar temizlenmeli
• Protected sayfalar auth olmadan erişilememeli
• Tokenlar mümkünse güvenli storage stratejisiyle tutulmalı

4. Route Koruma Kuralları

• Public sayfalar ile private sayfalar ayrılmalı
• Yetkisiz erişimde redirect uygulanmalı
• Session durumu app açılışında doğrulanmalı
• Kullanıcı yüklenmeden protected page render edilmemeli
• Yetki kontrolü UI seviyesinde de yapılmalı

5. API Client Kuralları

• Tüm API çağrıları merkezi client üzerinden yapılmalı
• Base URL environment değişkeninden okunmalı
• Error handling tek noktada normalize edilmeli
• 401 durumunda otomatik refresh akışı tetiklenmeli
• Aynı anda gelen çoklu 401 istekleri için deduplication düşünülmeli
• Timeout ve abort desteği eklenmeli

6. UI / UX Kuralları

• Responsive tasarım zorunlu
• Loading, empty ve error state’leri ayrı gösterilmeli
• Kritik aksiyonlarda confirmation kullanılmalı
• Form validation net olmalı
• Başarılı ve başarısız işlemler için feedback verilmeli
• Erişilebilirlik temel seviyede sağlanmalı
• Sidebar ve topbar düzeni tutarlı olmalı

7. State Management Kuralları

• Auth state merkezi bir store’da tutulmalı
• Server state ile UI state ayrılmalı
• Cache, invalidation ve refetch davranışı kontrollü olmalı
• Gereksiz global state yaratılmamalı
• Session bazlı bilgiler açıkça yönetilmeli

8. Güvenlik Kuralları

• Tokenlar client-side’da güvenli şekilde saklanmalı
• Console.log ile hassas veri basılmamalı
• XSS riskine karşı kullanıcı inputları dikkatli işlenmeli
• Admin olmayan kullanıcılar için erişim engeli olmalı
• Unauthorized ve forbidden cevapları düzgün ayrıştırılmalı
• Güvenlik açıkları yaratabilecek “debug” davranışları production’a taşınmamalı

9. Dosya ve Klasör Kuralları

• api/ klasörü yalnızca HTTP istemcisi ve endpoint wrapper’ları içermeli
• components/ sadece tekrar kullanılabilir UI parçalarını içermeli
• pages/ veya app/ routing katmanı için kullanılmalı
• stores/ auth ve UI state yönetimi için ayrılmalı
• types/ ortak tipleri içermeli
• utils/ yardımcı fonksiyonlar için kullanılmalı

10. Kod Kalitesi Kuralları

• Anlamlı isimlendirme kullan
• Magic number/string kullanımını azalt
• Ortak tipleri tekrar etme
• Fonksiyonları küçük ve test edilebilir tut
• Kenar durumlarını düşün
• Hata mesajları kullanıcı seviyesinde sade olmalı
• Gereksiz bağımlılık eklenmemeli

11. Test Kuralları

• Auth akışı test edilmeli
• Protected route davranışı test edilmeli
• API client error handling test edilmeli
• Kritik componentler için en az temel UI testleri yazılmalı
• Refresh token flow test edilmeli
• Upload/list/stream akışları için integration testler düşünülmeli

12. Dokümantasyon Kuralları

• Yeni ekranlar kısa şekilde dokümante edilmeli
• Önemli kararlar README veya docs altında açıklanmalı
• Endpoint kullanımı net örneklerle gösterilmeli
• Kurallar güncellendikçe bu dosya da güncellenmeli

13. Çıktı Üretim Kuralı

Yeni özellik tasarlarken şu sırayı takip et:

1. İhtiyacı netleştir
2. Backend uyumluluğunu kontrol et
3. Mimariyi seç
4. Component ve sayfa yapısını belirle
5. API bağlantılarını kur
6. Auth ve security’yi tamamla
7. Testleri ekle
8. Dokümante et

ares_cf00fb1de71a4854a6ac32065ebb3833b90e0ab453d2442c96c8f0e26da99123