Neufe

Biçerdöver ve Tarım Makineleri için Kapsamlı Yedek Parça Yönetim Sistemi

Özellikler • Kurulum • Kullanım • Katkıda Bulun • Güvenlik

---

📋 İçindekiler

• Özellikler
• Proje Durumu
• Teknoloji Yığını
• Kurulum
• Kullanım
• Demo Kullanıcılar
• Modüller
• Performans Optimizasyonları
• Prisma 7 Yapılandırması
• Bilinen Sorunlar & TODO
• Geliştirme

---

✨ Özellikler

🛒 Satış ve POS

• Hızlı satış noktası (POS) ekranı
• Barkod okuyucu desteği (useScanDetection hook)
• Gerçek zamanlı KDV/VAT hesaplamaları (%20)
• Günlük kasa özeti ve raporlama
• Nakit, kart ve veresiye ödeme desteği
• Otomatik fatura oluşturma ve PDF çıktı
• Termal yazıcı desteği (ESC/POS komutları)

📦 Stok Yönetimi

• Ürün ve stok takibi (OEM kodları, barkod)
• Düşük stok uyarıları (kritik/uyarı seviyeleri)
• Tedarikçi sipariş listesi oluşturma
• 2D Raf sistemi (interaktif grid görünümü)
• Raf hücre detayları ve renk kodlama
• Hızlı stok sayımı (barkod bazlı)
• Stok hareketleri ve tam izlenebilirlik

👥 Müşteri ve Tedarik

• Müşteri veritabanı (bireysel, kurumsal, bayi)
• Borç takibi ve ödeme yönetimi
• Müşteri borç izleyici (vadesi geçen ödemeler)
• Tedarikçi yönetimi (iletişim bilgileri, ödeme koşulları)
• Satın alma siparişleri (Draft → Sent → Confirmed → Received)
• Bulunmayan ürün kaydı (müşteri talepleri)

💹 Muhasebe ve Raporlama

• Satış raporları ve analizler (Bugün/Hafta/Ay/Yıl)
• Gelir/gider takibi (Chart of Accounts)
• Görsel grafikler (Recharts ile 5 farklı chart tipi)
• Satış trendi, ödeme yöntemleri, en çok satanlar
• Saatlik satış dağılımı, stok durumu grafikleri
• Yazdırılabilir raporlar

🔧 İş Özellikleri

• Makine uyumluluk kataloğu (tarım makineleri)
• Garanti takibi (Pending → Approved/Rejected/Replaced/Refunded)
• Fiyat listeleri ve kampanya kodları
• Kategori ve marka yönetimi (hiyerarşik yapı)
• Kullanıcı rolleri (Admin, Warehouse, Cashier)
• e-Fatura entegrasyonu (Logo/EDM hazır - test modu)
• Manuel/otomatik veritabanı yedeği

---

� Proje Durumu

Tamamlanan Phase'lar

• ✅ Phase 1: Foundation - Nextron, Tailwind, Prisma, Barkod okuyucu
• ✅ Phase 2: Full ERP - Auth, CRUD, Faturalama, KDV, Kullanıcı yönetimi
• ✅ Phase 3: Visual Shelf System - 2D Raf haritası, interaktif grid
• ✅ Phase 4: Business Features - Düşük stok, kasa özeti, borç takibi, hızlı sayım
• ✅ Phase 5: Extended ERP - Tedarikçi, satın alma, kategori, makine, garanti, fiyatlama, muhasebe

Devam Eden Geliştirmeler

• 🔄 Phase 6: Settings & Integration - Ayar kalıcılığı, backup sistemi, EDM e-Fatura, yazıcı yönetimi
• 🔄 Phase 7: Multi-Branch System - Şube yönetimi (schema hazır)

---

�🛠 Teknoloji Yığını

Katman	Teknoloji
Framework	Nextron (Electron 34 + Next.js 14)
Frontend	React 18, TypeScript 5.7, TailwindCSS
Backend	Electron IPC, Node.js
Veritabanı	PostgreSQL 14+ + Prisma 7 ORM
UI	Catppuccin Mocha tema, Lucide React ikonlar
Grafikler	Recharts (5 chart tipi)
PDF	@react-pdf/renderer
Yazıcı	ESC/POS komutları (termal yazıcı)
State	React Context API, Custom Hooks
Caching	dbService (30sn TTL)

---

📦 Kurulum

Gereksinimler

• Node.js 18+
• PostgreSQL 14+
• npm veya yarn

Adımlar

1. Projeyi klonlayın:

git clone https://github.com/your-username/neufe.git
cd neufe

2. Bağımlılıkları yükleyin:

npm install

3. Ortam değişkenlerini ayarlayın:

cp .env.example .env
# .env dosyasını düzenleyip PostgreSQL bağlantı bilgilerini girin

4. Prisma yapılandırmasını kontrol edin:

# Prisma 7 için prisma.config.ts dosyasının mevcut olduğundan emin olun
# DATABASE_URL environment variable'ının .env'de tanımlı olduğunu kontrol edin

5. Veritabanını hazırlayın:

npx prisma generate
npx prisma migrate deploy
# Demo veriler için login sayfasında "🌱 Demo Veritabanını Oluştur" butonunu kullanın

6. Uygulamayı başlatın:

npm run dev

7. İlk giriş:
   • Uygulama açıldığında login sayfasına gidin
   • "🌱 Demo Veritabanını Oluştur" butonuna tıklayarak demo verileri oluşturun
   • Aşağıdaki demo kullanıcılardan biriyle giriş yapın

---

💻 Kullanım

Geliştirme Modu

npm run dev

Üretim Derlemesi

npm run build

Kod Kalitesi

npm run lint        # ESLint kontrolü
npm run lint:fix    # Otomatik düzeltme
npm run format      # Prettier formatlama

---

🚀 Release ve CI/CD

Otomatik Build & Release

Bu proje GitHub Actions kullanarak Windows, macOS ve Linux için otomatik build yapar.

Yeni Release Oluşturma

1. Tag ile Release:

# Versiyon tag'i oluşturun
git tag v1.0.0
git push origin v1.0.0

2. Manuel Release (GitHub üzerinden):
   • GitHub → Actions → "Build and Release" workflow'una gidin
   • "Run workflow" butonuna tıklayın
   • Versiyon numarasını girin (opsiyonel)

Build Çıktıları

Platform	Dosya Türü
Windows	.exe (NSIS installer)
macOS	.dmg, .zip
Linux	.AppImage, .deb

Yerel Build

# Tüm platformlar için (sadece mevcut OS'ta çalışır)
npm run build

# Sadece renderer build (test için)
npm run build:renderer

---

� Demo Kullanıcılar

Sistem 3 farklı rol seviyesi ile gelir:

Rol	Email	Şifre	Yetkiler
Admin	admin@yedekparca.com	admin123	Tüm modüllere tam erişim
Warehouse (Depocu)	depo@yedekparca.com	depo123	POS, Stok, Satın Alma, Makineler
Cashier (Kasiyer)	kasa@yedekparca.com	kasa123	Sadece POS ve Dashboard

💡 Not: Demo kullanıcıları oluşturmak için login sayfasındaki "🌱 Demo Veritabanını Oluştur" butonunu kullanın.

---

�📱 Modüller

Modül	Açıklama	Özellikler
Dashboard	Ana sayfa	Günlük satış, kasa özeti, düşük stok uyarıları, müşteri borçları, interaktif grafikler
POS	Satış Noktası	Barkod okuma, sepet yönetimi, KDV hesaplama, ödeme, fiş yazdırma
Stok	Envanter	Ürün CRUD, 2D raf haritası, stok sayımı, düşük stok bildirimleri, tedarikçi sipariş listesi
Müşteriler	CRM	Müşteri kayıtları, vergi bilgileri, borç takibi, ödeme geçmişi, fiyat listesi atama
Faturalar	Faturalama	Fatura oluşturma, PDF indirme, e-Fatura gönderimi (EDM/Logo), durum yönetimi
Tedarikçiler	Satın Alma	Tedarikçi kayıtları, iletişim bilgileri, ödeme koşulları, tedarikçi bazlı ürünler
Satın Alma	Sipariş	Sipariş oluşturma, durum takibi (Draft/Sent/Confirmed/Received), teslim alma
Raporlar	Analiz	Satış trendi, ödeme yöntemleri, en çok satanlar, saatlik dağılım (dönem filtreleri)
Kategoriler	Organizasyon	Hiyerarşik kategori ağacı, marka yönetimi, toplu işlemler
Makineler	Katalog	Tarım makineleri veritabanı, ürün uyumluluğu, model yılı filtreleme
Fiyatlama	Pazarlama	Müşteri segmenti fiyat listeleri, kampanya/indirim kodları, geçerlilik tarihleri
Garanti	Servis	Garanti talepleri, durum workflow, çözüm takibi, iade/değişim yönetimi
Stok Hareketleri	İzlenebilirlik	Tüm stok hareketleri, hareket türü filtreleme, önceki/yeni stok karşılaştırma
Muhasebe	Finans	Hesap planı (Asset/Liability/Equity/Revenue/Expense), işlem defteri
Yedekleme	Bakım	Manuel/otomatik PostgreSQL yedeği, geri yükleme, yedek geçmişi
Kullanıcılar	Yetkilendirme	Kullanıcı CRUD, rol atama, şube atama, aktif/pasif durum
Ayarlar	Konfigürasyon	Şirket bilgileri, yazıcı yapılandırması, e-Fatura ayarları, genel tercihler

---

🔐 Kullanıcı Rolleri ve Yetkilendirme

Rol	Türkçe	Yetkiler	Erişebildiği Sayfalar
ADMIN	Yönetici	Tüm modüller, kullanıcı yönetimi, ayarlar	Tüm sayfalar
WAREHOUSE	Depocu	Satış, stok yönetimi, satın alma	POS, Stok, Stok Hareketleri, Makineler, Dashboard
CASHIER	Kasiyer	Sadece satış işlemleri	POS, Dashboard

Rol Bazlı Sayfa Koruma

Uygulama AuthContext ile rol bazlı erişim kontrolü yapar:

• Her sayfa gerekli minimum rolü kontrol eder
• Yetkisiz kullanıcılar otomatik olarak yönlendirilir
• Sidebar menüsü kullanıcı rolüne göre dinamik olarak filtrelenir

---

⚡ Performans Optimizasyonları

Backend Optimizasyonları

• Lightweight Endpoints: db:products:list-light - POS için hafif ürün listesi (gereksiz include'lar yok)
• Aggregated Queries: db:dashboard:stats - Dashboard için tek optimized sorgu
• Database Indexes: Product (barcode, name), Invoice (createdAt, customerId)

Frontend Service Layer

Merkezi Servis (dbService.ts):

import { dbService } from '../lib/dbService'

// 30 saniye cache ile otomatik veri yönetimi
const products = await dbService.getProductsLight({ search: 'filtre' })
dbService.invalidateCache('products') // Manuel cache temizleme

Custom Hooks:

• useProducts - Ürün listesi ve cache yönetimi
• useProductSearch - 300ms debounced arama
• useLowStockProducts - Düşük stoklu ürünler
• useCustomers - Müşteri listesi ve cache
• useCustomersWithDebt - Borçlu müşteriler
• useInvoices - Fatura yönetimi
• useTodayInvoices - Bugünün faturaları

Component Optimizasyonları

• React.memo: Gereksiz re-render'ları önler (ProductLookup, CartItemRow)
• useMemo: Hesaplamaları cache'ler (KDV, toplam, filtreleme)
• useCallback: Fonksiyon referanslarını sabit tutar
• Debouncing: Arama sorguları 300ms debounce ile optimize edildi

Performans İyileştirme Sonuçları

Metrik	Önce	Sonra	İyileştirme
POS API Çağrısı	3 ayrı istek	1 lightweight istek	~66% azalma
Veri Boyutu	Tüm ilişkiler	Sadece gerekli alanlar	~50% azalma
Arama Yükü	Her tuşta DB sorgusu	300ms debounce	Önemli azalma
Cache Hit	Yok	30sn TTL	Tekrar çağrı yok
CPU Kullanımı	Her render hesaplama	useMemo cache	Düşük

---

🔧 Prisma 7 Yapılandırması

Önemli Değişiklik

Prisma 7+ sürümünde schema.prisma içindeki datasource.url artık desteklenmiyor. Bağlantı yapılandırması prisma.config.ts dosyasına taşınmalıdır.

prisma.config.ts Örneği

import path from 'node:path'
import { defineConfig } from 'prisma'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(__dirname, 'prisma', 'schema.prisma'),
  migrate: {
    adapter: async () => {
      const { PrismaPg } = await import('@prisma/adapter-pg')
      const { Pool } = await import('pg')
      const pool = new Pool({ 
        connectionString: process.env.DATABASE_URL 
      })
      return new PrismaPg(pool)
    },
  },
})

Gerekli Paketler

npm install @prisma/adapter-pg pg

schema.prisma Değişikliği

datasource db {
  provider = "postgresql"
  // url satırı kaldırılmalı veya yorumlanmalı
  // url = env("DATABASE_URL") ❌ ARTIK DESTEKLENMİYOR
}

Daha Fazla Bilgi

• Prisma 7 Datasource Config
• Prisma 7 Client Config

---

🚧 Bilinen Sorunlar & TODO

Öncelikli (Phase 6 - Settings & Integration)

❌ Settings Kalıcılığı

Problem: Ayarlar sayfası UI var ama hiçbir ayar veritabanına kaydedilmiyor.

Yapılacaklar:

• main/database.ts - IPC handlers (db:settings:get, db:settings:save)
• useSettings hook ve SettingsContext oluştur
• Hardcoded değerleri ayarlardan çek (KDV oranları, şirket bilgileri, yazıcı ayarları)

❌ Backup Sistemi

Problem: Backup sayfası UI var ama gerçek PostgreSQL backup/restore yok.

Yapılacaklar:

• main/backup/manager.ts - pg_dump ile backup
• main/backup/scheduler.ts - Otomatik backup zamanlayıcı
• IPC handlers (db:backups:create, db:backups:restore)

❌ EDM e-Fatura Entegrasyonu

Problem: e-Fatura UI simüle edilmiş, gerçek API çağrısı yok.

Yapılacaklar:

• main/einvoice/edm.ts - EDM API client
• API endpoints: /invoice/send, /invoice/status, /invoice/cancel
• Invoice.eInvoiceStatus workflow implementasyonu

❌ Yazıcı Yönetimi

Problem: Yazıcı keşfi ve test fonksiyonu yok.

Yapılacaklar:

• main/printer/manager.ts - Yazıcı keşfi
• IPC handlers (printer:list, printer:test)

❌ Audit Log UI

Problem: Loglar kaydediliyor ama görüntüleme sayfası yok.

Yapılacaklar:

• pages/audit-logs.tsx - Log listesi, filtreleme
• Sidebar'a link ekle

❌ Export Fonksiyonları

Problem: "Dışa Aktar" butonları işlevsiz.

Yapılacaklar:

• lib/exportService.ts - CSV/Excel export
• xlsx paketi ekle

Gelecek Geliştirmeler (Phase 7)

🔮 Multi-Branch System

Durum: Schema hazır, UI ve iş mantığı eksik.

Özellikler:

• Şube yönetimi sayfası
• Şube bazlı stok ve faturalar
• Şubeler arası transfer sistemi
• Merkez yönetim ve konsolide raporlar

🔮 3D Warehouse View

Durum: Planlanmış, henüz başlanmadı.

Teknoloji: React Three Fiber

---

🎨 Tema

Uygulama Catppuccin Mocha renklerini kullanmaktadır.

---

📄 Lisans

Bu proje MIT License altında lisanslanmıştır.

Neural Forge One's Dark Triad: Architect the system, Execute decisively, Interpret results.

🔒 Güvenlik

Güvenlik açıklarını sorumlu bir şekilde bildirmek için lütfen SECURITY.md dosyasına bakın.

---

🤝 Katkıda Bulunma

Katkılarınızı bekliyoruz! Lütfen aşağıdaki dosyaları okuyun:

• CONTRIBUTING.md - Katkı rehberi
• CODE_OF_CONDUCT.md - Davranış kuralları (varsa)
• GITHUB_SETUP.md - GitHub'a yükleme rehberi

Hızlı Başlangıç

1. Bu repoyu fork edin
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add amazing feature')
4. Branch'i push edin (git push origin feature/amazing-feature)
5. Pull Request açın

---

Neufe ile yedek parça yönetimi hiç bu kadar kolay olmamıştı! 🚀