💸 Expense Tracker API

Aylık harcamalarınızı kategorize eden ve özet raporlar sunan, endüstri standartlarında, profesyonel bir REST API.

---

📑 İçindekiler

• Projenin Amacı
• Özellikler
• Teknoloji Yığını
• Mimari
• Kurulum ve Çalıştırma
• API Endpoint'leri
• Kullanım Örnekleri
• Test ve Lint
• CI/CD
• Proje Yapısı
• HTTP Hata Kodları
• Lisans

---

🎯 Projenin Amacı

Expense Tracker API, kullanıcıların aylık harcamalarını sistematik bir şekilde kaydetmesini, otomatik olarak kategorize etmesini ve tek bakışta anlaşılabilir özet raporlar üretmesini sağlayan bir web servisidir.

Tasarım kurgusu: harcamalar kaydedilir ≤ kategorilere ayrılır (manuel veya anahtar kelimeyle otomatik) ≤ aylık/dönem raporları ile finansal farkındalık sağlanır. Tüm bu akış üç özerk ve test edilebilir katmanda (route → service → model) çalışır.

✨ Özellikler

• 📋 Kategori Yönetimi — kategori CRUD (oluşturma, listeleme, güncelleme, silme).
• 💳 Harcama Yönetimi — harcama CRUD, arama, filtreleme (kategori, tarih aralığı, min/maks tutar) ve sayfalama (pagination).
• 🧠 Otomatik Kategorizasyon — kategori verilmezse harcama açıklamasındaki anahtar kelimelere göre kategori atanır: "Migros alışverişi" → Market, "taksi ücreti" → Ulaşım.
• 📊 Aylık Özet Rapor — toplam tutar, kayıt adedi ve kategori başına tutar + yüzdelik kırılım.
• 📈 Dönem Özeti — tarih aralığındaki toplam tutar, harcama sayısı, günlük ortalama ve en yüksek kategori.
• 🛡️ Tutarlı Hata Yönetimi — tüm uç noktalarda standart {"detail": ...} hata gövdesi ve doğru HTTP durum kodları (404/409/422/500).
• 🔐 Güvenli Yapılandırma — hiçbir sır koda gömülmez; tüm ayarlar .env üzerinden yüklenir (pydantic-settings).

🧰 Teknoloji Yığını

Bileşen	Teknoloji	Gerekçe
Dil	Python 3.10+	Temiz sözdizimi, geniştir ekosistem
Web çatısı	FastAPI	Yüksek performans, otomatik OpenAPI dokümantasyon
ORM	SQLAlchemy 2.0	Tip güvenli, deklaratif veri erişimi
Veritabanı	SQLite	Sıfır kurulum, dosya tabanlı
Şema/Doğrulama	Pydantic v2	Otomatik istemci doğrulamave 422
Test	pytest + httpx	Hızlı, güvenilir birim testleri
Lint + Format	Ruff	PEP8 uyumu ve anlık biçimleme
CI/CD	GitHub Actions	3 Python sürümünde otomatik kontrol

🧬 Mimari

Proje Separation of Concerns (sorumluluk ayrımı) ilkesine göre katmanlıdır:

HTTP (route)  ──►  services  ──►  models / SQLite (ORM)
    (yalnızca          (iş                             (veri
     istek-cevap       mantığı,                        erişimi)
     bağlayıcı)        kurallar,
                       doğrulama)

• Clean Code & DRY: ortak Pydantic taban şemaları (Base*), tek yerde toplanaraç hata yöneticileri (core/errors.py) ve tekrar eden serileştirme yardımcıları (expenses._to_out) ile tekrarlanan mantığın tamamı dokümente edilmiş tek noktalara indirgenmiştir.
• Her kritik fonksiyon/sınıf Türkçe docstring ve gerekli yerlerde inline açıklamalarla belgelenmiştir.

🚀 Kurulum ve Çalıştırma

1. Gereksinimler

• Python 3.10+

2. Klonlama

git clone https://github.com/Pastalikek65/expense-tracker-api.git
cd expense-tracker-api

3. Sanal ortam (önerilir)

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

4. Bağımlılıklar

pip install -r requirements-dev.txt

5. Ortam dosyası

cp .env.example .env

6. Çalıştır

uvicorn app.main:app --reload

Aç kaydırma:

Adres	Açıklama
http://127.0.0.1:8000	API kök adresi
http://127.0.0.1:8000/docs	Swagger UI (etkileşimli doküman)
http://127.0.0.1:8000/health	Sağlık durumu

İlk başlatmada data/expense_tracker.db otomatik oluşturulur ve varsayılan kategoriler ekelir: Market, Restoran, Ulaşım, Fatura, Eğlence, Alışveriş, Sağlık, Diğer.

---

🌌 API Endpoint'lerı

Tüm uç noktalar /api/v1 öneki altındadır.

Kategoriler — /api/v1/categories

Metot	Yol	Açıklama
GET	/categories	Tüm kategorileri listeler
POST	/categories	Yeni kategori (201)
GET	/categories/{id}	Tek kategori
PATCH	/categories/{id}	Kısmi güncelleme
DELETE	/categories/{id}	Silme (204)

Harcamalar — /api/v1/expenses

Metot	Yol	Açıklama
GET	/expenses	Filtreli + sayfalamalı liste
POST	/expenses	Harcama ekle (otomatik kategori)
GET	/expenses/{id}	Tek harcama
PATCH	/expenses/{id}	Kısmi güncelleme
DELETE	/expenses/{id}	Silme (204)

GET /expenses filtreleri:

Parametre	Anlam	Örnek
category_id	Kategori filtresi	2
date_from / date_to	Tarih aralığı (ISO-8601)	2026-08-01T00:00:00
min_amount / max_amount	Tutar aralığı	50
search	Açıklamada metin araması	migros
sort_by	Sıralama alanı	amount
order	asc / desc	desc
limit, offset	Sayfalama	10, 0

Raporlar — /api/v1/reports

Metot	Yol	Açıklama
GET	/reports/monthly?year=2026&month=8&currency=TRY	Aylık kategori kırılımlı özet
GET	/reports/summary?date_from=2026-08-01&date_to=2026-08-31&currency=TRY	Dönem genel özeti

---

🧪 Kullanım Örnekleri

Sağlık kontrolü

curl http://127.0.0.1:8000/health

{"status":"ok","app":"Expense Tracker API","version":"1.0.0"}

Kategori oluştur

curl -X POST http://127.0.0.1:8000/api/v1/categories \
  -H "Content-Type: application/json" \
  -d '{"name":"Seyehat","keywords":"otel, ucak, tren, gezi"}'

Harcama ekle (otomatik kategorizasyon)

curl -X POST http://127.0.0.1:8000/api/v1/expenses \
  -H "Content-Type: application/json" \
  -d '{"description":"Migros alışveriş","amount":320.75,"spent_at":"2026-08-06T10:00:00"}'

{
  "id": 1,
  "description": "Migros alışveriş",
  "amount": 320.75,
  "currency": "TRY",
  "spent_at": "2026-08-06T10:00:00",
  "category_id": 1,
  "category_name": "Market",
  "created_at": "2026-08-06T17:57:07"
}

category_id vermezseniz, açıklamadaki anahtar kelimelere göre kategori otomatik atanır. Bu örnekte "Migros" → Market.

Aylık rapor

curl "http://127.0.0.1:8000/api/v1/reports/monthly?year=2026&month=8"

{
  "year": 2026,
  "month": 8,
  "currency": "TRY",
  "total_amount": 320.75,
  "total_expenses": 1,
  "categories": [
    {
      "category_id": 1,
      "category_name": "Market",
      "total_amount": 320.75,
      "expense_count": 1,
      "percentage": 100.0
    }
  ]
}

Dönem özeti

curl "http://127.0.0.1:8000/api/v1/reports/summary?date_from=2026-08-01&date_to=2026-08-31"

Hata yanıtı örneği

curl -s http://127.0.0.1:8000/api/v1/expenses/999

{"detail":"Harcama (id=999) bulunamadı."}

---

🧪 Test ve Lint

Tüm testler pytest ile, CPU/disk bağımsız bellecik SQLite üzerinde çalışır:

pytest -v            # 32+ test

Stil ve biçim:

ruff check .         # statik analiz (PEP8)
ruff format --check .   # biçim doğrulama

⚙️ CI/CD

.github/workflows/main.yml her push ve pull_request'te otomatik çalışır:

1. Kod checkout edilir.
2. Python 3.11 / 3.12 / 3.13 matrisine kurulum yapılır.
3. pip install -r requirements-dev.txt
4. ruff format --check .
5. ruff check .
6. pytest -v

İşlem yalnızca üç adım birden başarılı olduğunda yeşil işaret alır.

---

🗂️ Proje Yapısı

expense-tracker-api/
├── .github/workflows/main.yml     # CI/CD (lint + test, 3 Python)
├── app/
│   ├── main.py                    # App factory + lifespan (init DB)
│   ├── config.py                  # .env ayarları (pydantic-settings)
│   ├── database.py                # Motor, session, seed işlevleri
│   ├── models.py                  # Category / Expense (SQLAlchemy 2.0)
│   ├── schemas.py                 # Pydantic v2 şemaları
│   ├── api/
│   │   ├── dependencies.py        # get_db bağımlılığı
│   │   └── routes/                # categories, expenses, reports
│   ├── services/                  # İş mantığı (SoC)
│   └── core/
│       ├── errors.py              # Özel hatalar + global handler'lar
│       └── logging.py             # Merkezi log yapılandırması
├── tests/                         # pytest birim testleri (32 adet)
├── requirements.txt
├── requirements-dev.txt
├── ruff.toml                      # Lint ayarları (PEP8)
├── .env.example
├── .gitignore
└── LICENSE                        # MIT

❌ HTTP Hata Kodları

Kod	Anlamı	Örnek trigger
201	Başarıyla oluşturma	POST /expenses
204	Başarıyla silme	DELETE /categories/1
404	Kaynak bulunamadı	Geçersiz {id}
409	Çakıma	Aynı isimde kategori
422	Doğrulama hatası	Eksik/geçersiz alan
500	Beklenmedik hata	Yakalanmamış istisna

📄 Lisans

Bu proje, MIT License ile lisanslanmıştır. Detaylar için LICENSE dosyasına bakabilirsiniz.

---

_{Build with ❤️ · FastAPI · SQLAlchemy · SQLite · Pydantic · Ruff
expense-tracker-api}