AI Prompt

Kıdemli bir yazılım mühendisi gibi davran. Aşağıdaki gereksinimlerle Bi'öğrenci entegrasyonunu, üretime uygun (prod-grade) şekilde tasarla ve kodla.

ÖNEMLİ KURAL:
- Endpoint, method ve alan isimlerini değiştirme; yeni endpoint uydurma.
- Eksik bilgi varsa makul varsayım yap, ama varsayımları net bir "Varsayımlar" başlığında yaz.
- Cevabın Türkçe olsun.

PROJE BAĞLAMI (ben dolduracağım):
- Tech Stack: [örn: Laravel 11 + Blade + Alpine / Node.js + Express + React / Next.js]
- Çalışma tipi: [Monolith / API + SPA]
- Paket yöneticisi: [npm/pnpm/yarn/composer]
- Veritabanı: [MySQL/PostgreSQL vb.]
- Ortam değişkenleri dosyası: [örn: .env]
- Kullanıcı oturum modeli: [session/jwt]

HEDEF ÖZELLİKLER:
1) Bi'öğrenci ile Giriş Yap (OAuth Login)
2) Kendi platformunda fırsatları listeleme (Partner API)
3) Fırsattan yararlanma / kod alma (Claim)

BI'ÖĞRENCİ API BİLGİLERİ (SABİT):
- Authorization Endpoint: https://biogrenci.com/oauth/authorize
- Token Endpoint: https://biogrenci.com/api/oauth/token (POST)
- UserInfo Endpoint: https://biogrenci.com/api/oauth/userinfo (GET)
- Opportunities List Endpoint: https://biogrenci.com/api/partner/opportunities (GET, token zorunlu değil)
- Opportunity Claim Endpoint: https://biogrenci.com/api/partner/opportunities/{id}/claim (POST, token zorunlu)

SCOPE'LAR:
- minimum: openid profile email opportunities.read
- opsiyonel: student_status education

OAUTH DETAYI:
- response_type=code zorunlu.
- state doğrulaması zorunlu (CSRF koruması).
- PKCE desteği var:
  - Public client (SPA/mobile) ise PKCE zorunlu.
  - Confidential client (server-side) ise client_secret ile standart authorization_code akışı.
- Token yenileme: grant_type=refresh_token (refresh token rotation olduğunu dikkate al).

UYGULAMA DAVRANIŞI:
1. Fırsatları Listeleme
- GET /api/partner/opportunities çağrısı ile herkese açık listeleme yap.
- Filtre/query desteği: category_id, brand_id, type, search, sort, page, per_page
- Pagination response'unda data + links + meta alanlarını UI ve API response'una doğru yansıt.

2. Claim Akışı
- Kullanıcı claim'e basınca:
  - Login yoksa OAuth authorize'a yönlendir.
  - Login varsa token geçerliliğini kontrol et; expired ise refresh dene.
  - Sonra POST /api/partner/opportunities/{id}/claim çağır.
- Claim response'una göre UI davranışı:
  - type=kupon: coupon_code göster, kopyalama aksiyonu, expires_at göster, varsa redirect_url butonu.
  - type=qr: qr_code (SVG) güvenli render et, coupon_code metin olarak da göster.
  - type=affiliate veya type=api: redirect_url ile "Fırsata Git" butonu göster.

3. Hata Yönetimi
- Aşağıdaki kodları kullanıcı dostu mesaja çevir:
  - unauthenticated
  - insufficient_scope
  - COUPONS_DEPLETED
  - OPPORTUNITY_EXPIRED
  - USER_USAGE_LIMIT_REACHED
  - student_verification_required
  - too_many_requests (Retry-After dikkate al)
- OAuth callback hata parametrelerini de işle: error, error_description.

GÜVENLİK VE KALİTE GEREKSİNİMLERİ:
- Secret bilgileri yalnızca environment variable'dan oku.
- Access/refresh token'ları güvenli sakla (sunucuda şifreli/korumalı).
- redirect_uri whitelist kontrolü ve sabit config kullan.
- SSRF/open redirect/XSS risklerine karşı önlem al.
- Claim işlemini idempotent UX ile yönet (çift tıklamada duplicate request engeli).
- Loglama yap ama token/secret asla loglama.

İSTEDİĞİM ÇIKTI FORMATI (TEK CEVAPTA):
1) Kısa Mimari Özeti
2) Dosya/klasör planı (hangi dosyaya ne eklenecek)
3) Ortam değişkenleri listesi (.env.example formatında)
4) Route tanımları
5) Controller/Service kodları
6) OAuth yönlendirme + callback + token refresh akışı
7) Opportunities listeleme kodu
8) Claim kodu (type bazlı response handling dahil)
9) Frontend/UI örneği (liste + claim modal/alanı)
10) Hata mesajı eşleme tablosu
11) Testler:
   - unit test (service seviyesinde)
   - integration test (oauth callback + claim)
   - en az 1 e2e senaryosu
12) Çalıştırma adımları (komutlar)
13) Kabul kriterleri checklist'i

KABUL KRİTERLERİ:
- Login olmadan fırsatlar listelenebilmeli.
- Login + opportunities.read scope ile claim başarılı olmalı.
- type=kupon/qr/affiliate(api) için doğru UI akışı çalışmalı.
- Expired token durumunda refresh ile akış devam etmeli.
- Yukarıdaki hata kodları doğru mesajlanmalı.

ÖRNEK AUTHORIZE URL:
https://biogrenci.com/oauth/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope=openid profile email opportunities.read&state={RANDOM_STATE}

ÖRNEK TOKEN İSTEĞİ (authorization_code):
POST https://biogrenci.com/api/oauth/token
{
  "grant_type": "authorization_code",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "redirect_uri": "{REDIRECT_URI}",
  "code": "{CODE}"
}

ÖRNEK TOKEN YENİLEME:
POST https://biogrenci.com/api/oauth/token
{
  "grant_type": "refresh_token",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "refresh_token": "{REFRESH_TOKEN}"
}

ÖRNEK CLAIM HATA YANITI:
{
  "success": false,
  "message": "Bu fırsatın kuponları tükenmiş.",
  "error": "COUPONS_DEPLETED"
}