# 📋 GAME POSTER - GEREKSİNİMLER BELGESİ v1.0

## Proje Özeti
Linux için bash tabanlı terminal uygulaması. Oyun .iso dosyalarını tespit edip IGDB API'den poster resimlerini indirir.

---

## 1. FONKSİYONEL GEREKSİNİMLER

### FR-1: Dizin Tarama
```
FR-1.1: Script'in çalıştığı dizindeki alt klasörleri recursive olarak taramalıdır
FR-1.2: Her klasörde .iso dosyası aramalıdır
FR-1.3: .iso bulunan klasörleri işleme almalıdır
FR-1.4: .iso bulunamayan klasörler için ".iso dosyası bulunamadı" mesajı vermeli ve atlamalıdır
```

### FR-2: Oyun Adı Çıkarımı
```
FR-2.1: .iso dosya adından oyun adını çıkarmalıdır
FR-2.2: ".iso" uzantısını kaldırmalıdır
FR-2.3: Örnek: "Cyberpunk 2077.iso" → "Cyberpunk 2077"
```

### FR-3: IGDB API Entegrasyonu
```
FR-3.1: IGDB API ile oyun aramalıdır
FR-3.2: Client ID: 6174nc97wqqt2ny13fildjy5co52rg
FR-3.3: OAuth redirect URI: http://localhost
FR-3.4: Access token almak için OAuth flow implement edilmelidir (client credentials flow)
FR-3.5: Oyun bulamazsa "[oyun_adı] VR" formatında yeniden aramalıdır
FR-3.6: Birden fazla sonuç dönerse ilk sonucu kullanmalıdır
FR-3.7: Access token'ı ~/.game-poster.conf'da cache'lemelidir
```

### FR-4: Poster İndirme
```
FR-4.1: IGDB'den poster URL'sini almalıdır
FR-4.2: Poster'i PNG formatında indirmelidir
FR-4.3: Dosya adı: poster.png
FR-4.4: .iso ile aynı dizine kaydetmelidir
FR-4.5: Aynı dizinde poster.png zaten varsa atlamalıdır
FR-4.6: İndirme başarısız olursa 3 kere yeniden denemelidir
FR-4.7: 3 deneme sonunda da başarısız olursa log'a yazmalıdır (dosya koyma)
FR-4.8: Poster bulunamazsa hiçbir dosya koyma, sadece log tut
```

### FR-5: Progress Gösterimi
```
FR-5.1: Basamalı ilerleme göstermelidir: "[1/15] Cyberpunk 2077..."
FR-5.2: Progress bar göstermelidir: "[████░░░░] 25%
FR-5.3: Default mode: "both" (hem steps hem bar)
```

---

## 2. NON-FONKSİYONEL GEREKSİNİMLER

### NFR-1: Teknoloji Yığını
```
NFR-1.1: Bash script (sh/POSIX uyumlu)
NFR-1.2: Minimum bağımlılık (curl, jq, figlet/toilet)
NFR-1.3: Python/Yarn vs. gerektirmemelidir
```

### NFR-2: Terminal Arayüzü
```
NFR-2.1: Renkli çıktı (ANSI renk kodları)
NFR-2.2: Başlangıçta "GAME POSTER" 3D ASCII logo (figlet/toilet)
NFR-2.3: Retro/pixel tarzı görsel efektler
NFR-2.4: Türkçe dil desteği
```

### NFR-3: Yapılandırma
```
NFR-3.1: Config dosyası: ~/.game-bash.conf
NFR-3.2: Log dosyası: ~/.game-bash.log
NFR-3.3: Access token'ı config'de cache'lemelidir
```

### NFR-4: Hata Yönetimi
```
NFR-4.1: İnternet bağlantısı yoksa hata verip çıkmalıdır
NFR-4.2: IGDB API hatasında kullanıcıyı bilgilendirmelidir
NFR-4.3: Her işlem için log tutmalıdır
```

---

## 3. KULLANICI HİKAYELERİ

| ID | Hikaye | Kabul Kriteri |
|----|--------|---------------|
| US-1 | Kullanıcı, oyun posterlerini otomatik indirmek istiyor | Script çalıştığında tüm oyunlar için poster indirilmeli |
| US-2 | Kullanıcı, ilerleme durumunu görmek istiyor | Terminalde progress bar ve basamalı ilerleme gösterilmeli |
| US-3 | Kullanıcı, zaten indirilmiş posterleri tekrar indirmek istemiyor | poster.png varsa atlanmalı |
| US-4 | Kullanıcı, VR oyunları için de poster indirmek istiyor | Oyun bulunamazsa "VR" eklenip aranmalı |

---

## 4. TEKNİK SPESİFİKASYON

### 4.1 Proje Yapısı
```
poster-bash/
├── poster-bash               # Ana script (executable)
├── lib/
│   ├── igdb.sh               # IGDB API fonksiyonları
│   ├── scanner.sh            # .iso tarama fonksiyonları
│   ├── downloader.sh         # Poster indirme fonksiyonları
│   └── ui.sh                 # Terminal UI fonksiyonları
├── src/
│   └── auth-setup.sh         # IGDB OAuth setup helper
└── README.md                 # Kullanım dokümantasyonu
```

### 4.2 Config Dosyası Formatı
```bash
# ~/.game-bash.conf
IGDB_CLIENT_ID="buyzvv6qoyzj7rmauwkfom79h7fvpx"
IGDB_CLIENT_SECRET="tivj7d6b21vqybpb4fx1oe85nffibt"
IGDB_REDIRECT_URI="http://localhost"
IGDB_ACCESS_TOKEN=""          # Token cache (auto-filled)
IGDB_TOKEN_EXPIRES=""         # Token expiration (auto-filled)
PROGRESS_MODE="both"          # steps, bar, both
LOG_LEVEL="info"
RETRY_COUNT=3
```

### 4.3 IGDB API Endpoints
```
OAuth Token: https://id.twitch.tv/oauth2/token
  - POST with: client_id, client_secret, grant_type=client_credentials

Games Search: https://api.igdb.com/v4/games
  - POST body: search "game name"; fields name,cover;

Covers: https://api.igdb.com/v4/covers
  - POST body: fields url,image_id; where id = X;
  - Image URL: https://images.igdb.com/igdb/image/upload/t_cover_big/{image_id}.jpg
```

### 4.4 OAuth Flow (Client Credentials)
```
1. Kullanıcıdan IGDB Client Secret al
2. POST https://id.twitch.tv/oauth2/token
   - client_id: 6174nc97wqqt2ny13fildjy5co52rg
   - client_secret: [kullanıcıdan alınan]
   - grant_type: client_credentials
3. Response: access_token, expires_in, token_type
4. Token'ı config'e cache'le
5. Token expired ise yenile
```

---

## 5. KABUL TESTLERİ

```
AT-1: Script games dizininde çalıştırıldığında tüm klasörleri tarar
AT-2: .iso dosyası "Cyberpunk 2077.iso" için "Cyberpunk 2077" aranır
AT-3: IGDB'den poster bulunursa poster.png olarak kaydedilir
AT-4: poster.png zaten varsa yeniden indirilmez
AT-5: Oyun bulunamazsa "Oyun Adı VR" olarak yeniden aranır
AT-6: Terminalde renkli çıktı ve 3D logo gösterilir
AT-7: Log dosyasına tüm işlemler yazılır
AT-8: İnternet yoksa hata verilip çıkılır
AT-9: İndirme başarısız olursa 3 kere yeniden denenir
```

---

## 6. LOG FORMATI

```
[2025-02-04 15:30:45] INFO  Starting poster-bash v1.0
[2025-02-04 15:30:46] INFO  Scanning directory: /home/user/Games
[2025-02-04 15:30:47] INFO  Found ISO: Cyberpunk 2077.iso
[2025-02-04 15:30:48] INFO  Searching IGDB: "Cyberpunk 2077"
[2025-02-04 15:30:49] INFO  Found game: Cyberpunk 2077 (ID: 10904)
[2025-02-04 15:30:50] INFO  Downloading poster: https://images.igdb.com/...
[2025-02-04 15:30:52] SUCCESS Poster saved: /home/user/Games/Cyberpunk 2077/poster.png
[2025-02-04 15:30:53] WARN  Game not found: "Unknown Game"
[2025-02-04 15:30:54] INFO  Retrying with VR suffix: "Unknown Game VR"
[2025-02-04 15:30:55] ERROR Poster download failed: HTTP 404
```

---

## 7. BİTİŞ KRİTERLERİ

- [x] Gereksinimler belgesi tamamlandı
- [x] OAuth flow planlandı
- [ ] Mimari tasarım tamamlanacak (/sc:design)
- [ ] Implementasyon tamamlanacak (/sc:implement)
- [ ] Testler yazılacak
- [ ] Dokümantasyon yazılacak

---

## 8. SONRAKİ ADIMLAR

1. ✅ **Gereksinim Belgesi** (TAMAMLANDI)
2. ⏭️ **Mimari Tasarım** → `/sc:design`
3. ⏭️ **Implementasyon** → `/sc:implement`
4. ⏭️ **Test & Dokümantasyon**

---

_v1.0 - 2025-02-04_