goGin/belgeler/admin_panel.md

Bağlam:

• Proje Next.js 16, React 19, TypeScript kullanıyor.
• Mevcut bağımlılıklar (önemli olanlar): next@16.1.6, react@19.2.3, next-auth, tailwindcss@^4, shadcn, radix-ui, lucide-react, class-variance-authority, clsx, tailwind-merge, zod, sweetalert2, nextjs-turnstile, tw-animate-css.
• Yeni paket eklemeden önce önce onay iste.

Görev: Tüm site temel olarak public olacak; ana içerik sayfaları (ana sayfa, blog/ürün listesi, ürün detay, hakkında, iletişim vb.) herkese açık. Bunun yanında /admin yolu altında ayrı, yetki kontrollü bir Admin Paneli olacak — bu alana sadece next-auth ile oturum açmış ve rolü "admin" olan kullanıcılar erişebilecek. Frontend Next.js 16 + TypeScript ile, mevcut bağımlılıkları kullanarak oluşturulacak; kod temiz, modüler ve production-ready olacak.

Mimari/Genel kurallar:

• Next.js 16, app router (tercih) ve TypeScript (strict).
• Styling: TailwindCSS v4 + shadcn komponentleri + Radix UI primitives. İkonlar: lucide-react.
• Form schema/validasyon: Zod (hem client hem server).
• Auth: next-auth ile role tabanlı erişim (user | admin). Login formunda Turnstile kullanılacak.
• UI yardımcıları: class-variance-authority, clsx, tailwind-merge.
• Uyarılar/confirm: SweetAlert2.
• Yeni bağımlılık eklenmeden önce onay iste.
• Veri katmanı: başlangıç mock/JSON veya isteğe göre Prisma+Postgres öner (ek paket için onay al).

Kapsam / Özellikler:

1. Public frontend

• Ana sayfa, katalog (liste), öğe detayı, hakkında, iletişim gibi public rotalar (SSR/SSG uygun yerlere göre).
• SEO meta, Open Graph etiketleri, erişilebilir markup.
• Responsive ve mobil-first tasarım.

2. Authentication & Authorization

• next-auth ile oturum yönetimi; kullanıcı nesnesinde role alanı.
• /auth/signin sayfası (Turnstile entegrasyonu).
• Admin alanına erişim: server-side guard (middleware veya server component) ve client-side koruma. Admin değilse /admin altında 403 veya redirect to /auth/signin.

3. Admin Panel (/admin)

• Layout: sidebar, header, responsive.
• Dashboard: KPI kartları (mock veya API), temel yönetim araçları.
• User Management: liste/arama/pagination, rol değiştir, aktif/pasif.
• Örnek CRUD: Products (create/read/update/delete) için tam çalışan UI ve API (Zod validasyonlu).
• Settings: admin için site ayarları (mock).

4. API & Veri

• Next.js route handlers (app router) veya /api altında tipli endpoints: /api/admin/users, /api/admin/products vb.
• Başlangıç için mock veri veya JSON file; gerçek DB istenirse Prisma + Postgres öner (migration ve .env örneği ile).

5. Formlar & Validasyon

• Zod şemaları hem client hem server tarafında kullanılsın.
• Hatalar kullanıcıya anlamlı gösterilsin.

6. UI & A11y

• shadcn komponentleri ve Radix primitives ile erişilebilir bileşenler.
• Lucide ikonları, SweetAlert2 confirm/toast.
• Keyboard erişimi ve aria-* attribute’ları.

7. Güvenlik

• Admin rotaları server-side yetki kontrolü.
• CSRF koruması next-auth ile sağlanmalı.
• Turnstile login/critical formlar için.

8. Tests (tercihli)

• Örnek birim testi ve en az 1 API entegrasyon testi (Jest veya testing-library; ek paket gerekiyorsa onay iste).

9. Kod kalitesi & teslimat

• TypeScript strict, ESLint ile uyumlu.
• Commit mesajları: feat/admin-, fix/, chore/*.
• PR: branch feat/admin-panel veya isteğe göre parça parça PR tercih edilebilir.

Klasör yapısı önerisi:

• app/
  • layout.tsx (global)
  • page.tsx (public ana sayfa)
  • products/
    • page.tsx
    • [slug]/page.tsx
  • (admin)/
    • layout.tsx
    • page.tsx (dashboard)
    • users/
      • page.tsx
      • [id]/page.tsx
    • products/
      • ...
• components/
  • ui/ (shadcn/radix wrappers)
  • public/ (Hero, Footer, Header)
  • admin/ (Sidebar, AdminTable, ProductForm)
• lib/
  • auth.ts (next-auth config)
  • db.ts (data access abstraction)
  • schemas/ (zod schemas)
• pages/api/ or app/api/
  • admin/
    • users.ts
    • products.ts
• styles/ (tailwind globals)

Acceptance kriterleri:

• Public sayfalar (ör. /, /products, /products/[slug]) herkes tarafından erişilebilir ve düzgün render oluyor.
• /admin sadece role === "admin" kullanıcılar tarafından erişilebilir; diğerleri redirect veya 403 alıyor.
• Login sayfası Turnstile çalışıyor.
• Product CRUD çalışıyor (Zod validasyon server+client).
• TypeScript derlemesi hatasız.
• README içinde gerekli env değişkenleri (NEXTAUTH_*, DATABASE_URL, TURNSTILE keys) ve çalıştırma talimatları var.
• PR açıklaması: hangi feature’lar eklendi, nasıl test edilir, eksikler/öneriler.

Teslim formatı:

• Tercih: tek PR (feat/admin-panel) veya küçük aşama PR’ları (her biri açıklamalı). README ve .env.example ekle.
• PR açıklamasında çalışma, test etme ve env değişkenleri belirtilmiş olacak.

Zaman tahmini (yaklaşık):

• Minimal (mock veri, temel public sayfalar + admin auth + temel CRUD): 3-5 iş günü.
• Tam (DB, testler, audit log, eksiksiz validasyon): 7-14 iş günü.