TEFAS Fon Analiz

Türkiye'deki yatırım, emeklilik (BES), borsa yatırım (BYF) ve girişim sermayesi (GYF) fonlarını listeleme, analiz ve karşılaştırma aracı. Fintables benzeri; veriler TEFAS'ın kamuya açık JSON API'sinden, hisse portföyleri KAP raporlarından gelir.

Canlı demo: fon.yourapiservice.com

Özellikler

• Fon listesi: 2000'den fazla fon. Getiri (1G–5Y), büyüklük ve nakit giriş-çıkışı sekmeleri; sıralama, sonsuz kaydırma
• Filtreler: arama, fon türü, kurucu (PYŞ), döviz/katılım/hisse yoğun/nitelikli fon, min büyüklük/yatırımcı, belirli bir hisseyi en az % X oranında tutan fonlar
• Fon detayı: fiyat/büyüklük/yatırımcı grafiği, net nakit akışı, varlık dağılımı, risk (volatilite)
• Risk ve getiri kalitesi: maks. düşüş ve toparlanma süresi, Sharpe/Sortino, kategorisindeki sırası, aylık/yıllık takvim getirileri; listede Risk sekmesi
• Endekslere karşı: BIST 100, USD/TRY ve gram altınla getiri kıyası; BIST 100 betası ve korelasyonu, kayan 3 aylık getiri dağılımı
• Rakipler ve örtüşme: aynı kategorideki rakip fonlar, hisse portföyü en çok örtüşen fonlar
• Karşılaştırma: en fazla 10 fon; 100'e endeksli grafik, getiri korelasyonu ve hisse örtüşme matrisi
• Hisse arama: bir hisseyi hangi fonların ne ağırlıkla tuttuğu ve tahmini TL pozisyonu
• Portföyüm: tutar (₺) ya da adet girerek portföy kur; birleşik varlık dağılımı, hisse maruziyeti, geçmiş performans, portföy volatilitesi ve fon başına risk katkısı, hedef ağırlıklara göre yeniden dengeleme (ek nakit / satış yapmadan). Adresi paylaşılabilir
• Simülasyon: "şu tarihte alsaydım?" Aylık düzenli alım (XIRR) ve tek seferlik alım, fon ve endekslerle kıyaslı; stopaj sonrası net getiri
• Hazır taramalar: en çok kazandıran hisse/BES fonları, düşük riskli yüksek getirili, en çok para girişi/çıkışı, en büyük, altın ve döviz fonları, katılıma uygun fonlar (genel, hisse, BES) (/tarama, sunucuda çizilir)
• SEO / agent: sayfa başına açıklama, canonical, Open Graph/Twitter kartı (fon başına dinamik görsel /og/fon/KOD.png), JSON-LD; DB'den sitemap.xml, AI tarayıcılarına açık robots.txt, agent'lar için llms.txt. Prod adresi SITE_URL (varsayılan canlı demo)
• Pinleme: fon listelerinde pinlenen fonlar tablonun en üstünde durur (tarayıcıda saklanır)
• Fon detayı aksiyon çubuğu: pinle, karşılaştır, portföye ekle (/portfoy?ekle=KOD), simüle et, hedef planla, PDF; kaydırırken üstte kalır
• PDF: fon detayı yazdırılarak PDF'e aktarılır
• Mobil uyumlu: hamburger menü, tek sütun kartlar, dokunmatik grafikler
• PWA ve tema: ana ekrana eklenebilir (manifest, ikonlar), service worker ile daha önce açılan sayfalar çevrimdışı da açılır; Sistem / Açık / Koyu tema düğmesi (tarayıcıda hatırlanır, yazdırırken açık)
• API ve MCP: sürümlü JSON API (/api/v1, OpenAPI: /api/v1/openapi.json) ve AI asistanları için MCP sunucusu (/mcp, Streamable HTTP; araçlar: search_funds, get_fund, funds_holding_stock, compare_funds, run_scan). Kimlik doğrulama yok, CORS açık, IP başına dakikada 60 istek. Belge: /api

Ekran görüntüleri

Fon detayı	Karşılaştırma
Portföyüm	Simülasyon
Hisseyi tutan fonlar

Mobil

Liste	Fon detayı	Karşılaştırma

Teknoloji

• Astro 7 (SSR, @astrojs/node) + React 19 adaları
• Tailwind CSS 4 + shadcn/ui (Base UI), Recharts grafikler, Geist yazı tipi
• PostgreSQL (pg), şema: db/schema.sql
• pdfjs-dist: KAP Portföy Dağılım Raporu PDF'lerini ayrıştırma
• Playwright e2e, node:test birim testleri
• Docker (Node 22 Alpine), Coolify ile deploy, GitHub Actions CI

Veri kaynakları

• TEFAS: yeni resmi JSON API (/api/funds/fonGnlBlgSiraliGetir, /dagilimSiraliGetirT). Auth ve scraper yok
• KAP: haftalık/aylık Portföy Dağılım Raporu PDF'lerinden hisse ağırlıkları
• Yahoo Finance: BIST 100, USD/TRY, gram altın (bench tablosu)

Proje yapısı

scripts/ingest.mjs    TEFAS + endeks verisini DB'ye çeker, volatiliteyi hesaplar
scripts/holdings.mjs  KAP PDF'lerinden hisse portföylerini çıkarır
src/pages/            Astro sayfaları ve API uçları (/api/funds/[tur], /api/holdings)
src/components/       React bileşenleri (FundTable, FundCharts, CompareChart, PortfolioForm, …)
src/lib/              DB sorguları, istatistik (stats.ts), veri sıkıştırma (compact.ts), biçimlendirme
db/schema.sql         Veritabanı şeması
e2e/                  Playwright senaryoları ve CI için sahte veri (seed.sql)

Kurulum

Gereksinimler: Node 22+, PostgreSQL.

npm i
export DATABASE_URL=postgres://tefas:tefas@localhost/tefas   # varsayılan bu
npm run db:init      # şema (ingest de otomatik oluşturur)
npm run ingest 400   # ~400 gün geçmiş; TEFAS dk'da 6 istek -> ~15 dk. Tekrar çalıştırınca sadece yeni günleri çeker
npm run dev          # http://localhost:4321

• 2Y/3Y/5Y getiri için tüm geçmiş çekilmez; ingest sadece o vadelerin hedef tarihi çevresindeki 1 haftalık pencereyi çeker (TEFAS en fazla 5 yıl geriye gider). Kayan tarihler her çalıştırmada tamamlanır.
• Günlük güncelleme için npm run ingest'i cron'a koyun.
• Hisse portföyü: npm run holdings. KAP 429 verdiği için yavaştır, ilk çalıştırma ~30 dk sürer.
• Endeks verisi: node scripts/ingest.mjs bench (günlük ingest sonunda otomatik çalışır).

Komutlar

Komut	Açıklama
npm run dev	Geliştirme sunucusu (4321)
npm run build / npm start	Üretim derlemesi ve sunucu
npm run ingest [gün]	TEFAS verisini çek
npm run ingest -- vol	Volatiliteyi yeniden hesapla
npm run holdings	KAP hisse portföylerini çek (her rapor holdings_hist geçmişine de yazılır)
npm run holdings -- gecmis	Fonların bir önceki KAP raporunu indirip geçmişe yaz ("önceki rapora göre değişim" hemen dolsun; bir kez, yavaş)
npm run stopaj-watch	Resmi Gazete'de yeni fon stopajı kararı ara (aşağıya bakın)
npm test	Birim testleri (PDF ayrıştırıcı, istatistik)
npm run test:e2e	Playwright e2e testleri

Stopaj oranları değişince

Simülasyondaki stopaj sonrası net getiri, alış tarihine göre dönemler ve fon grubu başına oranlardan hesaplanır: taban tablo src/lib/stopaj-rules.mjs, üstüne kaynaklardan otomatik eklenen dönemler (stopaj_rule). Oranlar Cumhurbaşkanı Kararı ile Resmi Gazete'de değişir; kararlar görüntü PDF olduğundan oranlar onları metin olarak yeniden yayımlayan kurumlardan okunur. Anahtar/token gerekmez.

• Bekçi (scripts/stopaj-watch.mjs, günlük döngüde otomatik):
  1. Resmi Gazete fihristini tarar, GVK geçici 67 kararlarını stopaj_karar'a yazar (bilinmeyen karar: bekliyor).
  2. Kaynakları okur (scripts/stopaj-sources.mjs, öncelik sırasıyla): Ziraat Portföy stopaj tablosu (ana sayfadaki PDF), Garanti BBVA ve Yapı Kredi stopaj duyuruları. Bir kaynak, tablodaki tüm geçmiş dönemlerle tutarlıysa güvenilir sayılır ve yalnız son bilinen dönemden sonraki yeni dönemleri önerebilir. Güvenilir ilk kaynağın yeni dönemi stopaj_rule'a yazılır; güvenilir iki kaynak yeni dönemde ayrışırsa hiçbir şey yazılmaz. Okunamayan/çelişen kaynak atlanır, bayat kaynak zararsızdır.
  3. Bekleyen karar, yeni dönem uygulanınca uygulandi; 30 gün içinde kaynaklarda değişiklik çıkmazsa etkisiz (ör. yalnız kurumları ilgilendiren karar) olur.
• Kayıtlar stopaj: önekiyle loglanır (UYGULANDI: ..., ... tablo ile çelişiyor, ... okunamadı). Kaynak sayfası adres/düzen değiştirirse o kaynak "okunamadı" der, diğerleri işe yarar; düzeltme stopaj-sources.mjs'teki ayrıştırıcıdadır.
• Elle müdahale gerekirse STOPAJ_RULES'a satır eklenebilir; etkisiz olduğu bilinen kararlar REVIEWED'a. İlk çalıştırma Resmi Gazete'de geriye 30 gün tarar (node scripts/stopaj-watch.mjs 200 ile daha fazla).

Sayfalar ve URL'ler

• /fonlar/{yat,bes,byf,gyf}: fon listesi
• /fon/KOD: fon detayı
• /karsilastir?codes=A&codes=B: en fazla 10 fon; endeks=1 endeks çizgilerini ekler (eski ?codes=A,B biçimi de çalışır)
• /hisse ve /hisse/TICKER: hisseyi tutan fonlar
• /portfoy?f=AFT:tl:5000&f=TCD:adet:120: paylaşılabilir portföy, ayrıca localStorage'a kaydedilir
• /portfoy?ekle=KOD: fonu kayıtlı portföye boş tutarlı satır olarak ekler
• /simulasyon?codes=AFT&monthly=5000&start=2025-09-21: alım simülasyonu; /bes-simulasyon ve /hedef ile ortak sekme menüsü

Hesaplama notları

• TEFAS'ta D tarihli fon fiyatı önceki işlem gününü yansıttığı için endeks tarihleri okunurken bir işlem günü kaydırılır (getBench). Saf hesaplar src/lib/stats.ts içinde.
• Nakit akışı = pay sayısı değişimi × güncel fiyat (yaklaşık). Kategori = en büyük varlık kalemi. Varlık dağılımı sadece son gün.
• Hisse örtüşmesi = iki fonun ortak hisselerinde Σ min(ağırlık).

Performans

• Volatilite (risk) her istekte değil ingest sonunda fund_vol tablosuna hesaplanır; liste sorgusu 0,7 sn → 60 ms.
• Liste sonucu tür başına 5 dk bellekte tutulur; tabloya giden veri sıkıştırılır (src/lib/compact.ts): HTML 2,6 MB → ~0,75 MB (gzip ~145 KB).
• Arama/filtre useDeferredValue ile ertelenir; arka plan işleri nice ile düşük öncelikli çalışır.

Sınırlar

• TEFAS API'sinde yönetim ücreti, stopaj ve KAP akışı yok.
• Hisse portföyü verisi olmayan gruplar: BES fonları (KAP'ta rapor yok), nitelikli yatırımcı (özel) fonları (rapordan muaf), yazısı vektör çizili PDF yayımlayanlar (İş, Nurol, EMAA Blue, kısmen Osmanlı; OCR güvenilmez). Kalanların ~%75'i okunur. Ağırlık sütunu PDF'in kendi grup toplamıyla doğrulanır, olmazsa TEFAS hisse %'sine bakılır. npm test ayrıştırıcıyı gerçek PDF'lerle sınar.

Deploy (Coolify)

Dockerfile + start.sh: konteyner şemayı hazırlar, ingest'i günlük döngüde arka planda çalıştırır (ilk açılışta ~20 dk backfill) ve web'i 4321 portunda sunar.

Env	Açıklama
DATABASE_URL	Zorunlu. Coolify Postgres iç adresi
SHOW_DISCLAIMER=1	Opsiyonel. Header'da "yatırım tavsiyesi değildir" uyarısı gösterir; resmi dağıtımda açık, varsayılan kapalı
UMAMI_SRC, UMAMI_ID	Opsiyonel. İkisi de verilirse Umami (çerezsiz, self-host) script'i yüklenir: UMAMI_SRC=https://umami.ornek.com/script.js, UMAMI_ID=<website id>. Gizlilik sayfası buna göre değişir. Olaylar: fon-aksiyon (tip: pin, karsilastir, portfoy, simulasyon, bes, hedef, pdf), tarama-cip (slug)

Domain: fon.yourapiservice.com (Cloudflare A kaydı → sunucu IP'si, proxied).

Testler

• npm test: KAP PDF ayrıştırıcısı ve istatistik fonksiyonları için birim testleri.
• npm run test:e2e: Playwright (masaüstü ve mobil senaryolar: liste filtre/sıralama/sekme, hisse filtresi, fon detayı, karşılaştırma, /api/holdings). Yerel Postgres verisiyle build alıp 4322 portunda çalıştırır; ilk seferde npx playwright install chromium-headless-shell. Canlıya karşı: E2E_BASE_URL=https://fon.yourapiservice.com npm run test:e2e.
• CI: .github/workflows/e2e.yml her PR'da ve main push'unda Postgres servisi + e2e/seed.sql (sahte veri) ile çalışır.

Lisans

PolyForm Noncommercial 1.0.0 © 2026 Alperen Gözüm

• Kişisel, akademik ve araştırma amaçlı kullanım serbesttir.
• Ticari kullanım ve satış yasaktır (kod, fork ya da türev fark etmez). Ticari kullanım için lisans sahibiyle iletişime geçin.

Yasal uyarı

Bu proje ve ürettiği çıktılar (fiyat, getiri, sıralama, grafik, karşılaştırma) yatırım tavsiyesi değildir. Veriler TEFAS, KAP ve Yahoo Finance'ten derlenir; projeye ait değildir ve doğruluğu garanti edilmez. Yatırım kararı vermeden önce resmi kaynakları kontrol edin.

Ayrıntılar: Terms (/terms), Privacy Policy (/privacy-policy) ve LICENSE içindeki "Not Investment Advice; Data Disclaimer" bölümü.