iddaai-be/mds/SOCIAL_POSTER_MODULE.md

Social Poster Modülü — Otomatik Sosyal Medya Paylaşım Sistemi

Son güncelleme: 1 Mart 2026

---

1. Amaç

Top liglerdeki maçların AI tahminlerini otomatik olarak görselleştirip Instagram, Facebook ve X (Twitter) üzerinden paylaşmak. Her maç için 30 dakika önceden tahmin alınıp, 1080×1920 (9:16 Instagram Story) formatında poster üretilir.

---

2. Mimari Akış

Cron (*/10 dk) → LiveMatch sorgusu (top_leagues.json filtresi)
  → AI Engine V20+ POST /v20plus/analyze/{match_id}
    → PredictionCardDto oluştur
      → Node Canvas ile 1080x1920 PNG render
        → Gemini ile Türkçe caption üret
          → Twitter / Facebook / Instagram API'ye paylaş

---

3. Dosya Yapısı

src/modules/social-poster/
├── social-poster.module.ts       # NestJS modül tanımı
├── social-poster.controller.ts   # Test endpointleri (preview, post)
├── social-poster.service.ts      # Ana orkestrasyon servisi
├── image-renderer.service.ts     # Node Canvas ile görsel üretimi
├── caption-generator.service.ts  # Gemini ile post metni üretimi
├── twitter.service.ts            # Twitter/X API entegrasyonu
├── meta.service.ts               # Facebook + Instagram Graph API
└── dto/
    └── prediction-card.dto.ts    # PredictionCardDto, TopPick, SocialPostResult

---

4. Temel Servisler

4.1 SocialPosterService

Cron: Her 10 dakikada bir çalışır. 25–40 dakika içinde başlayacak maçları top_leagues.json filtresiyle bulur.

Pipeline: predictAndPost(match) → Tahmin al → Görsel üret → Caption üret → Paylaş

AI Engine İsteği:

// POST — GET değil! AI Engine v20plus POST bekler.
axios.post(`${aiEngineUrl}/v20plus/analyze/${matchId}`, null, { timeout: 30000 })

Veri Haritalandırma (V20+ → CardDto):

V20+ Response Alanı	CardDto Alanı
score_prediction.ht	htScore (ör: "1-1")
score_prediction.ft	ftScore (ör: "2-1")
main_pick.confidence	scoreConfidence (ör: 65)
bet_summary[] (array)	topPicks[] (ilk 3, confidence'a göre sıralı)
risk.level	riskLevel (LOW/MEDIUM/HIGH/EXTREME)
match_info.home_team	homeTeam (fallback)

Bet Summary Market Kodları:

Kod	Türkçe	English
MS	Maç Sonucu	Match Result
OU15	Üst 1.5 Gol	Over 1.5
OU25	Üst 2.5 Gol	Over 2.5
OU35	Üst 3.5 Gol	Over 3.5
BTTS	Karşılıklı Gol	Both Teams Score
DC	Çifte Şans	Double Chance
HT	İlk Yarı Sonucu	Half Time Result
HT_OU05	İY 0.5 Üst/Alt	HT Over/Under 0.5
OE	Tek/Çift	Odd/Even
HTFT	İY/MS	HT/FT

4.2 ImageRendererService

Motor: node-canvas (Puppeteer/HTML yok — sunucu performansı için)

Çıktı: public/predictions/prediction_{matchId}_{timestamp}.png

Boyut: 1080×1920 px (Instagram Story / Reels uyumlu)

Özellikler:

• Koyu gradient arka plan (#0a0e27 → #1a1040 → #0d1b2a)
• Lig adı + tarih başlık satırı
• Takım logoları (200×200px) — public/uploads/teams/ altından okunur
• İlk Yarı / Maç Sonu skor kutuları
• Güven yüzdesi badge'i
• En iyi 3 tahmin (progress bar + yüzde)
• Risk seviyesi badge'i (renk kodlu)
• iddaai.com filigran (saydam, tekrarlı, döndürülmüş)
• Alt bilgi: "⚡ AI Powered by SuggestBet"

Logo Çözümleme:

1. Yerel dosya varsa → public/uploads/teams/xxx.png oku
2. URL http ile başlıyorsa → HTTP ile indir
3. Bulunamazsa → logo olmadan devam et (graceful fallback)

4.3 CaptionGeneratorService

Gemini API kullanarak maç verisi JSON'ından Türkçe post metni üretir.

4.4 TwitterService & MetaService

Üretilen görsel + caption'ı ilgili platformlara yükler.

---

5. API Endpointleri

Method	Path	Auth	Açıklama
GET	/api/social-poster/preview/:matchId	@Public	Sadece görsel üret + caption üret (paylaşma)
POST	/api/social-poster/post/:matchId	@Public	Görsel üret + caption üret + tüm platformlara paylaş

Not: Test endpointleri @Public() dekoratörüyle auth bypass edilmiştir. Production'da kaldırılmalı veya admin-only yapılmalıdır.

---

6. Environment Değişkenleri

Key	Zorunlu	Varsayılan	Açıklama
AI_ENGINE_URL	✅	http://localhost:8000	AI Engine base URL
APP_BASE_URL	✅	http://localhost:3000	Logo URL çözümleme için
SOCIAL_POSTER_ENABLED	❌	false	Cron job'ı aktif/pasif
GOOGLE_API_KEY	❌	—	Gemini caption için
Twitter API keys	❌	—	Twitter paylaşım için
Meta API keys	❌	—	FB/IG paylaşım için

---

7. Bağımlılıklar

{
  "canvas": "^2.x",       // Node Canvas — görsel üretimi
  "axios": "^1.x",        // HTTP istekleri (AI Engine + logo indirme)
  "@nestjs/schedule": "*"  // Cron job desteği
}

Kaldırılan: puppeteer — performans ve Raspberry Pi uyumluluğu için canvas ile değiştirildi.

---

8. Deploy Notları

Raspberry Pi (ARM64)

# canvas native bağımlılıkları (Dockerfile'da)
RUN apk add --no-cache cairo-dev pango-dev jpeg-dev giflib-dev librsvg-dev

Port Yönetimi

Servis	Port
NestJS Backend	3000 (production: 150X)
AI Engine	8000 (dev: 8005 — Windows port kısıtlaması)

Dosya Sistemi

public/
├── uploads/teams/         # Takım logoları (PNG)
└── predictions/           # Üretilen poster görselleri (PNG)

---

9. Bilinen Sorunlar & Çözümler

Sorun	Sebep	Çözüm
WinError 10013 port erişim hatası	Windows Hyper-V port rezervasyonu	Farklı port kullan (8005)
Invalid prisma.liveMatch.findUnique()	Prisma client eskimiş	npx prisma generate çalıştır
405 Method Not Allowed AI Engine	GET yerine POST gerekiyor	axios.post() kullan
Logolar görünmüyor (lokal dev)	Logo dosyaları sunucuda, lokalde yok	Deploy'da çalışır, lokal'de graceful skip