Roller & Add-On Erişimi | TotalApp Yardım

1. Kavramsal Model

Sistem dört katmanlı bir hiyerarşi üzerine kuruludur: Tenant (Kiracı) → Purchased Packages (Entitlement) → Domain Capabilities → Roles → Employee assignedRoles (hat).

Kavram	Nedir?
Domain	Bir add-on'un RBAC etiketi (LEGAL, HEALTHCARE, MOM…). Her rol ve capability bir domain'e aittir.
Capability	Atomik izin. `domain:resource:action` slug'ı (`legal:contract:approve`).
Role	Capability'lerin isimli demeti (Senior Partner, Plant Manager). Domain etiketlidir.
assignedRole (hat)	Bir kişiye atanan rol. Bir kişi birden fazla domain'de rol taşıyabilir ("çoklu şapka"). Atandığı anda rolün capability'leri kopyalanır (auto-grant).
Entitlement (paket)	Tenant'ın aktifleştirdiği add-on paketleri.

Capability ≠ Skill

Capability = kişinin platformda ne yapabileceği (sistem izni). Skill = kişinin kişisel yetkinliği (Python, Laparoskopi, Sözleşme Hukuku) — bu HR tarafında yönetilir, RBAC'ı etkilemez. Rol → capability bağlanır; bir kişiye "Paralegal" rolü atandığı an rolün tüm capability'lerini otomatik kazanır.

2. Merkezi Olmayan Rol Yönetimi

Her add-on kendi Roles ekranına sahiptir ama tüm roller tek bir tenant deposunda yaşar. Her rol arka planda domain etiketiyle kaydedilir — kullanıcı formda "type" seçmez, etiket ekran context'inden gelir (implicit tagging).

Add-on Kapsama (Scoping)

Bir add-on ekranı yalnızca GLOBAL + kendi domain'inin rollerini ve capability'lerini gösterir. Legal yöneticisi Healthcare capability'lerini göremez — güvenlik sınırı.

HR Master Matrisi

HR → Organizasyon → Roller ve Yetkiler ekranı TÜM domainlerin rollerini tek matriste gösterir, domain filtresi sunar ve add-on rolleri üzerinde nihai override sağlar.

Out-of-the-Box Roller

Bir add-on paketi aktif olduğunda, Roles ekranı ilk açıldığında sistem varsayılan rolleri otomatik kurar. Müşteri hiçbir rol tanımlamadan doğrudan Add Staff diyebilir.

3. Paket Yetkilendirme (Entitlement)

Her tenant'ın hangi add-on'ları aktifleştirdiği tenant başına saklanır (activePackages). Uygulama tarafı kendi entitlement'ını okur; admin tarafı (cross-tenant) herhangi bir tenant'ınkini yazabilir — aynı dosya. Böylece admin'in aktifleştirdiği şey, ModuleGuard'ın okuduğu şeydir (tek SSoT).

4. ModuleGuard — İki Katmanlı Ekran Koruması

Her add-on ekranı <ModuleGuard> ile sarılır ve AppLayout içinde render edilir — engellenen ekran boş sayfa/500 yerine tatlı bir Upsell/403 bileşeni gösterir.

Level 1 — Entitlement (Paywall)

Tenant bu add-on paketini satın almış mı? Hayır ise → Upsell/Upgrade ekranı: "… modülü paketinizde tanımlı değil. Planınızı yükseltin veya yöneticinizle iletişime geçin."

Level 2 — RBAC (Governance / Operational)

System/Governance (Roles, Staff-Master) yalnızca admin'e açıktır; Operational (Jobsites, Zones, Work Centers, Fields…) o domain'de rol taşıyan personele açıktır. İzin yoksa → 403 Access Denied.

Durum	Governance	Operational
Admin (veya local/demo)	✅ Girer	✅ Girer
Domain rolü olan personel	❌ 403	✅ Girer
Domain rolü olmayan personel	❌ 403	❌ 403
Paket aktif değil	🔒 Paywall	🔒 Paywall

5. UI Görünürlük — Governance Kartlarını Gizleme

403 yeterli değil; yetkisiz kullanıcı governance kartlarını hiç görmemeli. Sidebar ve My Apps bu kartları non-admin'e render etmez. Her add-on'un setup ekranları iki ayrı başlıklı gruba bölünür: OPERATIONAL SETUP (operasyonel çalışanlara açık) ve ADMINISTRATION & ACCESS (Roles + Staff-Master; sadece admin).

6. Staff Assignment — Auto-Grant & Çoklu Şapka

Auto-grant: bir rol seçildiğinde rolün capability'leri kişiye otomatik eklenir; ayrıca HR'a gidip yetki verdirmek gerekmez.
Çoklu şapka (+ Add Existing Employee): var olan Employee başka bir add-on'a eklenir; yeni kayıt oluşmaz. Örn. bir kişi hem LEGAL: Senior Partner hem HEALTHCARE: Advisor şapkasını taşıyabilir.
Detach: kişi ekipten çıkarıldığında o domain'in şapkaları kaldırılır (Employee kaydı ve HR geçmişi silinmez).

7. Path & Başlık Standardı

URL jenerik ve domain-prefixlidir (/{domain}/roles, /{domain}/staff); başlık domain'e özeldir (/legal/staff → "Legal Team", /mom/staff → "Plant Workers").

Sık Sorulanlar

Local'de neden her ekrana girebiliyorum ama rol atamadım?

Local/skipped/no-JWT oturum admin sayılır — tenant RBAC context'i olmadığı için uygulama tam kullanılabilir. Gerçek tenant kullanıcısında RBAC aynen çalışır.

Normal bir çalışan Roles ekranını neden hiç görmüyor?

Roles governance ekranıdır; bu kartlar non-admin'e render edilmez, direkt URL'e giderse de 403 alır.

Admin'in aktifleştirdiği paket ile uygulamanın gördüğü aynı mı?

Evet — ikisi de aynı entitlement dosyasını okur/yazar. Ayrı merkezi dosya yoktur.