first commit

uploads/mcp_docs/fe466dbf-3791-47fa-aefe-4fd132ce10bf/RULES.md

@@ -0,0 +1,125 @@
+# 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