portfolio-tracker

Bağlam ve amaç

portfolio-tracker, farklı kaynaklardaki yatırım varlıklarını ve nakit bakiyesini tek bir kişisel çalışma alanında takip etmek için geliştirildi. Uygulama, toplam değeri yalnızca fiyatlardan üretmez; alış ve satış hareketlerini korur, açık ve kapanmış pozisyonları bu hareketlerden hesaplar.

Odak noktası finansal tavsiye vermek değil, portföy verisinin nasıl modellendiğini görünür ve denetlenebilir kılmaktır. Bu nedenle işlem geçmişi, fiyat kaynağı, hesaplama ve arayüz birbirinden ayrılmıştır.

Nasıl çalışır

Kullanıcı bir varlık için alış veya satış işlemi eklediğinde kayıt önce işlem defterine yazılır. API, varlığın işlem geçmişi ile son fiyatını birleştirerek miktar, maliyet, gerçekleşmiş kâr/zarar ve gerçekleşmemiş kâr/zarar değerlerini hesaplar.

Dashboard; açık pozisyonları, kapanmış pozisyonları, nakit bakiyesini ve portföy özetini bu sonuçlardan okur. Piyasa verisi uygun olduğunda ayrı servis üzerinden alınır; uygun olmayan veya eksik sağlayıcı verisi için elle fiyat girilebilir. Fiyat yenileme hem periyodik arka plan işi hem de istek tabanlı kuyruk akışıyla desteklenir.

Sistem tasarımı

React ve TypeScript istemcisi, ASP.NET Core API ile aynı origin altında konuşur. API; EF Core aracılığıyla PostgreSQL’e erişir ve piyasa verisi gerektiğinde FastAPI tabanlı market-data-service’e HTTP isteği yapar. Python servisinin sağlayıcı seçimi ile finansal hesapların sahibi olan .NET API’nin sorumlulukları bu sayede ayrılır.

Temel veri modeli dört parçadan oluşur:

• Transactions, portföy hareketlerinin değiştirilemeyen kaynak kaydıdır.
• Assets, katalogdan gelen veya kullanıcı tarafından oluşturulan varlık tanımını taşır.
• MarketPrices, sağlayıcıdan ya da kullanıcıdan gelen en güncel fiyatı saklar.
• PortfolioPositions, arayüzün hızlı okuması için üretilen, yeniden kurulabilir pozisyon modelidir.

Öne çıkan teknik kararlar

İşlem defterini kaynak gerçek, pozisyon tablosunu ise okuma modeli olarak tutmak kritik bir seçimdir. Bir hesaplama kuralı veya fiyat verisi değiştiğinde pozisyonlar işlemlerden yeniden üretilebilir; geçmiş hareketlerin anlamı arayüz toplamlarına bağımlı kalmaz.

Maliyet hesabı ağırlıklı ortalama maliyet yöntemiyle yürütülür. Satışlar kalan maliyet tabanını günceller, gerçekleşmiş sonuçlar ayrı izlenir ve küçük miktar kalıntıları kapanış toleransıyla ele alınır. Hesaplama kuralları UI içinde tekrar edilmez; API tek hesaplama sahibi olarak kalır.

Piyasa verisini ayrı FastAPI servisinde tutmak, borsapy gibi sağlayıcı bağımlılıklarını uygulamanın finansal çekirdeğinden ayırır. Sağlayıcı sembolleri normalize edilir ve fiyatın kullanılabilir olup olmadığı sözleşme üzerinden API’ye aktarılır.

Doğrulama ve sınırlar

API katmanında Testcontainers ile gerçek PostgreSQL kullanan entegrasyon testleri, React tarafında Vitest ve Testing Library, Python servisinde pytest kontrolleri bulunur. Bu yaklaşım; hesaplama, HTTP sözleşmesi ve piyasa verisi köprüsünü ayrı ayrı doğrulamayı sağlar.

Uygulama kişisel ve eğitim amaçlıdır; çok kullanıcılı bir yatırım platformu veya finansal danışmanlık sistemi değildir. Piyasa verisinin doğruluğu ve sürekliliği dış sağlayıcılara bağlıdır. Eksik fiyat, bir yatırım kararını uygulamanın kendisinin verebileceği anlamına gelmez.