# 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:**
```json
{
  "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` |