HEGS Crossword - AI Destekli Çengel Bulmaca API

HEGS Crossword, yapay zeka destekli çengel bulmaca (crossword) oluşturma ve kontrol sistemidir. Güncel haberlerden veya AI'dan kelimeler alarak dinamik bulmacalar üretir ve kullanıcı cevaplarını doğrular.

🎯 Özellikler

Ana Özellikler

• AI Destekli Kelime Üretimi: OpenAI GPT-4 ile akıllı kelime seçimi
• Haber Entegrasyonu: Güncel haberlerden kelime çıkarma
• Dinamik Grid Oluşturma: 12x12 boyutunda özelleştirilebilir bulmaca grid'i
• Türkçe Desteği: Türkçe karakter normalizasyonu ve validasyon
• Cevap Kontrolü: Kullanıcı cevaplarını doğrulama sistemi
• SQLite Veritabanı: Bulmaca kayıtları ve skorlar

API Endpoints

• POST /generate - Yeni bulmaca oluşturma
• POST /check - Kullanıcı cevaplarını kontrol etme
• GET /puzzle/{puzzle_id} - Belirli bir bulmacayı getirme
• GET /health - Sistem sağlık kontrolü

🔧 Teknolojiler

• Framework: FastAPI 0.109.0
• AI Model: OpenAI GPT-4
• Database: SQLite (crossword.db)
• Web Server: Uvicorn
• Python: 3.8+

🚀 Kurulum

Bu servis HEGS mikroservis ekosisteminin bir parçasıdır ve HEGS-SETUP reposu üzerinden Docker Compose ile çalıştırılır.

Kurulum Adımları

Tüm HEGS sistemini kurmak ve çalıştırmak için:

1. HEGS-SETUP reposuna gidin: HEGS-SETUP Repository
2. HEGS-SETUP README'sindeki adımları takip edin
3. Tüm mikroservisler otomatik olarak başlatılacaktır

Not: Bu servisi tek başına çalıştırmak için Docker Compose yerine manuel kurulum yapabilirsiniz, ancak diğer servislere bağımlılıklar nedeniyle tam fonksiyonellik için HEGS-SETUP kullanılması önerilir.

📡 API Kullanımı

Bulmaca Oluşturma

curl -X POST "http://localhost:8001/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "use_ai": true,
    "theme": "spor",
    "use_news": true
  }'

Response:

{
  "id": "puzzle-abc123",
  "grid": [
    ["F", "U", "T", "B", "O", "L", "#", "#", "#", "#", "#", "#"],
    ["#", "#", "#", "#", "#", "#", "#", "#", "#", "#", "#", "#"],
    ...
  ],
  "words": [
    {
      "word": "FUTBOL",
      "clue": "22 kişi ile oynanan popüler takım sporu",
      "direction": "horizontal",
      "start_row": 0,
      "start_col": 0,
      "length": 6
    }
  ],
  "difficulty": "medium",
  "created_at": "2025-10-10T12:00:00Z"
}

Cevap Kontrolü

curl -X POST "http://localhost:8001/check" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "puzzle_id": "puzzle-abc123",
    "grid": [
      ["F", "U", "T", "B", "O", "L", "#", "#", "#", "#", "#", "#"],
      ...
    ]
  }'

Response:

{
  "success": true,
  "correct": true,
  "wrong_questions": [],
  "score": 100,
  "completion_time": 245,
  "message": "Tebrikler! Tüm cevaplar doğru!"
}

Bulmaca Getirme

curl -X GET "http://localhost:8001/puzzle/puzzle-abc123"

🏗️ Proje Yapısı

HEGS-CROSSWORD/
├── config/
│   ├── __init__.py
│   └── settings.py        # Konfigürasyon ayarları
├── models/
│   ├── __init__.py
│   └── schemas.py         # Pydantic modeller
├── routes/
│   ├── __init__.py
│   └── puzzle_routes.py   # API endpoint'leri
├── services/
│   ├── __init__.py
│   ├── ai_service.py      # OpenAI entegrasyonu
│   ├── news_service.py    # Haber API entegrasyonu
│   └── puzzle_service.py  # Bulmaca oluşturma mantığı
├── utils/
│   ├── __init__.py
│   ├── grid.py            # Grid oluşturma algoritmaları
│   ├── security.py        # Güvenlik ve validasyon
│   └── turkish.py         # Türkçe karakter işlemleri
├── database.py            # SQLite veritabanı yönetimi
├── main.py               # FastAPI uygulaması
├── index.html            # Test arayüzü
├── requirements.txt      # Python bağımlılıkları
└── README.md            # Bu dosya

🎮 Oyun Mekanikleri

Kelime Seçimi

1. AI Modundan (use_ai=true):

   • OpenAI'dan tema bazlı kelimeler
   • İpuçları otomatik oluşturulur
   • Zorluk seviyesine göre ayarlanır

2. Haber Modundan (use_news=true):

   • Backend API'den güncel haberler
   • Haber içeriğinden anahtar kelimeler
   • İlgili ve güncel içerik

Grid Oluşturma Algoritması

1. Kelimeleri uzunluklarına göre sırala
2. En uzun kelimeyle başla
3. Çaprazlama noktalarını bul
4. Yatay ve dikey dengeyi koru
5. Grid doluluk oranını optimize et

Zorluk Seviyeleri

• Easy: 5-6 kelime, kısa uzunluklar (3-5 harf)
• Medium: 7-8 kelime, orta uzunluklar (4-7 harf)
• Hard: 9-10 kelime, uzun uzunluklar (5-8 harf)

🔐 Güvenlik

• Input Validasyonu: Grid boyutu ve kelime uzunluğu kontrolleri
• Rate Limiting: API istekleri sınırlandırılabilir
• CORS: Sadece izin verilen origin'ler
• SQL Injection Koruması: Parametreli sorgular
• Türkçe Karakter Güvenliği: Özel karakter normalizasyonu

🔗 Entegrasyon

Backend (HEGS-HABER-backend)

• Port: 8080
• Haber API: http://localhost:8080/news/{kategori}

Frontend (HEGS-HABER-frontend)

• Port: 5173
• Crossword oyun bileşeni: src/games/crossword/CrosswordGame.tsx
• API çağrıları: generate ve check endpoint'leri

Diğer Mikroservisler

• HEGS-AI: Quiz ve AI özellikleri (Port: 8000)
• HEGS-SCRAPPER: Haber içerik çekme (Port: 9932)

📊 Performans

• Ortalama Bulmaca Oluşturma: 3-5 saniye
• Grid Hesaplama: < 1 saniye
• Cevap Kontrolü: < 100ms
• Eşzamanlı İstek Kapasitesi: 30+ concurrent users
• Hafıza Kullanımı: ~150MB (base)

🐛 Hata Ayıklama

Yaygın Hatalar

1. OpenAI API Hatası

   Çözüm: OPENAI_API_KEY kontrol edin
   Alternatif: use_ai=false ile haber modunu kullanın
   

2. Haber API Bağlantı Hatası

   Çözüm: Backend servisinin çalıştığından emin olun
   URL: http://localhost:8080/news/guncel
   

3. Grid Oluşturma Başarısız

   Çözüm: MIN_WORDS ve MAX_WORDS ayarlarını düşürün
   Veya: Kelime uzunluk limitlerini ayarlayın
   

Debug Modu

# main.py içinde
import logging
logging.basicConfig(level=logging.DEBUG)

📈 Veritabanı Şeması

CREATE TABLE puzzles (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    grid_data TEXT NOT NULL,
    words_data TEXT NOT NULL,
    difficulty TEXT,
    theme TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE puzzle_scores (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    puzzle_id TEXT NOT NULL,
    user_id TEXT NOT NULL,
    score INTEGER NOT NULL,
    completion_time INTEGER,
    completed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (puzzle_id) REFERENCES puzzles(id)
);

🧪 Test Arayüzü

index.html dosyasını tarayıcıda açarak test edebilirsiniz:

# Python HTTP server ile
python -m http.server 8002

# Tarayıcıda
http://localhost:8002/index.html

📈 Geliştirme Planları

• Çoklu zorluk seviyesi seçimi
• Tema kategorileri genişletme
• Multiplayer modu
• Leaderboard sistemi
• Günlük bulmaca challenge
• Bulmaca paylaşma özelliği

---

Not: Bu servis localhost üzerinde çalışacak şekilde yapılandırılmıştır. Docker ile çalıştırmak için root dizindeki docker-compose.yml dosyasını kullanın.