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ıç](#hızlı-başlangıç)
- [Sistem Mimarisi](#sistem-mimarisi)
- [Kullanıcı Rolleri ve Yetkileri](#kullanıcı-rolleri-ve-yetkileri)
- [İş Akışları](#iş-akışları)
- [Yaygın Sorunlar ve Çözümleri](#yaygın-sorunlar-ve-çözümleri)
- [Best Practices](#best-practices)
- [Kaynaklar ve Referanslar](#kaynaklar-ve-referanslar)

## 🚀 Hızlı Başlangıç

### Sistemi 5 Dakikada Çalıştırma

```bash
# 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](#admin-paneli) |
| Yakıt Sorumlusu | `yakitsorum` | `Yakit@123` | [Yakıt Sorumlusu Paneli](#yakıt-sorumlusu-paneli) |
| Mal Sorumlusu | `malsorum1` | `Mal@123` | [Mal Sorumlusu Paneli](#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:**
```bash
# 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:**
```javascript
// 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:**
```bash
# 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:**
```sql
-- 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:**
```bash
# 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:**
```javascript
// 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:**
```bash
# 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:**
```javascript
// Browser console'da test
const socket = io('http://localhost:5005');
socket.on('connect', () => console.log('Connected'));
```

## 📚 Best Practices

### Development Best Practices

#### 1. Code Organization
```javascript
// ✅ İ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
```javascript
// ✅ İ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
```javascript
// ✅ İ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
```javascript
// ✅ İ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
```javascript
// ✅ İ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
```javascript
// ✅ İ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
```javascript
// ✅ İ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](../README.md) - Proje genel bakış
- [API.md](API.md) - API dokümantasyonu
- [DATABASE.md](DATABASE.md) - Veritabanı şeması
- [STRUCTURE.md](STRUCTURE.md) - Proje yapısı
- [DEPLOYMENT.md](DEPLOYMENT.md) - Dağıtım kılavuzu
- [FRONTEND.md](FRONTEND.md) - Frontend mimarisi

### External Resources

#### Teknoloji Dokümantasyonları
- [Svelte Documentation](https://svelte.dev/docs)
- [Express.js Guide](https://expressjs.com/en/guide/)
- [Socket.IO Documentation](https://socket.io/docs/)
- [SQLite Documentation](https://www.sqlite.org/docs.html)
- [Vite Documentation](https://vitejs.dev/guide/)

#### Development Tools
- [VS Code](https://code.visualstudio.com/) + [Svelte Extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- [SQLite Browser](https://sqlitebrowser.org/) - Veritabanı yönetimi
- [Postman](https://www.postman.com/) - API testing
- [Git](https://git-scm.com/) - Versiyon kontrolü

#### Learning Resources
- [MDN Web Docs](https://developer.mozilla.org/) - Web teknolojileri
- [JavaScript Info](https://javascript.info/) - JavaScript öğrenme
- [CSS Tricks](https://css-tricks.com/) - CSS teknikleri
- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) - Node.js pratikleri

### Komut Referansı

#### Geliştirme Komutları
```bash
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ı
```bash
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ı
```bash
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.