first (part 2: other directories)

mds/archive/03_developer_guidelines.md

@@ -0,0 +1,72 @@
+# Geliştirici Kılavuzu ve Sonraki Adımlar
+
+**Dosya:** `03_developer_guidelines.md`
+**Amaç:** Projeyi devralan kişi/AI için operasyonel rehber.
+
+---
+
+## 🚀 Projeyi Çalıştırma
+
+### Standard Geliştirme Modu
+
+```bash
+# 1. Veri Tabanını Başlat (Docker/Local)
+# 2. Migration Kontrolü
+npx prisma migrate dev
+
+# 3. Backend'i Başlat
+npm run start:dev  # (Dikkat: 'dev' scripti tanımlı olmayabilir, 'start:dev' kullanın)
+```
+
+### AI Engine Backtest & Calibration
+
+Skor tahminlerini tekrar kalibre etmek isterseniz:
+
+```bash
+# 1 aylık veri üzerinde kalibrasyon testi yapar ve optimum katsayıları basar
+python3 ai-engine/scripts/backtest_v17_scores.py
+```
+
+_Çıkan sonuçları `services/smart_coupon_service.py` içindeki CONSTANT'lara uygulayın._
+
+### Tek Maç Analizi (Manuel Test)
+
+```bash
+# Debug modunda detaylı JSON çıktısı
+python3 ai-engine/services/smart_coupon_service.py --analyze <MATCH_ID> --json
+```
+
+---
+
+## 📋 Kritik Kontrol Listesi (Devralan İçin)
+
+### 1. JSON Fallback Yapısı
+
+Canlı maçlarda veri `live_matches` tablosundaki `jsonData` (odds/lineups) kolonlarında saklanır.
+
+- **Kural:** Schema değişikliği yaparsanız `FeederPersistenceService.saveLineups` içindeki JSON yapısını bozmamaya dikkat edin. Python tarafı bu yapıya (`home.xi`, `away.xi`) bağımlıdır.
+
+### 2. Auto-Fetch Mantığı
+
+`SmartCouponService.analyzeMatch` metodu, veri eksikse otomatik olarak Feeder'ı tetikler (`refreshMatch`).
+
+- **Uyarı:** Eğer Feeder çok sık hata veriyorsa (Mackolik IP ban vb.), bu mekanizma yavaşlığa sebep olabilir. Rate Limiting eklenebilir.
+
+### 3. Model Eğitimi (V18 Planı)
+
+Mevcut V17 modeli `ai-engine/models/v17_full_europe.pth` dosyasını kullanır.
+
+- Yeni bir model eğitilirse, `player_model_v17.py` dosyasındaki mimariyle (Embedding boyutu, Layer sayısı) uyumlu olduğundan emin olun.
+- Model input boyutu (24 context feature + embeddings) değişirse Python scriptleri patlar.
+
+---
+
+## 🔮 Sırada Ne Var? (Next Steps)
+
+1.  **Value Strategy Implementation:** `SmartCouponService` içinde şu an "Banko" stratejisi aktif. "Value" (Değer) bahsi için oran/olasılık marjını kullanan logic eklenebilir.
+2.  **HT/FT Odds Fetching:** Şu an HT/FT tahminleri yapılıyor ancak bu pazarların (1/1, X/1 vb.) gerçek oranları Mackolik'ten çekilmiyor (0 olarak dönüyor). Scraper güncellenip bu oranlar da çekilebilir.
+3.  **Real-Time Dashboard:** `live_matches` tablosunu dinleyen bir WebSocket arayüzü ile analizlerin anlık önüze düşmesi sağlanabilir.
+
+---
+
+**Not:** Bu dizindeki (`mds/`) dosyalar, projenin en güncel ve derin teknik bilgisini içerir. Kodlarda kaybolmadan önce burayı okuyun.