MarifetBul Backend API

Spring Boot 3.4 tabanlı MarifetBul freelance platform backend servisi.

---

Teknoloji Yığını

Kategori	Teknoloji
Framework	Spring Boot 3.4.1, Java 17
Veritabanı	PostgreSQL 16 + Flyway migrasyonları
Cache	Redis 7 (token blacklist, sorgu cache)
Arama	Elasticsearch 8.16
Güvenlik	Spring Security 6, JWT (HS512)
Ödeme	Iyzico (Türkiye ödeme altyapısı)
E-posta	SendGrid + Thymeleaf şablonları
Push	Firebase Admin SDK
SMS	Netgsm
Depolama	Cloudinary, AWS S3
WebSocket	STOMP over SockJS
Dayanıklılık	Resilience4j (circuit breaker, retry, bulkhead)
Monitoring	Sentry, Prometheus, Micrometer, OpenTelemetry
Dokümantasyon	SpringDoc OpenAPI (Swagger UI)
Test	JUnit 5, Testcontainers, H2
Derleme	Maven 3.8+

---

Önkoşullar

• Java 17+
• Maven 3.8+
• Docker ve Docker Compose

---

Kurulum

1. Altyapı Servislerini Başlatın

docker compose up -d

Bu komut şu servisleri başlatır:

• PostgreSQL 16 — port 5432
• Redis 7 — port 6379
• Elasticsearch 8.16 — port 9200

2. Yapılandırma

cp .env.example .env

.env dosyasını düzenleyin. Minimum gerekli değişkenler:

# Veritabanı
DB_URL=jdbc:postgresql://localhost:5432/marifetbul_dev
DB_USERNAME=postgres
DB_PASSWORD=postgres

# JWT — Production için güçlü bir secret kullanın
JWT_SECRET=dev_jwt_secret_key_change_in_production_minimum_512_bits_required
JWT_EXPIRATION=86400000
JWT_REFRESH_EXPIRATION=604800000

# CORS — Frontend adresi
CORS_ALLOWED_ORIGINS=http://localhost:3000

# Profil
SPRING_PROFILES_ACTIVE=dev

3. Uygulamayı Çalıştırın

mvn spring-boot:run -Dspring-boot.run.profiles=dev

API http://localhost:8080 adresinde başlar.

4. Doğrulama

# Sağlık kontrolü
curl http://localhost:8080/actuator/health

# Swagger UI
open http://localhost:8080/swagger-ui.html

---

Proje Yapısı

src/main/java/com/marifetbul/api/
├── MarifetBulApplication.java      # Ana sınıf
│
├── config/                         # Yapılandırma
│   ├── SecurityConfig.java         # Spring Security + JWT
│   ├── CorsConfig.java             # CORS ayarları
│   ├── WebSocketConfig.java        # STOMP WebSocket
│   ├── CacheConfiguration.java     # Redis cache
│   ├── RedisConfig.java            # Redis bağlantısı
│   ├── Resilience4jConfig.java     # Circuit breaker
│   ├── AsyncConfig.java            # Asenkron işlemler
│   └── GlobalExceptionHandler.java # Merkezi hata yönetimi
│
├── security/                       # Güvenlik katmanı
│   ├── JwtTokenProvider.java       # JWT üretim ve doğrulama
│   ├── JwtAuthenticationFilter.java# İstek filtresi
│   ├── UserPrincipal.java          # Kimlik doğrulama modeli
│   └── CustomUserDetailsService.java
│
├── common/                         # Ortak bileşenler
│   ├── entity/BaseEntity.java      # Temel entity (id, createdAt, updatedAt)
│   ├── dto/ApiResponse.java        # Standart API yanıtı
│   ├── exception/                  # Özel istisnalar
│   └── validation/                 # @NoXss gibi doğrulayıcılar
│
├── domain/                         # İş mantığı (DDD)
│   ├── auth/                       # Kimlik doğrulama
│   │   └── service/                # AuthService, TwoFactorAuthService
│   ├── user/                       # Kullanıcı yönetimi
│   │   ├── entity/User.java
│   │   ├── repository/
│   │   ├── service/
│   │   └── controller/
│   ├── job/                        # İş ilanları
│   ├── packages/                   # Hizmet paketleri
│   ├── proposal/                   # Teklifler
│   ├── order/                      # Siparişler (milestone, teslimat)
│   ├── payment/                    # Ödeme, cüzdan, iade, komisyon
│   ├── message/                    # Mesajlaşma
│   ├── notification/               # Bildirimler (multi-channel)
│   ├── review/                     # Değerlendirmeler
│   ├── dispute/                    # Anlaşmazlıklar
│   ├── blog/                       # Blog sistemi
│   ├── moderation/                 # İçerik moderasyonu
│   ├── favorites/                  # Favoriler
│   ├── portfolio/                  # Portföy
│   ├── category/                   # Kategoriler
│   ├── analytics/                  # Analitik
│   ├── dashboard/                  # Dashboard servisleri
│   ├── support/                    # Destek bilet sistemi
│   ├── scheduler/                  # Zamanlanmış görevler
│   └── settings/                   # Ayarlar
│
├── infrastructure/                 # Altyapı katmanı
│   ├── payment/
│   │   ├── iyzico/                 # Iyzico ödeme entegrasyonu
│   │   └── webhook/                # Webhook güvenlik filtresi
│   ├── email/                      # SendGrid e-posta servisi
│   ├── push/                       # Firebase push bildirimler
│   ├── sms/                        # Netgsm SMS servisi
│   ├── search/                     # Elasticsearch arama
│   ├── websocket/                  # STOMP WebSocket sunucusu
│   ├── storage/                    # Dosya depolama (Cloudinary, S3)
│   ├── cloudinary/                 # Görsel optimizasyonu
│   ├── geocoding/                  # Google Maps
│   ├── cache/                      # Cache invalidation
│   ├── audit/                      # Denetim günlükleri
│   ├── security/                   # Rate limiting, XSS koruması
│   ├── monitoring/                 # Sentry, Prometheus
│   ├── health/                     # Sağlık kontrolleri
│   └── testdata/                   # Seed data (geliştirme)
│
├── presentation/rest/v1/           # REST controller'lar
│   ├── admin/                      # Admin endpoint'leri
│   ├── analytics/
│   └── geocoding/
│
└── dto/                            # Veri transfer nesneleri

---

Veritabanı Migrasyonları

Flyway ile yönetilen 20+ migrasyon dosyası:

Versiyon	Açıklama
V1.0	Temel şema (kullanıcılar, kimlik doğrulama)
V2.x	Pazaryeri (iş ilanları, paketler, teklifler)
V3.x	Siparişler ve anlaşmazlıklar
V4.x	Ödeme sistemi (ödeme, cüzdan, iade)
V5.0	Değerlendirmeler
V7.x	Mesajlaşma ve bildirimler
V8.x	Destek, blog, moderasyon
V9.x	Analitik ve denetim günlükleri

Migrasyonlar uygulama başlatıldığında otomatik çalışır.

---

API Endpoint'leri

Kimlik Doğrulama

POST   /api/v1/auth/register              # Kayıt
POST   /api/v1/auth/login                 # Giriş
POST   /api/v1/auth/refresh               # Token yenileme
POST   /api/v1/auth/logout                # Çıkış
POST   /api/v1/auth/phone/send-code       # Telefon doğrulama
POST   /api/v1/auth/phone/verify          # Kod doğrulama

Kullanıcılar

GET    /api/v1/users/:id                  # Profil görüntüle
PUT    /api/v1/users/:id                  # Profil güncelle
GET    /api/v1/users/:id/reviews          # Kullanıcı yorumları

İş İlanları ve Paketler

GET    /api/v1/jobs                       # İlanları listele
POST   /api/v1/jobs                       # İlan oluştur
GET    /api/v1/packages                   # Paketleri listele
POST   /api/v1/packages                   # Paket oluştur
GET    /api/v1/categories                 # Kategoriler

Teklifler

POST   /api/v1/proposals                  # Teklif ver
PUT    /api/v1/proposals/:id/accept       # Kabul et
PUT    /api/v1/proposals/:id/reject       # Reddet

Siparişler

POST   /api/v1/orders/package             # Paket siparişi
POST   /api/v1/orders/job                 # İş siparişi
PUT    /api/v1/orders/:id/deliver         # Teslimat yap
PUT    /api/v1/orders/:id/approve         # Onayla
PUT    /api/v1/orders/:id/revision        # Revizyon iste

Ödeme ve Cüzdan

POST   /api/v1/payments                   # Ödeme başlat
GET    /api/v1/wallet                     # Cüzdan bilgisi
GET    /api/v1/wallet/escrow-details      # Escrow detayları
POST   /api/v1/payouts/request            # Çekim talebi

Mesajlaşma

GET    /api/v1/conversations              # Konuşmaları listele
POST   /api/v1/messages                   # Mesaj gönder
WS     /ws                                # WebSocket bağlantısı (STOMP)

Blog

GET    /api/v1/blog                       # Yazıları listele
POST   /api/v1/blog                       # Yazı oluştur
GET    /api/v1/blog/:id                   # Yazı detayı
GET    /api/v1/blog/slug/:slug            # Slug ile getir

Admin

GET    /api/v1/admin/system/health        # Sistem sağlığı
GET    /api/v1/admin/analytics            # Analitik
GET    /api/v1/admin/quality              # Kalite metrikleri
POST   /api/v1/refunds/bulk-approve       # Toplu iade onayı

Tam API dokümantasyonu: http://localhost:8080/swagger-ui.html

---

Ortam Değişkenleri

Tüm değişkenler .env.example dosyasında açıklanmıştır.

Değişken	Açıklama	Zorunlu
DB_URL	PostgreSQL JDBC URL	Evet
DB_USERNAME / DB_PASSWORD	Veritabanı kimlik bilgileri	Evet
JWT_SECRET	JWT imzalama anahtarı (min. 512 bit)	Evet
CORS_ALLOWED_ORIGINS	İzin verilen frontend adresleri	Evet
REDIS_HOST / REDIS_PORT	Redis bağlantısı	Evet
SENDGRID_API_KEY	SendGrid e-posta API anahtarı	E-posta için
IYZICO_API_KEY / IYZICO_SECRET_KEY	Iyzico ödeme kimlik bilgileri	Ödeme için
ELASTICSEARCH_URIS	Elasticsearch bağlantısı	Arama için
SENTRY_DSN	Sentry hata izleme	Monitoring için
GOOGLE_MAPS_API_KEY	Google Maps Geocoding	Konum için

---

Profiller

Profil	Kullanım
dev	Yerel geliştirme (mock servisler, verbose log)
test	Test ortamı (H2 in-memory)
prod	Üretim (SSL, optimize bağlantı havuzu)
storage	Depolama sağlayıcısı yapılandırması

# Profil ile çalıştırma
mvn spring-boot:run -Dspring-boot.run.profiles=dev

---

Docker

Geliştirme

# Altyapı servislerini başlat
docker compose up -d

# Sadece backend'i Dockerfile ile çalıştır
docker build -t marifetbul-api .
docker run -p 8080:8080 --env-file .env marifetbul-api

Üretim

docker build -f Dockerfile.prod -t marifetbul-api:latest .
docker compose -f docker-compose.prod.yml up -d

Kubernetes

kubectl apply -f k8s/

Kubernetes yapılandırması:

• Namespace: marifetbul-prod
• HPA: CPU bazlı otomatik ölçeklendirme
• Ingress: TLS/HTTPS terminasyonu
• PersistentVolume: 80Gi veritabanı depolama
• Health Probes: Liveness ve readiness kontrolleri

---

WebSocket

STOMP protokolü ile gerçek zamanlı mesajlaşma:

Yapılandırma	Değer
Endpoint	/ws
Protokol	STOMP over SockJS
Heartbeat	10 saniye
Max Mesaj	512 KB
Auth	JWT doğrulama (bağlantı anında)

Topic'ler:

/topic/{category}                  # Broadcast
/queue/{userId}                    # Kullanıcıya özel
/user/{userId}/queue/notifications # Bildirimler
/user/{userId}/queue/messages      # Mesajlar
/user/{userId}/queue/orders        # Sipariş güncellemeleri

---

Güvenlik

• Kimlik Doğrulama: JWT (HS512), httpOnly cookie
• Yetkilendirme: Spring Security, method-level @PreAuthorize
• CORS: Whitelist bazlı origin kontrolü
• Rate Limiting: Bucket4j ile endpoint bazlı limitleme
• XSS Koruması: @NoXss özel doğrulayıcı
• CSRF: State-changing isteklerde token doğrulama
• Webhook Güvenliği: HMAC-SHA256 imza doğrulama
• Hassas Veri: Log'larda otomatik maskeleme
• Dosya Doğrulama: MIME tipi ve boyut kontrolü

---

Monitoring

Araç	Endpoint / Yapılandırma
Actuator	/actuator/health, /actuator/metrics
Prometheus	/actuator/prometheus
Sentry	SENTRY_DSN environment variable
Swing Log	logs/marifetbul-backend.log (max 10MB, 30 rotasyon)

Sağlık kontrolleri: PostgreSQL, Redis, Elasticsearch, bellek kullanımı.

---

Test

# Tüm testleri çalıştır
mvn test

# Belirli bir test sınıfını çalıştır
mvn test -Dtest=OrderFacadeServiceTest

# Coverage raporu
mvn test jacoco:report
# Rapor: target/site/jacoco/index.html

Test altyapısı:

• JUnit 5 + Mockito
• Testcontainers (PostgreSQL)
• H2 in-memory (birim testleri)
• JaCoCo hedefi: %40 satır, %35 branch

---

Katkıda Bulunma

1. Projeyi fork'layın
2. Feature branch oluşturun
3. Değişikliklerinizi commit edin
4. Pull Request açın

Kurallar

• Java 17 özellikleri kullanılabilir
• Yeni entity'ler için Flyway migrasyonu zorunludur
• Servis sınıfları @Transactional annotation'ı ile işaretlenmeli
• @NoXss validator'ı kullanıcı girdilerinde kullanılmalı
• Hata mesajları Türkçe olmalı

---

Lisans

MIT