atahango/belgeler/QUICK_REFERENCE.md

# 🚀 GAuth-Central - Quick Reference

## 🏃 Hızlı Başlatma

```bash
# Standalone Mode (Mevcut PostgreSQL & Redis ile)
./start.sh

# Docker ile (Tüm servisler)
./start-with-docker.sh

# Manuel
go run main.go
```

## 🔗 Önemli URL'ler

| Servis | URL | Açıklama |
|--------|-----|----------|
| API | http://localhost:8080 | Ana API |
| Swagger | http://localhost:8080/docs/index.html | API Dokümantasyonu |
| PostgreSQL | localhost:5432 | Database |
| Redis | localhost:6379 | Cache |

## 📝 Temel Komutlar

```bash
# Docker Servisleri
docker-compose up -d              # Başlat
docker-compose down               # Durdur
docker-compose down -v            # Durdur + Volume'ları sil
docker-compose logs -f app        # Logları izle
docker-compose ps                 # Servis durumları

# Go Komutları
go run main.go                    # Çalıştır
go build -o main .                # Derle
go mod tidy                       # Bağımlılıkları temizle
swag init -g main.go             # Swagger güncelle

# Redis Komutları
docker exec -it gauth_redis redis-cli
> PING                            # Bağlantı testi
> KEYS *                          # Tüm key'leri listele
> GET user:UUID                   # User cache getir
> DEL session:TOKEN               # Session sil
> FLUSHDB                         # Tüm cache'i temizle

# PostgreSQL Komutları
docker exec -it gauth_postgres psql -U postgres -d gauth
\dt                              # Tabloları listele
\d users                         # Users tablosu yapısı
SELECT * FROM roles;             # Rolleri listele
SELECT * FROM users LIMIT 10;   # Kullanıcıları listele
```

## 🔧 Environment Variables

| Değişken | Varsayılan | Açıklama |
|----------|------------|----------|
| `PORT` | 8080 | Server portu |
| `DB_URL` | - | PostgreSQL bağlantısı |
| `REDIS_URL` | - | Redis bağlantısı |
| `JWT_SECRET` | - | JWT gizli anahtar |
| `GOOGLE_CLIENT_ID` | - | Google OAuth |
| `GITHUB_CLIENT_ID` | - | GitHub OAuth |

## 📡 API Endpoints

### Public Endpoints

```bash
# Register
POST /v1/auth/register
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "user_name": "username"
}

# Login
POST /v1/auth/login
{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

# OAuth
GET /v1/auth/google
GET /v1/auth/github

# Verify Email
GET /v1/auth/verify-email?token=...

# Refresh Token
POST /v1/auth/refresh
{
  "refresh_token": "..."
}
```

### Protected Endpoints (Requires Authorization Header)

```bash
# Get User Info
GET /v1/auth/me
Authorization: Bearer <token>

# Validate Token
GET /v1/auth/validate
Authorization: Bearer <token>
```

## 🛡️ Rate Limits

| Endpoint | Limit | Süre |
|----------|-------|------|
| `/v1/auth/login` | 5 | 1 dakika |
| `/v1/auth/register` | 3 | 5 dakika |
| Genel API | 100 | 1 dakika |

## 🗄️ Redis Keys

| Pattern | Açıklama | TTL |
|---------|----------|-----|
| `user:{id}` | User cache | 1 saat |
| `session:{token}` | Session data | 24 saat |
| `blacklist:{token}` | Invalidated tokens | 24 saat |
| `ratelimit:{key}` | Rate limit counters | Dinamik |
| `email_verify:{email}` | Email verification | Dinamik |
| `password_reset:{email}` | Password reset | Dinamik |

## 🧪 Test Komutları

```bash
# Health Check
curl http://localhost:8080/

# Register Test
curl -X POST http://localhost:8080/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"Test123!","user_name":"testuser"}'

# Login Test
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"Test123!"}'

# Get User Info (with token)
curl http://localhost:8080/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

## 🐛 Sorun Giderme

```bash
# Servis durumlarını kontrol et
docker-compose ps

# App loglarını kontrol et
docker-compose logs app

# Redis bağlantısı
docker exec -it gauth_redis redis-cli PING

# PostgreSQL bağlantısı
docker exec -it gauth_postgres pg_isready -U postgres

# Container'ı yeniden başlat
docker-compose restart app

# Tüm servisleri yeniden oluştur
docker-compose down
docker-compose up -d --build
```

## 📊 Database Schema

```sql
-- Users Table
users (
  id UUID PRIMARY KEY,
  email VARCHAR UNIQUE,
  user_name VARCHAR NOT NULL,
  password_hash VARCHAR,
  email_verified BOOLEAN,
  email_verify_token VARCHAR,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

-- Roles Table
roles (
  id UUID PRIMARY KEY,
  name VARCHAR UNIQUE,
  description TEXT
)

-- Permissions Table
permissions (
  id UUID PRIMARY KEY,
  name VARCHAR UNIQUE,
  description TEXT
)
```

## 🔐 CORS Yapılandırması

Varsayılan: `http://localhost:3000`

Değiştirmek için `main.go`:
```go
AllowOrigins: []string{
  "http://localhost:3000",
  "https://yourdomain.com",
}
```

## 📚 Cache Service Örnekleri

```go
import "gauth-central/internal/services"

cache := services.NewCacheService()

// User caching
cache.SetUser(userID, user, 1*time.Hour)
user, err := cache.GetUser(userID)

// Session
cache.SetSession(token, userID, 24*time.Hour)
userID, err := cache.GetSession(token)

// Rate limiting
count, err := cache.IncrementRateLimit("login:"+ip, 1*time.Minute)
if count > 5 {
  // Rate limit exceeded
}

// Token blacklist
cache.BlacklistToken(token, 24*time.Hour)
isBlacklisted, err := cache.IsTokenBlacklisted(token)
```

## 🎯 Önemli Dosyalar

| Dosya | Açıklama |
|-------|----------|
| `main.go` | Ana uygulama |
| `config/config.go` | Yapılandırma |
| `internal/database/redis.go` | Redis bağlantısı |
| `internal/services/cache_service.go` | Cache servisi |
| `api/routes/routes.go` | Route tanımları |
| `api/middlewares/rate_limit_middleware.go` | Rate limiting |
| `docker-compose.yml` | Docker yapılandırması |
| `.env` | Environment variables |

## 📖 Dokümantasyon

- `README.md` - Genel proje bilgisi
- `SETUP.md` - Detaylı kurulum rehberi
- `CHANGELOG.md` - Versiyon geçmişi
- `QUICK_REFERENCE.md` - Bu dosya

---

💡 **İpucu**: Swagger UI'da tüm endpoint'leri test edebilirsiniz: http://localhost:8080/docs/index.html