125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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 |