ytp/docs/KNOWLEDGE_BASE.md

YTP Bilgi Bankası

Yakıt Takip Sistemi kapsamlı bilgi bankası - hızlı referans, kılavuzlar ve sorun giderme rehberi.

📋 İçerik

• Hızlı Başlangıç
• Sistem Mimarisi
• Kullanıcı Rolleri ve Yetkileri
• İş Akışları
• Yaygın Sorunlar ve Çözümleri
• Best Practices
• Kaynaklar ve Referanslar

🚀 Hızlı Başlangıç

Sistemi 5 Dakikada Çalıştırma

# 1. Projeyi klonlayın
git clone <repository-url>
cd ytp

# 2. Bağımlılıkları yükleyin
npm install && cd client && npm install && cd ..

# 3. Veritabanını başlatın
npm run prepare:db

# 4. Sistemi çalıştırın
npm run dev

# 5. Tarayıcıda açın
# Frontend: http://localhost:5173
# Backend API: http://localhost:5005/api

Varsayılan Giriş Bilgileri

Rol	Kullanıcı Adı	Şifre	Panel
Admin	admin	Admin!123	Admin Paneli
Yakıt Sorumlusu	yakitsorum	Yakit@123	Yakıt Sorumlusu Paneli
Mal Sorumlusu	malsorum1	Mal@123	Mal Sorumlusu Paneli

İlk Yakıt Fişi Oluşturma

1. Giriş Yap: Yakıt sorumlusu ile giriş yapın
2. Kaynak Kontrolü: Araç, birlik ve personel kayıtlarını kontrol edin
3. Fiş Oluştur: "Yeni Fiş" butonuna tıklayın
4. Form Doldur: Tüm zorunlu alanları doldurun
5. Onay Gönder: Mal sorumlusuna gönder
6. Bildirim Takibi: Real-time bildirimleri izleyin

🏗️ Sistem Mimarisi

Mimari Diyagram

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Database      │
│   (Svelte)      │◄──►│   (Express)     │◄──►│   (SQLite)      │
│                 │    │                 │    │                 │
│ - UI Components │    │ - REST API      │    │ - users         │
│ - State Mgmt    │    │ - Socket.IO     │    │ - vehicles      │
│ - Routing       │    │ - Auth/Authz    │    │ - units         │
│ - API Client    │    │ - PDF Generation│    │ - fuel_personnel│
└─────────────────┘    └─────────────────┘    │ - fuel_slips    │
                                                └─────────────────┘

Teknoloji Stack Karşılaştırması

Katman	Teknoloji	Neden?	Alternatifler
Frontend	Svelte + Vite	Hızlı, küçük bundle, reaktif	React, Vue, Angular
Backend	Node.js + Express	Hızlı development, JavaScript ekosistemi	Python, PHP, Java
Database	SQLite3	Hafif, kurulum gerektirmeyen, taşınabilir	PostgreSQL, MySQL
Real-time	Socket.IO	WebSocket wrapper, fallback mekanizmaları	Raw WebSocket, SSE
PDF	PDFKit	Node.js uyumlu, esnek	Puppeteer, jsPDF

👥 Kullanıcı Rolleri ve Yetkileri

Admin (Sistem Yöneticisi)

Yetkiler:

• ✅ Tüm kullanıcıları yönetme
• ✅ Mal sorumluları ekleme/güncelleme/silme
• ✅ Araç kayıtlarını yönetme
• ✅ Birlik bilgilerini yönetme
• ✅ Personel kayıtlarını yönetme
• ✅ Sistem ayarlarını yapılandırma
• ❌ Yakıt fişi oluşturma
• ❌ Fiş onaylama/reddetme

Kullanım Alanları:

• Sistem kurulum ve bakım
• Kullanıcı yönetimi
• Temel veri girişi
• Raporlama ve analiz

Yakıt Sorumlusu

Yetkiler:

• ✅ Yakıt fişi oluşturma
• ✅ Fiş durumlarını takip etme
• ✅ PDF fiş indirme
• ✅ Kaynak bilgilerini görme
• ❌ Kullanıcı yönetimi
• ❌ Fiş onaylama
• ❌ Temel veri düzenleme

Kullanım Alanları:

• Günlük yakıt ikmal işlemleri
• Fiş oluşturma ve takip
• Raporlama

Mal Sorumlusu

Yetkiler:

• ✅ Atanan fişleri görme
• ✅ Fiş onaylama/reddetme
• ✅ Onay/reddetme gerekçesi ekleme
• ✅ Atanan fişleri arşivleme
• ❌ Fiş oluşturma
• ❌ Kullanıcı yönetimi
• ❌ Temel veri düzenleme

Kullanım Alanları:

• Yakıt ikmal onay süreçleri
• Stok takibi
• Raporlama

🔄 İş Akışları

1. Kullanıcı Yönetimi Akışı (Admin)

Başlangıç
    ↓
Admin Girişi
    ↓
"Kullanıcı Yönetimi" → "Mal Sorumluları"
    ↓
"Ekle" butonu → Form doldur → Kaydet
    ↓
Kullanıcı oluşturuldu → Bilgilendirme
    ↓
Bitiş

2. Yakıt Fişi Oluşturma Akışı

Başlangıç
    ↓
Yakıt Sorumlusu Girişi
    ↓
"Yeni Fiş" butonu
    ↓
Form doldurma:
├─ Tarih seçimi
├─ Kuvvet seçimi
├─ Birlik seçimi
├─ Araç seçimi
├─ Yakıt bilgileri
├─ Personel seçimi
└─ Mal sorumlusu atama
    ↓
"Oluştur" butonu
    ↓
Validasyon → Veritabanı kayıt
    ↓
Mal sorumlusuna bildirim
    ↓
PDF fiş oluştur (opsiyonel)
    ↓
Bitiş

3. Fiş Onay Akışı

Başlangıç
    ↓
Mal Sorumlusu Girişi
    ↓
"Atanan Fişler" listesi
    ↓
Fiş seçimi → Detay görüntüle
    ↓
Karar verme:
├─ "Onayla" → Durum: approved
└─ "Reddet" → Gerekçe gir → Durum: rejected
    ↓
Yakıt sorumlusuna bildirim
    ↓
Bitiş

4. Real-time Bildirim Akışı

Olay Tetiklenir
    ↓
Server Event Oluştur
    ↓
Socket.IO Emit
    ↓
İlgili Client'a Gönder
    ↓
UI Güncellenir
    ↓
Kullanıcı Bilgilendirilir

🔧 Yaygın Sorunlar ve Çözümleri

Giriş ve Oturum Sorunları

Sorun: "Kullanıcı adı veya şifre hatalı"

Nedenler:

• Yanlış kullanıcı adı/şifre
• Büyük/küçük harf duyarlılığı
• Boşluk karakterleri

Çözümler:

# Varsayılan kullanıcıları kontrol et
sqlite3 data/app.db "SELECT username, role FROM users;"

# Şifre sıfırlama (admin için)
sqlite3 data/app.db "UPDATE users SET password = 'Admin!123' WHERE username = 'admin';"

Sorun: "Oturum bulunamadı"

Nedenler:

• Token süresi dolmuş
• Browser storage temizlenmiş
• Sunucu yeniden başlatılmış

Çözümler:

// Browser console'dan kontrol et
localStorage.getItem('sessionToken');

// Manuel temizleme
localStorage.removeItem('sessionToken');
location.reload();

Veritabanı Sorunları

Sorun: "Veritabanı okunamadı"

Nedenler:

• Veritabanı dosyası yok
• İzin sorunları
• Dosya kilitli

Çözümler:

# Veritabanını yeniden oluştur
rm data/app.db
npm run prepare:db

# İzinleri kontrol et
ls -la data/app.db
chmod 664 data/app.db

Sorun: "Bu kullanici adi zaten mevcut"

Nedenler:

• Unique constraint ihlali
• Önceki kayıt silinmemiş

Çözümler:

-- Mevcut kullanıcıları listele
SELECT id, username, role FROM users;

-- Kullanıcıyı sil (ID'ye göre)
DELETE FROM users WHERE id = 3;

API ve Bağlantı Sorunları

Sorun: "Network Error"

Nedenler:

• Backend çalışmıyor
• Port çakışması
• Firewall engeli

Çözümler:

# Port durumunu kontrol et
lsof -i :5005

# Backend'i yeniden başlat
npm run start:server

# Port değiştir
PORT=3000 npm run start:server

Sorun: "CORS hatası"

Nedenler:

• Origin mismatch
• CORS ayarları eksik

Çözümler:

// server/index.js CORS ayarları
app.use(cors({
  origin: ['http://localhost:5173', 'http://localhost:3000'],
  credentials: true
}));

Frontend Sorunları

Sorun: Component yüklenmiyor

Nedenler:

• JavaScript error
• Import hataları
• Build sorunları

Çözümler:

# Frontend'i yeniden build et
cd client
npm run build

# Development modunda kontrol et
npm run dev

Sorun: Socket.IO bağlantı kurulamıyor

Nedenler:

• Token geçersiz
• Server kapalı
• WebSocket engellendi

Çözümler:

// Browser console'da test
const socket = io('http://localhost:5005');
socket.on('connect', () => console.log('Connected'));

📚 Best Practices

Development Best Practices

1. Code Organization

// ✅ İyi pratik - Component based structure
src/
├── components/
│   ├── auth/
│   ├── admin/
│   └── shared/
├── lib/
├── api/
└── styles/

// ❌ Kötü pratik - Tüm dosyaları tek dizinde
src/
├── LoginView.svelte
├── AdminPanel.svelte
├── api.js
└── styles.css

2. Error Handling

// ✅ İyi pratik - Spesifik error handling
async function createFuelSlip(data) {
  try {
    const response = await api.post('/fuel-slips', data);
    return response.slip;
  } catch (error) {
    if (error.status === 409) {
      throw new Error('Bu fiş zaten mevcut');
    } else if (error.status === 400) {
      throw new Error('Form verileri geçersiz');
    }
    throw new Error('Fiş oluşturulamadı');
  }
}

// ❌ Kötü pratik - Generic error handling
async function createFuelSlip(data) {
  try {
    return await api.post('/fuel-slips', data);
  } catch (error) {
    console.log(error); // Silent fail
  }
}

3. State Management

// ✅ İyi pratik - Minimal reactivity
let search = '';
let items = [];

$: filteredItems = items.filter(item =>
  item.name.toLowerCase().includes(search.toLowerCase())
);

// ❌ Kötü pratik - Unnecessary reactivity
$: searchLower = search.toLowerCase();
$: filteredItems = items.filter(item =>
  item.name.toLowerCase().includes(searchLower)
);

Security Best Practices

1. Input Validation

// ✅ İyi pratik - Server-side validation
app.post('/api/vehicles', (req, res) => {
  const { brand, model, year, plate } = req.body;

  // Server-side validation
  if (!brand || !model || !year || !plate) {
    return res.status(400).json({ message: 'All fields required' });
  }

  if (year < 1990 || year > new Date().getFullYear() + 1) {
    return res.status(400).json({ message: 'Invalid year' });
  }

  // Process valid data
});

// ❌ Kötü pratik - Sadece client-side validation
// Frontend validation bypass edilebilir

2. Session Management

// ✅ İyi pratik - Secure session handling
function createSession(user) {
  const token = crypto.randomBytes(32).toString('hex');
  const session = {
    id: user.id,
    role: user.role,
    createdAt: Date.now(),
    expiresAt: Date.now() + (24 * 60 * 60 * 1000) // 24 hours
  };

  sessions.set(token, session);
  return { token, session };
}

// ❌ Kötü pratik - Predictable tokens
function createSession(user) {
  const token = `${user.id}-${Date.now()}`; // Predictable!
  // ...
}

Performance Best Practices

1. Database Queries

// ✅ İyi pratik - Efficient queries
async function getFuelSlipsByStatus(status) {
  return db.all(`
    SELECT fs.*, u.display_name as inventoryManagerName
    FROM fuel_slips fs
    LEFT JOIN users u ON u.id = fs.inventory_manager_id
    WHERE fs.status = ?
    ORDER BY fs.created_at DESC
  `, [status]);
}

// ❌ Kötü pratik - N+1 query problem
async function getFuelSlipsByStatus(status) {
  const slips = await db.all(`
    SELECT * FROM fuel_slips WHERE status = ?
  `, [status]);

  // N+1 queries!
  for (const slip of slips) {
    const user = await db.get(`
      SELECT display_name FROM users WHERE id = ?
    `, [slip.inventory_manager_id]);
    slip.inventoryManagerName = user.display_name;
  }

  return slips;
}

2. Component Optimization

// ✅ İyi pratik - Lazy loading
const AdminPanel = lazy(() => import('./components/AdminPanel.svelte'));

// Usage
{#if user.role === 'admin'}
  <Suspense fallback={<div>Loading...</div>}>
    <AdminPanel {token} />
  </Suspense>
{/if}

// ❌ Kötü pratik - Her zaman tüm component'leri yüklemek
import AdminPanel from './components/AdminPanel.svelte';
import FuelManagerPanel from './components/FuelManagerPanel.svelte';
// ... tüm component'ler import edildi

🔗 Kaynaklar ve Referanslar

Dokümantasyon Linkleri

• README.md - Proje genel bakış
• API.md - API dokümantasyonu
• DATABASE.md - Veritabanı şeması
• STRUCTURE.md - Proje yapısı
• DEPLOYMENT.md - Dağıtım kılavuzu
• FRONTEND.md - Frontend mimarisi

External Resources

Teknoloji Dokümantasyonları

• Svelte Documentation
• Express.js Guide
• Socket.IO Documentation
• SQLite Documentation
• Vite Documentation

Development Tools

• VS Code + Svelte Extension
• SQLite Browser - Veritabanı yönetimi
• Postman - API testing
• Git - Versiyon kontrolü

Learning Resources

• MDN Web Docs - Web teknolojileri
• JavaScript Info - JavaScript öğrenme
• CSS Tricks - CSS teknikleri
• Node.js Best Practices - Node.js pratikleri

Komut Referansı

Geliştirme Komutları

npm run dev              # Geliştirme sunucusu
npm run start:server     # Sadece backend
cd client && npm run dev # Sadece frontend
npm run prepare:db       # Veritabanı başlangıç

Production Komutları

npm run build            # Frontend build
npm start                # Production sunucusu
pm2 start ecosystem.config.js  # PM2 ile başlat
docker-compose up -d     # Docker ile başlat

Veritabanı Komutları

sqlite3 data/app.db              # Veritabanına bağlan
sqlite3 data/app.db ".tables"    # Tabloları listele
sqlite3 data/app.db ".schema"    # Şemayı göster
sqlite3 data/app.db ".backup backup.db"  # Yedek al

Hızlı Referans Kartları

API Endpoint'leri

Authentication:
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/session

Admin Operations:
GET/POST/PUT/DELETE /api/inventory-managers
GET/POST/PUT/DELETE /api/vehicles
GET/POST/PUT/DELETE /api/units
GET/POST/PUT/DELETE /api/fuel-personnel

Fuel Operations:
GET    /api/fuel/resources
GET    /api/fuel-slips
POST   /api/fuel-slips
GET    /api/fuel-slips/:id/pdf
PATCH  /api/fuel-slips/:id/status

Varsayılan Veriler

Users:
- admin/Admin!123 (admin)
- yakitsorum/Yakit@123 (fuel_manager)
- malsorum1/Mal@123 (inventory_manager)

Vehicles:
- Ford Transit 2021 (34 AYT 312)
- Isuzu NPR 2019 (34 FZT 908)

Forces:
- MSB, K.K.K., Dz.K.K., Hv.K.K., SGK, Gnkur. Bşk., Hrt.Gn.K.

---

Not: Bu bilgi bankesi sürekli güncellenmektedir. Yeni sorunlar ve çözümler eklenecektir.