hDiyanetProxy/REQUIREMENTS.md

hDiyanetProxy Projesi - AI Agent Prompt'u

---

Proje Adı: hDiyanetProxy

Görev: Aşağıdaki gereksinimlere göre tam kapsamlı bir web uygulaması ve API servisi geliştir.

---

📌 GENEL TANIM

Türkiye Diyanet İşleri Başkanlığı'nın namaz vakitleri API'sinden (https://awqatsalah.diyanet.gov.tr) veri çeken, bu verileri yerel veritabanında saklayan ve dışarıya kendi güvenli API'si üzerinden sunan hDiyanetProxy adlı bir uygulama geliştir.

---

🏗️ TEKNOLOJİ YIĞINI

• Backend: Node.js + Express.js (veya Python + FastAPI — tercihe bırak)
• Veritabanı: PostgreSQL (ya da SQLite geliştirme ortamı için)
• Auth: JWT tabanlı token sistemi
• Frontend: Sade, modern bir web arayüzü (HTML/CSS/JS veya React)
• Ortam: Docker Compose ile ayağa kalkabilir yapı (opsiyonel ama önerilir)

---

🔌 KAYNAK API BİLGİLERİ

Base URL: https://awqatsalah.diyanet.gov.tr

Kullanılacak endpointler:

Namaz Vakitleri

POST /api/AwqatSalah/Yearly
Body:
{
  "cityId": {cityId},
  "startDate": "2026-01-01T00:00:00.0Z",
  "endDate": "2026-12-31T23:59:59.0Z"
}

Ramazan İmsakiyesi

GET /api/AwqatSalah/Ramadan/{cityId}

Bayram Vakti ve Bayram Namazı

GET /api/AwqatSalah/Eid/{cityId}

Yer Bilgileri

GET /api/Place/Countries
GET /api/Place/States
GET /api/Place/States/{countryId}
GET /api/Place/Cities
GET /api/Place/Cities/{stateId}
GET /api/Place/CityDetail/{cityId}

Cache Temizleme

GET /api/Cache/ClearCache

---

🗄️ VERİTABANI YAPISI

Aşağıdaki tabloları oluştur:

1. users — Kullanıcı adı, şifre (hash'li), rol, oluşturulma tarihi
2. countries — Ülke id, adı
3. states — İl/Eyalet id, adı, ülke foreign key
4. cities — Şehir id, adı, eyalet foreign key, koordinatlar
5. prayer_times — cityId, tarih, imsak, güneş, öğle, ikindi, akşam, yatsı, kıble vakti
6. ramadan_times — cityId, tarih, imsak, iftar, sahur saati gibi alanlar
7. eid_times — cityId, bayram adı, tarih, namaz saati
8. fetch_logs — Ne zaman, kim tarafından, hangi şehir için veri çekildiği logu

---

⚙️ BACKEND FONKSİYONELLİK

1. Veri Çekme Servisi

• Manuel tetikleme: Kullanıcı arayüzden şehir ve tarih aralığı seçip "Veri Çek" butonuna basar
• Zamanlanmış çekme: Cron job ile belirli aralıklarla otomatik çekme (örn. her gün gece 02:00)
• Çekilen veriler önce kontrol edilir; aynı şehir + tarih için kayıt varsa güncellenir, yoksa eklenir (upsert)
• Yer bilgileri (ülke, eyalet, şehir) ayrı tablolarda saklanır ve periyodik olarak güncellenir

2. Kimlik Doğrulama

• POST /auth/register — Yeni kullanıcı kaydı (admin onaylı veya açık, tercihe göre)
• POST /auth/login — Kullanıcı adı + şifre ile giriş, JWT token döner
• Token süresi: 24 saat (refresh token desteği eklenebilir)
• Tüm veri endpointleri Authorization: Bearer {token} header'ı zorunlu tutar

3. Cache Yönetimi

• Kaynak API'nin cache'ini temizlemek için /api/Cache/ClearCache çağrısını proxy eden bir endpoint yaz
• Yerel cache için Redis entegrasyonu eklenebilir (opsiyonel)

---

🌐 hDiyanetProxy API ENDPOINTLERİ

Token ile korunan aşağıdaki endpointleri oluştur:

# Auth
POST   /api/v1/auth/login
POST   /api/v1/auth/register

# Yer Bilgileri
GET    /api/v1/places/countries
GET    /api/v1/places/states?countryId={id}
GET    /api/v1/places/cities?stateId={id}
GET    /api/v1/places/city/{cityId}

# Namaz Vakitleri
GET    /api/v1/prayer-times?cityId={id}&startDate={date}&endDate={date}
GET    /api/v1/prayer-times/today?cityId={id}

# Ramazan / İftar
GET    /api/v1/ramadan?cityId={id}
GET    /api/v1/ramadan/today?cityId={id}

# Bayram
GET    /api/v1/eid?cityId={id}

# Veri Çekme (Admin)
POST   /api/v1/admin/fetch/yearly    Body: { cityId, startDate, endDate }
POST   /api/v1/admin/fetch/ramadan   Body: { cityId }
POST   /api/v1/admin/fetch/eid       Body: { cityId }
POST   /api/v1/admin/fetch/places    (Tüm yer bilgilerini günceller)

# Cache
POST   /api/v1/admin/cache/clear

# Loglar
GET    /api/v1/admin/logs

---

🖥️ WEB ARAYÜZÜ

Aşağıdaki sayfaları içeren sade ve işlevsel bir web arayüzü oluştur:

1. Giriş Sayfası (/login)

• Kullanıcı adı ve şifre formu
• Başarılı girişte token'ı localStorage'a kaydet
• Hata mesajlarını göster

2. Dashboard (/dashboard)

• Sistemdeki toplam kayıt sayıları (şehir, namaz vakti, ramazan kaydı)
• Son veri çekme logları tablosu
• Hızlı veri sorgulama alanı

3. Veri Çekme Paneli (/fetch)

• Ülke → Eyalet → Şehir dropdown seçimi (dinamik, birbirini tetikleyen)
• Tarih aralığı seçici
• "Yıllık Namaz Vakitlerini Çek", "Ramazan Verilerini Çek", "Bayram Verilerini Çek" butonları
• İşlem sonucunu canlı gösteren log/konsol alanı

4. Namaz Vakitleri Sorgulama (/prayer-times)

• Şehir ve tarih aralığı seçimi
• Tablo şeklinde listeleme
• CSV/JSON dışa aktarma butonu

5. Ramazan / İftar Vakitleri (/ramadan)

• Şehir seçimi
• Ramazan takvimi tablo görünümü
• İftar vakti vurgulu satır tasarımı

6. Kullanıcı Yönetimi (/admin/users) — Sadece admin rolü

• Kullanıcı listeleme, ekleme, pasif etme

7. API Token Bilgisi (/profile)

• Mevcut token'ı göster
• Yeni token üret butonu
• API kullanım dokümantasyonu linki

---

🔐 GÜVENLİK GEREKSİNİMLERİ

• Şifreler bcrypt ile hash'lenmeli
• JWT secret .env dosyasında saklanmalı
• Rate limiting eklenmeli (örn. dakikada 60 istek)
• CORS ayarları yapılmalı
• Input validasyonu tüm endpointlerde olmalı
• .env.example dosyası oluşturulmalı

---

📁 PROJE DOSYA YAPISI

hDiyanetProxy/
├── backend/
│   ├── src/
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── models/
│   │   ├── routes/
│   │   ├── middleware/
│   │   ├── jobs/          (cron jobs)
│   │   └── utils/
│   ├── .env.example
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   └── services/      (API çağrıları)
│   └── package.json
├── docker-compose.yml
└── README.md

---

📋 TAMAMLANMA KRİTERLERİ

• Kaynak Diyanet API'sinden başarıyla veri çekilebiliyor
• Çekilen veriler veritabanına doğru şekilde kaydediliyor
• JWT ile kullanıcı girişi ve token alma çalışıyor
• Token ile korunan tüm endpointler çalışıyor
• Web arayüzünden veri çekme ve sorgulama yapılabiliyor
• Şehir listesi dinamik dropdown'larla yüklenebiliyor
• Ramazan ve bayram verileri ayrı ayrı sorgulanabiliyor
• Admin panelinden kullanıcı yönetimi yapılabiliyor
• Tüm işlemler loglanıyor
• README.md kurulum adımlarını içeriyor

---

Projeyi adım adım geliştir. Önce veritabanı şemasını ve backend iskeletini kur, ardından API endpointlerini yaz, en son web arayüzünü tamamla. Her adımda çalışır durumda kod üret.