Plan ve Abonelik Yönetimi

COS platformunda plan yönetimi, organizasyonların hangi özelliklere ve limitlere sahip olacağını belirler. Planlar TenantGroup (holding) seviyesinde tanımlanır; bir TenantGroup'a bağlı tüm tenant'lar aynı plan limitlerinden etkilenir.

---

Temel Kavramlar

Plan Hiyerarşisi

PlanTemplate (Şablon)
  └─ PlanFeature (Plan Özellikleri — her feature için enabled/limit/tier)
       └─ PlanFeatureOverride (Grup Bazında İstisna)
            └─ FeatureDefinition (Platform Geneli Özellik Tanımı)

Terminoloji

Terim	Açıklama
PlanTemplate	Plan şablonu (Free, Business, Enterprise vb.)
FeatureDefinition	Platform genelinde tanımlı özellik (ör. max_users, swot_analysis)
PlanFeature	Bir planın belirli bir özellik için değerleri (açık/kapalı, limit, seviye)
PlanFeatureOverride	Belirli bir TenantGroup için plan değerini ezen istisna tanımı
TenantGroup	Bir veya birden fazla tenant'ı barındıran holding/grup yapısı

---

Varsayılan Planlar

COS platformu 3 varsayılan plan ile gelir:

Free (Ücretsiz)

Küçük takımlar için temel plan.

• Kullanıcı: 3
• Tenant: 1
• OKR: 5 hedef, 15 anahtar sonuç, 10 inisiyatif
• KPI: 10
• Strateji modülleri: Kapalı (SWOT, BSC, Tema vb.)
• RBAC: BASIC (Admin + Member)
• Dashboard: BASIC
• KPI Kütüphanesi: BASIC

Business (İş)

Orta ölçekli şirketler için gelişmiş plan.

• Kullanıcı: 50
• Tenant: 3
• OKR: Sınırsız
• KPI: Sınırsız
• Strateji modülleri: Açık (EA ve VRIO hariç)
• PESTLE Analizi: Açık
• Birim Seviyesi Strateji: Kapalı (TL oluşturma/düzenleme/silme yapamaz)
• RBAC: FULL (4 rol: ADMIN/SM/TL/MEMBER)
• Dashboard: STANDARD
• KPI Kütüphanesi: FULL
• Ek: API erişimi, denetim günlüğü, gap yönetimi, performans raporları

Enterprise (Kurumsal)

Büyük kurumlar ve holdingler için tam özellikli plan.

• Kullanıcı: Sınırsız
• Tenant: Sınırsız
• OKR: Sınırsız
• KPI: Sınırsız
• Strateji modülleri: Tümü açık (EA, VRIO, Olgunluk Değerlendirmesi, PESTLE dahil)
• Birim Seviyesi Strateji: Açık (TL kendi birimi için analiz oluşturabilir)
• RBAC: FULL
• Dashboard: FULL
• Ek: SSO, white-label, çapraz tenant görünüm, öncelikli destek, tam entegrasyon

---

Özellik Kategorileri

Platform özellikleri 7 kategoride gruplandırılmıştır:

Kullanıcı ve Organizasyon (USERS_ORG)

Özellik	Açıklama	Değer Tipi
max_users	Maksimum kullanıcı sayısı	Sayısal
max_tenants	Maksimum tenant sayısı	Sayısal
max_org_depth	Organizasyon derinliği	Sayısal
org_versioning	Organizasyon versiyonlama	Açık/Kapalı

Strateji (STRATEGY)

Alt kategorilere ayrılmıştır: general, swot, pestle, porter, bcg, bsc, asis, resource, dma, excellence, findings.

Özellik	Alt Kategori	Açıklama	Değer Tipi
max_strategic_cycles	general	Maksimum stratejik döngü	Sayısal
max_okr_cycles	general	Maksimum OKR döngüsü	Sayısal
strategic_themes	general	Stratejik Temalar	Açık/Kapalı
max_strategic_themes	general	Maks stratejik tema sayısı	Sayısal
strategy_roadmap	general	Strateji Yol Haritası	Açık/Kapalı
unit_level_strategy	general	Birim Seviyesi Strateji	Açık/Kapalı
ea_module	general	Kurumsal Mimari (EA)	Açık/Kapalı
maturity_assessment	general	Olgunluk Değerlendirmesi	Açık/Kapalı
swot_analysis	swot	SWOT Analizi	Açık/Kapalı
max_swot_per_unit	swot	Birim başına maks SWOT	Sayısal
pestle_analysis	pestle	PESTLE Analizi	Açık/Kapalı
max_pestle_per_unit	pestle	Birim başına maks PESTLE	Sayısal
porter_analysis	porter	Porter 5 Güç Analizi	Açık/Kapalı
max_porter_per_unit	porter	Birim başına maks Porter	Sayısal
bcg_matrix	bcg	BCG Büyüme-Pay Matrisi	Açık/Kapalı
max_bcg_per_unit	bcg	Birim başına maks BCG	Sayısal
bsc_module	bsc	Balanced Scorecard	Açık/Kapalı
max_bsc_per_unit	bsc	Birim başına maks BSC	Sayısal
current_state_analysis	asis	Mevcut Durum Analizi	Açık/Kapalı
max_asis_per_unit	asis	Birim başına maks As-Is	Sayısal
resource_inventory_vrio	resource	Kaynak Envanteri & VRIO	Açık/Kapalı
max_resource_per_unit	resource	Birim başına maks kaynak analizi	Sayısal
digital_maturity_assessment_core	dma	DMA Temel (60 soru)	Açık/Kapalı
digital_maturity_assessment_extended	dma	DMA Genişletilmiş (150 soru)	Açık/Kapalı
digital_maturity_assessment_multi_rater	dma	DMA Çoklu Değerlendirici	Açık/Kapalı
max_digital_maturity_per_unit	dma	Birim başına maks DMA	Sayısal
max_digital_maturity_raters_per_assessment	dma	Değerlendirme başına maks değerlendirici	Sayısal
max_digital_maturity_raters_per_question	dma	Soru başına maks değerlendirici	Sayısal
excellence_assessment_core	excellence	Mükemmellik Değerlendirmesi (Temel)	Açık/Kapalı
excellence_assessment_advanced	excellence	Mükemmellik Değerlendirmesi (Genişletilmiş)	Açık/Kapalı
excellence_assessment_multi_rater	excellence	Mükemmellik Çoklu Değerlendirici	Açık/Kapalı
max_excellence_assessment_per_unit	excellence	Birim başına maks mükemmellik	Sayısal
max_excellence_raters_per_assessment	excellence	Değerlendirme başına maks değerlendirici	Sayısal
max_excellence_raters_per_question	excellence	Soru başına maks değerlendirici	Sayısal
findings_module	findings	Bulgular Modülü	Açık/Kapalı

OKR

Özellik	Açıklama	Değer Tipi
max_objectives	Maksimum hedef	Sayısal
max_key_results	Maksimum anahtar sonuç	Sayısal
max_initiatives	Maksimum inisiyatif	Sayısal
okr_hierarchy	OKR hiyerarşisi	Açık/Kapalı
okr_approval_workflow	Onay iş akışı	Açık/Kapalı
okr_confidentiality	Gizlilik kontrolü	Açık/Kapalı
okr_multi_alignment	Çoklu hizalama	Açık/Kapalı
okr_snapshots	Anlık görüntü	Açık/Kapalı

KPI ve Raporlama (KPI_REPORT)

Özellik	Açıklama	Değer Tipi
max_kpis	Maksimum KPI sayısı	Sayısal
kpi_library_tier	KPI Kütüphanesi seviyesi	Seviye (BASIC/FULL)
dashboards_tier	Dashboard erişimi	Açık/Kapalı
reports_tier	Raporlama erişimi	Açık/Kapalı
gap_management	Gap yönetimi	Açık/Kapalı
performance_reports	Performans raporları	Açık/Kapalı

Ürün Yönetimi (PRODUCT)

Alt kategorilere ayrılmıştır: general, product_swot, product_scorecard, product_kpi.

Özellik	Alt Kategori	Açıklama	Değer Tipi
max_products	general	Maksimum ürün sayısı	Sayısal
product_ownership	general	Ürün sahipliği atama	Açık/Kapalı
product_swot	product_swot	Ürün SWOT Analizi	Açık/Kapalı
product_scorecard	product_scorecard	Ürün Scorecard	Açık/Kapalı
max_product_scorecard_kpis	product_scorecard	Maks ürün scorecard KPI	Sayısal
product_kpi_library	product_kpi	Ürün KPI Kütüphanesi	Açık/Kapalı

Yönetim ve Güvenlik (ADMIN_SECURITY)

Özellik	Açıklama	Değer Tipi
rbac_tier	Yetki yönetimi	Açık/Kapalı
cross_tenant_view	Çapraz tenant görünüm	Açık/Kapalı
white_label	Özel marka	Açık/Kapalı
sso	Tek oturum açma (SSO)	Açık/Kapalı
api_access	API erişimi	Açık/Kapalı
integrations_tier	Entegrasyon erişimi	Açık/Kapalı
kpi_api_integration	KPI API Entegrasyonu	Açık/Kapalı
max_api_integrations	Maks API entegrasyon sayısı	Sayısal
min_cron_interval_minutes	Min cron aralığı (dakika)	Sayısal
notification_tier	Bildirim seviyesi	Seviye (BASIC/FULL)
audit_log	Denetim günlüğü	Açık/Kapalı
priority_support	Öncelikli destek	Açık/Kapalı

Yapay Zeka (AI)

Özellik	Açıklama	Değer Tipi
ai_assistant	AI Asistan	Açık/Kapalı
ai_daily_messages	Günlük AI mesaj limiti	Sayısal
ai_max_conversations	Maks aktif konuşma	Sayısal
ai_history_retention_days	Chat saklama süresi (gün)	Sayısal
ai_web_research	Web araştırma	Açık/Kapalı
ai_daily_web_searches	Günlük web araştırma limiti	Sayısal
ai_data_generation	Örnek veri üretimi	Açık/Kapalı
ai_rate_limit_per_minute	Dakikalık AI istek limiti	Sayısal

---

Plan Yönetimi (SuperAdmin)

Plan yönetimi sadece SUPER_ADMIN rolüne sahip kullanıcılar tarafından yapılabilir.

Plan Oluşturma

1. Planlar sayfasına gidin
2. Yeni Plan butonuna tıklayın
3. Plan bilgilerini doldurun:
   • Kod: Benzersiz tanımlayıcı (ör. premium)
   • Ad: Görüntülenen ad
   • Açıklama: Plan açıklaması
   • Maks Tenant: Bu planla oluşturulabilecek tenant sayısı (0 = sınırsız)
   • Sıralama: Listede görünme sırası
4. Her özellik için değerleri belirleyin (açık/kapalı, limit, seviye)
5. Kaydet butonuna tıklayın

Plan Düzenleme

• Mevcut bir planın özellik değerleri değiştirilebilir
• Plan kodu değiştirilebilir (benzersiz olmalı)
• Aktif/pasif durumu değiştirilebilir

Plan Atama

1. Planı atamak istediğiniz TenantGroup'u belirleyin
2. POST /plans/:planId/assign endpoint'ini kullanarak planı gruba atayın
3. Değişiklik anında tüm grup tenant'larını etkiler

Grup Override (İstisna Tanımlama)

Belirli bir TenantGroup için plan değerlerinden farklı değerler tanımlamak istediğinizde override kullanılır:

1. Override tanımlamak istediğiniz grubun override sayfasına gidin
2. Değiştirmek istediğiniz özelliği seçin
3. Yeni değeri girin
4. İsteğe bağlı olarak bir sebep ekleyin
5. Kaydet butonuna tıklayın

Not: Override yalnızca ilgili feature için plan değerinin üzerine yazar. Override tanımlanmayan özellikler plandaki değerleri kullanır.

---

Değer Çözümleme Sırası

Bir feature'ın efektif değeri şu sıra ile belirlenir (aktif abonelik olduğunda):

1. PlanFeatureOverride — Grup bazında override tanımlıysa bu değer kullanılır
2. PlanFeature — Override yoksa, plandaki değer kullanılır
3. FeatureDefinition — Planda da tanımlı değilse, platform varsayılanı kullanılır

Dikkat: Override'lar yalnızca aktif bir abonelik (subscription) olduğunda geçerlidir. Abonelik sona erdiğinde veya iptal edildiğinde override'lar devre dışı kalır ve Free plan değerleri uygulanır.

---

Abonelik (Subscription) Yönetimi

Abonelik sistemi, planlara zaman bazlı erişim sağlar. Bir TenantGroup'un ücretli bir plana erişebilmesi için o plana ait aktif bir aboneliğe sahip olması gerekir.

Abonelik Modeli

TenantGroup
  └─ Subscription (1 aktif, N geçmiş)
       ├─ PlanTemplate → hangi plana abone
       ├─ BillingPeriod → MONTHLY / YEARLY
       ├─ startDate, endDate → abonelik dönemi
       ├─ gracePeriodDays → süre bitiminde ek süre (varsayılan: 7 gün)
       ├─ autoRenew → otomatik yenileme flag'i
       └─ status → ACTIVE / CANCELLED / EXPIRED

Abonelik Durumları

Durum	Açıklama
ACTIVE	Abonelik aktif, plan özellikleri ve override'lar geçerli
CANCELLED	Yönetici tarafından iptal edildi, grup Free plana düştü
EXPIRED	Süre + grace period doldu, otomatik olarak Free plana düşürüldü

Grace Period (Ek Süre)

Abonelik bitiş tarihi geçtiğinde 7 günlük bir ek süre tanınır. Bu süre boyunca:

• Plan özellikleri aktif kalır
• Override'lar geçerli kalır
• FE'de uyarı banner'ı gösterilir

Grace period sonunda otomatik olarak:

• Abonelik durumu EXPIRED olur
• Grubun planı Free'ye düşürülür
• Override'lar devre dışı kalır

İş Kuralları

1. Bir grupta aynı anda yalnızca 1 aktif abonelik olabilir
2. Free plana abonelik oluşturulamaz — Free varsayılan plandır
3. Plan değişikliği: Mevcut aboneliği iptal edin → yeni abonelik oluşturun
4. İptal: Abonelik iptal edildiğinde grup anında Free plana düşer
5. Silme: Yalnızca CANCELLED veya EXPIRED abonelikler soft-delete edilebilir
6. autoRenew: Şu an yalnızca flag olarak tutulur, otomatik yenileme henüz aktif değildir

FE Uyarı Banner'ı

Abonelik süresi dolmaya yaklaştığında tüm kullanıcılara uyarı banner'ı gösterilir:

Kalan Gün	Banner Tipi	Mesaj
≤ 30 gün	Bilgi (mavi)	"Aboneliğiniz X gün sonra sona erecek"
≤ 7 gün	Uyarı (turuncu)	"Aboneliğiniz X gün sonra sona erecek"
≤ 1 gün	Acil (kırmızı)	"Aboneliğiniz yarın sona erecek!"
Grace period	Hata (kırmızı)	"Aboneliğiniz sona erdi. Ek süre: X gün"

Abonelik API Endpoint'leri

Endpoint	Method	Açıklama	Erişim
/subscriptions	GET	Tüm abonelikleri listele	SUPER_ADMIN
/subscriptions/:id	GET	Abonelik detayı	SUPER_ADMIN
/subscriptions	POST	Yeni abonelik oluştur	SUPER_ADMIN
/subscriptions/:id	PATCH	Abonelik güncelle (endDate/autoRenew/notes)	SUPER_ADMIN
/subscriptions/:id/cancel	POST	Abonelik iptal	SUPER_ADMIN
/subscriptions/:id	DELETE	Abonelik sil (soft)	SUPER_ADMIN
/subscriptions/my-status	GET	Kendi grup abonelik durumu	Tüm Roller

Sayısal Limit Kuralları

• 0 = Sınırsız (kullanıcı, tenant, hedef vs. için limit yok)
• Pozitif sayı = Belirtilen miktar kadar izin verilir
• enabled: false ise limit değeri dikkate alınmaz (özellik kapalı)

---

Yetki Matrisi

İşlem	SUPER_ADMIN	GROUP_ADMIN	ADMIN	Diğer
Plan listeleme	✅	❌	❌	❌
Plan oluşturma	✅	❌	❌	❌
Plan düzenleme	✅	❌	❌	❌
Plan silme	✅	❌	❌	❌
Plan atama	✅	❌	❌	❌
Feature tanımı CRUD	✅	❌	❌	❌
Override tanımlama	✅	❌	❌	❌
Efektif plan görüntüleme	✅	✅*	❌	❌

* GROUP_ADMIN: Yalnızca kendi grubunun efektif planını görüntüleyebilir.

---

API Endpoint'leri

Endpoint	Method	Açıklama	Erişim
/plans	GET	Tüm planları listele	SUPER_ADMIN
/plans	POST	Yeni plan oluştur	SUPER_ADMIN
/plans/:planId	GET	Plan detayı	SUPER_ADMIN
/plans/:planId	PATCH	Plan güncelle	SUPER_ADMIN
/plans/:planId	DELETE	Plan sil	SUPER_ADMIN
/plans/:planId/assign	POST	Planı TenantGroup'a ata	SUPER_ADMIN
/plans/features	GET	Feature tanımları listesi	SUPER_ADMIN
/plans/features	POST	Yeni feature tanımı	SUPER_ADMIN
/plans/features/:featureKey	PATCH	Feature tanımı güncelle	SUPER_ADMIN
/plans/effective/:groupId	GET	Efektif plan (override dahil)	SUPER_ADMIN, GROUP_ADMIN*
/plans/my-groups	GET	Kendi gruplarımın planları	SUPER_ADMIN, GROUP_ADMIN*
/plans/overrides/:groupId	GET	Grup override'ları	SUPER_ADMIN
/plans/overrides/:groupId	PUT	Override tanımla/güncelle	SUPER_ADMIN

* GROUP_ADMIN: Yalnızca kendi grubunun planını görüntüleyebilir.

---

Plan Enforcement (Limit Kontrolü)

Plan limitleri backend'de otomatik olarak kontrol edilir. Limit aşıldığında işlem 422 (Unprocessable Entity) hatası ile reddedilir.

Kontrol Edilen Noktalar

Entity Oluşturma	Feature Key	Kapsam
Tenant ekleme	maxTenants (PlanTemplate)	Grup geneli
Kullanıcı ekleme	max_users	Grup geneli (tüm tenant'lar toplam)
Hedef (Objective) ekleme	max_objectives	Tenant bazlı
Anahtar Sonuç (KR) ekleme	max_key_results	Tenant bazlı
İnisiyatif ekleme	max_initiatives	Tenant bazlı

Davranış Kuralları

• 0 = Sınırsız: Limit değeri 0 ise kontrol yapılmaz
• Mevcut veriler korunur: Limit aşıldığında mevcut veriler silinmez, sadece yeni ekleme engellenir
• Hata mesajı: "[Entity] limiti dolmuş (mevcut/limit). Plan yükseltmesi gerekiyor."
• Loglama: Her reddedilen işlem logger.warn ile loglanır

PlanFeature Guard (Boolean Özellik Kontrolü)

Boolean özellikler (ör. swot_analysis, bsc_module) @PlanFeature dekoratörü ile route seviyesinde kontrol edilebilir:

@UseGuards(PlanFeatureGuard)
@PlanFeature('swot_analysis')
@Get('swot')
getSwot() { ... }

Devre dışı olan feature'lara erişim 422 hatası ile reddedilir.

---

GROUP_ADMIN Plan Görünürlüğü

GROUP_ADMIN kullanıcılar menüde Platform → Plan Bilgileri sayfasından kendi gruplarının planını görüntüleyebilir. Bu sayfa salt okunurdur:

• Plan adı ve özellikleri görüntülenir
• Her özelliğin değeri ve kaynağı (Plan/Özel Ayar/Varsayılan) gösterilir
• Limitler ve aktif özellikler kategorilere göre gruplanır
• GROUP_ADMIN plan değişikliği yapamaz, override tanımlayamaz

---

Sık Sorulan Sorular

S: Bir tenant'ın planını değiştirebilir miyim? H: Hayır. Planlar tenant seviyesinde değil, TenantGroup seviyesinde tanımlanır. Tenant'ın planını değiştirmek için grubunun planını değiştirin.

S: Override ile planın tamamını değiştirebilir miyim? C: Override sadece tek tek feature'lar için tanımlanır. Tüm değerleri değiştirmek istiyorsanız yeni bir plan oluşturup gruba atayın.

S: Bir planı silerken mevcut gruplar ne olur? C: Bir plana bağlı TenantGroup varsa plan silinemez. Önce tüm grupları başka bir plana taşıyın.

S: Free plan kullanıcısı limit aşarsa ne olur? C: Yeni ekleme işlemleri engellenir. Mevcut veriler silinmez, ancak limit dahilinde olana kadar yeni kayıt oluşturulamaz.

S: Abonelik süresi dolduğunda ne olur? C: 7 günlük grace period başlar. Bu sürede plan aktif kalır. Grace period sonunda grup otomatik olarak Free plana düşer.

S: Abonelik iptal edildiğinde mevcut veriler silinir mi? C: Hayır. Grup Free plana düşer ve limitler Free değerlerini kullanır. Mevcut veriler korunur, ancak Free limitlerini aşan yeni ekleme işlemleri engellenir.

S: Bir grubun planını değiştirmek için ne yapmalıyım? C: Mevcut aboneliği iptal edin, ardından istediğiniz plana yeni bir abonelik oluşturun.

S: Override'lar abonelik olmadan çalışır mı? C: Hayır. Override'lar yalnızca aktif bir abonelik olduğunda geçerlidir. Abonelik yoksa Override değerleri dikkate alınmaz.