insta/GUIDE.md

# Instagram Clone API - Detaylı Kılavuz

## 📋 İçindekiler
1. [Proje Yapısı](#proje-yapısı)
2. [Kurulum](#kurulum)
3. [Çalıştırma](#çalıştırma)
4. [Özellikler](#özellikler)
5. [API Endpoints](#api-endpoints)
6. [Veritabanı Modelleri](#veritabanı-modelleri)
7. [Celery & Otomasyonlar](#celery--otomasyonlar)
8. [Admin Paneli](#admin-paneli)
9. [Sorun Giderme](#sorun-giderme)

---

## 🏗️ Proje Yapısı

```
insta/
├── core/                    # Django ana ayarları
│   ├── settings.py         # Proje konfigürasyonu
│   ├── urls.py             # Ana URL router
│   ├── celery.py           # Celery app tanımı
│   └── wsgi.py
├── accounts/               # Kullanıcı yönetimi
│   ├── models.py           # CustomUser model (active_until ile)
│   ├── views.py            # Auth views
│   ├── urls.py             # Auth endpoints
│   ├── admin.py            # Admin paneli
│   ├── middleware.py       # Hesap süresi kontrol
│   ├── tasks.py            # Celery görevleri
│   └── migrations/
├── namecreate/             # ML model eğitimi
│   ├── models.py           # TrainingJob model
│   ├── views.py            # Model eğitim endpoints
│   ├── tasks.py            # Eğitim task'ı
│   ├── admin.py            # Admin paneli
│   ├── urls.py             # ML endpoints
│   └── migrations/
├── db.sqlite3              # Veritabanı (geliştirme)
├── requirements.txt        # Python dependencies
└── .env                    # Ortam değişkenleri
```

---

## 🚀 Kurulum

### 1. Virtual Environment Oluştur
```bash
cd /home/beyhan/Projeler/python/insta
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# veya
.venv\Scripts\activate     # Windows
```

### 2. Dependencies Yükle
```bash
pip install -r requirements.txt
```

### 3. Veritabanı Hazırla
```bash
python manage.py makemigrations
python manage.py migrate
```

### 4. Admin Kullanıcısı Oluştur
```bash
python manage.py createsuperuser
# Email: admin@example.com
# Password: ***
```

### 5. .env Dosyası Oluştur
```bash
cat > .env << EOF
DEBUG=True
SECRET_KEY=your-secret-key-here
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# Redis (Celery)
CELERY_BROKER_URL=redis://localhost:6379/5

# Go Servisi (opsiyonel)
GO_SERVICE_URL=http://localhost:8080

# Email
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
EOF
```

---

## ⚙️ Çalıştırma

### Terminal 1: Django Development Server
```bash
source .venv/bin/activate
python manage.py runserver
# Erişim: http://localhost:8000
```

### Terminal 2: Celery Worker
```bash
source .venv/bin/activate
celery -A core worker -l info
```

### Terminal 3: Celery Beat (Scheduler)
```bash
source .venv/bin/activate
celery -A core beat -l info
```

### Terminal 4: Redis (Gerekli)
```bash
redis-server
# veya
docker run -d -p 6379:6379 redis:latest
```

---

## ⭐ Özellikler

### 1. **Admin-Only Kullanıcı Kaydı**
- Sadece admin kullanıcılar yeni hesap oluşturabilir
- `/api/v1/auth/users/` - POST (admin only)
- `/api/v1/auth/users/activation/` - POST (admin only)
- `/api/v1/auth/users/resend_activation/` - POST (admin only)

### 2. **Zamanlı Hesap Aktifliği**
- Kullanıcılara sınırlı kullanım süresi verilebilir
- `active_until` alanı ile kontrol edilir
- Otomatik pasife çekilir (middleware + Celery)

### 3. **Model Eğitimi (ML)**
- RandomForest modeli eğitilir
- ONNX formatına kaydedilir
- Metrikleri kaydedilir (accuracy, precision, recall, f1)
- Go servisine bildirilir

### 4. **Celery Otomasyonları**
- Süresi dolmuş hesapları günlük deaktif etme
- Model eğitimini arka planda yapma
- Database scheduler ile yönetim

### 5. **Admin Panelden Terminalsiz Uretim (2 Mod)**
- Terminal erisimi olmadan admin panelden kisi uretimi yapabilirsiniz.
- Yol: `Admin > Namecreate > Training jobs`
- Bir veya birden fazla `TrainingJob` secin, sonra `Action` menusunden secin:
  - `Secili job(lar) icin 100 kisi uret (Istatistiksel)`
  - `Secili job(lar) icin 100 kisi uret (LLM + fallback)`
  - `Secili job(lar) icin 1000 kisi uret (Istatistiksel)`
  - `Secili job(lar) icin 1000 kisi uret (LLM + fallback)`
- LLM servisi kapaliysa `LLM + fallback` secenegi otomatik olarak istatistiksel uretime duser.

---

## 🔌 API Endpoints

### **Kimlik Doğrulama (Djoser)**

#### Kayıt (Admin Only)
```bash
POST /api/v1/auth/users/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "strongpass123",
  "re_password": "strongpass123",
  "first_name": "John",
  "last_name": "Doe"
}

# Yanıt (201 Created)
{
  "id": 1,
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe"
}
```

#### Login
```bash
POST /api/v1/auth/jwt/create/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "strongpass123"
}

# Yanıt
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

#### Profil Bilgileri
```bash
GET /api/v1/auth/users/me/
Authorization: Bearer <access_token>

# Yanıt
{
  "id": 1,
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "date_joined": "2026-03-27T12:00:00Z"
}
```

### **ML Model Eğitimi**

#### Eğitim Başlat
```bash
POST /api/v1/ml/train-model/
Authorization: Bearer <access_token>

# Yanıt (Task başlatıldı)
{
  "status": "queued",
  "message": "Model eğitim görevi başlatıldı.",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "celery_task_id": "abc123xyz"
}
```

#### Eğitim Durumunu Sorgula
```bash
GET /api/v1/ml/training-status/?task_id=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <access_token>

# Yanıt (Tamamlandı)
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2026-03-27T12:00:00Z",
  "started_at": "2026-03-27T12:00:05Z",
  "completed_at": "2026-03-27T12:01:30Z",
  "model_version": "2026-03-27T12-00-00",
  "metrics": {
    "accuracy": 0.96,
    "precision": 0.97,
    "recall": 0.95,
    "f1_score": 0.96
  }
}
```

---

## 💾 Veritabanı Modelleri

### **CustomUser (accounts/models.py)**
```python
class CustomUser(AbstractBaseUser, PermissionsMixin):
    email                # Unique email
    first_name          # İsim
    last_name           # Soyisim
    is_active           # Aktif mi?
    is_staff            # Admin mi?
    is_superuser        # Superuser mi?
    active_until        # ⭐ Hesap bitiş tarihi
    date_joined         # Kayıt tarihi
    last_login          # Son giriş
    
    # Metodlar:
    is_expired()        # Süresi doldu mu?
    deactivate_if_expired()  # Pasif yap
    set_active_for_days(days)  # N gün için aktif et
```

### **TrainingJob (namecreate/models.py)**
```python
class TrainingJob(models.Model):
    task_id             # Celery task ID
    status              # pending, running, completed, failed
    model_type          # Model tipi (RandomForest)
    model_version       # Timestamp (versiyonlama)
    model_path          # Dosya yolu
    
    # Metrikleri
    accuracy            # Doğruluk
    precision           # Kesinlik
    recall              # Geri çağırma
    f1_score            # F1 skoru
    
    # Zaman damgaları
    created_at          # Oluşturulma
    started_at          # Başlama
    completed_at        # Tamamlanma
    
    # Go Servisi
    go_service_notified # Bildirildi mi?
    
    # Hata
    error_message       # Hata mesajı
```

---

## 🤖 Celery & Otomasyonlar

### **Otomatik Prosesler**

#### 1. Süresi Dolmuş Hesapları Deaktif Etme
**Periyodiklik:** Her 24 saatte 1 kez
**Task:** `accounts.tasks.deactivate_expired_users_task()`
**Veritabanı:** `active_until <= now()` olan users pasif olur

Manuel çalıştırmak:
```bash
python manage.py deactivate_expired_users
```

#### 2. Model Eğitimi
**Periyodiklik:** İsteğe bağlı (manual trigger)
**Task:** `namecreate.tasks.train_model_task(task_id)`
**İşler:**
1. Veriyi yükle (Iris dataset)
2. Modeli eğit (RandomForest)
3. Metrikleri hesapla
4. ONNX formatına kaydet (versiyonlu)
5. Go servisine bildir

### **Celery Settings (core/settings.py)**
```python
CELERY_BROKER_URL = 'redis://localhost:6379/5'
CELERY_RESULT_BACKEND = 'django-db'
CELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers:DatabaseScheduler'

CELERY_BEAT_SCHEDULE = {
    'deactivate-expired-users-daily': {
        'task': 'accounts.tasks.deactivate_expired_users_task',
        'schedule': 60 * 60 * 24,  # Her 24 saat
    },
}
```

### **Task Monitoring**

Celery Flower ile gerçek zamanlı monitoring:
```bash
pip install flower
celery -A core flower
# Erişim: http://localhost:5555
```

---

## 👨‍💼 Admin Paneli

### **Admin Erişimi**
```
http://localhost:8000/admin/
Email: admin@example.com
Şifre: ***
```

### **Admin Sayfalarında Neleri Yönetebilirsin?**

#### 1. **Kullanıcılar** (`/admin/accounts/customuser/`)
- Yeni kullanıcı oluştur
- `active_until` tarihi belirle
- Hesabı aktif/pasif yap
- Filtreleme: İçinden çıkış tarihi, aktif durum, staff status

#### 2. **Eğitim Görevleri** (`/admin/namecreate/trainingjob/`)
- Tüm eğitim görevlerini görüntüle
- Status takibi: pending → running → completed/failed
- Metrikleri kontrol et (accuracy, f1, vb.)
- Error loglarını göster (başarısız task'lar)
- Go servisine bildirilip bildirilmediğini kontrol et

#### 3. **Periyodik Görevler** (`/admin/django_celery_beat/periodictask/`)
- Celery Beat task'larını yönet
- Schedule'ı özelleştir
- Yeni periyodik görev ekle

---

## 🔍 Sorun Giderme

### **Problem: Celery Worker hata veriyor**

**Çözüm 1:** Redis çalışıyor mu?
```bash
redis-cli ping
# Yanıt: PONG ise OK
```

**Çözüm 2:** Hata logu kontrol et
```bash
celery -A core worker -l debug
```

**Çözüm 3:** Database migrations kontrol et
```bash
python manage.py migrate
```

---

### **Problem: Model eğitimi başlamıyor**

**Çözüm 1:** Task'ı manuel test et
```bash
python manage.py shell
>>> from namecreate.tasks import train_model_task
>>> task_id = 'test-123'
>>> from namecreate.models import TrainingJob
>>> job = TrainingJob.objects.create(task_id=task_id)
>>> result = train_model_task.delay(task_id)
>>> result.get()
```

**Çözüm 2:** Worker loglarını kontrol et (`celery -A core worker -l info`)

---

### **Problem: Admin panelinde TrainingJob görmüyorum**

**Çözüm:** Migration'ı çalıştır
```bash
python manage.py migrate namecreate
```

---

### **Problem: Djoser endpoints 403 Forbidden dönem**

**Sebep:** Admin değilsin (register/activation admin-only'dir)
- Admin kullanıcı ile yapabilirsin
- Veya superuser token'ı kullan

**Test:**
```bash
# Superuser ile
TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/jwt/create/ \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"***"}' | jq -r '.access')

curl -X POST http://localhost:8000/api/v1/auth/users/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email":"newuser@example.com",
    "password":"pass123",
    "re_password":"pass123"
  }'
```

---

## 📊 Örnek İş Akışı

### **Senaryo 1: Yeni Kullanıcı Ekleme (Admin)**

```bash
# 1. Admin token al
curl -X POST http://localhost:8000/api/v1/auth/jwt/create/ \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"adminpass123"}' \
  | jq .

# Response: access token vs refresh token

# 2. Yeni kullanıcı oluştur
curl -X POST http://localhost:8000/api/v1/auth/users/ \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "email":"john@example.com",
    "password":"johnpass123",
    "re_password":"johnpass123",
    "first_name":"John",
    "last_name":"Doe"
  }'

# 3. Admin panelinden active_until tarihi belirle
# http://localhost:8000/admin/accounts/customuser/
# John'ın profiline gir → active_until = 2026-04-27 (30 gün başlar)

# 4. 30 gün sonra otomatik pasif olur
```

### **Senaryo 2: Model Eğitimi**

```bash
# 1. Eğitim başlat
curl -X POST http://localhost:8000/api/v1/ml/train-model/ \
  -H "Authorization: Bearer <TOKEN>" \
  | jq .

# Response: task_id = "550e8400-e29b-41d4-a716-446655440000"

# 2. Durum sorgula (5-10 saniye sonra)
curl http://localhost:8000/api/v1/ml/training-status/?task_id=550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <TOKEN>" \
  | jq .

# 3. Tamamlanınca:
#    - Model: media/models/iris_model_2026-03-27_12-30-45.onnx
#    - Metrikler: accuracy=0.96, f1=0.96
#    - Go servisi bilgilendirildi (varsa)
```

---

## 📝 Notlar

- **Geliştirme:** SQLite kullanıyor. Production'da PostgreSQL kullan.
- **Redis:** Celery için gerekli. Docker'da `redis:latest` kullan.
- **Go Servisi:** `.env` dosyasında `GO_SERVICE_URL` tanımlarsan otomatik bildirim yapılır.
- **Emails:** Console backend kullanıyor. SMTP konfigürasyonu yapabilirsin.

---

## 📚 Faydalı Commands

```bash
# Veritabanı işlemleri
python manage.py makemigrations
python manage.py migrate
python manage.py flush  # Tüm veriyi sil (DİKKAT!)

# Shell (Python repl)
python manage.py shell

# Superuser oluştur
python manage.py createsuperuser

# Celery test
python manage.py celery -A core worker -l info

# Datab Shell (SQL)
python manage.py dbshell

# Yeni app oluştur
python manage.py startapp appname
```

---

## 🎯 Sonraki Adımlar

- [ ] PostgreSQL kurulumu
- [ ] Production settings
- [ ] Docker containerization
- [ ] CI/CD pipeline (GitHub Actions)
- [ ] Monitoring & logging
- [ ] API Rate limiting
- [ ] WebSocket entegrasyonu (asenkron güncellemeler)

---

**Hazırlandı:** 27 Mart 2026  
**Versiyon:** 1.0