5.5 KiB
5.5 KiB
Admin Panel — Görev Tanımı (Next.js 16 + TypeScript)
Kısa Özet
Bu görevde Next.js 16 ve paylaştığın paketler kullanılarak önce masaüstü öncelikli, responsive bir Admin Paneli geliştirilecek; Admin Kod üretimi için aşağıdaki gereksinimler ve kabul kriterleri tam uygulanmalıdır.
Teknoloji Yığını (Zorunlu)
- Next.js 16 (App Router /app)
- React 19, TypeScript
- Tailwind CSS v4, shadcn bileşenleri
- class-variance-authority, tailwind-merge
- lucide-react (ikonlar)
- sweetalert2 (bildirimler/konfirmasyonlar)
- zod (validasyon)
- next-auth (kimlik doğrulama)
- nextjs-turnstile (Cloudflare Turnstile entegrasyonu)
- tw-animate-css (isteğe bağlı animasyonlar)
Yeni büyük kütüphaneler eklemek gerekiyorsa önceden onay istenmelidir. Küçük yardımcı util paketleri gerektiğinde kabul edilebilir ama öncelik mevcut paketlerle çözmek.
Tasarım Sistemi ve UI
- shadcn + Tailwind üzerinde tutarlı bir design-system oluştur: tokenlar (renk, spacing, tipografi), light/dark tema.
- Temel component seti: Button, Input, Select, TextArea, Modal, Table, Pagination, Badge, Toast, Card, Form.
- class-variance-authority ile variant/size yönetimi, tailwind-merge ile conditional class birleştirme.
- İkonlar lucide-react ile sağlanacak.
- Erişilebilirlik: semantic HTML, aria attributeleri, klavye erişimi, WCAG AA hedefleri.
Mimari ve Veri Akışı
- App Router (app/) kullan, sunucu bileşenleri (server components) ile veri yüklemesi/SSR; client components interaktivite için.
- Veri yüklemelerinde sunucu tarafı yükleme (server components) tercih edilir; client-side filtreleme/paginasyon için fetch + useState/useEffect kullanılabilir.
- Global state gerekiyorsa React Context ile minimal çözüm (yeni global state kütüphanesi eklenmeyecek).
Kimlik Doğrulama & Yetkilendirme
- NextAuth ile güvenli oturum/JWT tabanlı kimlik doğrulama uygulanacak.
- Role-based access control: en az iki rol (superadmin, admin).
- Admin rotaları server-side yetki kontrolü ile korunacak (middleware veya server actions).
- /admin/login sayfasına Cloudflare Turnstile (nextjs-turnstile) entegre edilecek.
Routing & Sayfalar (Zorunlu)
- /admin/login
- /admin → /admin yönlendirme (Dashboard)
- /admin (KPI kartları, son işlemler, hızlı aksiyonlar)
- /admin/users (liste, arama, filtre, pagination, CSV export)
- /admin/users/[id] (profil, roller, aktif/devre dışı)
- /admin/products (CRUD: liste, oluştur, düzenle, sil)
- /admin/orders (liste, detay, durum güncelleme)
- /admin/settings (genel, güvenlik, entegrasyonlar)
- /admin/profile
Veri Modelleri (Örnek)
- Users: id, name, email, role, status, createdAt
- Products: id, title, sku, price, inventory, images[], status
- Orders: id, userId, items[], total, status, createdAt
(Not: Backend yoksa örnek/mock endpoint’ler veya mevcut API ile uyumlu yapı sağlanmalı.)
Formlar & Validasyon
- Tüm formlarda Zod ile hem client-side hem server-side validasyon.
- Form submitleri server actions veya route handlers ile işlenmeli.
- Başarı/hata bildirimleri için sweetalert2 kullanılacak.
Dosya/Resim Yükleme
- Gerçek bir backend/3rd-party (S3) yoksa: client-side önizleme sağlayan placeholder upload akışı oluştur; upload endpoint için gerekli iskelet/protokol hazır olsun.
Güvenlik
- Tüm admin rotaları server-side yetkilendirmeyle korunacak.
- Hassas veriler .env ile saklanacak (README’de açıkça listelenecek).
- XSS/CSRF/SSRF risklerini azaltacak NextAuth & server actions en iyi uygulamalarına uyulacak.
Performans & Optimizasyon
- Hedef: sayfa başlangıç süresi < 1.5s (kritik CSS minimal, resimler optimize).
- Lazy load, code-splitting, image optimization kullanımı önerilir.
Test & Kalite
- TypeScript tipleri zorunlu, ESLint konfigürasyonuna uyulacak.
- Component-level testler opsiyonel; ek paket gerekiyorsa sonradan onay alınacak.
- README: kurulum, env değişkenleri, çalıştırma ve mimari kısa açıklama olacak.
Hata Yönetimi & İzleme
- Merkezi error handling mekanizması.
- Kullanıcıya sweetalert2 ile başarılı/başarısız geri bildirimleri göster.
Internationalization
- Proje i18n'ye hazır olmalı (tüm metinler merkezi çeviri kaynağından çekilecek).
Kabul Kriterleri (Öncelikli)
- Admin login çalışıyor; Turnstile doğrulaması entegre ve çalışır.
- Rol tabanlı erişim ile korunan tüm /admin sayfalarına yetkisiz erişim engelleniyor.
- Dashboard KPI kartları ve tablolar sunuyor; kullanıcı ve ürün CRUD fonksiyonları tamam.
- Tüm formlar Zod ile client ve server validasyonu sağlıyor.
- Component kütüphanesi shadcn + Tailwind ile tutarlı, responsive ve erişilebilir.
- UX geri bildirimleri sweetalert2 ile gösteriliyor.
- Kod TypeScript ile tam tiplenmiş ve ESLint uyarılarına duyarlı.
Teslimat (Çıktı)
- Çalışır Next.js projesi (kaynak kod).
- README: kurulum, env değişkenleri (NEXTAUTH_URL, NEXTAUTH_SECRET, DATABASE_URL, TURNSTILE_SITEKEY, TURNSTILE_SECRET vb.), çalıştırma talimatları.
- Temel component listesi ve kısa kullanım notları.
- Kabul testi checklist'i (madde madde doğrulanabilir).
Ek Kurallar & Notlar
- Yeni ana kütüphaneler eklemeden önce onay iste.
- Tasarım ve component kararları tutarlılık için belgelenmeli.
- Admin tamamlandıktan sonra müşteri-facing frontend için aynı design-system kullanılacak; bu aşama ayrı kabul kriterleriyle planlanacak.
Bu dosyayı doğrudan görev olarak kullan: ve detayli bir kulanama kılavuzu hazırla.