docs: proje dokümantasyonunu ekle
README.md ve detaylı teknik dokümantasyon dosyaları (genel bakış, backend yapısı, frontend yapısı, teknoloji yığını) eklendi.
This commit is contained in:
351
doc/backend-yapisi.md
Normal file
351
doc/backend-yapisi.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user