bookibra/doc/backend-yapisi.md

# Bookibra - Backend Dokümantasyonu

## Backend Genel Bakış

Backend, **Node.js** ve **Express.js** kullanılarak geliştirilmiş REST API sunucusudur. Amazon kitap verilerini scraping eder, kullanıcı kimlik doğrulaması yönetir ve önbellekleme sağlar.

## Teknoloji Yığını

| Teknoloji | Versiyon | Kullanım Amacı |
|-----------|----------|----------------|
| Express | ^5.1.0 | Web framework |
| Node.js | - | Runtime environment |
| PostgreSQL | 8.16.3 | Kullanıcı veritabanı |
| Redis (ioredis) | ^5.8.2 | Önbellekleme |
| Socket.IO | ^4.8.1 | WebSocket desteği |
| JWT | ^9.0.2 | Kimlik doğrulama |
| bcrypt | ^6.0.0 | Şifre hashleme |
| Axios | ^1.13.2 | HTTP istekleri |
| Cheerio | ^1.1.2 | HTML parsing |

## Dizin Yapısı

```
src/
├── config/
│   ├── env.js              # Ortam değişkenleri yapılandırması
│   ├── services.js         # Redis ve PostgreSQL bağlantıları
│   └── socket.js           # Socket.IO yapılandırması
├── controllers/
│   ├── authController.js   # Kimlik doğrulama endpoint'leri
│   └── bookController.js   # Kitap arama endpoint'leri
├── middleware/
│   ├── auth.js             # JWT doğrulama middleware
│   ├── errorHandler.js     # Hata yakalama middleware
│   ├── notFound.js         # 404 middleware
│   └── requestLogger.js    # İstek loglama middleware
├── routes/
│   ├── authRoutes.js       # /api/auth rotaları
│   └── bookRoutes.js       # /api/books rotaları
├── services/
│   ├── amazonService.js    # Amazon scraping iş mantığı
│   ├── cacheService.js     # Redis önbellekleme
│   └── userService.js      # Kullanıcı işlemleri
├── utils/
│   ├── isbn.js             # ISBN doğrulama ve normalizasyon
│   ├── logger.js           # Loglama yardımcıları
│   ├── mediaCache.js       # Medya önbellekleme
│   └── request.js          # İstek parametre çözümleme
├── validators/
│   └── authValidators.js   # İstek doğrulama kuralları
├── app.js                  # Express uygulaması
└── server.js               # HTTP sunucusu
```

## API Endpoint'leri

### Sağlık Kontrolü

```
GET /health
```

**Cevap**: `{"status": "ok", "timestamp": "2026-02-10T..."}`

### Kitap Endpoint'leri

#### ISBN ile Arama

```
GET /api/books/isbn/:isbn
```

**Query Parametreleri:**
- `locales` (string): Amazon siteleri (örn: "tr,en" veya "tr")
- `withGemini` (boolean): Gemini AI entegrasyonu
- `limit` (number): Sonuç sayısı limiti

**Örnek:**
```
GET /api/books/isbn/9786053717355?locales=tr,en&withGemini=false&limit=3
```

**Cevap:**
```json
{
  "isbn": "9786053717355",
  "normalizedIsbn": "9786053717355",
  "locales": ["tr", "en"],
  "includeGemini": false,
  "data": {
    "tr": {
      "title": "Suç ve Ceza",
      "authorName": "Fyodor Dostoyevski",
      "isbn": "9786053717355",
      "thumbImage": "https://...",
      "page": 752,
      "rate": 4.5,
      "publisher": "İthaki Yayınları"
    },
    "en": { ... }
  },
  "cacheHit": false,
  "cachedAt": "2026-02-10T..."
}
```

#### Başlık ile Arama

```
GET /api/books/title?title={kitap-adi}
```

**Query Parametreleri:**
- `title` (required): Kitap başlığı
- `locales` (optional): Amazon siteleri
- `withGemini` (optional): Gemini AI entegrasyonu
- `limit` (optional): Sonuç limiti (default: 3)

**Örnek:**
```
GET /api/books/title?title=Su%C3%A7%20ve%20Ceza&locales=tr&limit=5
```

#### Başlık ve Tarihe Göre Filtreleme

```
GET /api/books/filter?title={kitap-adi}&published={yil}
```

**Query Parametreleri:**
- `title` (required): Kitap başlığı
- `published` (required): Yayın yılı
- `locales`, `withGemini`, `limit`: ISBN aramasıyla aynı

**Örnek:**
```
GET /api/books/filter?title=Sapiens&published=2011&locales=en
```

### Kimlik Doğrulama Endpoint'leri

#### Kayıt Olma

```
POST /api/auth/register
```

**İstek Gövdesi:**
```json
{
  "email": "ornek@email.com",
  "password": "sifre123"
}
```

**Cevap:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "ornek@email.com"
  }
}
```

#### Giriş Yapma

```
POST /api/auth/login
```

**İstek Gövdesi:** Kayıt olma ile aynı

**Cevap:** Kayıt olma ile aynı

#### Profil Bilgisi

```
GET /api/auth/profile
```

**Header:** `Authorization: Bearer {token}`

**Cevap:**
```json
{
  "user": {
    "id": "uuid",
    "email": "ornek@email.com"
  }
}
```

## Middleware Yapısı

### 1. Auth Middleware (`src/middleware/auth.js`)

JWT token doğrulaması yapar.

```javascript
// Kullanıcı
req.user = { id: decoded.sub, email: decoded.email }
```

### 2. Error Handler Middleware (`src/middleware/errorHandler.js`)

Hataları yakalar ve standart formatta döner.

```javascript
// Cevap formatı
res.status(error.status || 500).json({
  message: error.message || 'Sunucu hatası'
})
```

### 3. Request Logger Middleware (`src/middleware/requestLogger.js`)

Her isteği loglar. Ortam değişkeni ile kontrol edilir:
- `REQUEST_LOGGING=true` → Aktif

### 4. Not Found Middleware (`src/middleware/notFound.js`)

Tanımsız rotalar için 404 döner.

## Servis Katmanı

### Amazon Service (`src/services/amazonService.js`)

Amazon'dan kitap verisi çekme iş mantığı.

**Ana Fonksiyonlar:**
- `getBooksByIsbn(isbn, locales, includeGemini)`: ISBN ile arama
- `searchBooksByTitle({ title, locales, includeGemini, limit })`: Başlık ile arama
- `searchBooksByTitleAndDate(...)`: Başlık ve tarih ile arama

**Dış Bağımlılıklar:**
- `szbk-amazon-book-search`: Amazon scraping kütüphanesi

### Cache Service (`src/services/cacheService.js`)

Redis ile önbellekleme iş mantığı.

**Cache Anahtar Formatları:**
- ISBN: `book:isbn:{isbn}:loc={tr,en}:gem={0|1}`
- Title: `book:title:q={title}:loc={...}:gem={...}:limit={n}`
- Filter: `book:filter:q={title}:pub={year}:loc={...}:gem={...}:limit={n}`

**Cache TTL:** 6 saat (21600 saniye)

### User Service (`src/services/userService.js`)

PostgreSQL ile kullanıcı işlemleri.

**Veritabanı Tablosu:**
```sql
CREATE TABLE users (
  id VARCHAR(36) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

**Ana Fonksiyonlar:**
- `ensureUserTable()`: Tablo oluşturma
- `createUser({ email, password })`: Yeni kullanıcı
- `validateCredentials({ email, password })`: Giriş doğrulama
- `buildAuthResponse(user)`: Token ve kullanıcı bilgisi

## Socket.IO Entegrasyonu

WebSocket bağlantıları için Socket.IO kullanılır.

**Yapılandırma (`src/config/socket.js`):**
```javascript
// Bağlantı eventi
io.on('connection', (socket) => {
  socket.emit('connection:ack', {
    message: 'Bookibra soket servisine hos geldiniz.'
  });
});
```

## Veritabanı Yapılandırması

### PostgreSQL Bağlantısı

```javascript
// src/config/services.js
const pgPool = new Pool({
  host: env.postgres.host,      // postgres
  port: env.postgres.port,      // 5432
  database: env.postgres.database, // bookibra
  user: env.postgres.user,      // bookibra
  password: env.postgres.password // bookibra
});
```

### Redis Bağlantısı

```javascript
const redis = new Redis(env.redisUrl, {
  lazyConnect: true,
  maxRetriesPerRequest: null
});
```

## Ortam Değişkenleri

```bash
NODE_ENV=development
PORT=8080
GEMINI_API_KEY=your_gemini_key      # İsteğe bağlı
ALLOWED_ORIGINS=*                   # CORS için
REQUEST_LOGGING=true
REDIS_URL=redis://redis:6379
ISBN_CACHE_TTL_SECONDS=21600
JWT_SECRET=please_change_me         # Production'da değiştirilmeli
JWT_EXPIRES_IN=1h
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=bookibra
POSTGRES_USER=bookibra
POSTGRES_PASSWORD=bookibra
```

## Hata Yönetimi

Tüm hatalar `errorHandler` middleware tarafından yakalanır.

**Hata Durum Kodları:**
- `400`: Geçersiz istek parametresi
- `401`: Kimlik doğrulama hatası
- `404`: Kaynak bulunamadı
- `409`: Çakışma (örn: email zaten kayıtlı)
- `500`: Sunucu hatası

## Güvenlik

1. **JWT**: Kimlik doğrulama için JWT token kullanılır
2. **bcrypt**: Şifreler hash'lenir (10 rounds)
3. **CORS**: Çapraz kaynak istekleri kontrol edilir
4. **Input Validation**: express-validator ile istek doğrulama

---

**İlgili Dosyalar:**
- [Proje Genel Bakış](./proje-genel-bakis.md)
- [Frontend Yapısı](./frontend-yapisi.md)
- [Teknoloji Yığını](./teknoloji-yigini.md)