193 lines
6.3 KiB
Markdown
193 lines
6.3 KiB
Markdown
# Değerlendirme ve Puanlama Sistemi (Reviews API) Dokümantasyonu
|
||
|
||
Bu doküman, `reviews` uygulaması tarafından sağlanan API endpoint'lerinin frontend tarafında nasıl kullanılacağını açıklar. Bu sistem polimorfik bir yapıdadır, yani sadece ürünler için değil, ileride eklenebilecek diğer modüller (Blog, Satıcı vb.) için de kullanılabilir.
|
||
|
||
## 1. Genel Bilgiler
|
||
|
||
* **Base URL:** `/api/v1/reviews/`
|
||
* **Authentication:** Oy verme işlemi (`POST`) için kullanıcının giriş yapmış olması (Token ile) gerekir. Listeleme (`GET`) işlemi herkese açıktır.
|
||
|
||
## 2. Ürün Verisinde Puanlama Bilgisi
|
||
|
||
Ürünleri listelediğinizde (`/api/v1/products/`) veya detayını çektiğinizde (`/api/v1/products/<slug>/`), ürün objesi artık şu iki alanı içerir:
|
||
|
||
* **`average_rating` (Float):** Ürünün ortalama puanı (1.0 - 5.0 arası). Hiç oy yoksa `0.0` döner.
|
||
* **`rating_count` (Integer):** Toplam kaç kişinin oy verdiği.
|
||
|
||
**Örnek Ürün Objesi:**
|
||
```json
|
||
{
|
||
"id": 15,
|
||
"title": "Örnek Ürün",
|
||
"price": 100.0,
|
||
"average_rating": 4.5, // <-- Ortalama Puan
|
||
"rating_count": 12, // <-- Oy Sayısı
|
||
"images": "/media/uploads/products/example.avif",
|
||
...
|
||
}
|
||
```
|
||
Bu bilgileri ürün kartlarında yıldız göstermek için kullanabilirsiniz.
|
||
|
||
---
|
||
|
||
## 3. API Endpoint'leri
|
||
|
||
### 3.1. Oy Verme ve Yorum Yapma
|
||
|
||
Kullanıcının bir nesneye (örneğin bir ürüne) puan vermesini ve isteğe bağlı olarak yorum yapmasını sağlar. Bir kullanıcı aynı nesneye sadece bir kez oy verebilir; ikinci istekte mevcut oy güncellenir.
|
||
|
||
* **URL:** `/api/v1/reviews/rate/`
|
||
* **Method:** `POST`
|
||
* **Permission:** `IsAuthenticated` (Header'da `Authorization: Bearer <token>` olmalı)
|
||
|
||
#### İstek (Request) Body Parametreleri:
|
||
|
||
| Parametre | Tip | Zorunlu | Açıklama |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `model_name` | String | Evet | Oylanacak nesnenin model adı. Örn: `"product"` |
|
||
| `object_id` | Integer | Evet | Oylanacak nesnenin ID'si. Örn: `15` |
|
||
| `score` | Integer | Evet | 1 ile 5 arasında bir tam sayı. |
|
||
| `comment` | String | Hayır | Kullanıcının yorumu. |
|
||
|
||
#### Örnek İstek (JSON):
|
||
|
||
```json
|
||
{
|
||
"model_name": "product",
|
||
"object_id": 15,
|
||
"score": 5,
|
||
"comment": "Ürün beklediğimden çok daha kaliteli çıktı, tavsiye ederim."
|
||
}
|
||
```
|
||
|
||
#### Başarılı Yanıt (201 Created veya 200 OK):
|
||
|
||
```json
|
||
{
|
||
"id": 42,
|
||
"score": 5,
|
||
"comment": "Ürün beklediğimden çok daha kaliteli çıktı, tavsiye ederim.",
|
||
"user": "kullanici_adi",
|
||
"created_at": "2023-10-27T10:00:00Z",
|
||
"model_name": "product",
|
||
"object_id": 15
|
||
}
|
||
```
|
||
|
||
#### Hata Yanıtları:
|
||
|
||
* **400 Bad Request:** Eksik parametre veya geçersiz puan (1-5 dışı).
|
||
* **401 Unauthorized:** Giriş yapılmamış.
|
||
* **404 Not Found:** Belirtilen model veya ID bulunamadı.
|
||
|
||
---
|
||
|
||
### 3.2. Değerlendirmeleri Listeleme
|
||
|
||
Belirli bir nesneye ait tüm yorumları ve puanları listeler. Genellikle ürün detay sayfasının altındaki "Yorumlar" sekmesinde kullanılır.
|
||
|
||
* **URL:** `/api/v1/reviews/list/`
|
||
* **Method:** `GET`
|
||
* **Permission:** `AllowAny` (Herkes erişebilir)
|
||
|
||
#### Query Parametreleri:
|
||
|
||
| Parametre | Zorunlu | Açıklama |
|
||
| :--- | :--- | :--- |
|
||
| `model` | Evet | Listelenecek nesnenin model adı. Örn: `product`|
|
||
| `id` | Evet | Listelenecek nesnenin ID'si. |
|
||
|
||
#### Örnek İstek:
|
||
|
||
`GET /api/v1/reviews/list/?model=product&id=15`
|
||
|
||
#### Başarılı Yanıt (200 OK):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 42,
|
||
"score": 5,
|
||
"comment": "Harika ürün!",
|
||
"user": "ahmet123",
|
||
"created_at": "2023-10-27T10:00:00Z",
|
||
"model_name": "product",
|
||
"object_id": 15
|
||
},
|
||
{
|
||
"id": 43,
|
||
"score": 4,
|
||
"comment": "Kargo biraz geç geldi ama ürün güzel.",
|
||
"user": "ayse_yilmaz",
|
||
"created_at": "2023-10-26T14:30:00Z",
|
||
"model_name": "product",
|
||
"object_id": 15
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Frontend Entegrasyon Senaryosu (React Örneği)
|
||
|
||
Bir ürün detay sayfasında (Product Detail Page) yapılması gerekenler:
|
||
|
||
1. **Ürün Bilgisini Çek:** `/api/v1/products/<slug>/` endpoint'inden ürünü çekin. Gelen `average_rating` ve `rating_count` ile sayfanın üst kısmında yıldızları gösterin.
|
||
2. **Yorumları Çek:** Ürün ID'sini kullanarak `/api/v1/reviews/list/?model=product&id=<id>` endpoint'inden yorumları çekin ve aşağıda listeleyin.
|
||
|
||
```javascript
|
||
import React, { useState, useEffect } from 'react';
|
||
import axios from 'axios';
|
||
|
||
function ProductDetail({ slug }) {
|
||
const [product, setProduct] = useState(null);
|
||
const [reviews, setReviews] = useState([]);
|
||
|
||
useEffect(() => {
|
||
async function fetchData() {
|
||
// 1. Ürün detayını çek
|
||
const prodRes = await axios.get(`/api/v1/products/${slug}/`);
|
||
setProduct(prodRes.data);
|
||
|
||
// 2. Ürünün yorumlarını çek (prodRes.data.id kullanarak)
|
||
const reviewRes = await axios.get(`/api/v1/reviews/list/`, {
|
||
params: { model: 'product', id: prodRes.data.id }
|
||
});
|
||
setReviews(reviewRes.data);
|
||
}
|
||
fetchData();
|
||
}, [slug]);
|
||
|
||
if (!product) return <div>Yükleniyor...</div>;
|
||
|
||
return (
|
||
<div>
|
||
<h1>{product.title}</h1>
|
||
|
||
{/* Özet Puan Gösterimi */}
|
||
<div className="rating-summary">
|
||
<span>Ortalama Puan: {product.average_rating} / 5</span>
|
||
<span>({product.rating_count} değerlendirme)</span>
|
||
</div>
|
||
|
||
{/* ... Ürün detayları ... */}
|
||
|
||
{/* Yorumlar Listesi */}
|
||
<div className="reviews-section">
|
||
<h3>Yorumlar</h3>
|
||
{reviews.map(review => (
|
||
<div key={review.id} className="review-card">
|
||
<strong>{review.user}</strong> - <span>{review.score} Yıldız</span>
|
||
<p>{review.comment}</p>
|
||
</div>
|
||
))}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
## 5. Notlar
|
||
|
||
* **Resim Yolları:** API'den dönen resim yolları `/media/...` şeklinde olabilir. Frontend tarafında base URL'i (`http://localhost:8000` veya canlı sunucu adresi) başına eklemeniz gerekebilir.
|