211 lines
6.7 KiB
Markdown
211 lines
6.7 KiB
Markdown
# 📋 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_
|