Kantin Cepte
teslim dosyası.

01 Proje Hakkında

Kantin Cepte, okul kantinleri için tasarlanmış bir dijital sipariş ve tahsilat sistemidir. Üç kullanıcı tipi vardır:

• Veli — telefondan sipariş oluşturur, bakiye yönetir, çocuğunun beslenmesini takip eder
• Öğrenci — kantinde temassız kart veya QR kodu okutarak siparişini teslim alır (öğrencinin ayrı bir arayüzü yoktur, veli hesabına bağlıdır)
• Kantin işletmesi — sipariş kuyruğunu yönetir, teslim onayı verir, tahsilatı dijital olarak alır

Temel akış: Veli sipariş onaylar → tutar bakiyeden bloke edilir → öğrenci kantinde kartını okutur → kantinci teslim onayı verir → tutar veli bakiyesinden kantin hesabına aktarılır.

02 Teknik Mimari

Kullanılan Teknolojiler

Mimari Notlar

• Tüm sayfalar App Router ile yazılmıştır (app/ klasörü).
• "use client" direktifi ile etkileşimli bileşenler işaretlenmiştir.
• Sayfa içerikleri client component olarak hazırlanmıştır çünkü state ve etkileşim önemlidir.
• Statik (server-rendered) içerik landing sayfasında baskındır.

03 Klasör Yapısı

kantin-cepte-frontend/
├── app/                            # Next.js App Router
│   ├── layout.tsx                  # Kök layout (fontlar, body)
│   ├── globals.css                 # Genel CSS (Tailwind + özel stiller)
│   ├── page.tsx                    # Landing (anasayfa)
│   │
│   ├── veli/                       # Veli akışı (giriş + 9 panel sayfası)
│   ├── kantinci/                   # İşletme akışı (giriş + 9 panel sayfası)
│   │
│   └── components/                 # React bileşenleri
│       ├── Logo.tsx                # Marka logosu (SVG)
│       ├── Nav.tsx, Hero.tsx ...   # Landing bileşenleri
│       ├── AuthShell.tsx           # Giriş sayfaları ortak iskelet
│       │
│       ├── panel/                  # Panel iskeleti (iki rol için ortak)
│       │   ├── PanelShell.tsx
│       │   ├── Sidebar.tsx
│       │   ├── TopBar.tsx
│       │   ├── BigQR.tsx           # Sahte QR kod üretici
│       │   └── ui.tsx              # Card, Button, Tag, Modal, EmptyState, StatusPill
│       │
│       ├── veli/                   # Veli paneli içerik bileşenleri (11)
│       └── kantinci/               # İşletme paneli içerik bileşenleri (10)
│
├── lib/                            # Veri, state, yardımcılar
│   ├── types.ts                    # TypeScript tipleri
│   ├── mock-data.ts                # Tüm sahte veri
│   ├── store.ts                    # Zustand merkezi state (EN ÖNEMLİ)
│   └── utils.ts                    # formatTL, shortDate, relativeTime
│
├── public/                         # Statik dosyalar
│   ├── sunum.html                  # Yarışma sunumu (bağımsız HTML)
│   └── dokumantasyon/
│       └── index.html              # Bu doküman
│
├── sunum.html                      # Sunum (kök kopya)
├── DOKUMANTASYON.md                # Markdown sürüm
├── tailwind.config.ts              # Renkler, fontlar, animasyonlar
├── next.config.mjs                 # Next.js ayarları
├── tsconfig.json
├── postcss.config.mjs
└── package.json                    # Bağımlılıklar ve scriptler

04 Sayfa ve Rota Haritası

Toplam 25 çalışan sayfa bulunur.

Genel (3)

Veli Paneli (9)

İşletme Paneli (9)

Statik Dosyalar

05 Özellikler — Detay

5.1 Landing Sayfası

Üst nav, hero, "Nasıl çalışır" 3 adım, kullanıcı tipleri kartları, slogan şeridi, SSS akordeon, footer. Tüm metinler kurumsal Türkçe ile yazılmıştır.

5.2 Veli Akışı — Önemli Özellikler

• Çoklu öğrenci yönetimi — bir veli hesabı altında birden fazla öğrenci, her birinin alerjen ve limit bilgisi ayrı.
• Alerjen güvenliği — tanımlı alerjenli ürünler sepete eklenemez, menüde uyarılı görünür.
• Bakiye sistemi — sipariş onayında tutar bloke edilir; teslim onayı ile aktarılır.
• Otomatik yükleme — bakiye eşiğin altına düşünce tanımlı tutar yüklenir.
• Haftalık plan — Pzt–Cuma × 2 teneffüs matrisinde tek seferde sipariş.
• İptal ve iade — hazırlık başlamadıysa tek tıkla iptal; teslim edilmeyen sipariş otomatik iade.
• QR kod — her sipariş için ID'ye bağlı deterministik QR görseli (simülasyon).

5.3 İşletme Akışı — Önemli Özellikler

• Kanban kuyruk — üç sütun: Sıra → Hazırlanıyor → Teslime hazır.
• Tarama — QR ve NFC simülasyonu; demo modunda rastgele eşleştirme.
• Teslim onayı — ürünler kontrol listesi gibi tiklendikten sonra "Teslim onayı" butonu aktifleşir; onayla birlikte aktarım gerçekleşir.
• Ürün katalogu — CRUD; emoji + bg rengi seçimi; alerjen seçimi zorunlu önerilir.
• Günlük menü — bugün/yarın ayrı; adet limiti ve otomatik kapatma saati; bir günü diğerine kopyalama.
• Raporlar — 7/30 gün ciro grafiği, top ürünler, teneffüs dağılımı, sınıf bazlı yoğunluk, alerjen-uyumlu oran.
• Teneffüs çizelgesi — günlük saatler ve kesim dakikaları; tatil günleri.
• Çalışan yönetimi — Yönetici ve Kasiyer rolleri.

06 Veri Modeli ve State Yönetimi

6.1 Tipler — lib/types.ts

Tüm veri tipleri burada tanımlanır. Önemli tipler:

• Student — öğrenci profili (id, ad, sınıf, kart, alerjenler, limit, bakiye)
• Product — ürün (id, ad, kategori, fiyat, stok, alerjenler, kalori, emoji, bg)
• Order — sipariş (id, öğrenciId, tarih, teneffüs, ürünler, toplam, status, not)
• Transaction — bakiye hareketi (id, tip, tutar, tarih, orderId)
• Parent — veli (id, ad, telefon, e-posta, bakiye, otomatik yükleme)
• Notification — bildirim (id, kategori, başlık, body, okundu)

Ayrıca: Allergen (9 değer), Category (5 değer), OrderStatus (6 değer).

6.2 Mock Veri — lib/mock-data.ts

6.3 State Yönetimi — lib/store.ts

Tüm uygulama state'i Zustand ile yönetilir. Tek bir store: useApp.

Önemli Action'lar

6.4 Para Akışı

[Veli bakiyesi]
       │
       ▼ Sipariş onayı
[Bloke (kesinti tx)]
       │
       ▼ Kantinci teslim onayı
[Kantin hesabı (+aktarım tx)]


İptal/teslim edilmediği durumda:
[Bloke] → [İade tx] → [Veli bakiyesi]

Mali kayıt transaction olarak useApp.transactions listesinde saklanır. Her sipariş için en az 1, en fazla 3 transaction oluşur.

07 Marka Kimliği

7.1 Renk Paleti — tailwind.config.ts

7.2 Yazı Tipleri

Üç Google Font kullanılır, app/layout.tsx içinde Next.js next/font/google ile yüklenir:

• Fraunces (display-serif) — başlıklar
• Bricolage Grotesque (sans-serif) — gövde metni
• JetBrains Mono (monospace) — sayılar, kodlar, etiketler

7.3 Ortak Bileşenler — app/components/panel/ui.tsx

08 Kurulum ve Geliştirme

Gereksinimler

• Node.js 18.17 veya üzeri
• npm (Node ile birlikte gelir)

İlk Kurulum

npm install

Yaklaşık 24 saniye sürer, ~112 paket yükler.

Geliştirme Sunucusunu Başlat

npm run dev

Sunucu http://localhost:3000 adresinde açılır. Dosya değişikliklerinde otomatik yeniden yüklenir.

Üretim Derlemesi (Sunucu Modu)

npm run build
npm start

Node.js sunucu ile çalışır. Bu mod normalde gerekmez — statik export kullanılması önerilir.

09 Yayına Alma · Statik Derleme

Projeyi statik HTML olarak derleyip herhangi bir web sunucusuna yükleyebilirsiniz.

9.1 next.config.mjs Güncellemesi

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',           // Statik HTML üret
  reactStrictMode: true,
  images: {
    unoptimized: true,         // Statik export için
  },
  trailingSlash: true,         // .html olarak çalışsın
};

export default nextConfig;

9.2 Derleme

npm run build

Derleme bittiğinde out/ klasörü oluşur. İçinde tüm HTML, CSS, JS ve sunum.html, dokumantasyon/ dosyaları bulunur.

9.3 Dinamik Rotalar — Ek Yapılandırma

/veli/siparisler/[id], /veli/ogrenciler/[id], /kantinci/siparisler/[id] ve /kantinci/urunler/[id] gibi dinamik rotaların statik export ile çalışması için her dinamik sayfaya generateStaticParams eklenmelidir.

Örnek olarak app/veli/siparisler/[id]/page.tsx dosyasının başına şu eklenmelidir:

export async function generateStaticParams() {
  return [
    { id: 'KC-0481' },
    { id: 'KC-0480' },
    { id: 'KC-0479' },
    { id: 'KC-0470' },
    { id: 'KC-0468' },
    { id: 'KC-0465' },
    { id: 'KC-0460' },
  ];
}

Benzer şekilde:

• /veli/ogrenciler/[id] için s-001, s-002
• /kantinci/urunler/[id] için u-001...u-042 ve yeni

9.4 Sunucuya Yükleme

out/ klasörünün içeriğini sunucunuzun web kök dizinine yükleyin.

FTP / cPanel ile

1. out/ klasörünün içini seçin (Ctrl+A)
2. Tüm dosya ve alt klasörleri sunucunuzun web kök dizinine yükleyin
3. Tarayıcıdan domain adresinizi açın

Nginx yapılandırması (öneri)

server {
    listen 80;
    server_name kantincepte.com.tr;
    root /var/www/kantincepte;
    index index.html;

    location / {
        try_files $uri $uri.html $uri/index.html =404;
    }
}

9.5 Sunum Dosyası

sunum.html bağımsız bir HTML dosyasıdır, Next.js'e bağlı değildir. Statik derleme yapmasanız bile sunum dosyasını tek başına kantincepte.com.tr/sunum.html olarak yayınlayabilirsiniz.

10 Özelleştirme Rehberi

10.1 Okul Adı, Saatler

lib/mock-data.ts dosyasındaki SCHOOL sabitini düzenleyin:

export const SCHOOL = {
  name: "Karahüyük Mah. Ahmet Haşhaş İlkokulu",
  shortName: "Karahüyük A.H.İ.",
  district: "Karahüyük Mh.",
  breakHours: {
    1: { start: "10:10", end: "10:30", cutoff: "10:00" },
    2: { start: "12:00", end: "12:40", cutoff: "11:50" },
  },
};

10.2 Kantin İşletmesi Bilgileri

lib/mock-data.ts dosyasındaki CANTEEN_INIT sabitini düzenleyin (ad, IBAN, telefon, e-posta).

10.3 Renkler

tailwind.config.ts dosyasındaki colors bölümünden hex değerleri değiştirin. Tüm uygulama otomatik güncellenir.

10.4 Yeni Ürün Eklemek

İki yöntem vardır:

A. Demo veri olarak (kalıcı)

lib/mock-data.ts içindeki PRODUCTS dizisine yeni nesne ekleyin:

{
  id: "u-099",
  name: "Yeni ürün",
  description: "Açıklama",
  category: "atistir",
  price: 25,
  stock: 20,
  active: true,
  allergens: [],
  calories: 100,
  emoji: "🍪",
  bg: "mustard",
  cost: 12,
},

B. Uygulama içinden

Kantinci paneli → Ürünler → Yeni ürün. Bu eklenenler tarayıcının localStorage'ında saklanır, demoyu sıfırlayınca kaybolur.

10.5 İletişim Bilgileri

E-posta ve telefon bilgileri şu dosyalarda geçer:

• app/components/Footer.tsx (landing footer)
• app/components/FAQ.tsx (SSS bölümü)
• app/components/KantinciLoginForm.tsx (destek hattı)
• lib/mock-data.ts (CANTEEN_INIT)
• sunum.html ve public/sunum.html (kapanış slaytı)

11 Sunum Dosyası (sunum.html)

Bağımsız bir HTML sunum dosyasıdır, Next.js'e ihtiyaç duymaz. Tek dosya, tüm CSS ve JS gömülü. Google Fonts CDN bağlantısı vardır (internet gerekir).

Özellikler

• 16 slayt (kapak, gündem, problem, vizyon, ribbon, nasıl çalışır, para akışı, veli paneli, işletme paneli, marka, teknoloji, güvenlik, etki, yol haritası, pilot okul, kapanış)
• Klavye gezintisi: → ← Space PageUp PageDown Home End
• Dokunmatik kaydırma desteği
• F tuşu ile tam ekran
• URL hash ile derin link (sunum.html#7 → 7. slayt)
• Sıralı giriş animasyonları, sayı sayaçları, fiş kayma, damga düşme efektleri

Bağımsız Yayınlama

Dosyayı tek başına kantincepte.com.tr/sunum.html olarak veya başka bir sunucuda doğrudan açarak kullanabilirsiniz. Hiçbir bağımlılık yoktur (sadece internet üzerinden Google Fonts CDN'i).

12 Bilinen Sınırlamalar

13 Hızlı Başlangıç Komutları

# Bağımlılıkları yükle
npm install

# Geliştirme modunda başlat (http://localhost:3000)
npm run dev

# Production build (sunucu modu için)
npm run build && npm start

# Statik HTML üretimi (sunucuya yüklemek için)
# Önce next.config.mjs'i güncelleyin (output: 'export')
npm run build
# Çıktı: out/ klasörü