---
name: evrensel-finans-uzmani
description: Evrensel Finans Raporlama projesinin mimarisi, veri akışı, hesap eşleştirmeleri ve bilinen tuzakları hakkında uzman asistan. Kod yazarken bu kuralları uygular.
---

# Evrensel Finans Raporlama — Proje Uzmanı

Bu skill, projenin teknik kurallarını ve mimarisini bilir. Kod değişikliği yaparken bu kurallara uygunluğu denetler.

> **Ön Kontrol:** Kritik UI değişiklikleri yapmadan önce `scripts/audit-charts.cjs` dosyasını çalıştırarak güvenlik kurallarına uyumu denetle.
> ```bash
> node .agents/skills/evrensel-finans-uzmani/scripts/audit-charts.cjs
> ```

---

## 1. Mimari Kurallar

### Veri Akışı (Tek Yönlü)
```
MSSQL (Wolvox) → C# Agent → Supabase (reports/unified_financial_records) → React Frontend
```
- **Agent** her 15 dakikada `data_mappings.source_sql` sorgularını çalıştırır
- **Frontend** sadece Supabase'den okur, asla MSSQL'e doğrudan bağlanmaz
- **DataContext.tsx** tüm veri state'lerini yönetir — sayfalar `useData()` ile okur

### State Yönetimi
- Tüm finansal veriler `DataContext.tsx` içinde tutulur
- Sayfalar kendi fetch'lerini YAPMAZ — `useData()` hook'u kullanır
- `refreshKey` değiştiğinde tüm bağımlı sayfalar güncellenir
- `dateRange` değişikliği otomatik re-fetch tetikler

### Bileşen Hiyerarşisi
```
App.tsx → AuthContext → DataContext → Router → Pages → Components
```

---

## 2. Supabase Sorgu Kuralları

### Tablo Seçimi
| Öncelik | Tablo | Kullanım |
|---------|-------|----------|
| 1 | `reports` | Ana veri tablosu, `data_source_id` ile filtrelenir |
| 2 | `unified_financial_records` | Fallback, `organization_id` ile filtrelenir |

### PostgREST Kısıtlamaları
- **Max rows:** 1000 (tek sorguda)
- **Çözüm:** `report_type` bazında paralel sorgular veya `range()` ile pagination
- **Pagination limiti:** `MAX_PAGES = 5` (sonsuz döngü koruması)
- **Deferred fetch:** Ağır sorgular (FIFO vb.) `setTimeout(3000)` ile ertelenir

### Tarih Normalizasyonu
- Tüm tarihler `12:00:00 UTC` olarak normalize edilir
- `DateTime.SpecifyKind(value, DateTimeKind.Utc)` — Agent tarafında
- Frontend'de `toISOString().split('T')[0]` ile gün bazında karşılaştırma

---

## 3. Hesap Eşleştirmeleri

> Referans implementasyon: `examples/equity-calculation.ts`

### Bilanço (balance_sheet)
| Hesap | account_name | Sınıf |
|-------|-------------|-------|
| 100 | 100 KASA | Dönen Varlık |
| 102 | 102 BANKALAR | Dönen Varlık |
| 103 | Verilen Çekler | Dönen Varlık (–) |
| 108 | 108 POS TAHSILATLARI | Dönen Varlık |
| 120 | 120 ALICILAR | Dönen Varlık |
| 121 | Alacak Senetleri | Dönen Varlık |
| 150 | 150 ILK MADDE VE MALZEME | Stok |
| 153 | 153 TICARI MALLAR | Stok |
| 300 | 300 BANKA KREDİLERİ | Kısa Vadeli Kaynak |
| 320 | 320 SATICILAR | Kısa Vadeli Kaynak |
| 360 | 360 ÖDENECEK VERGİ VE FONLAR | Kısa Vadeli Kaynak |
| 361 | 361 ÖDENECEK SGK | Kısa Vadeli Kaynak |

### Gelir/Gider (income_statement)
| Hesap | account_name |
|-------|-------------|
| 600 | 600 YURTİÇİ SATIŞLAR |
| 601 | 601 YURTDIŞI SATIŞLAR |
| 770 | 770 GENEL YÖNETİM GİDERLERİ |

### Öz Kaynak Formülü
```
Dönen Varlıklar = KASA + BANKALAR + POS + ALICILAR + ALACAK SENET + STOK150 + STOK153
Kısa Vadeli = BANKA KREDİ + SATICILAR + VERGİ + SGK
Öz Kaynaklar = Dönen Varlıklar - Kısa Vadeli
Dönem Net Karı = Şimdiki Öz Kaynaklar - Bir Ay Önceki Öz Kaynaklar
```

---

## 4. Bilinen Tuzaklar ve Çözümleri

### ⚠️ React Error #185 (Maximum Update Depth)
**Neden:** Recharts `ResponsiveContainer` + yoğun state güncellemeleri
**Çözüm:**
- `SafeResponsiveContainer` → sıfır hook, `window.innerWidth` ile genişlik
- Ağır fetch'ler (FIFO vb.) `setTimeout(3000)` ile ertelenir
- Pagination: `MAX_PAGES` limiti ile sonsuz döngü koruması
- `ResponsiveContainer` doğrudan import EDİLMEZ

> Doğru kullanım örnekleri: `examples/safe-chart-implementation.tsx`

### ⚠️ Supabase AbortError
**Neden:** React Strict Mode veya hızlı navigasyon
**Çözüm:** `catch` bloğunda `e.name === 'AbortError'` kontrolü → sessizce yoksay

### ⚠️ Backfill Döngüsü
**Neden:** Boş SQL sonucu, kayıt "eksik" olarak tekrar görünür
**Çözüm:** `amount=0` ile kayıt yazılır → "eksik" sayılmaz

### ⚠️ Türkçe Karakter Normalizasyonu
**Çözüm:** `cleanStr()` fonksiyonu: İ→I, Ş→S, Ü→U, Ö→O, Ç→C, Ğ→G

---

## 5. Deployment Kuralları

### Git → Vercel (Otomatik)
```bash
git add . && git commit -m "açıklama" && git push
# Vercel otomatik deploy alır (~2 dk)
```

### Doğrulama
- Deploy sonrası `Cmd+Shift+R` ile hard refresh
- Konsol'da Error #185 kontrolü
- Network tab'da istek sayısı kontrolü (FIFO ≤ 5 istek)

### Agent (Lokal Mac)
```bash
cd ~/EvrenselFinansAgent && dotnet run
```

---

## 6. Kod Yazma Kuralları

### useEffect Disiplini
- [ ] Dependency array'de **object/array** reference olmasın (sonsuz döngü riski)
- [ ] Ağır fetch'ler `setTimeout` ile ertelensin
- [ ] Pagination döngüleri `MAX_PAGES` limiti ile korunsun
- [ ] `AbortError` sessizce yakalansın

### Recharts Kuralları
- [ ] `ResponsiveContainer` KULLANMA — `SafeResponsiveContainer` kullan
- [ ] `height` prop her zaman **sayısal** olsun (`height={400}`, asla `height="100%"`)
- [ ] Pie chart'lar direct `PieChart` ile render edilsin (container yok)

### Supabase Kuralları
- [ ] `supabaseRest()` veya `safeFrom()` kullan — doğrudan `supabase.from()` KULLANMA
- [ ] Report type bazında paralel sorgular: `Promise.all([...reportTypes.map(...)])`
- [ ] `data_source_id` = `db4ee891-d031-4da0-a9c5-c470b76da193`

### Component Kuralları
- [ ] `useCallback` ile handler wrap'le
- [ ] `React.memo` ağır bileşenler için
- [ ] Render path'de `console.log` yok (sadece `debugLog` ile)

---

## 7. Dayanıklılık ve Hata Yönetimi (Resilience)

### Bağlantı Kesintisi Yönetimi
- Veri tabanı erişim sorunlarında (`ERR_NAME_NOT_RESOLVED`, `502 Bad Gateway`) sistem çökmemeli
- React Error Boundary katmanları ile kullanıcıya anlamlı hata mesajı gösterilmeli
- `supabaseRest()` fonksiyonu otomatik retry (exponential backoff, max 3 deneme) uygular

### Sessiz Fallback Mekanizması (Graceful Degradation)
- Eksik tablolar (ör: `app_labels` 404 dönerse) → sessizce boş array döner
- Şema değişiklikleri → `normalized_amount ?? amount` fallback zinciri
- Cache'den stale veri gösterilir, arka planda taze veri çekilir (SWR pattern)

---

## 8. İleri Seviye Finansal Mühendislik

### Şeffaf Hesap Eşleştirme (Formula Transparency)
- Dashboard KPI'ları hangi Wolvox hesap kodlarından (100, 102, 300 vb.) beslendiğini gösterir
- `data_mappings` tablosu hesap kodu ↔ SQL sorgusu eşleştirmesini tutar
- `MappingEditor` bileşeni ile admin kullanıcılar SQL sorgularını düzenleyebilir

### Dinamik Özkaynak Modellemesi
- Dönen varlıklar ve kısa vadeli kaynaklar arasındaki fark canlı hesaplanır
- Dönem net kârı: mevcut öz kaynaklar − bir ay önceki öz kaynaklar
- Sermaye (500): öz kaynaklar − dönem net kârı

> Referans: `examples/equity-calculation.ts`

---

## 9. Otonom Analiz ve Raporlama

### Agent Döngüsü (15 dk)
- C# Agent her 15 dakikada MSSQL'den veri çeker ve Supabase'e yazar
- Lokal `checkpoint.txt` ile backfill ilerleme takibi
- 23:59 döngüsü: gece yarısı otomatik günlük snapshot

### Anomali Algılama (Planlanan)
- Günlük veri değişimlerinde belirli eşiği aşan sapmalar otomatik raporlanacak
- Kritik nakit seviyelerinde Supabase Edge Functions ile push bildirim (yapılacak)

---

## 10. Performans ve Modernizasyon

### Grafik Render Motoru
- `SafeResponsiveContainer` → sıfır hook, sıfır `ResizeObserver`
- Recharts `ResponsiveContainer` projeden tamamen çıkarılmıştır
- `window.innerWidth` tabanlı genişlik hesabı (RAF-throttled resize)

### Frontend Build Optimizasyonu
- Vite code splitting: lazy-loaded sayfa bileşenleri
- SWR cache: `localStorage` tabanlı stale-while-revalidate
- Deferred loading: ağır veri setleri (FIFO) 3 saniye gecikme ile yüklenir

### Tailwind Geçişi (Planlanan)
- CDN → PostCSS/JIT derleme mimarisine geçiş yapılacak
- `tailwind.config.js` ile tema renkleri `resources/branding.json` ile senkronize edilecek

---

## 11. Güvenlik ve Yetkilendirme

### Kullanıcı Rolleri
| Rol | Yetkiler |
|-----|----------|
| `SUPER_ADMIN` | Tüm organizasyonlara erişim, kullanıcı yönetimi |
| `admin` | Kendi organizasyonu: raporlar, ayarlar, mapping düzenleme |
| `user` | Raporları görüntüleme, simülasyon |
| `viewer` | Sadece görüntüleme |
| `Partner` | İş ortağı erişimi — sınırlı raporlar |
| `Yönetici` | Yönetim kurulu görünümü |

### Organizasyonel İzolasyon
- RLS (Row Level Security) ile her organizasyon sadece kendi verisini görür
- `organization_id` filtresi tüm sorguların temelini oluşturur
- `profiles.role` ile yetki kontrolü (Supabase Auth + RLS)

### WYSIWYG Export Standartı
- Kullanıcının ekranda gördüğü filtrelenmiş veri birebir PDF/Excel'e aktarılır
- Türkçe karakter desteği: jsPDF + Roboto font (Latin Extended)
- Branding: `resources/branding.json` renk ve meta bilgileri kullanılır

> Referans: `examples/wysiwyg-export-pattern.tsx`

---

## Skill Dosya Yapısı

```
evrensel-finans-uzmani/
├── SKILL.md                    ← Bu dosya (ana talimat)
├── scripts/
│   ├── audit-charts.cjs        ← Grafik güvenlik denetimi (5 kural)
│   └── check-integrity.cjs     ← Supabase bağlantı/veri testi
├── examples/
│   ├── equity-calculation.ts    ← Öz kaynak hesaplama referansı
│   ├── safe-chart-implementation.tsx  ← Doğru grafik kullanımı
│   └── wysiwyg-export-pattern.tsx     ← PDF/Excel export pattern
└── resources/
    ├── branding.json            ← Renk paleti, tipografi, PDF meta
    ├── labels-init.sql          ← app_labels tablo ve başlangıç verisi
    └── pdf-fonts.md             ← Türkçe font gömme talimatları
```