iddaai-be/mds/changelog-2026-03-25.md

Spor Toto Modülü — Changelog

Tarih: 25 Mart 2026
Konu: Süper Toto (parimutuel bahis) modülünün sıfırdan oluşturulması

---

1. Genel Bakış

Süper Toto, İddaa'dan farklı olarak parimutuel (havuz) sistemi ile çalışır. 15 maçın sonucunu (1/X/2) doğru tahmin etmeye dayalıdır. Bu modül, Spor Toto bültenlerini resmi API'den çekme, sistem kuponu üretme, sonuç değerlendirme ve havuz analitiği sağlar.

---

2. Veritabanı Değişiklikleri

Yeni Tablolar

Tablo	Açıklama
toto_bulletins	Haftalık bülten bilgileri (gameCycleNo, havuz, devir, tarihler)
toto_bulletin_matches	Bültendeki 15 maç (takım adları, lig, kickoff, sonuç)
toto_results	Bülten sonuçları (15/14/13/12 bilen sayıları ve ödüller)
toto_coupons	Kullanıcı kuponları (strateji, kolon sayısı, maliyet)
toto_columns	Kupon kolonları (15 karakter tahmin string'i, doğru sayısı)

Yeni Enumlar

• TotoBulletinStatus: UPCOMING, IN_PROGRESS, COMPLETED, CANCELLED
• TotoMatchResult: HOME, DRAW, AWAY

Önemli Alanlar

• toto_bulletin_matches.match_id → Mevcut matches tablosuyla bağlantı (fuzzy match ile doldurulacak)
• toto_columns.predictions → "1X2102X112X2101" formatında 15 karakterlik string

---

3. Modül Yapısı

src/modules/spor-toto/
├── dto/spor-toto.dto.ts              # CreateBulletinDto, UpdateResultsDto, GenerateColumnsDto
├── services/
│   ├── toto-fetcher.service.ts       # sportotov2.iddaa.com API entegrasyonu
│   ├── toto-combinatorics.service.ts # Sistem kuponu üretme (full/reduced)
│   └── toto-analytics.service.ts     # Havuz dağılımı, EV hesabı, devir analizi
├── spor-toto.controller.ts           # 8 REST endpoint
├── spor-toto.service.ts              # Ana iş mantığı (CRUD + orchestration)
└── spor-toto.module.ts               # NestJS modül tanımı

---

4. API Endpoints

Method	Endpoint	Açıklama
POST	/spor-toto/sync	Resmi API'den güncel bülteni çek ve kaydet
GET	/spor-toto/bulletins	Bülten listesi (status filtresi, limit)
GET	/spor-toto/bulletins/:id	Bülten detayı (maçlar + sonuçlar dahil)
POST	/spor-toto/bulletins	Manuel bülten oluşturma
PATCH	/spor-toto/bulletins/:id/results	Maç sonuçlarını güncelle
GET	/spor-toto/bulletins/:id/stats	Havuz dağılımı ve EV istatistikleri
GET	/spor-toto/history	Devir tarihçesi ve trendler
POST	/spor-toto/columns/generate	Sistem kuponu üret (full/reduced)
POST	/spor-toto/columns/evaluate	Kolonları sonuçlara karşı değerlendir

---

5. Servis Detayları

TotoFetcherService

• Kaynak: https://sportotov2.iddaa.com/SporToto
• fetchCurrentBulletin() → Güncel bülten + 15 maç verisi
• Event adlarını parse edip homeTeamName / awayTeamName çıkartır
• Desteklenen lig formatları: "eventName": "Blackpool-Burton Albion"

TotoCombinatoricsService

• Full System: Cartesian product — tüm kombinasyonları üretir
  • Örnek: 5 maçta çift seçim → 2⁵ = 32 kolon
• Reduced System: Belirli bir garanti seviyesiyle kolon sayısını düşürür
• generateFullSystem(selections) → string[] (her biri 15 karakter)
• evaluateColumns(columns, results) → { column, correctCount }[]

TotoAnalyticsService

• Havuz dağılımı: %35 (15 bilen), %20 (14 bilen), %20 (13 bilen), %25 (12 bilen)
• Expected Value (EV): poolShare × probability - cost
• Devir analizi: Son N bültenin devir trendi

---

6. Mevcut Durum & Bilinen Sorunlar

✅ Tamamlanan

• Veritabanı şeması (raw SQL ile oluşturuldu)
• Prisma Client türleri üretildi (totoBulletin, totoResult vs. FOUND)
• Tüm servisler implement edildi
• Build başarılı (nest build → 0 error)
• app.module.ts'e SporTotoModule kayıtlandı
• AI Prediction Engine implement edildi ✅

⚠️ Bekleyen

• Dev server testi: DB bağlantısı test edilmeli (npm run start:dev)
• API sync testi: /spor-toto/sync endpoint'inin çalıştığı doğrulanmalı
• Canlı prediction testi: Sync sonrası POST /spor-toto/predict çalıştırılmalı

---

7. AI Prediction Engine (Tamamlandı ✅)

Yeni Servis: toto-prediction.service.ts (~490 satır)

Bülten maçlarını AI Engine ile analiz edip, contrarian parimutuel strateji ile akıllı sistem kuponu üreten tahmin motoru.

Çalışma Akışı

POST /spor-toto/predict { bulletinId, strategy }
  ↓
1. Bülteni DB'den getir (15 maç)
  ↓
2. Her maç için:
   a) Fuzzy Match Link → live_matches / matches tablosundan matchId bul
      - Normalize: lowercase, Türkçe karakter çevir, ILIKE arama
      - ±3 gün tarih filtresi
   b) AI Engine → /v20plus/analyze/{matchId} çağır
      - Maç Sonucu market'ını bul, pick + confidence al
      - xG bazlı olasılık hesabı
   c) Fallback: AI erişilemezse → Tarihsel form analizi (son 10 maç)
  ↓
3. Contrarian Strateji uygula (maç başı seçim sayısı belirle)
  ↓
4. Combinatorics ile sistem kuponu üret
  ↓
5. EV raporu hesapla → PLAY / WAIT / HIGH_VALUE önerisi

Contrarian Strateji (Fading the Public)

Parimutüel'de herkesin bildiği tahmin = düşük ödül. Motor, favori yığılmasının tersine pozisyon alır:

AI Confidence	Seçim	Parimutüel Mantık
≥ 65%	Tek (1/X/2)	Güvenli, ama contrarian bias ile çift olma ihtimali
50-65%	İkili (en olası 2)	Varyans koruması — sürprizleri yakalar
< 50%	Üçlü (1X2 kapatma)	Maç çok belirsiz, herkes yanılabilir

4 Strateji Modu

Strateji	Max Kolon	Tek Eşiği	Çift Eşiği	Contrarian Bias	Açıklama
CONSERVATIVE	100	55%	35%	%0	Düşük bütçe, güvenli
BALANCED	500	60%	40%	%15	Orta risk, önerilen
AGGRESSIVE	2.500	70%	50%	%30	Yüksek varyans, 15 bilme şansı
FORMULA_6PCT	2.500	60%	40%	%20	Tam sistemden %6 örnekleme

EV-Bazlı Oynama Önerisi

Devir miktarına göre otomatik tavsiye:

• Devir > 50M TL → 🔥 HIGH_VALUE — Agresif oyna
• Devir > 5M TL → ✅ PLAY — Oynamaya değer
• Devir < 5M TL → ⏳ WAIT — Havuz büyümesini bekle

Yeni Endpoint

Method	Endpoint	Açıklama
POST	/spor-toto/predict	AI tahmin + contrarian strateji + sistem kuponu üret

Request:

{
  "bulletinId": "<uuid>",
  "strategy": "BALANCED",
  "maxBudget": 500
}

Response: Match analizi (maç başı AI pick, confidence, contrarian skor), kupon (kolonlar, maliyet), EV raporu (havuz, devir, öneri)

---

8. Dosya Değişiklikleri Özeti

Dosya	Değişiklik
prisma/schema.prisma	+112 satır (5 model, 2 enum)
src/modules/spor-toto/services/toto-prediction.service.ts	YENİ — AI tahmin motoru (~490 satır)
src/modules/spor-toto/services/toto-fetcher.service.ts	Bülten çekici
src/modules/spor-toto/services/toto-combinatorics.service.ts	Kolon üretim motoru
src/modules/spor-toto/services/toto-analytics.service.ts	Havuz & EV analizi
src/modules/spor-toto/dto/spor-toto.dto.ts	+GeneratePredictionDto, +EvaluateColumnsDto
src/modules/spor-toto/spor-toto.controller.ts	+POST /predict endpoint
src/modules/spor-toto/spor-toto.service.ts	+TotoPredictionService entegrasyonu
src/modules/spor-toto/spor-toto.module.ts	+HttpModule, ConfigModule, TotoPredictionService
src/app.module.ts	SporTotoModule import

---

9. Swagger & Endpoint Summary Güncellemesi

Controller Swagger Dekoratörleri

Tüm 10 endpoint'e kapsamlı Swagger dekoratörleri eklendi:

• @ApiOperation({ summary, description }) — Her endpoint için detaylı açıklama
• @ApiParam({ name, description }) — Path parametreleri (:id → Bulletin UUID)
• @ApiBody({ type: DtoClass }) — POST/PATCH body DTO referansları
• @ApiResponse({ status, description }) — Başarı ve hata durumları (200, 201, 404, 409)

backend_endpoints_swagger_summary.json

Değişiklik	Detay
Endpoint sayısı	50 → 60
Yeni tag	Spor Toto (10 endpoint)
Eklenen endpointler	sync, bulletins (CRUD), stats, history, columns/generate, columns/evaluate, predict
Yeni DTO şemaları	CreateBulletinDto, UpdateResultsDto, GenerateColumnsDto, EvaluateColumnsDto, GeneratePredictionDto
Tarih	2026-02-17 → 2026-03-25