Bundles/Internal/Backstage — Panel çekirdeği: sidebar, e-posta ve ayar mimarisi

Doğrulanan kod tabanı: d49b4413 (dal feat/fw-license-master) · Tarih: 2026-10-05 · Yayın: 0.9.7 = bu commit + sonrası; belge yalnız doğrulama anındaki kodu anlatır
Kaynak klasör: Bundles/Internal/Backstage/ — 24 *.php + 12 *.rbn.php görünüm.
Envanter: 24 php dosyasının 24'ü bu belgede anlatıldı.
Belge tek dosyadır çünkü hiçbir alt dal 20 *.php eşiğini geçmez
(SPEC §1 "alan büyükse (≥20 php)" kuralı; en büyük alt dal Controllers/ = 4).

1. Ne işe yarar, kimler kullanır

Backstage, panelin kendisini ayarlayan modüldür — sitenin içeriğini değil,
yönetim arayüzünü yönetir:

1. Sidebar — panel menülerinin kategori + hiyerarşik menü ağacı (rol süzgeçli).
2. E-posta — SMTP/gönderen/genel e-posta ayarları ve test e-postası gönderimi.
3. Ayar Mimarisi — z_settings ve z_setting_groups tablolarının yapısal
   yönetimi: alan ekleme, tip/etiket/rol/yardım metni düzenleme.

Modül diğer modüllerin ayar verisini de okur (BackstageService::getEmailSettings()
repository('project.settings') üzerinden email grubunu çeker), ama yazma
yetkisi yalnız kendi alanlarındadır.

Kimler çağırır: geliştirici paneli (#[Module(panel:'developer', context:'panel')],
BackstageController.php:15).

2. Klasör/dosya envanteri (24 php)

2.1 Controllers/ (4)

2.2 Services/ (2)

2.3 Providers/ (3)

2.4 Handlers/ (1)

2.5 Models/ (2)

2.6 Views/ (12)

Kapsama: 24/24.

3. Akış

3.1 Panel sidebar'ı üretimi

bir panel isteği
  → SidebarService::getStructure($userRole)              SidebarService.php:33
      → SidebarProvider::getSidebarStructure($userRole)  SidebarProvider.php:37
          → cache()->remember("sidebar_{$activeProject}_{$userRole}", …)   :53
              ├─ SidebarCategoriesModel: is_active=1, order_num ASC          :54-58
              ├─ her kategori için getMenusForCategory()                     :63
              │    ├─ SidebarMenusModel: category_id + parent_id=0 + is_active=1
              │    │    + order_num ASC                                     :86-92
              │    ├─ checkRoleAccess($menu['required_role'], $userRole)     :96
              │    └─ children: parent_id = $menu['id'], is_active=1         :101-106
              └─ sonuç: [{name, icon, menus:[…]}]                            :66-70

Rol kapısı (SidebarProvider.php:192):

required_role boşsa           → true
userRole === 'developer'      → true (geliştirici her şeyi görür)
aksi halde: AuthRole::ROLES[$userRole]['level'] >= AuthRole::ROLES[$required]['level']

3.2 Sidebar yazma ve atomik sıralama

POST backstage/sidebar/category/save
  → SidebarController::categorySave()                SidebarController.php:65
      → request->form(['category_name' => 'required'])
      → $this->service->saveCategory($data)           SidebarService.php:49
          → SidebarProvider::saveCategory()           SidebarProvider.php:162
              ├─ category_slug yoksa turkishSlug(category_name)   :165-167
              ├─ BaseModel::fillProjectKeyIfMissing($data)        :169
              └─ SidebarCategoriesModel->save($data)              :171
          → başarılıysa clearCache()                   SidebarService.php:53

POST backstage/sidebar/menu/reorder  → 'bulkOrder' (BulkControllerTrait)
  → SidebarHandler::reorder('menu', $ids)             SidebarHandler.php:44
      ├─ field = 'category' ? 'category_order' : 'menu_order'     :46-47
      ├─ beginTransaction()                            :49
      ├─ her id için update(id, [field => index+1]); başarısızsa rollBack + false  :52-57
      └─ commit() / catch → rollBack + false           :58-63

3.3 E-posta ayarları ve test gönderimi

GET backstage/email
  → EmailController::index()                          EmailController.php:18
      → BackstageService::getEmailSettings()          BackstageService.php:21
          → repository('project.settings')->fetch([group_key=>'email',
                                                    project_key=>active_project_key()])   :24-27
          → beş kümeye ayrıştırır: smtp / sender / general / enabled / mapped   :29-52
      → render('Emails/index', array_merge($emailData))         EmailController.php:22

POST backstage/email/test-mail
  → EmailController::testMail()                       EmailController.php:63
      → settings = service('settings')->read('email')             :65
      → targetEmail = settings['email_admin_address'] ?? null      :66
      → service('rbnEmail')->sendTemplate('test_connection', $targetEmail, $data)  :78
          $data = ['time' => now('d.m.Y H:i:s'),
                   'site_name' => service('seo')?->get('site_title') ?? 'RBN Framework']  :73-76
      → Route->handleResult($result, [success_message, error_message])  :81-84

3.4 Ayar mimarisi

GET backstage/settings/group/{id}
  → SettingsArchitectController::group($id)           SettingsArchitectController.php:27
      → BackstageService::getGroupWithSettings($id)   BackstageService.php:80
          → fetch(['target'=>'groups','id'=>$id]) → ilk kayıt
          → fetch(['group_id'=>$id]) → alanlar        :93-95
      → render('Settings/group_settings', ['group'=>…, 'settings'=>…])   :36

POST backstage/settings/createSetting
  → createSetting()                                   :87
      → request->form([11 kural])                     :91-103
      → BackstageService::createSetting()             BackstageService.php:106
          → CrudSettingsProvider::createSetting()     CrudSettingsProvider.php:18
              ├─ unset(redirect_url, view, id)        :21
              ├─ setting_key yoksa: turkishSlug(label_tr) → '-' yerine '_'   :23-26
              ├─ is_active yoksa 1                    :27
              ├─ field_options boşsa null             :30-32
              └─ SettingsModel->create($data)         :34

4. Yapılandırma / ayar anahtarları ve sabitler

5. Tuzaklar ve kurallar (kodda görülen, ölçülmüş)

1. Kök Module attribute'inde service: yok. BackstageController'da
   #[Module(name:'backstage', data:…, panel:'developer', context:'panel')]
   (BackstageController.php:15). SyshubController ve WebhubController service: bildiriyor.
   Kök controller $this->service kullanmadığı için sorun çıkmıyor; alt modüller
   SubModule attribute'inden çözüyor (ComponentContext.php:52).
2. SidebarProvider::afterBoot() URI'ye bakar. str_contains($uri, '/category') ⇒
   SidebarCategories, aksi halde /menu ⇒ SidebarMenus (SidebarProvider.php:25).
   URI ikisini de içermiyorsa SidebarMenus kalır. Bu, aynı provider'ın iki modeli
   karıştırmasına dayanır — getCategories()/getParentMenus() açık model adı kullandığı
   için etkilenmez.
3. Sıralama alanı ikiye ayrılmış. Okuma order_num (SidebarProvider.php:57,:90),
   yazma menu_order/category_order (SidebarHandler.php:47). Sıralama arayüzü ikinci alanı
   doldurduğunda panelde hiçbir görünüm değişmez; tersi de doğrudur.
4. Alt öğe koruması sessiz false döner. deleteCategory() menüsü olan kategoriyi
   silmez (SidebarHandler.php:68), deleteMenu() alt menüsü olanı silmez (:76-77).
   Webhub'taki FrontendMenuProvider::destroy() ile aynı desen. Kullanıcıya neden
   söylenmediği için controller mesajı geneldir.
5. reorder() transaction'ı model üzerinden yürütüyor. $model->beginTransaction()
   (SidebarHandler.php:49) — model nesnesi üzerinden, yani bağlantı bu modelin
   bağlandığı PDO'da. update() çağrıları aynı modelde olduğu için tutarlıdır; farklı bir
   bağlantıya kaçarsa commit/rollback etkisiz kalır (kodda böyle bir çağrı yok).
6. Yazma iki farklı servise dağılmış durumda. SidebarService::saveCategory() →
   SidebarProvider::saveCategory(); SidebarHandler::saveCategory() ise ayrı bir
   yol (SidebarHandler.php:20). Handler, ModuleData.php:34'te handlers.sidebar olarak
   kayıtlı olsa da hiçbir controller'dan çağrılmıyor — kayıtlı ama kullanılmıyor.
7. BackstageService okumada repository, yazmada provider kullanıyor. getGroups() ve
   getSettingsRaw() → repository('project.settings')->fetch() (:61,:71);
   createSetting() vb. → provider('CrudSettingsProvider') (:108,:111,:116,:120,:145).
   Bu, Anayasa §8'in repository kuralıyla uyumlu tek yazma kapısıdır.
8. fetch() sözleşmesi: target anahtarı hedef tabloyu seçer. fetch(['target'=>'groups'])
   grup tablosunu, fetch(['group_id'=>$id]) ayar tablosunu okur (BackstageService.php:58,:94).
9. getSettingsGroup() JOIN'de tablo ön ekini zorlar. select('z_settings.*') ve
   join('z_setting_groups', …) (BackstageProvider.php:57) — tablo ön eki kodda
   gömülü; ön ek değişirse bu sorgu sessizce bozulur.
10. CrudSettingsProvider "parazit koruması" her metotta tekrarlanır.
    unset($data['redirect_url'], $data['view'], $data['id']) (:21,:42,:57,:66) —
    id de silindiği için updateSetting() çağırdığı $id argümandan gelir; veri
    dizisindeki id yok sayılır.
11. bulkUpdateSettings() önbellek anahtarları eksik. Yalnız settings_group_seo ve
    settings_group_system düşürülür (:130-131). email grubu toplu güncellendiğinde
    önbellek düşmez — EmailController::updateMailSettings() tam olarak bu yolu kullanır
    (EmailController.php:97).
12. testMail() email_admin_address yoksa hiç göndermez, ayar önce kaydedilmelidir
    (EmailController.php:68). site_name kaynak olarak service('seo')?->get('site_title')
    kullanılır (:75) — bu anahtar Webhub'ın yazdığı meta-title/site-title ile aynı değildir.
13. EmailController::updateMailSettings() iki senaryo, iki doğrulama. settings dizisi
    varsa doğrulamasız toplu yazma (:96-99); yoksa 8 kurallu yapısal güncelleme
    (:102-113). Ham request->input('settings') kullanıldığı için toplu yolda beyaz liste yok.

6. Örnek (gerçek koddan)

// Bundles/Internal/Backstage/Handlers/SidebarHandler.php:44-64
public function reorder(string $type, array $ids): bool
{
    $model = ($type === 'category') ? $this->SidebarCategoriesModel : $this->SidebarMenusModel;
    $field = ($type === 'category') ? 'category_order' : 'menu_order';

    $model->beginTransaction();

    try {
        foreach ($ids as $index => $id) {
            if (!$model->update((int) $id, [$field => $index + 1])) {
                $model->rollBack();
                return false;
            }
        }
        $model->commit();
        return true;
    } catch (Exception $e) {
        $model->rollBack();
        return false;
    }
}

// Bundles/Internal/Backstage/Providers/CrudSettingsProvider.php:18-35
public function createSetting(array $data): int|bool
{
    // 🛡️ [PARASITE PROTECTION] - Veri tabanında olmayan UI alanlarını temizle
    unset($data['redirect_url'], $data['view'], $data['id']);

    if (empty($data['setting_key']) && !empty($data['label_tr'])) {
        $slug = $this->helper('text')->turkishSlug($data['label_tr']);
        $data['setting_key'] = str_replace('-', '_', $slug);
    }
    $data['is_active'] = $data['is_active'] ?? 1;

    // 🛡️ [JSON PROTECTION] - Boş gelen JSON alanlarını null yap
    if (isset($data['field_options']) && empty($data['field_options'])) {
        $data['field_options'] = null;
    }

    return $this->SettingsModel->create($data);
}

7. İlgili belgeler

• Core/Base/README.md — BaseComponent, uydurma özellik çözümü
• Core/Base/Services.md — BaseService / BaseProvider sözleşmeleri
• Core/Database/Repositories.md — SettingsRepository::fetch()
• kavramlar/02-yapilandirma.md — z_settings / z_setting_groups şeması
• acik-sorular.md