first (part 2: other directories)

mds/changelog-2026-03-25.md

@@ -0,0 +1,222 @@
+# 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` |
+