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:
341
doc/frontend-yapisi.md
Normal file
341
doc/frontend-yapisi.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Bookibra - Frontend Dokümantasyonu
|
||||
|
||||
## Frontend Genel Bakış
|
||||
|
||||
Frontend, **React 19** ve **Vite** kullanılarak geliştirilmiş modern bir SPA (Single Page Application) uygulamasıdır. Mobil öncelikli tasarıma sahiptir ve kitap arama, barkod tarama, kütüphane yönetimi özellikleri sunar.
|
||||
|
||||
## Teknoloji Yığını
|
||||
|
||||
| Teknoloji | Versiyon | Kullanım Amacı |
|
||||
|-----------|----------|----------------|
|
||||
| React | ^19.1.1 | UI framework |
|
||||
| Vite | ^7.1.7 | Build tool ve dev server |
|
||||
| React Router | ^7.9.5 | Client-side routing |
|
||||
| Framer Motion | ^12.23.24 | Animasyonlar |
|
||||
| FontAwesome | ^7.1.0 | İkonlar |
|
||||
| react-qr-barcode-scanner | ^2.1.18 | Barkod tarama |
|
||||
| react-image-glow | ^1.0.6 | Resim efektleri |
|
||||
| color-thief-react | ^2.1.0 | Renk extract |
|
||||
|
||||
## Dizin Yapısı
|
||||
|
||||
```
|
||||
frontend/src/
|
||||
├── components/ # Yeniden kullanılabilir bileşenler
|
||||
│ ├── BookCard.jsx # Kitap kartı bileşeni
|
||||
│ └── SocialButton.jsx # Sosyal medya butonu
|
||||
├── pages/ # Sayfa bileşenleri
|
||||
│ ├── HomePage.jsx # Ana sayfa
|
||||
│ ├── MyBooksPage.jsx # Kütüphane sayfası
|
||||
│ ├── AddBooksPage.jsx # Kitap ekleme sayfası
|
||||
│ └── ProfilePage.jsx # Profil sayfası
|
||||
├── context/ # React Context
|
||||
│ └── SavedBooksContext.jsx # Kitap kütüphanesi state yönetimi
|
||||
├── assets/ # Statik dosyalar
|
||||
│ ├── booklibra-logo.svg
|
||||
│ └── ...
|
||||
├── App.jsx # Ana uygulama bileşeni
|
||||
├── main.jsx # Uygulama giriş noktası
|
||||
├── App.css # Ana stiller
|
||||
└── index.css # Global stiller
|
||||
```
|
||||
|
||||
## Uygulama Mimarisi
|
||||
|
||||
### App Bileşeni (`src/App.jsx`)
|
||||
|
||||
Uygulamanın kök bileşenidir. Routing ve layout yapısını belirler.
|
||||
|
||||
**Ana Özellikler:**
|
||||
- `SavedBooksProvider` ile context provider wrapping
|
||||
- `BrowserRouter` ile routing
|
||||
- Bottom navigation ile sayfa geçişi
|
||||
|
||||
**Navigasyon Yapısı:**
|
||||
```javascript
|
||||
const tabs = [
|
||||
{ path: '/', label: 'Home', icon: faHouse },
|
||||
{ path: '/my-books', label: 'My Books', icon: faBookOpen },
|
||||
{ path: '/add-books', label: 'Add Books', icon: faPlusCircle },
|
||||
{ path: '/profile', label: 'Profile', icon: faUser }
|
||||
];
|
||||
```
|
||||
|
||||
### Sayfalar
|
||||
|
||||
#### 1. HomePage (`src/pages/HomePage.jsx`)
|
||||
|
||||
Ana sayfa bileşeni. Şu anda basit bir başlık gösterir.
|
||||
|
||||
**Gelecek Özellikler:**
|
||||
- Son eklenen kitaplar
|
||||
- Önerilen kitaplar
|
||||
- İstatistikler
|
||||
|
||||
#### 2. AddBooksPage (`src/pages/AddBooksPage.jsx`)
|
||||
|
||||
Kitap arama ve ekleme sayfası. En karmaşık sayfa bileşenidir.
|
||||
|
||||
**Ana Özellikler:**
|
||||
- Başlık ile arama (yayın yılı filtreleme desteği)
|
||||
- Barkod tarama ile ISBN ile arama
|
||||
- Sonuçları listeleme
|
||||
- Kitapları kütüphaneye ekleme
|
||||
|
||||
**Önemli Fonksiyonlar:**
|
||||
|
||||
```javascript
|
||||
// API Base URL çözümleme
|
||||
const resolveApiBaseUrl = () => {
|
||||
// 1. Environment variable kontrolü
|
||||
// 2. Window location tabanlı çözümleme
|
||||
// 3. Default localhost:8080
|
||||
};
|
||||
|
||||
// Arama input'u parsing
|
||||
const parseSearchInput = (raw) => {
|
||||
// "Kitap Adı .2020" → { title: "Kitap Adı", published: "2020" }
|
||||
// "Kitap Adı" → { title: "Kitap Adı", published: undefined }
|
||||
};
|
||||
|
||||
// API cevabını normalizasyon
|
||||
const normalizeBook = (item) => ({
|
||||
title, authorName, thumbImage, page, rate,
|
||||
publisher, description, isbn, raw
|
||||
});
|
||||
```
|
||||
|
||||
**Barkod Tarama Akışı:**
|
||||
1. Kamera butonuna tıklama
|
||||
2. `react-qr-barcode-scanner` ile kamera açma
|
||||
3. Barkod algılama (`handleBarcodeUpdate`)
|
||||
4. ISBN ile API çağrısı
|
||||
5. Sonuçları gösterme
|
||||
|
||||
**API Endpoint'ler:**
|
||||
- `/api/books/title?title={query}`
|
||||
- `/api/books/filter?title={query}&published={year}`
|
||||
- `/api/books/isbn/{isbn}?locales=en`
|
||||
|
||||
#### 3. MyBooksPage (`src/pages/MyBooksPage.jsx`)
|
||||
|
||||
Kullanıcının kayıtlı kitaplarını gösterir.
|
||||
|
||||
**Ana Özellikler:**
|
||||
- Kitap listesi görünümü
|
||||
- Kitap detay görünümü
|
||||
- Kitap silme
|
||||
- Görsel efektler (ImageGlow)
|
||||
|
||||
**State Yönetimi:**
|
||||
```javascript
|
||||
const { savedBooks, removeBook } = useSavedBooks();
|
||||
const [selected, setSelected] = useState(null);
|
||||
```
|
||||
|
||||
**Detay Görünümü:**
|
||||
Seçili kitap için:
|
||||
- Kapak resmi (glow efekti ile)
|
||||
- Kitap bilgileri (başlık, yazar, sayfa, puan)
|
||||
- Açıklama
|
||||
- Silme butonu
|
||||
|
||||
#### 4. ProfilePage (`src/pages/ProfilePage.jsx`)
|
||||
|
||||
Kullanıcı profili sayfası. Şu anda placeholder durumunda.
|
||||
|
||||
**Gelecek Özellikler:**
|
||||
- Kullanıcı bilgileri
|
||||
- Ayarlar
|
||||
- İstatistikler
|
||||
|
||||
### Bileşenler
|
||||
|
||||
#### BookCard (`src/components/BookCard.jsx`)
|
||||
|
||||
Tek bir kitabı gösteren kart bileşeni.
|
||||
|
||||
**Props:**
|
||||
```javascript
|
||||
{
|
||||
book: {
|
||||
title: string,
|
||||
authorName: string,
|
||||
thumbImage: string,
|
||||
page: number,
|
||||
rate: number,
|
||||
...
|
||||
},
|
||||
onSelect: (book) => void
|
||||
}
|
||||
```
|
||||
|
||||
**Özellikler:**
|
||||
- Kitap kapak resmi
|
||||
- Başlık ve yazar
|
||||
- Sayfa sayısı ve puan
|
||||
- Tıklanabilir (onSelect callback)
|
||||
|
||||
#### SocialButton (`src/components/SocialButton.jsx`)
|
||||
|
||||
Sosyal medya giriş butonu.
|
||||
|
||||
**Props:**
|
||||
```javascript
|
||||
{
|
||||
provider: 'apple' | 'google',
|
||||
onClick: () => void
|
||||
}
|
||||
```
|
||||
|
||||
### Context Yönetimi
|
||||
|
||||
#### SavedBooksContext (`src/context/SavedBooksContext.jsx`)
|
||||
|
||||
Kitap kütüphanesi için global state yönetimi.
|
||||
|
||||
**API:**
|
||||
```javascript
|
||||
const { savedBooks, addBook, removeBook } = useSavedBooks();
|
||||
```
|
||||
|
||||
**Özellikler:**
|
||||
- `savedBooks`: Kayıtlı kitaplar dizisi
|
||||
- `addBook(book)`: Kitap ekleme (tekrarı kontrol eder)
|
||||
- `removeBook(title)`: Kitap silme
|
||||
|
||||
**Persistence:**
|
||||
Kitaplar `localStorage`'da saklanır:
|
||||
```javascript
|
||||
localStorage.setItem('bookibra_saved_books', JSON.stringify(savedBooks));
|
||||
```
|
||||
|
||||
## Stil Yapısı
|
||||
|
||||
### Ana Layout (`App.css`)
|
||||
|
||||
**Mobile Shell Pattern:**
|
||||
```css
|
||||
.mobile-shell {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
height: 100vh;
|
||||
}
|
||||
|
||||
.page-container {
|
||||
flex: 1;
|
||||
overflow-y: auto;
|
||||
padding-bottom: 70px; /* Bottom nav için boşluk */
|
||||
}
|
||||
```
|
||||
|
||||
**Bottom Navigation:**
|
||||
```css
|
||||
.bottom-nav {
|
||||
position: fixed;
|
||||
bottom: 0;
|
||||
width: 100%;
|
||||
display: flex;
|
||||
justify-content: space-around;
|
||||
}
|
||||
```
|
||||
|
||||
### Renk Paleti
|
||||
|
||||
CSS değişkenleri ile tanımlı:
|
||||
```css
|
||||
:root {
|
||||
--primary: /* Ana renk */;
|
||||
--secondary: /* İkincil renk */;
|
||||
--accent: /* Vurgu rengi */;
|
||||
--text: /* Metin rengi */;
|
||||
--bg: /* Arka plan */;
|
||||
}
|
||||
```
|
||||
|
||||
## API Entegrasyonu
|
||||
|
||||
### API Base URL Çözümleme
|
||||
|
||||
```javascript
|
||||
const resolveApiBaseUrl = () => {
|
||||
// 1. Environment variable (VITE_API_BASE_URL)
|
||||
if (import.meta.env.VITE_API_BASE_URL)
|
||||
return import.meta.env.VITE_API_BASE_URL;
|
||||
|
||||
// 2. Window location (production)
|
||||
if (typeof window !== 'undefined') {
|
||||
const { protocol, hostname } = window.location;
|
||||
return `${protocol}//${hostname}:8080`;
|
||||
}
|
||||
|
||||
// 3. Default (development)
|
||||
return 'http://localhost:8080';
|
||||
};
|
||||
```
|
||||
|
||||
### Örnek API Çağrısı
|
||||
|
||||
```javascript
|
||||
const response = await fetch(`${API_BASE_URL}/api/books/isbn/${isbn}?locales=en`);
|
||||
const data = await response.json();
|
||||
if (!response.ok) {
|
||||
throw new Error(data.message || 'Kitap bulunamadi');
|
||||
}
|
||||
```
|
||||
|
||||
## Build ve Deployment
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
# Çıktı: dist/ dizini
|
||||
```
|
||||
|
||||
### Docker Build
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm install
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
CMD ["npm", "run", "preview"]
|
||||
```
|
||||
|
||||
## Ortam Değişkenleri
|
||||
|
||||
```bash
|
||||
# .env.example (frontend/.env.example)
|
||||
VITE_API_BASE_URL=http://localhost:8080
|
||||
```
|
||||
|
||||
## Performans İpuçları
|
||||
|
||||
1. **Lazy Loading**: Sayfalar ihtiyaç anında yüklenir
|
||||
2. **Image Optimization**: Kapak resimleri lazy loading
|
||||
3. **Local Caching**: Kitaplar localStorage'da saklanır
|
||||
4. **API Debouncing**: Arama input'u için debounce eklenebilir
|
||||
|
||||
## Erişilebilirlik
|
||||
|
||||
- Semantic HTML kullanımı
|
||||
- Keyboard navigation desteği
|
||||
- Screen reader friendly (ikonlar için aria-label)
|
||||
|
||||
---
|
||||
|
||||
**İlgili Dosyalar:**
|
||||
- [Proje Genel Bakış](./proje-genel-bakis.md)
|
||||
- [Backend Yapısı](./backend-yapisi.md)
|
||||
- [Teknoloji Yığını](./teknoloji-yigini.md)
|
||||
Reference in New Issue
Block a user