Debug Sistemi Geliştirme Planı

Geliştirme Haritası

#	Konu	Tür	Öncelik	Migration
1	Teknik Terimler — Gizli Kod Adları	JS	Yüksek	—
2	Panel Küçültme (Minimize / Simge Modu)	JS	Yüksek	—
3	Sayfa Geçişinde Şarkı Başlamıyor — Bug Fix	Bug	Kritik	—
4	Kopyala → Log Dosyası Oluştur	JS + PHP	Yüksek	—
5	Users Tablosu — is_debugger Alanı	Migration	Yüksek	✋ Onay Gerekli
6	Admin Panel — Kullanıcıya Debug Atama	PHP	Orta	5'e bağlı
7	Debug Görünürlük Kontrolü (Premium / Root)	JS + PHP	Orta	5'e bağlı
8	Rapor Gönderince Otomatik Kapanma	JS + PHP	Orta	—
9	Daha Fazla Veri Toplama (Genişletilmiş Metrikler)	JS	Düşük	—

1

Teknik Terimler — Gizli Kod Adları

Panelde görünen etiketler değişiyor. "Donma", "Gecikme" gibi terimler kimsenin anlamayacağı kod adlarıyla değiştirilecek.

Basit Anlatım

Müşteri paneli açıp "bakıyorum donuyor, gecikiyor" gibi yorum yapmasın diye tüm etiketler teknik kod adlarıyla değiştirilecek. Etiketler bizim sözlüğümüze göre olacak — dışarıdan bakan anlayamaz.

Terim Değişim Tablosu

Eski (Görünen)	Yeni Kod Adı	Teknik Anlamı
Gecikme	PROC-HOLD	Process Hold — işlem tutulması (≥100ms blokaj)
Donma	SYN-STALL	Synchronization Stall — senkronizasyon durması
Son Gecikme	LAST PROC-HOLD	En son yakalanan process hold olayı
Gecikme Sayısı	PHC	Process Hold Count
Şarkı Geçişi	SEQ-DELTA	Sequence Delta — dizi değişimi
Crossfade	XMIX	Cross-Mix — çapraz karıştırma
Fallback	CHAIN-RTRN	Chain Return — zincir geri dönüşü
Cache	APC	Audio Pool Cache
Eski Audio (Stale)	ORPHAN-AE	Orphaned Audio Element — sahipsiz audio kaynağı
Bellek	HEAP	Heap Memory — yığın bellek
Preload	PRE-STAGE	Pre-staging — ön hazırlık
Bant Genişliği	BW-EST	Bandwidth Estimate — bant genişliği tahmini
Aktif Kalite	QL-ACTIVE	Quality Level Active
GC Temizle	MEM-SWEEP	Memory Sweep — bellek süpürmesi
Sebep	ROOT-CAUSE	Kök neden analizi
Kaynak	RES-POOL	Resource Pool
Oturum	SES-STAT	Session Statistics
Güncelleme	TICK	Son güncelleme zamanı

    // Değişecek dosya: performance-debug.js

    // Sadece innerHTML içindeki etiket metinleri değişiyor

    // Değişken adları, fonksiyon adları AYNI kalıyor

2

Panel Küçültme — Minimize / Simge Modu

Kullanıcı paneli küçültebilir, sağ alta küçük bir rozet olarak kalır.

Nasıl Çalışacak?

Normal Mod

⚡ DEBUG v4 — ×

... panel içeriği ...

Minimize Modu (sağ alt köşe)

⚡ DBG ▲

Teknik Detaylar

• Header'a — (minimize) butonu ekleniyor (× butonunun yanına)
• Minimize: Panel içeriği gizlenir, küçük floating badge görünür (sağ alt)
• Badge'e tıklayınca panel açılır, badge kaybolur
• State: isMinimized değişkeni + localStorage'da hatırla
• × butonu → tamamen kapatır (hide())
• — butonu → minimize eder

3

🐛 Kritik Bug: Sayfa Geçişinde Şarkı Başlamıyor

Debug açıkken başka sayfaya gidince albüm/playlist başlatılınca şarkılar çalmıyor.

Basit Anlatım

Debug paneli açıkken başka sayfaya geçip müzik başlatmaya çalışınca çalmıyor. Bunun nedeni Livewire'ın sayfa geçişi sırasında ?debug=1 parametresini kaldırması ve init() fonksiyonunun tekrar çalışmaması.

Kök Neden (ROOT-CAUSE) Analizi

    // Mevcut kod (SORUNLU):

    function init() {

      setupEventListeners();

      const params = new URLSearchParams(window.location.search);

      if (params.get('debug') === '1') { setTimeout(show, 1000); }

    }

    // Livewire navigate event'i init()'i tekrar çağırmıyor!

    // SPA navigasyonunda URL parametresi kaybolabilir

Çözüm

    // Livewire SPA navigation event'i dinle:

    document.addEventListener('livewire:navigate', () => {

      // Debug session'da açıksa → sayfa geçişinde de çalışmaya devam et

      if (sessionStorage.getItem('mz_debug_active') === '1') {

        setTimeout(() => { if (!isVisible) show(); }, 500);

      }

    });

    // show() çağrıldığında sessionStorage'a yaz

    // hide() çağrıldığında sil

4

Kopyala → Log Dosyası Oluştur

Kopyala butonuna basınca hem panoya kopyalansın hem de backend'de log dosyası oluşturulsun.

Log Dosya Yolu

        storage/logs/debug-mod/

          2026/

            02/

              19/

                user-{id}/

                  report-14-35-22.log

                  report-15-10-05.log

API Endpoint

        POST /api/debug/save-log

        Body: {

          report: "...", // metin rapor

          data: {...},   // JSON ham veri

          user_agent: ".."

        }

        Auth: Bearer token veya session

Log Dosya İçeriği

    ═══════════════════════════════════════════

    MUZIBU DEBUG REPORT — 2026-02-19 14:35:22

    User: 42 | Session: abc123 | Tenant: 1001

    ═══════════════════════════════════════════

    [Tam metin rapor]

    ───────────────────────────────────────────

    [JSON: Ham metrikler]

Frontend Değişiklik

• copyReport() → hem clipboard.writeText() hem fetch('/api/debug/save-log')
• Başarıda: "✅ Kaydedildi" butonu göster
• Hata durumunda: sadece kopyalama çalışmaya devam eder
• Log başarı mesajı panele eklenir: "📁 report-14-35-22.log kaydedildi"

5

Users Tablosu — is_debugger Alanı

✋ Migration — 3 aşamalı onay gerekli

Eklenecek Alan

        // Tenant + Central users tablosuna:

        $table->boolean('is_debugger')

          ->default(false)

          ->comment('Hata ayıklayıcı aktif mi?');

Etkilenen Tablolar

Tenant users	database/migrations/tenant/
Central users	database/migrations/

Onay Süreci:
AŞAMA 1 → Migration gerektiğini açıkla, onay al
AŞAMA 2 → Migration dosya içeriğini göster, onay al
AŞAMA 3 → "migrate çalıştırayım mı?" onay al → sonra çalıştır

6

Admin Panel — Kullanıcıya Debug Atama

UserManage sayfasına "Hata Ayıklayıcı" toggle'ı ekleniyor. Sadece root görebilir.

Değişecek Dosyalar

• Modules/UserManagement/App/Http/Livewire/UserManageComponent.php → is_debugger alanı ekle
• manage.blade.php → Sadece root'a görünen toggle switch
• Toggle: "Hata Ayıklayıcı Modu" — aktif/pasif
• Root değilse bu alan tamamen gizli

7

Debug Görünürlük Kontrolü

Kim debug panelini görebilir?

🔴

Normal Kullanıcı

?debug=1 eklese bile göremez

🟡

Premium Kullanıcı (is_debugger=true)

?debug=1 ile görebilir

🟢

Root Kullanıcı

Her zaman, her şekilde görebilir

Teknik Uygulama

    // Blade layout'a ekleniyor (temaya özel):

    @if(auth()->check() && (auth()->user()->hasRole('root') || auth()->user()->is_debugger))

      <meta name="debug-allowed" content="1">

    @endif

    // JS tarafında kontrol:

    const debugAllowed = document.querySelector('meta[name="debug-allowed"]');

    if (!debugAllowed) { /* init() çalışmaz, panel hiç oluşturulmaz */ }

Root vs. Debugger Farkı

Özellik	Root	Debugger (Premium)
Panel açma	✅	✅ (?debug=1 ile)
Manuel kapat (debug aktif kalır)	✅	❌
Rapor gönderince kapanır	İsteğe bağlı	✅ Otomatik
Rapor gönderince is_debugger=false	❌ (root kalır)	✅ Pasif olur

8

Rapor Gönderince Otomatik Kapanma

Kopyala butonuna basınca → log kaydedilir → panel kapanır → is_debugger=false olur

Akış

Kopyala'ya bas → Panoya kopyala → API: log kaydet → API: is_debugger=false → Panel kapanır

Root İstisnası

Root kullanıcılar için bu akış çalışmaz. Root kendi isteğiyle kapatabilir ama otomatik kapanma sadece is_debugger'ı true olan normal kullanıcılarda çalışır.

9

Genişletilmiş Metrikler

Daha fazla veri toplanacak — panel yeni bölümler kazanacak

Yeni Bölümler

📡NET-PROBE: Gerçek zamanlı bağlantı hızı, RTT, efektif bağlantı tipi (4G/3G/WiFi)
🖥️SYS-INFO: CPU çekirdek sayısı, cihaz belleği, tarayıcı, platform
📊STREAM-STAT: Toplam byte indirilen, segment başarı/fail oranı
🔄NAV-CNT: Bu oturumda kaç sayfa geçişi yapıldı, hangi sayfalardan müzik başlatıldı
⚠️ERR-LOG: Console error'ları yakala, son 10 hata göster
⏱️TIME-TO-PLAY: İlk ses gelene kadar geçen süre (ms)

Genişletilmiş Log Tipleri

NET_CHANGE	Bağlantı tipi değişimi
PAGE_ENTER	Sayfa girişi (SPA)
TTP_MEASURE	Time-to-play ölçümü
JS_ERROR	Yakalanan JS hatası
SEG_FAIL	HLS segment yükleme hatası
REBUFFER	Buffer tükenip yeniden doldurma

Uygulama Sırası (Önerilen)

1. Önce Bug Fix (#3) — Sayfa geçişinde şarkı sorunu

2. Sonra Terimler (#1) + Minimize (#2)

3. Migration onayı al (#5) → Log API (#4) → Görünürlük (#7) → Admin Panel (#6)

4. Son Otomatik kapanma (#8) + Genişletilmiş metrikler (#9)

Debug Sistemi — Kapsamlı Geliştirme Planı