nodebb-plugin-pdf-secure 1.2.25 → 1.2.27

package/PRD (2).md

@@ -0,0 +1,844 @@
+# PRD: IEU Forum Çok Katmanlı Premium Abonelik Sistemi
+
+## 1. Bağlam (Context)
+
+### Amaç
+
+Sistemi 3 kademeli abonelik planına (Lite, Premium, VIP), aylık + yıllık ödeme seçeneklerine, plan yükseltme mekanizmasına, ve gelişmiş admin paneline dönüştürmek.
+
+---
+
+## 2. Abonelik Planları
+
+### 2.1 Plan Tanımları
+
+| Plan                     | Aylık | Yıllık (8 ay bedava) | NodeBB Grubu | Seviye |
+| ------------------------ | ----- | -------------------- | ------------ | ------ |
+| **Lite**                 | 119₺  | 476₺                 | `lite`       | 1      |
+| **Premium** (En Popüler) | 139₺  | 556₺                 | `premium`    | 2      |
+| **VIP** (Elit)           | 159₺  | 636₺                 | `vip`        | 3      |
+
+### 2.2 Plan Özellikleri
+
+**Lite (Seviye 1)**
+
+- Tüm çalışma sorularına sınırsız erişim
+- En güncel ders notları arşivi
+
+**Premium (Seviye 2) — Lite + ekstralar**
+
+- Gelişmiş PDF önizleme ve araçları
+- Akıllı CV Oluşturucu
+- Hedef odaklı GPA Hesaplayıcı
+- Sıfır Reklam (reklamsız arayüz)
+- Niki Wallet: %30 indirimli kahve hediye
+- Sosyal Analitik: Profil ve konu görüntüleyenleri görme
+
+**VIP (Seviye 3) — Premium + ekstralar**
+
+- Prestij: Profilde özel VIP Badge
+- Öncülük: Yeni özelliklere erken erişim
+
+### 2.3 Ödeme Periyotları
+
+- **Aylık**: Standart fiyat, 30 günlük süre
+- **Yıllık**: 8 ay bedava (4 aylık ödemeyle 12 ay kullanım), 365 günlük süre
+
+---
+
+## 3. İş Kuralları
+
+### 3.1 Plan Yükseltme (Upgrade)
+
+- Kullanıcı sadece **üst plana** geçebilir (Lite → Premium, Lite → VIP, Premium → VIP)
+- **Prorated fark ücreti**: Kalan günlerin fiyat farkı hesaplanır
+  - Formül: `fark = (yeniPlanFiyat - eskiPlanFiyat) / toplamGün * kalanGün`
+  - Örnek: Lite'tan Premium'a, 15 gün kala: `(139-119)/30*15 = 10₺`
+- Yükseltme sonrası bitiş tarihi değişmez, sadece plan seviyesi ve grup değişir
+- Yıllık abonelikte de aynı prorated mantık geçerli
+
+### 3.2 Downgrade
+
+- **Desteklenmiyor**. Kullanıcı alt plana geçemez
+- Alt plan isteyen kullanıcı mevcut aboneliği iptal edip süre bittikten sonra yeni plan satın almalı
+
+### 3.3 Abonelik Süresi Dolduğunda
+
+- Mevcut cron job (10dk) kontrol eder
+- Kullanıcı ilgili NodeBB grubundan çıkarılır
+- Subscription status "expired" olarak işaretlenir
+
+### 3.4 Yenileme
+
+- **Otomatik yenileme varsayılan olarak açık** gelir (checkbox tikli)
+- Kullanıcı istemezse satın alma sırasında tiki kaldırarak kapatabilir
+- Otomatik yenileme tercihi subscription kaydında `autoRenew: true/false` olarak saklanır
+- Abonelik süresi dolmadan önce (ör. 1 gün kala) cron job otomatik yenileme yapılacak abonelikleri tespit eder
+- Otomatik yenileme açık olan kullanıcılar için aynı plan + period ile yeni ödeme talebi oluşturulur (PayTR tekrarlayan ödeme veya kayıtlı kart ile)
+- Otomatik yenileme kapalıysa: kullanıcı manuel olarak tekrar ödeme yaparak süre uzatır
+- Aynı plan ile uzatma: mevcut bitiş tarihine süre eklenir
+
+### 3.5 Kullanıcı Abonelik İptali — IP Kısıtlamalı Endpoint
+
+NodeBB tarafında **herhangi bir plugin yazılmaz** ve geçici grup mekanizması kullanılmaz. Bunun yerine ödeme servisinde **sadece NodeBB sunucusunun IP adresinden gelen istekleri kabul eden** bir endpoint bulunur. NodeBB tarafında navigasyon menüsüne eklenen bir link ile kullanıcı bu endpoint'e yönlendirilir.
+
+#### Mekanizma
+
+- Ödeme servisinde `POST /pay/api/cancel-subscription` endpoint'i oluşturulur
+- Bu endpoint **sadece** izin verilen IP adresinden gelen istekleri kabul eder (NodeBB sunucusunun IP'si)
+- İzin verilen IP adresi admin panelden **Ayarlar** sayfasından değiştirilebilir (veritabanında `Setting` modelinde saklanır)
+- Varsayılan değer `ALLOWED_CANCEL_IP` environment değişkeninden okunur; admin panelden güncelleme yapıldığında veritabanındaki değer önceliklidir
+- NodeBB tarafında navigasyon menüsüne "Aboneliği İptal Et" linki eklenir; bu link kullanıcıyı ödeme servisindeki iptal sayfasına yönlendirir
+- Kullanıcı iptal sayfasında onay vererek aboneliğinin otomatik yenilenmesini kapatır
+
+#### İptal Akışı
+
+```
+1. Kullanıcı NodeBB'de navigasyon menüsünden "Aboneliği İptal Et" linkine tıklar
+   → /pay/cancel?uid={uid} sayfası açılır (ödeme servisi)
+2. Sayfa, kullanıcının aktif abonelik bilgilerini gösterir
+3. Kullanıcı "Otomatik Yenilemeyi İptal Et" butonuna tıklar
+4. Frontend, POST /pay/api/cancel-subscription isteği gönderir (uid parametresiyle)
+5. Endpoint IP kontrolü yapar:
+   - İstek NodeBB sunucu IP'sinden gelmiyorsa → 403 Forbidden
+   - İstek doğru IP'den geliyorsa → devam et
+6. Aktif abonelik bulunur:
+   - autoRenew = false olarak güncellenir
+   - cancelRequestedAt = now kaydedilir
+7. Kullanıcıya onay sayfası gösterilir:
+   "Otomatik yenileme iptal edildi. Aboneliğiniz {bitiş tarihi} tarihine kadar aktif kalacaktır."
+8. Abonelik mevcut dönem sonuna kadar aktif kalır
+9. Dönem dolduğunda mevcut cron job (10 dk) normal şekilde plan grubundan çıkarır ve expired işaretler
+```
+
+#### Neden Bu Yaklaşım Güvenli?
+
+- Endpoint **sadece** NodeBB sunucusunun IP adresinden gelen istekleri kabul eder
+- Kullanıcı NodeBB'ye giriş yapmadan bu sayfaya erişemez (NodeBB'nin kendi auth sistemi link'i gösterir)
+- Dış dünyadan (farklı IP'lerden) gelen istekler reddedilir
+- Cron job veya geçici grup mekanizmasına gerek yoktur — istek anında işlenir
+- Cross-service auth, HMAC, OTP gibi ek mekanizmalara ihtiyaç yok
+
+#### Kullanıcıya Bilgilendirme
+
+- İptal sayfasında şu bilgiler gösterilir:
+  > "Otomatik yenilemeyi iptal ettiğinizde mevcut abonelik süreniz sonuna kadar erişiminiz devam edecektir. Süre sonunda aboneliğiniz yenilenmeyecektir."
+- İptal işlendikten sonra onay mesajı:
+  > "Otomatik yenileme iptal edildi. Aboneliğiniz {bitiş tarihi} tarihine kadar aktif kalacaktır."
+
+#### Kullanıcı Fikir Değiştirirse
+
+- İptal sadece otomatik yenilemeyi kapatır, mevcut dönem erişimi devam eder
+- Kullanıcı forumdan yeniden `/pay/checkout?uid={uid}` üzerinden aynı planı satın alarak devam edebilir
+- Veya admin panelden otomatik yenileme tekrar açılabilir
+
+### 3.6 NodeBB Grup Yönetimi
+
+- Her plan için ayrı NodeBB grubu: `lite`, `premium`, `vip`
+- Kullanıcı **sadece** aktif planının grubunda olur
+- Plan yükseltmede: eski gruptan çıkar, yeni gruba ekle
+- Süre dolduğunda: gruptan çıkar
+
+### 3.7 Admin Paneli — Tam Yetki
+
+Admin paneli NodeBB foruma bağlıdır ve admin aşağıdaki tüm işlemleri yapabilir:
+
+#### Kullanıcı Doğrulama
+
+- Admin, UID veya kullanıcı adı girerek işlem yapar
+- Girilen bilgi NodeBB API üzerinden doğrulanır; kullanıcı bulunamazsa hata gösterilir
+- Doğrulanan kullanıcının profil bilgileri (avatar, username, email, kayıt tarihi) gösterilir
+
+#### Manuel Plan Atama
+
+- Admin herhangi bir kullanıcıya herhangi bir plan (Lite / Premium / VIP) atayabilir
+- Manuel atama PayTR ödemesi gerektirmez
+- Süre admin tarafından belirlenir (1 ay / 3 ay / 6 ay / 12 ay / özel tarih, varsayılan: 30 gün)
+- Period admin tarafından seçilir (aylık / yıllık)
+- Atama sonrası NodeBB'de ilgili gruba eklenir (eski grup varsa çıkarılır)
+- Subscription kaydı `source: "admin"` ve `adminAssignedBy` ile oluşturulur
+
+#### Manuel Plan Değiştirme (Upgrade & Downgrade)
+
+- Admin, kullanıcının mevcut planını **herhangi bir plana** değiştirebilir (hem yükseltme hem düşürme)
+- Downgrade dahil — normal kullanıcılar yapamaz ama admin yapabilir
+- Plan değiştirildiğinde: eski NodeBB grubundan çıkarılır, yeni gruba eklenir
+- Bitiş tarihi korunur (admin isterse bitiş tarihini de değiştirebilir)
+- `previousPlan` kaydedilir, `source: "admin"` olarak işaretlenir
+
+#### Abonelik İptali
+
+- Admin, aktif bir aboneliği anında iptal edebilir
+- İptal sonrası: kullanıcı NodeBB grubundan çıkarılır, status "cancelled" olarak işaretlenir
+- İptal nedeni opsiyonel olarak kaydedilebilir (`cancelReason`)
+
+#### Süre Düzenleme
+
+- Admin, mevcut aboneliğin bitiş tarihini ileri veya geri alabilir
+- Süre uzatma veya kısaltma serbesttir
+
+#### Kullanıcı Detay Sayfası
+
+- Tek kullanıcıya ait tüm abonelik geçmişi (aktif + geçmiş) listelenir
+- Mevcut plan, period, başlangıç/bitiş tarihi, kaynak (ödeme/admin/upgrade), otomatik yenileme durumu
+- Üzerinden doğrudan plan değiştirme, iptal, süre düzenleme işlemleri yapılabilir
+- NodeBB'deki grup üyeliği durumu gösterilir
+
+---
+
+## 4. Teknik Tasarım
+
+### 4.1 Veritabanı Modeli Değişiklikleri
+
+**Subscription Model** (`src/models/subscription.model.js`) — güncellenecek alanlar:
+
+```javascript
+{
+  // Mevcut alanlar (korunacak)
+  uid, username, status, startedAt, expiresAt, premiumRevokedAt,
+  billingInfo, paytrMerchantOid, paytrRaw,
+
+  // YENİ ALANLAR
+  plan: {
+    type: String,
+    enum: ["lite", "premium", "vip"],
+    required: true,
+    index: true
+  },
+  period: {
+    type: String,
+    enum: ["monthly", "yearly"],
+    default: "monthly"
+  },
+  amount: {
+    type: Number,  // kuruş cinsinden ödenen tutar
+    required: true
+  },
+  source: {
+    type: String,
+    enum: ["payment", "admin", "upgrade"],
+    default: "payment"
+  },
+  previousPlan: {
+    type: String,
+    enum: ["lite", "premium", "vip", null],
+    default: null
+  },
+  autoRenew: {
+    type: Boolean,
+    default: true  // varsayılan olarak açık
+  },
+  adminAssignedBy: {
+    type: String,  // admin username (null if not admin-assigned)
+    default: null
+  },
+  cancelReason: {
+    type: String,  // admin tarafından iptal edildiğinde sebep (opsiyonel)
+    default: null
+  }
+}
+```
+
+**Yeni Model: Setting** (`src/models/setting.model.js`) — admin panelden yönetilebilen ayarlar:
+
+```javascript
+{
+  key: {
+    type: String,
+    required: true,
+    unique: true,
+    index: true
+  },
+  value: {
+    type: String,
+    required: true
+  },
+  updatedBy: {
+    type: String, // admin username
+    default: null
+  },
+  updatedAt: {
+    type: Date,
+    default: Date.now
+  }
+}
+```
+
+Önceden tanımlı ayar anahtarları:
+- `allowedCancelIp` — Abonelik iptali endpoint'inin kabul ettiği IP adresi. Boş veya kayıt yoksa `ALLOWED_CANCEL_IP` env değişkenine fallback yapılır.
+
+**Yeni Model: Plan Config** (`src/models/plan.model.js`) — plan tanımları için (opsiyonel, config dosyasında da tutulabilir):
+
+Plan tanımları `src/config/plans.js` config dosyasında tutulacak (veritabanında değil):
+
+```javascript
+const PLANS = {
+  lite: {
+    name: "Lite",
+    slug: "lite",
+    level: 1,
+    monthlyPrice: 11900, // kuruş
+    yearlyPrice: 47600, // kuruş (8 ay bedava)
+    nodebbGroup: "lite",
+    features: ["Tüm çalışma sorularına sınırsız erişim", "En güncel ders notları arşivi"],
+  },
+  premium: {
+    name: "Premium",
+    slug: "premium",
+    level: 2,
+    monthlyPrice: 13900,
+    yearlyPrice: 55600,
+    nodebbGroup: "premium",
+    badge: "En Popüler",
+    features: ["Lite planındaki her şey", "Gelişmiş PDF önizleme ve araçları", "Akıllı CV Oluşturucu", "Hedef odaklı GPA Hesaplayıcı", "Sıfır Reklam", "Niki Wallet: %30 indirimli kahve hediye", "Sosyal Analitik"],
+  },
+  vip: {
+    name: "VIP",
+    slug: "vip",
+    level: 3,
+    monthlyPrice: 15900,
+    yearlyPrice: 63600,
+    nodebbGroup: "vip",
+    badge: "Elit Deneyim",
+    features: ["Premium'daki her şey", "Prestij: Profilde özel VIP Badge", "Öncülük: Yeni özelliklere erken erişim"],
+  },
+};
+```
+
+### 4.2 Değiştirilecek Dosyalar
+
+| Dosya                                   | Değişiklik                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `src/models/subscription.model.js`      | plan, period, amount, source, previousPlan, adminAssignedBy alanları eklenir    |
+| `src/config/plans.js`                   | **YENİ** — Plan tanımları ve fiyatlandırma                                      |
+| `src/config/env.js`                     | Yeni NodeBB grup env değişkenleri (veya plans.js'den okunur)                    |
+| `src/services/paytr.service.js`         | Dinamik fiyat ve ürün adı desteği (plan + period parametreleri)                 |
+| `src/services/nodebb.service.js`        | Çoklu grup desteği: addToGroup(uid, groupName), removeFromGroup(uid, groupName) |
+| `src/services/subscription.service.js`  | createOrExtend → plan-aware, upgrade hesaplaması, admin atama                   |
+| `src/services/admin.service.js`         | Plan bazlı istatistikler, manuel atama servisi, gelir hesabı güncelleme         |
+| `src/controllers/payment.controller.js` | Plan seçimi ve period akışı, upgrade flow                                       |
+| `src/controllers/admin.controller.js`   | Manuel plan atama endpoint'i, gelişmiş dashboard                                |
+| `src/routes/payment.routes.js`          | Yeni route'lar (plan seçim, upgrade)                                            |
+| `src/routes/admin.routes.js`            | Manuel atama route'ları                                                         |
+| `src/jobs/subscriptionWatcher.job.js`   | Plan-aware grup çıkarma                                                         |
+| `src/views/home.ejs`                    | 3 kart plan seçim UI, aylık/yıllık toggle                                       |
+| `src/views/billing-form.ejs`            | Plan ve period bilgisi taşıma                                                   |
+| `src/views/payment.ejs`                 | Seçilen plan bilgisi gösterme                                                   |
+| `src/views/result.ejs`                  | Plan adı gösterme                                                               |
+| `src/models/setting.model.js`           | **YENİ** — Ayarlar modeli (key-value, admin panelden yönetilen yapılandırmalar) |
+| `src/middleware/ipRestrict.js`          | **YENİ** — IP kısıtlama middleware'i (DB'den veya env'den IP okur)              |
+| `src/views/cancel.ejs`                  | **YENİ** — Kullanıcı iptal sayfası (abonelik bilgileri + iptal butonu)          |
+| `src/views/admin/dashboard.ejs`         | Plan bazlı istatistikler, gelişmiş grafikler                                    |
+| `src/views/admin/subscribers.ejs`       | Plan filtresi, manuel atama butonu                                              |
+| `src/views/admin/assign.ejs`            | **YENİ** — Admin kullanıcı arama + manuel plan atama formu                      |
+| `src/views/admin/subscriber-detail.ejs` | **YENİ** — Tek kullanıcı detay sayfası (plan değiştir, iptal, süre düzenle)     |
+| `src/views/admin/settings.ejs`          | **YENİ** — Ayarlar sayfası (IP adresi vb. yapılandırmalar)                      |
+| `.env.example`                          | Yeni env değişkenleri                                                           |
+
+### 4.3 API Endpoint'leri
+
+#### Mevcut Route'lar (Güncelleme)
+
+- `GET /pay/checkout?uid={uid}` → Plan seçim sayfası (3 kart + aylık/yıllık toggle)
+- `GET /pay/checkout/billing?uid={uid}&plan={slug}&period={monthly|yearly}` → Fatura formu
+- `POST /pay/checkout/billing` → Form işleme (plan + period eklenir)
+- `GET /pay/checkout/start?uid={uid}&plan={slug}&period={monthly|yearly}&...` → PayTR başlat
+- `POST /pay/checkout/callback` → PayTR callback (plan bilgisi merchantOid'den parse)
+- `GET /pay/checkout/result` → Sonuç sayfası
+
+#### Yeni Route'lar
+
+- `GET /pay/checkout/upgrade?uid={uid}&plan={slug}` → Upgrade sayfası (fark ücreti göster)
+- `POST /pay/checkout/upgrade` → Upgrade işlemi başlat → PayTR'ye yönlendir
+- `GET /pay/cancel?uid={uid}` → İptal sayfası (abonelik bilgileri + iptal butonu)
+- `POST /pay/api/cancel-subscription` → IP kısıtlamalı iptal endpoint'i (sadece NodeBB sunucu IP'sinden)
+
+#### Admin Route'ları (Güncelleme + Yeni)
+
+- `GET /pay/admin` → Gelişmiş dashboard (plan bazlı breakdown)
+- `GET /pay/admin/subscribers` → Plan filtresiyle liste
+- `GET /pay/admin/subscriber/:uid` → **YENİ** Tek kullanıcı detay sayfası (abonelik geçmişi + işlemler)
+- `GET /pay/admin/assign` → **YENİ** Manuel plan atama formu (UID/username ile kullanıcı arama)
+- `POST /pay/admin/assign` → **YENİ** Manuel plan atama işlemi
+- `POST /pay/admin/change-plan` → **YENİ** Plan değiştirme (upgrade/downgrade)
+- `POST /pay/admin/cancel` → **YENİ** Abonelik iptal etme
+- `POST /pay/admin/extend` → **YENİ** Süre düzenleme (uzatma/kısaltma)
+- `GET /pay/admin/lookup?q={uid|username}` → **YENİ** NodeBB kullanıcı arama (AJAX)
+- `GET /pay/admin/settings` → **YENİ** Ayarlar sayfası (IP adresi vb. yapılandırmalar)
+- `POST /pay/admin/settings` → **YENİ** Ayarları kaydet
+
+### 4.4 Ödeme Akışı (Güncel)
+
+```
+1. Kullanıcı → /pay/checkout?uid=123
+2. Plan seçim sayfası gösterilir (3 kart + aylık/yıllık toggle)
+   - Aktif aboneliği varsa: mevcut plan gösterilir + sadece üst planlar seçilebilir (upgrade)
+   - Aktif aboneliği yoksa: tüm planlar seçilebilir
+3. Kullanıcı plan + period seçer → "Satın Al" butonuna tıklar
+4. Billing form → Plan ve period bilgisi hidden field'larda taşınır
+5. PayTR'ye gönderilir:
+   - merchantOid formatı: {uid}x{planSlug}x{period}x{timestamp}
+   - Tutar: plans.js'den ilgili fiyat
+   - Basket: Plan adı + period
+6. PayTR callback gelir → merchantOid parse edilir → plan + period çıkarılır
+7. NodeBB'de ilgili gruba eklenir (eski grup varsa önce çıkarılır)
+8. Subscription kaydı oluşturulur (plan, period, amount bilgileriyle)
+```
+
+### 4.5 Upgrade Akışı
+
+```
+1. Kullanıcı → /pay/checkout?uid=123 (aktif aboneliği var)
+2. Mevcut planı gösterilir, üst planların "Yükselt" butonu aktif
+3. "Yükselt" → /pay/checkout/upgrade?uid=123&plan=premium
+4. Prorated fark ücreti hesaplanıp gösterilir:
+   - kalanGün = (expiresAt - now) / (1000*60*60*24)
+   - eskiGünlükFiyat = eskiPlan.fiyat / toplamGün
+   - yeniGünlükFiyat = yeniPlan.fiyat / toplamGün
+   - fark = (yeniGünlükFiyat - eskiGünlükFiyat) * kalanGün
+   - Minimum fark: 1₺ (100 kuruş)
+5. Kullanıcı onaylar → Billing form → PayTR (fark ücreti kadar)
+6. Callback → Eski gruptan çıkar, yeni gruba ekle
+7. Subscription güncelle: plan değişir, expiresAt aynı kalır, previousPlan kaydedilir
+```
+
+### 4.6 Admin Paneli Güncellemeleri
+
+#### Dashboard İstatistikleri
+
+- **Toplam Gelir**: Plan ve period bazlı breakdown
+- **Aktif Aboneler**: Plan bazlı dağılım (pasta grafik veya bar)
+- **Plan Dağılımı**: Lite vs Premium vs VIP oranları
+- **Aylık vs Yıllık**: Period dağılımı
+- **Bu Ay Gelir**: Plan bazlı
+- **Son Abonelikler**: Plan bilgisiyle birlikte
+- **Aylık Gelir Grafiği**: Plan bazlı stacked bar chart
+
+#### Kullanıcı Arama & Atama Sayfası (`assign.ejs`)
+
+- UID veya kullanıcı adı giriş alanı
+- "Ara" butonuna basıldığında NodeBB API'den kullanıcı doğrulanır (AJAX ile `/pay/admin/lookup`)
+- Kullanıcı bulunamazsa hata mesajı gösterilir
+- Bulunursa: avatar, username, email, kayıt tarihi ve mevcut abonelik durumu gösterilir
+- Plan seçimi (Lite / Premium / VIP)
+- Period seçimi (Aylık / Yıllık)
+- Süre seçimi (1 ay / 3 ay / 6 ay / 12 ay / özel tarih)
+- "Ata" butonuna basıldığında:
+  - Subscription kaydı oluşturulur (source: "admin", adminAssignedBy kaydedilir)
+  - NodeBB grubuna eklenir (eski grup varsa çıkarılır)
+
+#### Ayarlar Sayfası (`settings.ejs`) — YENİ
+
+- Admin panelde **Ayarlar** menü öğesi eklenir
+- Ayarlar sayfasında sistem genelindeki yapılandırmalar yönetilir:
+  - **İptal IP Adresi**: Abonelik iptali endpoint'inin kabul ettiği IP adresi (NodeBB sunucu IP'si)
+    - Mevcut IP gösterilir
+    - Yeni IP girilerek güncellenebilir
+    - Boş bırakılırsa `ALLOWED_CANCEL_IP` env değişkenine fallback yapılır
+- Ayarlar veritabanında `Setting` modelinde key-value olarak saklanır
+
+#### Kullanıcı Detay Sayfası (`subscriber-detail.ejs`)
+
+- NodeBB'den çekilen profil bilgileri (avatar, username, email, uid)
+- Mevcut aktif abonelik bilgisi (plan, period, başlangıç/bitiş, kaynak, otomatik yenileme)
+- NodeBB grup üyeliği durumu
+- **İşlem butonları:**
+  - **Plan Değiştir**: Dropdown ile yeni plan seç → onayda upgrade veya downgrade yapılır
+  - **Süre Düzenle**: Bitiş tarihini değiştir (date picker)
+  - **Aboneliği İptal Et**: Onay modal → iptal nedeni (opsiyonel) → iptal işlemi
+- Geçmiş abonelik kayıtları tablosu (tüm subscription history)
+
+#### Abone Listesi (`subscribers.ejs`)
+
+- Mevcut filtreler + plan filtresi (Lite / Premium / VIP)
+- Period filtresi (Aylık / Yıllık)
+- Source filtresi (Ödeme / Admin / Upgrade)
+- Her satırda plan badge'i gösterilir
+- Her satırda kullanıcı detay sayfasına link
+- Hızlı işlem butonları (iptal, plan değiştir)
+
+---
+
+## 5. NodeBB Entegrasyonu (Plugin Yok)
+
+NodeBB tarafında **herhangi bir plugin yazılmaz**. Tüm iletişim NodeBB'nin yerleşik grup sistemi ve API'si üzerinden sağlanır.
+
+### 5.1 Güvenlik Modeli
+
+| İşlem                                                  | Güvenlik Riski                                                                                         | Çözüm                                          |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| **Plan satın alma** (`/pay/checkout?uid={uid}`)        | Düşük — saldırgan başkasının uid'sini girse bile kendi parasıyla başkasına abonelik alır (hediye gibi) | Mevcut akış yeterli                            |
+| **Plan yükseltme** (`/pay/checkout/upgrade?uid={uid}`) | Düşük — aynı mantık, saldırgan kendi kartıyla ödeme yapar                                              | Mevcut akış yeterli                            |
+| **Abonelik iptali**                                    | Yüksek — başkasının aboneliğini iptal etme riski                                                       | IP kısıtlamalı endpoint ile çözüldü (bkz. 3.5) |
+
+Sonuç: Ödeme gerektiren işlemlerde cross-service auth gerekmez (PayTR güvenliği yeterli). İptal endpoint'i sadece NodeBB sunucusunun IP'sinden gelen istekleri kabul eder.
+
+### 5.2 NodeBB Tarafında Yapılacaklar (Admin Panelden, Kod Yazmadan)
+
+#### 1. Grupları Oluştur
+
+NodeBB Admin Panel → Groups → Create:
+
+| Grup Adı  | Tür            | Amaç                 |
+| --------- | -------------- | -------------------- |
+| `lite`    | Gizli (Hidden) | Lite plan üyeleri    |
+| `premium` | Gizli (Hidden) | Premium plan üyeleri |
+| `vip`     | Gizli (Hidden) | VIP plan üyeleri     |
+
+- Plan grupları (`lite`, `premium`, `vip`) → **Hidden** ve sadece API ile yönetilir. Kullanıcılar kendileri katılamaz/çıkamaz.
+
+#### 2. Navigasyon Linkleri
+
+NodeBB Admin Panel → Navigation:
+
+- **"Planını Yükselt"** → `https://pay.ieu.app/pay/checkout?uid={uid}` (NodeBB template değişkeni ile uid otomatik eklenir)
+- **"Aboneliği İptal Et"** → `https://pay.ieu.app/pay/cancel?uid={uid}` (ödeme servisindeki iptal sayfasına yönlendirir)
+
+### 5.3 Ödeme Servisi Tarafında — IP Kısıtlamalı İptal Endpoint'i
+
+Ödeme servisinde kullanıcının abonelik iptalini işleyen, IP kısıtlamalı endpoint:
+
+#### Endpoint: `POST /pay/api/cancel-subscription`
+
+```
+Request:
+  Body: { uid: Number }
+  IP Kontrolü: Sadece ALLOWED_CANCEL_IP env değişkeninde tanımlı IP'den gelen istekler kabul edilir
+
+İşlem:
+1. IP kontrolü yap:
+   - req.ip veya x-forwarded-for header'ından gelen IP kontrol edilir
+   - ALLOWED_CANCEL_IP ile eşleşmiyorsa → 403 Forbidden döndür
+2. MongoDB'de aktif abonelik ara (uid, status: "active")
+3. Aktif abonelik varsa:
+   - autoRenew = false
+   - cancelRequestedAt = new Date()
+4. Aktif abonelik yoksa → 404 döndür
+5. Başarılı yanıt döndür (abonelik bitiş tarihi bilgisiyle)
+
+Response (200):
+  { success: true, expiresAt: "2025-03-15T00:00:00Z", message: "Otomatik yenileme iptal edildi." }
+
+Response (403):
+  { error: "Forbidden" }
+
+Response (404):
+  { error: "Aktif abonelik bulunamadı." }
+```
+
+#### İptal Sayfası: `GET /pay/cancel?uid={uid}`
+
+- Kullanıcının aktif abonelik bilgilerini gösterir (plan, bitiş tarihi, otomatik yenileme durumu)
+- "Otomatik Yenilemeyi İptal Et" butonu
+- Butona tıklandığında `POST /pay/api/cancel-subscription` çağrılır
+- İşlem sonrası onay mesajı gösterilir
+
+#### IP Kısıtlama Middleware'i
+
+```javascript
+// src/middleware/ipRestrict.js
+const Setting = require("../models/setting.model");
+
+async function ipRestrict(req, res, next) {
+  // Önce veritabanından admin panelde tanımlanan IP'yi kontrol et
+  const setting = await Setting.findOne({ key: "allowedCancelIp" });
+  const allowedIp = setting?.value || process.env.ALLOWED_CANCEL_IP;
+
+  const clientIp = req.ip || req.headers["x-forwarded-for"]?.split(",")[0].trim();
+  if (clientIp !== allowedIp) {
+    return res.status(403).json({ error: "Forbidden" });
+  }
+  next();
+}
+```
+
+> **Not**: IP adresi öncelik sırası: 1) Veritabanındaki `allowedCancelIp` ayarı (admin panelden yönetilir), 2) `ALLOWED_CANCEL_IP` environment değişkeni. Admin panelden ayar yapıldığında sunucu yeniden başlatılmadan IP değişikliği uygulanır.
+
+### 5.4 Akış Diyagramları
+
+#### Kullanıcı Aboneliğini İptal Eder
+
+```
+Kullanıcı (forum.ieu.app)                                    Ödeme Servisi (pay.ieu.app)
+        │                                                              │
+        │  "Aboneliği İptal Et" linkine tıklar                        │
+        │  → /pay/cancel?uid=123                                      │
+        │─────────────────────────────────────────────────────────────►│
+        │                                                              │
+        │  İptal sayfası (aktif abonelik bilgileri + iptal butonu)     │
+        │◄─────────────────────────────────────────────────────────────│
+        │                                                              │
+        │  "Otomatik Yenilemeyi İptal Et" butonuna tıklar             │
+        │  POST /pay/api/cancel-subscription {uid: 123}               │
+        │─────────────────────────────────────────────────────────────►│
+        │                                                              │
+        │                                        IP kontrolü (ALLOWED_CANCEL_IP)
+        │                                        ✓ Geçerli IP → devam et
+        │                                                              │
+        │                                        autoRenew = false
+        │                                        cancelRequestedAt = now
+        │                                                              │
+        │  Onay: "İptal edildi, aboneliğiniz                          │
+        │   {tarih}'e kadar aktif kalacaktır"                          │
+        │◄─────────────────────────────────────────────────────────────│
+```
+
+#### Kullanıcı Plan Satın Alır
+
+```
+Kullanıcı (forum.ieu.app)                                    Ödeme Servisi (pay.ieu.app)
+        │                                                              │
+        │  "Planını Yükselt" tıklar                                    │
+        │  → /pay/checkout?uid=123                                     │
+        │─────────────────────────────────────────────────────────────►│
+        │                                                              │
+        │  Plan seçim sayfası (3 kart + aylık/yıllık)                  │
+        │◄─────────────────────────────────────────────────────────────│
+        │                                                              │
+        │  Plan seçer → billing form → PayTR ödeme                     │
+        │─────────────────────────────────────────────────────────────►│
+        │                                                              │
+        │                               PayTR callback → NodeBB grubuna ekle
+        │                               → Subscription oluştur         │
+        │                                                              │
+        │  result?status=success                                       │
+        │◄─────────────────────────────────────────────────────────────│
+```
+
+---
+
+## 6. Frontend Tasarım
+
+### 6.1 Plan Seçim Sayfası (home.ejs)
+
+- 3 kart yan yana (mobilde alt alta)
+- Aylık/Yıllık toggle switch (üstte)
+- Yıllık seçildiğinde: "8 ay bedava!" badge, aylık eşdeğer fiyat gösterimi
+- Premium kartı: "En Popüler" badge, hafif vurgu (border/shadow)
+- VIP kartı: "Elit Deneyim" badge
+- Her kartta: Özellik listesi + fiyat + "Satın Al" butonu
+- Aktif aboneliği olan kullanıcı: mevcut plan vurgulanır, alt planlar disabled, üst planlarda "Yükselt" butonu
+
+### 6.2 Upgrade Sayfası
+
+- Mevcut plan vs yeni plan karşılaştırması
+- Prorated fark ücreti hesabı gösterimi
+- Kalan gün bilgisi
+- Onay butonu → billing form'a yönlendir
+
+---
+
+## 7. Yasal Uyumluluk ve Bilgilendirmeler
+
+Ödeme içeren bir abonelik sistemi olduğundan, Türkiye mevzuatına tam uyum sağlanmalıdır.
+
+### 7.1 Uyulması Gereken Mevzuat
+
+| Mevzuat                                                          | Kapsam                                                              |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **6502 sayılı Tüketicinin Korunması Hakkında Kanun**             | Tüketici hakları, cayma hakkı, haksız şartlar                       |
+| **Mesafeli Sözleşmeler Yönetmeliği**                             | Ön bilgilendirme, sözleşme, cayma hakkı, dijital içerik istisnaları |
+| **6698 sayılı KVKK**                                             | Kişisel verilerin korunması, aydınlatma yükümlülüğü, açık rıza      |
+| **6563 sayılı Elektronik Ticaretin Düzenlenmesi Hakkında Kanun** | Hizmet sağlayıcı bilgileri, ticari iletişim, sipariş onayı          |
+| **5651 sayılı İnternet Kanunu**                                  | İçerik sağlayıcı sorumlulukları                                     |
+| **Abonelik Sözleşmeleri Yönetmeliği**                            | Otomatik yenileme bilgilendirme, abonelik iptali                    |
+
+### 7.2 Satın Alma Öncesi Bilgilendirmeler
+
+Kullanıcı ödeme yapmadan önce aşağıdaki bilgilendirmeler **açıkça** sunulmalı ve onay alınmalıdır:
+
+#### Ön Bilgilendirme Formu (Zorunlu)
+
+Plan seçim sayfasında veya billing formunda kullanıcıya gösterilecek:
+
+- Hizmet sağlayıcı bilgileri (unvan, adres, iletişim)
+- Seçilen planın adı, kapsamı ve özellikleri
+- Toplam fiyat (KDV dahil, kuruş cinsinden net tutar)
+- Ödeme yöntemi ve koşulları
+- Abonelik süresi (aylık: 30 gün, yıllık: 365 gün)
+- Otomatik yenileme durumu ve koşulları
+- Cayma hakkı bilgilendirmesi (dijital içerik istisnası dahil)
+- Şikayet ve itiraz mekanizmaları
+
+#### Onay Checkbox'ları (Satın alma butonundan önce)
+
+Kullanıcının tüm checkbox'ları işaretlemesi zorunludur:
+
+1. **Sözleşme onayı** (mevcut, güncellenmeli):
+
+   > "Mesafeli Satış Sözleşmesi'ni, Kullanım Koşulları'nı, Gizlilik Politikası'nı ve KVKK Aydınlatma Metni'ni okudum, anladım ve kabul ediyorum."
+
+2. **Dijital içerik cayma hakkı feragati** (mevcut, güncellenmeli):
+
+   > "Dijital içerik hizmetinin derhal ifasına başlanmasını talep ettiğimi ve bu sebeple 14 günlük cayma hakkımdan feragat ettiğimi onaylıyorum."
+
+3. **Otomatik yenileme bilgilendirmesi** (YENİ — varsayılan tikli):
+
+   > "Abonelik sürem dolduğunda, aynı plan ve ödeme tutarı ile otomatik olarak yenileneceğini biliyorum. Otomatik yenilemeyi istediğim zaman iptal edebileceğimi anlıyorum."
+
+4. **Ön bilgilendirme formu onayı** (YENİ):
+   > "Ön Bilgilendirme Formu'nu okudum ve satın alma öncesi gerekli tüm bilgileri aldım."
+
+### 7.3 Otomatik Yenileme — Yasal Gereklilikler
+
+Abonelik Sözleşmeleri Yönetmeliği gereği:
+
+- **Satış anında**: Otomatik yenileme tercihi açıkça gösterilmeli, fiyat ve yenilenme tarihi belirtilmeli
+- **Yenileme öncesi bildirim**: Abonelik sona ermeden **en az 3 gün önce** kullanıcıya e-posta ile bildirim gönderilmeli:
+  - Yenilenecek plan adı
+  - Yenileme tutarı
+  - Yenileme tarihi
+  - İptal etme linki / talimatları
+- **Kolay iptal**: Kullanıcı otomatik yenilemeyi kolayca kapatabilmeli (forum profili veya ödeme sayfası üzerinden)
+- **İptal onayı**: Otomatik yenileme kapatıldığında kullanıcıya onay bildirimi gönderilmeli
+
+### 7.4 Cayma Hakkı ve İade Politikası
+
+6502 sayılı Kanun ve Mesafeli Sözleşmeler Yönetmeliği kapsamında:
+
+- **Genel kural**: Mesafeli satışlarda tüketici 14 gün içinde cayma hakkına sahiptir
+- **Dijital içerik istisnası**: Elektronik ortamda anında ifa edilen dijital içeriklerde, tüketicinin önceden açık onayı ve cayma hakkından feragat beyanı alınmışsa cayma hakkı uygulanmaz
+- **Bu sistemde**: Kullanıcı satın alma öncesinde dijital içerik feragat checkbox'ını onayladığı için cayma hakkı bulunmaz
+- **İade**: İade politikası sayfasında (`legal-refund.ejs`) bu durum açıkça belirtilmelidir
+- **Admin iptali**: Admin tarafından yapılan iptallerde iade kararı admin'in insiyatifindedir
+
+### 7.5 Güncellenecek Yasal Sayfalar
+
+Mevcut yasal sayfalar çok katmanlı plan yapısına göre güncellenmelidir:
+
+| Sayfa                | Güncellenecek İçerik                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `legal-distance.ejs` | Plan isimleri (Lite/Premium/VIP), fiyat tablosu, otomatik yenileme maddeleri, yıllık abonelik koşulları, upgrade/downgrade kuralları |
+| `legal-terms.ejs`    | Çoklu plan tanımları, plan yükseltme/düşürme koşulları, otomatik yenileme kuralları, admin iptal yetkisi                             |
+| `legal-refund.ejs`   | Plan bazlı iade kuralları, upgrade'de prorated hesaplama açıklaması, otomatik yenileme iptali prosedürü                              |
+| `legal-privacy.ejs`  | Otomatik yenileme için saklanan ödeme bilgileri, plan tercihi verisi                                                                 |
+| `legal-kvkk.ejs`     | Ödeme bilgileri işleme amacı, otomatik yenileme kapsamında veri saklama süresi                                                       |
+
+### 7.6 Satın Alma Sonrası Bilgilendirmeler
+
+#### Sipariş Onay E-postası / Ekranı
+
+Ödeme başarılı olduğunda kullanıcıya gösterilecek ve (e-posta altyapısı varsa) gönderilecek bilgiler:
+
+- Satın alınan plan adı ve özellikleri
+- Ödenen tutar (KDV dahil)
+- Abonelik başlangıç ve bitiş tarihi
+- Otomatik yenileme durumu (açık/kapalı)
+- Bir sonraki yenileme tarihi ve tutarı (otomatik yenileme açıksa)
+- İptal ve iletişim bilgileri
+
+#### Result Sayfası (`result.ejs`)
+
+Başarılı ödeme sonrası gösterilecek ek bilgiler:
+
+- Seçilen plan adı
+- Abonelik bitiş tarihi
+- Otomatik yenileme durumu
+- Destek iletişim bilgileri
+
+### 7.7 Fiyat Gösterimi Kuralları
+
+- Tüm fiyatlar **KDV dahil** olarak gösterilmelidir
+- Para birimi açıkça belirtilmelidir (₺ / TL)
+- Yıllık planda: toplam tutar + aylık eşdeğer fiyat + tasarruf miktarı gösterilmelidir
+- Upgrade'de: fark ücreti hesaplaması kullanıcıya şeffaf şekilde gösterilmelidir (kalan gün, günlük fark, toplam fark)
+- İndirimli fiyat gösteriminde eski fiyat ve indirim oranı belirtilmelidir
+
+### 7.8 Hizmet Sağlayıcı Bilgileri
+
+Tüm sayfalarda (footer veya erişilebilir bir yerde) bulunması gereken bilgiler:
+
+- Hizmet sağlayıcı unvanı
+- İletişim e-posta adresi
+- Website adresi
+- Şikayet/destek kanalı
+
+---
+
+## 8. Environment Değişkenleri
+
+```env
+# Mevcut değişkenler korunur, ek olarak:
+NODEBB_LITE_GROUP=lite
+NODEBB_PREMIUM_GROUP=premium
+NODEBB_VIP_GROUP=vip
+ALLOWED_CANCEL_IP=1.2.3.4  # NodeBB sunucusunun IP adresi — varsayılan değer; admin panelden güncellenebilir (DB'deki değer önceliklidir)
+```
+
+> Not: Grup isimleri `src/config/plans.js` içinde tanımlı olacağından, env'den de okunabilir veya direkt config'te sabitlenebilir.
+
+---
+
+## 9. Migration / Geçiş Planı
+
+Mevcut "premium" grubundaki kullanıcılar için geçiş:
+
+1. Mevcut tüm aktif aboneliklere `plan: "premium"` ve `period: "monthly"` atanır (geriye dönük uyumluluk)
+2. `amount: 9990` (mevcut fiyat 99.90₺) olarak set edilir
+3. NodeBB'de mevcut "premium" grubundaki kullanıcılar "premium" grubunda kalır (grup adı aynı)
+4. Migration script'i `src/scripts/migrate-plans.js` olarak yazılır
+
+---
+
+## 10. Uygulama Sırası
+
+### Faz 1: Altyapı
+
+1. `src/config/plans.js` oluştur — plan tanımları
+2. `subscription.model.js` güncelle — yeni alanlar
+3. Migration script yaz ve çalıştır
+
+### Faz 2: Servis Katmanı
+
+4. `nodebb.service.js` güncelle — çoklu grup desteği
+5. `paytr.service.js` güncelle — dinamik fiyat/ürün
+6. `subscription.service.js` güncelle — plan-aware CRUD + upgrade hesaplama
+
+### Faz 3: Ödeme Akışı
+
+7. `payment.controller.js` güncelle — plan seçimi + upgrade flow
+8. `payment.routes.js` güncelle — yeni route'lar
+9. Frontend: `home.ejs` (plan kartları), `billing-form.ejs`, `payment.ejs`, `result.ejs`
+
+### Faz 4: Admin Paneli
+
+10. `admin.service.js` güncelle — plan bazlı istatistikler + manuel atama
+11. `admin.controller.js` güncelle — yeni endpoint'ler
+12. `admin.routes.js` güncelle — yeni route'lar
+13. Frontend: `dashboard.ejs`, `subscribers.ejs`, `assign.ejs` (yeni)
+
+### Faz 5: Yasal Uyumluluk
+
+14. Yasal sayfalar güncelle — çoklu plan, otomatik yenileme, upgrade/downgrade kuralları
+15. Ön bilgilendirme formu ve onay checkbox'ları ekle
+16. Otomatik yenileme öncesi bildirim mekanizması (cron + e-posta)
+
+### Faz 6: Test & Doğrulama
+
+17. `.env.example` güncelle
+18. Tüm akışları test et (yeni abone, upgrade, admin atama, süre dolumu, yasal onaylar)
+
+---
+
+## 11. Doğrulama (Verification)
+
+### Test Senaryoları
+
+1. **Yeni Abonelik**: Her 3 plan x 2 period = 6 senaryo test
+2. **Upgrade**: Lite→Premium, Lite→VIP, Premium→VIP = 3 senaryo
+3. **Admin Atama**: Her plan için manuel atama testi
+4. **Süre Dolumu**: Cron job'un doğru grubu kaldırdığını doğrula
+5. **NodeBB Grup**: Upgrade'de eski gruptan çıkıp yeni gruba girdiğini doğrula
+6. **PayTR Callback**: merchantOid parse'ın doğru çalıştığını doğrula
+7. **Prorated Hesaplama**: Fark ücretinin doğru hesaplandığını doğrula
+8. **Dashboard**: Plan bazlı istatistiklerin doğru gösterildiğini doğrula
+9. **Yasal Onaylar**: Checkbox'lar işaretlenmeden ödeme butonunun aktif olmadığını doğrula
+10. **Otomatik Yenileme Bildirimi**: Süre dolmadan 3 gün önce bildirim cron job'ının çalıştığını doğrula
+11. **Yasal Sayfalar**: Tüm yasal sayfalarda plan isimleri, fiyatlar ve otomatik yenileme bilgilerinin güncel olduğunu doğrula
+
+### Test Yöntemi
+
+- PayTR test mode ile ödeme akışı testi
+- MongoDB'de kayıt doğrulama
+- NodeBB API'den grup üyeliği doğrulama
+- Admin panel üzerinden manuel kontrol