01 — Temel Kavramlar

Kimin için: Tüm entegrasyon geliştiricileri ve mimarlar.
Ön koşul: Temel SaaS ve kimlik doğrulama kavramları.
Tahmini süre: 10 dakika.

Ne Öğreneceksiniz

Bu bölümde, TALOST ID ekosisteminin temel yapı taşlarını, veri modellerini ve mimari ilişkilerini öğreneceksiniz:

• Kullanıcı (sub) ve kalıcı kimlik mantığı,
• Uygulama ve erişim modelleri (access_model),
• İstemci (OAuthClient) ve ortam (environment) ayrımı,
• Planlar, yetkiler (entitlements) ve kurumsal koltuk (seat) lisanslaması.

Kavram ve Mimari Model

TALOST ID, tüm uygulamalarınız için merkezi bir kimlik sağlayıcı (IdP), lisans denetleyicisi ve abonelik motorudur:

flowchart TD
    User["Kullanıcı (sub: UUID)"] -->|"Giriş Yapar (OIDC PKCE)"| App["SaaS Uygulaması (slug)"]
    App -->|"Erişim & Plan Sorgusu"| TalostID["TALOST ID Sunucusu"]
    
    subgraph "TALOST ID Ekosistemi"
        TalostID --> Clients["OAuth İstemcileri (DEV / STG / PROD)"]
        TalostID --> Plans["Planlar & Özellikler (features / limits)"]
        TalostID --> Entitlements["Kullanıcı Hakları (Entitlements)"]
        TalostID --> Webhooks["Webhook Kuyruğu (HMAC-SHA256)"]
        TalostID --> Config["Uzaktan Konfigürasyon & Feature Flag"]
    end
    
    subgraph "Lisans Kaynakları"
        Entitlements --> IndSub["Bireysel Abonelik"]
        Entitlements --> OrgSeat["Organizasyon Koltuk Lisansı"]
        Entitlements --> FreeApp["Ücretsiz Uygulama Erişimi"]
    end

Temel Yapı Taşları

1. Kullanıcı (`sub`)

• Evrensel Kalıcı Kimlik: Her kullanıcının TALOST ID sisteminde değişmez, benzersiz bir sub (Subject Identifier) değeri vardır (örn: usr_01h8x9... veya UUID formatında).
• Altın Kural: Uygulamanızın veritabanında kullanıcıları kesinlikle e-posta adresine göre değil, sub değerine göre ilişkilendirin. Kullanıcı e-postasını değiştirebilir; ancak sub asla değişmez.

2. Uygulama (`SaasApplication`)

• TALOST ID ekosistemine kayıtlı her ürün bağımsız bir uygulamadır.
• Slug: Benzersiz url tanımlayıcısıdır (örn: talost-crm, talost-accounting).
• Erişim Modelleri (access_model):
  • FREE: Tüm kayıtlı kullanıcılara ücretsiz erişim sunulur.
  • SUBSCRIPTION: Yalnızca aktif bir plana abone olan veya organizasyon koltuğu bulunan kullanıcılar girebilir.
  • ONE_TIME: Tek seferlik lisans satın alanlar erişebilir.
  • HYBRID: Temel özellikler ücretsiz, üst özellikler abonelikle açılır.

3. İstemci (`OAuthClient`) ve Ortamlar (`AppEnvironment`)

Her uygulama için 3 farklı çalışma ortamı mevcuttur. Her ortamın kendine ait client_id ve client_secret anahtarları bulunur:

1. DEVELOPMENT (Geliştirme):
   • Yerel geliştirme ortamınızdır (http://localhost:*, http://127.0.0.1:* URI'lerine izin verilir).
   • Yalnızca ilgili uygulamada ekip üyesi (APP_OWNER, APP_DEVELOPER) veya platform yöneticisi olan hesaplar giriş yapabilir.
2. STAGING (Ön İzleme / Test):
   • Test sunucularınız içindir.
   • Kesinlikle HTTPS protokolü gerektirir.
   • Sadece ekip üyeleri giriş yapabilir.
3. PRODUCTION (Canlı):
   • Son kullanıcılara açık canlı ortamdır.
   • Kesinlikle HTTPS protokolü zorunludur.
   • İlgili uygulamanın erişim modeline uygun tüm kullanıcılara açıktır.

4. Planlar ve Haklar (`Entitlements`)

• Plan: Uygulamanızın ücretlendirme paketidir (örn: starter, pro, enterprise).
• Özellikler (features): Plana dahil olan yetenek dizgileridir (örn: export_pdf, custom_domain).
• Limitler (limits): Sayısal kotalardır (örn: max_projects: 10, storage_gb: 50).
• Entitlement: Kullanıcının uygulamaya giriş yapma izni ve aktif haklarının toplam durumudur.

5. Organizasyon ve Koltuk (`LicenseSeat`)

• Kurumsal müşteriler tek bir fatura ile birden fazla kullanıcı için lisans satın alabilir.
• Organizasyon sahibi veya yöneticisi, satın alınan koltukları şirket çalışanlarına tahsis eder.
• Koltuk tahsis edilen kullanıcı, uygulamanıza giriş yaptığında lisans kaynağı ORGANIZATION_LICENSE olarak bildirilir.

Sık Yapılan Hatalar

Güvenlik Notları

• client_secret ve AppApiKey değerleri gizli anahtarlardır. Kesinlikle frontend JavaScript kodlarında, mobil uygulama paketlerinde veya halka açık Git depolarında paylaşılmamalıdır.
• Ortamlar arasındaki yetki izolasyonu TALOST ID çekirdeğinde uygulanmaktadır; DEV ortamındaki bir istemci ile canlı kullanıcılar giriş yapamaz.

İlgili Sayfalar

• 02. Hızlı Başlangıç
• 03. Uygulama Kaydı ve Ortamlar
• 07. Lisans ve Entitlement Kontrolü

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/lib/billing/entitlement-contract.ts