first commit

belgeler/EMAIL_VERIFICATION.md

@@ -0,0 +1,236 @@
+# Email Doğrulama Sistemi
+
+## Genel Bakış
+
+AuthCentral'da kullanıcılar iki şekilde kayıt olabilir:
+
+1. **Email/Password ile Kayıt**: Email doğrulaması gerektirir
+2. **OAuth (Google/GitHub)**: Otomatik olarak doğrulanmış kabul edilir
+
+## Email/Password ile Kayıt Akışı
+
+### 1. Kullanıcı Kaydı
+```bash
+POST /v1/auth/register
+{
+  "username": "johndoe",
+  "email": "john@example.com",
+  "password": "securepass123"
+}
+```
+
+**Yanıt:**
+```json
+{
+  "message": "User created. Please verify your email.",
+  "user_id": "...",
+  "username": "johndoe",
+  "email": "john@example.com",
+  "email_verified": false,
+  "verification_token": "..."
+}
+```
+
+**Not:** Kullanıcı oluşturulur ancak `email_verified: false` olarak ayarlanır.
+
+### 2. Email Doğrulama
+
+Kullanıcıya otomatik olarak doğrulama email'i gönderilir. Email'deki linke tıklayarak doğrulama yapılır:
+
+```bash
+GET /v1/auth/verify-email?token=VERIFICATION_TOKEN
+```
+
+**Yanıt:**
+```json
+{
+  "message": "Email verified successfully"
+}
+```
+
+### 3. Login Denemesi (Email Doğrulanmadan)
+
+Email doğrulanmadan login yapılamaz:
+
+```bash
+POST /v1/auth/login
+{
+  "email": "john@example.com",
+  "password": "securepass123"
+}
+```
+
+**Hata Yanıtı:**
+```json
+{
+  "error": "email not verified"
+}
+```
+
+### 4. Login (Email Doğrulandıktan Sonra)
+
+Email doğrulandıktan sonra başarıyla login yapılabilir:
+
+```bash
+POST /v1/auth/login
+{
+  "email": "john@example.com",
+  "password": "securepass123"
+}
+```
+
+**Başarılı Yanıt:**
+```json
+{
+  "access_token": "...",
+  "refresh_token": "...",
+  "user_id": "...",
+  "username": "johndoe",
+  "email": "john@example.com",
+  "avatar": "",
+  "roles": [...]
+}
+```
+
+## OAuth (Google/GitHub) ile Kayıt
+
+OAuth sağlayıcıları email'i zaten doğruladığı için, bu kullanıcılar otomatik olarak `email_verified: true` olarak kaydedilir.
+
+```bash
+GET /v1/auth/google
+GET /v1/auth/github
+```
+
+OAuth callback'ten sonra kullanıcı otomatik olarak login edilir ve token'lar döndürülür.
+
+## Veritabanı Yapısı
+
+### Users Tablosu
+
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY,
+  user_name TEXT NOT NULL,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password TEXT,
+  avatar VARCHAR(500),
+  email_verified BOOLEAN DEFAULT false,
+  email_verify_token TEXT,
+  email_verified_at TIMESTAMP,
+  created_at TIMESTAMP,
+  updated_at TIMESTAMP,
+  deleted_at TIMESTAMP  -- Soft delete için
+);
+```
+
+### Email Verification Alanları
+
+- `email_verified`: Boolean - Email doğrulandı mı? (Email/password için false, OAuth için true)
+- `email_verify_token`: String - Doğrulama token'ı (email/password kayıt için)
+- `email_verified_at`: Timestamp - Email ne zaman doğrulandı?
+
+## Admin Kullanıcı Yönetimi
+
+### Kullanıcı Silme
+
+#### Soft Delete (Varsayılan)
+```bash
+DELETE /v1/admin/users/{user_id}
+```
+
+Kullanıcı `deleted_at` timestamp'i ile işaretlenir, veritabanından silinmez.
+
+#### Hard Delete (Kalıcı Silme)
+```bash
+DELETE /v1/admin/users/{user_id}?hard=true
+```
+
+Kullanıcı ve tüm ilişkili kayıtları (user_roles, social_accounts) kalıcı olarak silinir.
+
+**Not:** Kendi hesabınızı silemezsiniz.
+
+## Email Ayarları
+
+Email gönderimi için `.env` dosyasındaki ayarları yapılandırın:
+
+```env
+# Email Settings (Mailpit - Development)
+EMAIL_HOST=212.64.215.243
+EMAIL_PORT=1025
+EMAIL_HOST_USER=""
+EMAIL_HOST_PASSWORD=""
+EMAIL_USE_TLS=false
+EMAIL_USE_SSL=false
+EMAIL_FROM=noreply@gauth.local
+```
+
+## Güvenlik Notları
+
+1. **Verification Token**: 32 byte güvenli rastgele token oluşturulur
+2. **Token Süresi**: Şu anda token'ların süresi dolmuyor (ileride eklenebilir)
+3. **Rate Limiting**: Register endpoint'i için rate limit aktif
+4. **Password Hashing**: bcrypt kullanılarak güvenli şekilde hash'lenir
+
+## Geliştirme Notları
+
+### Migration
+
+Email verification özelliği sonradan eklendiği için, mevcut kullanıcılar otomatik olarak `email_verified: true` olarak işaretlenmiştir. Yeni kayıtlar `email_verified: false` ile başlar.
+
+Migration fonksiyonu `internal/database/db.go` dosyasında devre dışı bırakılmıştır.
+
+### Model Değişiklikleri
+
+User model'de `EmailVerified` alanı `*bool` (pointer) olarak tanımlanmıştır. Bu, GORM'un false değerlerini doğru şekilde işlemesini sağlar.
+
+```go
+type User struct {
+    // ...
+    EmailVerified    *bool      `gorm:"default:false" json:"email_verified"`
+    EmailVerifyToken string     `gorm:"index" json:"-"`
+    EmailVerifiedAt  *time.Time `json:"email_verified_at,omitempty"`
+    // ...
+}
+```
+
+## Test Senaryosu
+
+```bash
+# 1. Yeni kullanıcı kaydı
+curl -X POST http://localhost:8080/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "testuser",
+    "email": "test@example.com",
+    "password": "password123"
+  }'
+
+# 2. Email doğrulanmadan login dene (BAŞARISIZ)
+curl -X POST http://localhost:8080/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "password123"
+  }'
+# Yanıt: {"error": "email not verified"}
+
+# 3. Email'i doğrula
+curl -X GET "http://localhost:8080/v1/auth/verify-email?token=VERIFICATION_TOKEN"
+
+# 4. Login (BAŞARILI)
+curl -X POST http://localhost:8080/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "password123"
+  }'
+# Yanıt: access_token, refresh_token, user bilgileri
+```
+
+## Özet
+
+✅ Email/password ile kayıt olanlar email doğrulaması yapmalı
+✅ Email doğrulanmadan login yapılamaz
+✅ OAuth ile giriş yapanlar otomatik doğrulanmış kabul edilir
+✅ Soft delete varsayılan, hard delete `?hard=true` ile yapılır
+✅ Email doğrulama sistemi tam çalışır durumda