# Soyağacı PWA Kurulumu ve Dağıtım Rehberi

## PWA Özellikleri

Soyağacı uygulaması Progressive Web App (PWA) olarak yapılandırılmıştır ve aşağıdaki özellikleri sunar:

- **Native Uygulama Deneyimi**: Ana ekrana ekle, tam ekran çalışma
- **Çevrimdışı Destek**: Hizmet çalışanı (Service Worker) ile temel işlevler çevrimdışı çalışır
- **Hızlı Yükleme**: Akıllı önbelleğe alma (caching) stratejisi
- **Kurulum**: Tüm cihazlarda bir-dokunuşla kurulabilir
- **Güvenlik**: HTTPS üzerinden sunulur

## Dosya Yapısı

```
soyagaci/
├── public/
│   ├── manifest.json           # PWA metaveri dosyası
│   └── service-worker.js       # Service Worker (çevrimdışı destek)
├── src/
│   └── index.html              # PWA meta etiketleri
├── dist/soyagaci/browser/      # Dağıtıma hazır çıktı
│   ├── manifest.json           (build tarafından kopyalanır)
│   ├── service-worker.js       (build tarafından kopyalanır)
│   └── index.html
└── PWA_SETUP.md                # Bu dosya
```

## Build ve Dağıtım

### Geliştirme Ortamında Test

```bash
# Build oluştur
npm run build

# Dağıtım dosyalarını kontrol et
ls -la dist/soyagaci/browser/
```

Dosyalar şunları içermeli:
- `manifest.json` - PWA yapılandırması
- `service-worker.js` - Service Worker dosyası
- `index.html` - Güncellenmiş meta etiketleri ile

### Lokal Test (HTTP Sunucu)

```bash
# Node.js http-server kullanarak
npx http-server dist/soyagaci/browser -p 8080 -c-1

# Veya Python
python -m http.server 8080 --directory dist/soyagaci/browser
```

Sonra tarayıcıda `http://localhost:8080` adresini açın.

## Hosting Seçenekleri

### 1. Firebase Hosting (Önerilen)

```bash
# Firebase CLI'yi yükle
npm install -g firebase-tools

# Giriş yap
firebase login

# Projeyi başlat
firebase init hosting

# Cevapla:
# - Public directory: dist/soyagaci/browser
# - Single-page app (rewrite all URLs): Yes
# - Automatic builds with GitHub: Optional

# Dağıt
firebase deploy
```

Firebase otomatik olarak:
- HTTPS sağlar
- Service Worker'ı düzgün cache headers'ı ile sunar
- CORS'u yönetir

### 2. Vercel

```bash
# Vercel CLI'yi yükle
npm install -g vercel

# Dağıt (ilk seferinde interactive)
vercel

# Sonraki dağıtımlar
vercel deploy --prod
```

### 3. Netlify

```bash
# Netlify CLI'yi yükle
npm install -g netlify-cli

# Dağıt
netlify deploy --prod --dir=dist/soyagaci/browser
```

### 4. GitHub Pages

`gh-pages` branşında dağıt:

```bash
npm install --save-dev gh-pages

# package.json'a ekle:
# "deploy": "ng build --base-href=/soyagaci/ && gh-pages -d dist/soyagaci/browser"

npm run deploy
```

### 5. Özel Sunucu (Nginx)

```nginx
server {
    listen 443 ssl http2;
    server_name soyagaci.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Gzip sıkıştırma
    gzip on;
    gzip_types text/plain text/css text/javascript application/javascript application/json;

    root /var/www/soyagaci;

    # Service Worker düzgün cache headers'ı ile sun
    location = /service-worker.js {
        add_header Cache-Control "max-age=0, no-cache, no-store, must-revalidate";
        add_header Pragma "no-cache";
        add_header Expires "0";
    }

    # manifest.json düzgün MIME type ile sun
    location = /manifest.json {
        add_header Content-Type "application/manifest+json";
        add_header Cache-Control "public, max-age=3600";
    }

    # Service Worker kaynaklarını cache et
    location ~* \.(js|css|png|jpg|jpeg|svg|woff|woff2|ttf|eot)$ {
        add_header Cache-Control "public, max-age=31536000";
    }

    # index.html'yi cache etme, rewrite yap
    location / {
        try_files $uri $uri/ /index.html;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
}
```

### 6. Apache

`.htaccess` dosyası:

```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # Service Worker'ın cache etmesini engelle
    <FilesMatch "^(service-worker\.js|manifest\.json|index\.html)$">
        Header set Cache-Control "no-cache, no-store, must-revalidate"
        Header set Pragma "no-cache"
        Header set Expires "0"
    </FilesMatch>

    # Statik dosyaları cache et
    <FilesMatch "\.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$">
        Header set Cache-Control "public, max-age=31536000"
    </FilesMatch>

    # SPA rewrite
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
    RewriteRule ^ index.html [QSA,L]
</IfModule>

# MIME type tanımlaması
AddType application/manifest+json .json
```

## PWA Özellik Kontrolü

### Chrome DevTools'ta Test

1. F12 açın → Application tab
2. Manifest alt sekmesi:
   - ✅ manifest.json yüklü
   - ✅ Icons görünür
   - ✅ Theme color uygulanmış

3. Service Workers alt sekmesi:
   - ✅ Service Worker kaydedilmiş
   - ✅ "Offline" modu test edin

### PWA İnstallation Testi

1. Chrome'da açın
2. Adres çubuğunda PWA ikonu görün
3. "Yükle" butonuna tıkla
4. Ana ekrana eklendiğini kontrol et
5. Uygulamayı açıp çevrimdışı çalışmasını test et

### Lighthouse Audit

```bash
# Chrome DevTools > Lighthouse > Progressive Web App
# Hedef: 90+ puan
```

## Cache Stratejileri

### Statik Dosyalar (HTML, JS, CSS)
- **Strateji**: Cache First (Ağ Fallback)
- **TTL**: 1 yıl (hash'lenmiş dosyalar)
- **manifest.json, service-worker.js**: no-cache

### API İstekleri
- **Strateji**: Network First (Cache Fallback)
- **Offline Fallback**: Bağlantı arızası mesajı

### Medya Dosyaları
- **Strateji**: Cache First
- **TTL**: 30 gün

## Güncellemeler

### Yeni Sürüm Dağıtımı

1. Kod değişiklikleri yap
2. Sürümü artır: `package.json` → `version`
3. Build oluştur: `npm run build`
4. Hosting'e dağıt
5. Service Worker otomatik olarak güncellenecek

### Manuel Güncelleme İstemi

Service Worker `controllerchange` olayını dinler ve sayfayı yeniler.
Kullanıcı tarafından başlatan güncellemeler için:

```typescript
// Component'te
if ('serviceWorker' in navigator) {
  const registration = await navigator.serviceWorker.ready;
  registration.update();
}
```

## Sorun Giderme

### Service Worker Kaydedilmiyor

```javascript
// Chrome DevTools Console'ta
navigator.serviceWorker.getRegistrations()
  .then(registrations => console.log(registrations));
```

Sorunlar:
- ❌ HTTPS değil (localhost hariç)
- ❌ Service Worker dosyası yüklenemiyor (404)
- ❌ Kodda hata var (Console'ta kontrol et)

### Cache Temizleme

```javascript
// Console'ta
caches.keys().then(cacheNames => {
  return Promise.all(
    cacheNames.map(cacheName => caches.delete(cacheName))
  );
});

// Storage'ı sil
localStorage.clear();
sessionStorage.clear();
```

### Manifest Hatası

manifest.json dosyasını kontrol et:
- ✅ JSON geçerli (jsonlint.com)
- ✅ Icons URL'leri erişilebilir
- ✅ Colors heksadesimal format (#2d5016)

## İstatistikler ve Monitoring

### Google Play Console
- PWA olarak Android'de Yükle
- Google Play Store'da dağıt

### Web App Analytics
```typescript
// GA4 entegrasyonu (opsiyonel)
gtag('event', 'app_install');
gtag('event', 'app_open');
```

### Performance Monitoring
```typescript
// Core Web Vitals
web-vitals kütüphanesini ekle:
npm install web-vitals
```

## Kaynaklar

- [MDN: Progressive Web Apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
- [Google: Web Fundamentals - PWA](https://developers.google.com/web/progressive-web-apps)
- [web.dev: PWA Checklist](https://web.dev/pwa-checklist)
- [Web App Manifest Spec](https://www.w3.org/TR/appmanifest)

## Sık Sorulan Sorular

**S: PWA nasıl kurulur?**
A: Chrome/Edge'de, sağ-üst köşedeki PWA ikonuna tıkla. iOS Safari'de "Paylaş" → "Ana Ekrana Ekle".

**S: Çevrimdışı ne kadar uzun çalışır?**
A: Bir kez yüklendikten sonra, kullanıcı tarafından silinene kadar. API istekleri için veriler cache'den gelir (30 gün).

**S: Güvenli mi?**
A: HTTPS tarafından güvenlidir. Service Worker sadece HTTPS veya localhost'ta çalışır.

**S: Tam uygulama mı?**
A: Kısmi: offline erişim, push bildirimleri, home screen ekleme. Cihaz özelliklerine tam erişim yok (Contact, Camera vs web APIs ile kısıtlı).