Admin Paneli Geliştirme Kılavuzu

Bu kılavuz, admin_user.md dosyasındaki gereksinimlere dayanarak Next.js 16 + TypeScript + Tailwind v4 + shadcn teknolojileriyle geliştirilecek Admin Paneli için mimari yapıyı ve geliştirme süreçlerini içerir.

1. Teknoloji Yığını ve Kurulum

Proje frontend klasörü altında yapılandırılmıştır. Gerekli tüm paketler (package.json) önceden yüklenmiştir:

Framework: Next.js 16 (App Router)
UI: React 19, Tailwind CSS v4, shadcn/ui
İkonlar: lucide-react
Validasyon: Zod
Auth: NextAuth.js
Bildirimler: SweetAlert2
Güvenlik: nextjs-turnstile (Cloudflare)

Kurulum ve Çalıştırma

cd frontend
npm install
npm run dev

2. Proje Klasör Yapısı (Önerilen)

Admin paneli için aşağıdaki klasör yapısını takip edeceğiz:

frontend/
├── app/
│   ├── admin/                  # Admin paneli rotaları
│   │   ├── layout.tsx          # Admin layout (Sidebar, Header, Auth Check)
│   │   ├── dashboard/          # Dashboard (KPI kartları)
│   │   ├── users/              # Kullanıcı yönetimi
│   │   ├── products/           # Ürün yönetimi
│   │   └── settings/           # Ayarlar
│   ├── api/auth/[...nextauth]/ # NextAuth API rotası
│   └── globals.css             # Global stiller (Tailwind)
├── components/
│   ├── admin/                  # Admin'e özel bileşenler
│   │   ├── sidebar.tsx
│   │   ├── header.tsx
│   │   ├── data-table.tsx      # Reusable tablo yapısı
│   │   └── recent-sales.tsx
│   └── ui/                     # shadcn bileşenleri (Button, Input, vb.)
├── lib/
│   ├── utils.ts                # cn() ve diğer yardımcılar
│   ├── auth.ts                 # NextAuth konfigürasyonu
│   └── db.ts                   # Veritabanı bağlantısı (veya API client)
├── actions/                    # Server Actions (Zod validasyonlu)
│   ├── auth-actions.ts
│   └── user-actions.ts
└── public/
    └── admin/                  # Admin ile ilgili statik dosyalar

3. Ortam Değişkenleri (.env)

Kök dizindeki .env dosyasına aşağıdaki değişkenlerin eklenmesi gerekmektedir:

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=gizli-bir-anahtar-olusturun

# Backend API (Go)
NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1

# Cloudflare Turnstile (Login güvenliği için)
NEXT_PUBLIC_TURNSTILE_SITEKEY=your-site-key
TURNSTILE_SECRET_KEY=your-secret-key

4. Geliştirme Adımları

Geliştirme süreci aşağıdaki sırayla ilerleyecektir:

Temel Bileşenler: shadcn kurulumunun doğrulanması ve temel bileşenlerin (Button, Input, Card, Form) eklenmesi.
Auth Yapısı: NextAuth yapılandırması ve middleware.ts ile /admin rotalarının korunması.
Login Sayfası: /admin/login sayfasının tasarımı ve Turnstile entegrasyonu.
Admin Layout: Sidebar ve Header içeren ana yerleşim düzeninin oluşturulması.
Dashboard: KPI kartları ve özet tabloların eklenmesi.
CRUD Sayfaları: Kullanıcılar (/users), Ürünler (/products) sayfalarının geliştirilmesi.

5. Güvenlik ve Validasyon Kuralları

Zod: Tüm form verileri hem istemci (client) hem sunucu (server) tarafında Zod şemaları ile doğrulanmalıdır.
Server Actions: Veri mutasyonları (Create, Update, Delete) Server Actions üzerinden yapılmalı ve oturum kontrolü içermelidir.
Role-Based Access: Sadece admin veya superadmin rolüne sahip kullanıcılar /admin paneline erişebilmelidir.

6. Örnek Kullanım (Server Action ile Form)

// actions/login.ts
"use server"
import { z } from "zod";

const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
});

export async function loginAction(formData: FormData) {
  const data = Object.fromEntries(formData);
  const parsed = loginSchema.safeParse(data);
  
  if (!parsed.success) {
    return { error: "Geçersiz veri" };
  }
  
  // Auth işlemleri...
}

4.1 KiB Raw Permalink Blame History Unescape Escape