6.7 KiB
6.7 KiB
📋 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ı
# ~/.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İ
- Gereksinimler belgesi tamamlandı
- OAuth flow planlandı
- Mimari tasarım tamamlanacak (/sc:design)
- Implementasyon tamamlanacak (/sc:implement)
- Testler yazılacak
- Dokümantasyon yazılacak
8. SONRAKİ ADIMLAR
- ✅ Gereksinim Belgesi (TAMAMLANDI)
- ⏭️ Mimari Tasarım →
/sc:design - ⏭️ Implementasyon →
/sc:implement - ⏭️ Test & Dokümantasyon
v1.0 - 2025-02-04