Readme index'ler eklendi.

2025-11-03 23:12:45 +03:00
parent 7edbab2689
commit 63abf6eaff
10 changed files with 3867 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,729 @@
+# Geliştirme ve Dağıtım Kılavuzu
+
+Yakıt Takip Sistemi geliştirme ortamı kurulumu, test süreçleri ve prodüksiyon dağıtımı hakkında kapsamlı rehber.
+
+## 📋 İçerlik
+
+- [Geliştirme Ortamı Kurulumu](#geliştirme-ortamı-kurulumu)
+- [Geliştirme Süreci](#geliştirme-süreci)
+- [Test Stratejisi](#test-stratejisi)
+- [Prodüksiyon Dağıtımı](#prodüksiyon-dağıtımı)
+- [İzleme ve Bakım](#izleme-ve-bakım)
+- [Sorun Giderme](#sorun-giderme)
+
+## 🛠️ Geliştirme Ortamı Kurulumu
+
+### Gereksinimler
+- **Node.js**: 16.x veya üzeri
+- **npm**: 7.x veya üzeri
+- **Git**: Son sürüm
+- **Editör**: VS Code (önerilen)
+- **Tarayıcı**: Chrome/Firefox (geliştirme araçları)
+
+### Adım 1: Sistemi Kurun
+
+#### Node.js Kurulumu
+```bash
+# macOS (Homebrew)
+brew install node
+
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Windows
+# https://nodejs.org/en/download/ adresinden indirin
+```
+
+#### VS Code ve Eklentiler
+```bash
+# Önerilen VS Code eklentileri
+- Svelte for VS Code
+- SQLite
+- Thunder Client (API testing)
+- GitLens
+- Prettier
+- ESLint
+```
+
+### Adım 2: Projeyi Kurun
+
+```bash
+# 1. Repoyu klonlayın
+git clone <repository-url>
+cd ytp
+
+# 2. Ana proje bağımlılıklarını yükleyin
+npm install
+
+# 3. Frontend bağımlılıklarını yükleyin
+cd client
+npm install
+cd ..
+
+# 4. Veritabanını başlatın
+npm run prepare:db
+
+# 5. Ortam değişkenlerini yapılandırın
+cp .env.example .env
+```
+
+### Adım 3: Ortam Değişkenleri
+
+#### .env Dosyası
+```bash
+# Sunucu ayarları
+PORT=5005
+NODE_ENV=development
+
+# Veritabanı ayarları
+DB_PATH=./data/app.db
+
+# Session ayarları
+SESSION_SECRET=your-secret-key-here
+SESSION_TIMEOUT=24h
+
+# CORS ayarları
+CORS_ORIGIN=http://localhost:5173
+
+# Log seviyesi
+LOG_LEVEL=debug
+```
+
+### Adım 4: Geliştirme Sunucusunu Başlatın
+
+```bash
+# Geliştirme modunda başlatma (hem backend hem frontend)
+npm run dev
+
+# Sadece backend sunucusu
+npm run start:server
+
+# Sadece frontend (ayrı terminal)
+cd client && npm run dev
+```
+
+### Adım 5: Doğrulama
+
+```bash
+# Sunucu çalışıyor mu?
+curl http://localhost:5005/api/session
+
+# Frontend çalışıyor mu?
+# Tarayıcıda http://localhost:5173 açın
+```
+
+## 🔄 Geliştirme Süreci
+
+### Git Workflow
+
+#### Branch Stratejisi
+```
+main                 # Prodüksiyon branch'i
+├── develop          # Geliştirme branch'i
+├── feature/*        # Yeni özellikler
+├── bugfix/*         # Hata düzeltmeleri
+└── hotfix/*         # Acil düzeltmeler
+```
+
+#### Commit Mesajları
+```bash
+# Format
+<type>(<scope>): <description>
+
+# Örnekler
+feat(auth): add JWT token refresh mechanism
+fix(api): handle null vehicle_id gracefully
+docs(readme): update installation instructions
+refactor(db): optimize fuel_slip queries
+```
+
+#### Geliştirme Akışı
+```bash
+# 1. Yeni feature branch oluştur
+git checkout -b feature/fuel-slip-pdf
+
+# 2. Geliştirme yap
+# ... kod değişiklikleri
+
+# 3. Değişiklikleri commit et
+git add .
+git commit -m "feat(fuel): add PDF generation for fuel slips"
+
+# 4. Branch'e push et
+git push origin feature/fuel-slip-pdf
+
+# 5. Pull Request oluştur
+# GitHub/GitLab üzerinden PR oluştur
+
+# 6. Review ve merge
+# Code review sonrası develop branch'ine merge
+
+# 7. Geliştirme sunucusunu güncelle
+git checkout develop
+git pull origin develop
+```
+
+### Kod Kalitesi
+
+#### ESLint Yapılandırması
+```json
+// .eslintrc.json
+{
+  "extends": ["eslint:recommended"],
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "rules": {
+    "no-console": "warn",
+    "no-unused-vars": "error",
+    "prefer-const": "error"
+  }
+}
+```
+
+#### Prettier Yapılandırması
+```json
+// .prettierrc
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2
+}
+```
+
+### Test Stratejisi
+
+#### Test Türleri
+- **Unit Tests**: Fonksiyon ve bileşen testleri
+- **Integration Tests**: API endpoint testleri
+- **E2E Tests**: Kullanıcı senaryoları
+- **Manual Tests**: Manuel QA süreçleri
+
+#### Test Tools
+```bash
+# Test framework'leri
+npm install --save-dev jest supertest
+npm install --save-dev @testing-library/svelte
+npm install --save-dev playwright
+```
+
+#### Örnek Testler
+```javascript
+// tests/api.test.js
+const request = require('supertest');
+const app = require('../server/index');
+
+describe('Authentication', () => {
+  test('POST /api/auth/login with valid credentials', async () => {
+    const response = await request(app)
+      .post('/api/auth/login')
+      .send({ username: 'admin', password: 'Admin!123' })
+      .expect(200);
+
+    expect(response.body).toHaveProperty('token');
+    expect(response.body.user.role).toBe('admin');
+  });
+});
+```
+
+## 🚀 Prodüksiyon Dağıtımı
+
+### Dağıtım Seçenekleri
+
+#### 1. Docker Dağıtımı (Önerilen)
+
+##### Dockerfile
+```dockerfile
+# Multi-stage build
+FROM node:18-alpine AS builder
+
+# Build stage
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+WORKDIR /app/client
+RUN npm ci
+RUN npm run build
+
+# Production stage
+FROM node:18-alpine AS production
+
+WORKDIR /app
+COPY --from=builder /app/package*.json ./
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/server ./server
+COPY --from=builder /app/client/dist ./client/dist
+COPY --from=builder /app/data ./data
+
+EXPOSE 5005
+
+CMD ["node", "server/index.js"]
+```
+
+##### docker-compose.yml
+```yaml
+version: '3.8'
+
+services:
+  ytp-app:
+    build: .
+    ports:
+      - "5005:5005"
+    environment:
+      - NODE_ENV=production
+      - PORT=5005
+    volumes:
+      - ./data:/app/data
+      - ./logs:/app/logs
+    restart: unless-stopped
+
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf
+      - ./ssl:/etc/nginx/ssl
+    depends_on:
+      - ytp-app
+    restart: unless-stopped
+```
+
+##### Docker Komutları
+```bash
+# Build ve çalıştırma
+docker-compose up -d --build
+
+# Logları izleme
+docker-compose logs -f ytp-app
+
+# Yeniden başlatma
+docker-compose restart ytp-app
+
+# Temizleme
+docker-compose down -v
+```
+
+#### 2. PM2 ile Dağıtım
+
+##### PM2 Yapılandırması
+```json
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'ytp-app',
+    script: 'server/index.js',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env: {
+      NODE_ENV: 'production',
+      PORT: 5005
+    },
+    error_file: './logs/err.log',
+    out_file: './logs/out.log',
+    log_file: './logs/combined.log',
+    time: true
+  }]
+};
+```
+
+##### PM2 Komutları
+```bash
+# PM2 kurulumu
+npm install -g pm2
+
+# Uygulamayı başlatma
+pm2 start ecosystem.config.js
+
+# Durumunu kontrol etme
+pm2 status
+
+# Logları izleme
+pm2 logs ytp-app
+
+# Yeniden başlatma
+pm2 restart ytp-app
+
+# Sunucu yeniden başlatığında otomatik başlatma
+pm2 startup
+pm2 save
+```
+
+#### 3. Systemd Service
+
+##### Service Dosyası
+```ini
+# /etc/systemd/system/ytp.service
+[Unit]
+Description=Yakit Takip Sistemi
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/var/www/ytp
+ExecStart=/usr/bin/node server/index.js
+Restart=always
+RestartSec=10
+Environment=NODE_ENV=production
+Environment=PORT=5005
+
+[Install]
+WantedBy=multi-user.target
+```
+
+##### Systemd Komutları
+```bash
+# Service'i etkinleştirme
+sudo systemctl enable ytp.service
+
+# Service'i başlatma
+sudo systemctl start ytp.service
+
+# Durumunu kontrol etme
+sudo systemctl status ytp.service
+
+# Logları izleme
+sudo journalctl -u ytp.service -f
+```
+
+### Nginx Yapılandırması
+
+#### nginx.conf
+```nginx
+events {
+    worker_connections 1024;
+}
+
+http {
+    upstream ytp_backend {
+        server 127.0.0.1:5005;
+    }
+
+    server {
+        listen 80;
+        server_name your-domain.com;
+
+        # Frontend statik dosyaları
+        location / {
+            root /var/www/ytp/client/dist;
+            try_files $uri $uri/ /index.html;
+
+            # Cache headers
+            location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+                expires 1y;
+                add_header Cache-Control "public, immutable";
+            }
+        }
+
+        # API requests
+        location /api/ {
+            proxy_pass http://ytp_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_cache_bypass $http_upgrade;
+        }
+
+        # WebSocket connections
+        location /socket.io/ {
+            proxy_pass http://ytp_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    # HTTPS (SSL kuruluysa)
+    server {
+        listen 443 ssl http2;
+        server_name your-domain.com;
+
+        ssl_certificate /etc/nginx/ssl/cert.pem;
+        ssl_certificate_key /etc/nginx/ssl/key.pem;
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers HIGH:!aNULL:!MD5;
+
+        # Aynı proxy ayarları burada da geçerli
+        # ...
+    }
+}
+```
+
+### Prodüksiyon Kurulum Script'i
+
+#### setup.sh
+```bash
+#!/bin/bash
+
+# Prodüksiyon kurulum script'i
+set -e
+
+echo "🚀 YTP Prodüksiyon Kurulumu Başlatılıyor..."
+
+# Sistem güncellemeleri
+sudo apt update && sudo apt upgrade -y
+
+# Node.js kurulumu
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# PM2 kurulumu
+sudo npm install -g pm2
+
+# Nginx kurulumu
+sudo apt install -y nginx
+
+# Firewall ayarları
+sudo ufw allow ssh
+sudo ufw allow 'Nginx Full'
+sudo ufw --force enable
+
+# Proje kurulumu
+sudo mkdir -p /var/www/ytp
+sudo chown $USER:$USER /var/www/ytp
+
+# Git ile projeyi çek
+cd /var/www/ytp
+git clone <repository-url> .
+
+# Bağımlılıkları yükle
+npm install
+cd client && npm install && cd ..
+
+# Veritabanını başlat
+npm run prepare:db
+
+# PM2 başlat
+pm2 start ecosystem.config.js
+pm2 startup
+pm2 save
+
+# Nginx yapılandırması
+sudo cp nginx.conf /etc/nginx/sites-available/ytp
+sudo ln -s /etc/nginx/sites-available/ytp /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+
+echo "✅ Kurulum tamamlandı!"
+echo "🌐 Uygulama: http://your-domain.com"
+echo "📊 PM2 durumu: pm2 status"
+echo "📋 Loglar: pm2 logs ytp-app"
+```
+
+## 📊 İzleme ve Bakım
+
+### Log Yönetimi
+
+#### Log Yapılandırması
+```javascript
+// server/logger.js
+const winston = require('winston');
+
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'logs/combined.log' }),
+    new winston.transports.Console({
+      format: winston.format.simple()
+    })
+  ]
+});
+
+module.exports = logger;
+```
+
+#### Log Rotasyon
+```bash
+# logrotate yapılandırması
+# /etc/logrotate.d/ytp
+/var/www/ytp/logs/*.log {
+    daily
+    missingok
+    rotate 52
+    compress
+    notifempty
+    create 644 www-data www-data
+    postrotate
+        pm2 reloadLogs
+    endscript
+}
+```
+
+### Performans İzleme
+
+#### Metrics Collection
+```javascript
+// server/metrics.js
+const express = require('express');
+const responseTime = require('response-time');
+
+const app = express();
+
+// Response time middleware
+app.use(responseTime((req, res, time) => {
+  console.log(`${req.method} ${req.url} - ${time}ms`);
+}));
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+    memory: process.memoryUsage()
+  });
+});
+```
+
+### Backup Stratejisi
+
+#### Database Backup Script
+```bash
+#!/bin/bash
+# backup.sh
+
+BACKUP_DIR="/var/backups/ytp"
+DATE=$(date +%Y%m%d_%H%M%S)
+DB_PATH="/var/www/ytp/data/app.db"
+
+mkdir -p $BACKUP_DIR
+
+# Veritabanı yedeği
+sqlite3 $DB_PATH ".backup $BACKUP_DIR/app_backup_$DATE.db"
+
+# Eski yedekleri temizle (30 gün)
+find $BACKUP_DIR -name "app_backup_*.db" -mtime +30 -delete
+
+echo "Backup completed: $BACKUP_DIR/app_backup_$DATE.db"
+```
+
+#### Cron Job
+```bash
+# Günlük backup (saat 02:00)
+0 2 * * * /var/www/ytp/scripts/backup.sh
+
+# Log rotation (haftalık)
+0 3 * * 0 /usr/sbin/logrotate /etc/logrotate.d/ytp
+
+# Sistem health check (5 dakikada bir)
+*/5 * * * * curl -f http://localhost:5005/health || echo "Health check failed" | mail -s "YTP Alert" admin@domain.com
+```
+
+## 🔧 Sorun Giderme
+
+### Yaygın Sorunlar
+
+#### 1. Port Çakışması
+```bash
+# Port kullanan süreci bul
+lsof -i :5005
+
+# Süreci sonlandır
+kill -9 <PID>
+
+# Farklı port kullan
+PORT=3000 npm start
+```
+
+#### 2. Veritabanı Hataları
+```bash
+# Veritabanı dosyası izinleri
+sudo chown www-data:www-data data/app.db
+sudo chmod 664 data/app.db
+
+# Veritabanı durumu
+sqlite3 data/app.db ".tables"
+sqlite3 data/app.db "SELECT COUNT(*) FROM fuel_slips;"
+```
+
+#### 3. Memory Issues
+```bash
+# Memory kullanımı
+free -h
+ps aux --sort=-%mem | head
+
+# Node.js memory limit
+node --max-old-space-size=4096 server/index.js
+```
+
+#### 4. Socket.IO Connection Issues
+```bash
+# WebSocket connection test
+wscat -c ws://localhost:5005/socket.io/?EIO=4&transport=websocket
+
+# Nginx log kontrolü
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Debugging Tools
+
+#### Node.js Debugging
+```bash
+# Debug mode
+node --inspect server/index.js
+
+# Chrome DevTools ile debugging
+# chrome://inspect adresini açın
+```
+
+#### Network Debugging
+```bash
+# Port test
+telnet localhost 5005
+
+# SSL cert test
+openssl s_client -connect your-domain.com:443
+```
+
+### Performance Optimization
+
+#### Database Optimization
+```sql
+-- Index ekleme
+CREATE INDEX idx_fuel_slips_date ON fuel_slips(slip_date);
+CREATE INDEX idx_fuel_slips_status ON fuel_slips(status);
+
+-- Query optimization
+EXPLAIN QUERY PLAN SELECT * FROM fuel_slips WHERE status = 'pending';
+```
+
+#### Frontend Optimization
+```javascript
+// vite.config.js
+export default {
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['svelte'],
+          api: ['./src/api.js']
+        }
+      }
+    }
+  }
+};
+```
+
+---
+
+**Not**: Prodüksiyon dağıtımından önce mutlaka test ortamında tüm senaryoları doğrulayın.