shopback/README.md

Django REST API - Authentication System

Django 6.0 tabanlı, email authentication, JWT tokens ve social login desteği olan modern bir REST API.

🚀 Özellikler

• ✅ Email-based Authentication (username yok)
• ✅ JWT Tokens (access + refresh)
• ✅ Email Activation (kayıt sonrası aktivasyon)
• ✅ Social Login (Google, GitHub, Facebook)
• ✅ Password Reset (email ile)
• ✅ Rate Limiting (güvenlik için)
• ✅ CORS Support (SPA frontend'ler için)
• ✅ Modern Email Templates (HTML + plain text)

📋 Gereksinimler

• Python 3.10+
• Django 6.0
• PostgreSQL (production) veya SQLite (development)
• MailPit (development için email testing)

🛠️ Kurulum

1. Repository'yi Clone'layın

git clone <your-repo-url>
cd server

2. Virtual Environment Oluşturun

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# veya
.venv\Scripts\activate  # Windows

3. Bağımlılıkları Yükleyin

pip install -r req.txt

4. Environment Variables

cp .env.example .env
# .env dosyasını düzenleyin

5. Database Migration

python manage.py migrate

6. Superuser Oluşturun

python manage.py createsuperuser

7. Development Server'ı Başlatın

python manage.py runserver

API: http://localhost:8000/api/v1/ Admin: http://localhost:8000/admin/

📧 Email Testing (MailPit)

Development ortamında email'leri test etmek için MailPit kullanıyoruz.

MailPit Kurulumu

# Docker ile
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit

# veya binary ile
# https://github.com/axllent/mailpit/releases

MailPit Web UI

http://localhost:8025 - Gönderilen email'leri görüntüleyin

🔐 Authentication Endpoints

Register

POST /api/v1/auth/users/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "StrongP@ssw0rd123",
  "re_password": "StrongP@ssw0rd123",
  "first_name": "Ali",
  "last_name": "Veli"
}

Activate Account

POST /api/v1/auth/users/activation/
Content-Type: application/json

{
  "uid": "MQ",
  "token": "c4h7vu-..."
}

Login

POST /api/v1/auth/jwt/create/
Content-Type: application/json

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

Social Login

POST /api/v1/auth/social/google-oauth2/
Content-Type: application/json

{
  "access_token": "ya29.a0AfH6SMBx..."
}

Detaylı API dokümantasyonu için: AUTH.md

🏗️ Proje Yapısı

server/
├── accounts/               # Custom user app
│   ├── migrations/
│   ├── models.py          # CustomUser model
│   ├── serializers.py     # DRF serializers
│   ├── views.py           # Social login view
│   ├── admin.py           # Admin configuration
│   ├── pipeline.py        # Social auth pipeline
│   └── urls.py            # URL routing
├── core/                  # Project settings
│   ├── settings.py        # Main settings
│   ├── urls.py            # Root URL config
│   └── wsgi.py
├── templates/
│   └── email/             # Email templates
│       ├── activation_email.html
│       ├── activation_email.txt
│       ├── confirmation_email.html
│       ├── confirmation_email.txt
│       ├── password_reset_email.html
│       └── password_reset_email.txt
├── manage.py
├── req.txt                # Python dependencies
├── .env.example           # Environment variables template
├── AUTH.md                # API documentation
├── COPILOT_MEMORY.md      # Development log
└── README.md              # This file

🔧 Konfigürasyon

Social Auth Setup

Google OAuth2

1. Google Cloud Console → Create Project
2. APIs & Services → Credentials → Create OAuth 2.0 Client ID
3. Authorized redirect URIs: http://localhost:8000/api/v1/social/complete/google-oauth2/
4. .env dosyasına ekleyin:

SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=your-client-id
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=your-client-secret

GitHub OAuth

1. GitHub Settings → OAuth Apps → New OAuth App
2. Authorization callback URL: http://localhost:8000/api/v1/social/complete/github/
3. .env dosyasına ekleyin:

SOCIAL_AUTH_GITHUB_KEY=your-client-id
SOCIAL_AUTH_GITHUB_SECRET=your-client-secret

Facebook OAuth

1. Facebook Developers → Create App
2. Add Facebook Login product
3. Valid OAuth Redirect URIs: http://localhost:8000/api/v1/social/complete/facebook/
4. .env dosyasına ekleyin:

SOCIAL_AUTH_FACEBOOK_KEY=your-app-id
SOCIAL_AUTH_FACEBOOK_SECRET=your-app-secret

🧪 Testing

Manuel Test

# Register
curl -X POST http://localhost:8000/api/v1/auth/users/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestP@ss123","re_password":"TestP@ss123","first_name":"Test","last_name":"User"}'

# Check MailPit: http://localhost:8025

# Activate (uid ve token email'den alın)
curl -X POST http://localhost:8000/api/v1/auth/users/activation/ \
  -H "Content-Type: application/json" \
  -d '{"uid":"MQ","token":"c4h7vu-..."}'

# Login
curl -X POST http://localhost:8000/api/v1/auth/jwt/create/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestP@ss123"}'

Unit Tests (TODO)

python manage.py test accounts

📱 Frontend Entegrasyonu

Nuxt.js / Next.js

Detaylı entegrasyon örnekleri için AUTH.md dosyasına bakın.

Temel Flow:

1. Frontend'de register form → Backend'e POST
2. Kullanıcı email'ini kontrol eder
3. Aktivasyon linkine tıklar → Frontend yakalayıp backend'e POST
4. Login form → JWT tokens alınır
5. Tokens localStorage/cookie'de saklanır
6. Her request'te Authorization: Bearer <token> header'ı eklenir

🚀 Production Deployment

1. Environment Variables

DEBUG=False
SECRET_KEY=<strong-random-key>
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com

# PostgreSQL
DATABASE_URL=postgresql://user:pass@host:5432/dbname

# SMTP Email
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

# Social Auth Keys
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=...
SOCIAL_AUTH_GITHUB_KEY=...

2. Security Settings

settings.py içinde production için:

DEBUG = False
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000

3. Static Files

python manage.py collectstatic

4. Database Migration

python manage.py migrate

5. Gunicorn/uWSGI

gunicorn core.wsgi:application --bind 0.0.0.0:8000

📚 Dokümantasyon

• API Documentation: AUTH.md
• Cache Documentation: CACHE.md
• Development Log: COPILOT_MEMORY.md
• Djoser Docs: https://djoser.readthedocs.io/
• SimpleJWT Docs: https://django-rest-framework-simplejwt.readthedocs.io/
• Python Social Auth: https://python-social-auth.readthedocs.io/

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

👤 Author

Your Name - @yourhandle

🙏 Acknowledgments

• Django Team
• Django REST Framework
• Djoser
• Python Social Auth
• MailPit

---

Happy Coding! 🎉