kakeibo/backend/api.http

### Kakeibo API — örnek istekler (VS Code REST Client eklentisi)
### Satırın üstündeki "Send Request" bağlantısına tıklayın.
### ┌──────────────────────────────────────────────────────────────────────┐
### │ GİRİŞ İÇİN HAZIR HESAPLAR (yalnızca yerel geliştirme veritabanı):    │
### │   demo@ornek.com / demo12345  → hane sahibi (Demo Hanesi)            │
### │   es@ornek.com   / demo12345  → üye (aynı hane)                      │
### └──────────────────────────────────────────────────────────────────────┘

@baseUrl = http://localhost:8080/api

### Sağlık kontrolü (DB erişilemezse 503 + "db": "error")
GET {{baseUrl}}/health

# ─────────────────────────── Kimlik doğrulama ───────────────────────────
# REST Client cookie'leri otomatik saklar: kayıt/giriş sonrası diğer istekler oturumlu gider.

### KAYIT ÖRNEĞİ — bu bir hesap DEĞİL, hesap OLUŞTURMA isteğidir.
### Hesap ancak bu isteği gönderince oluşur (kullanıcı + hane + örnek kategoriler/ödeme türleri).
### Aynı e-postayla ikinci kez gönderirseniz 409 "zaten kayıtlı" alırsınız.
### REGISTRATION=invite_only (varsayılan): sistemde zaten hane varsa davetsiz kayıt 403 "registration_closed" döner
### → aşağıdaki "Davet koduyla kayıt" örneğini kullanın (kodu hane sahibi oluşturur).
POST {{baseUrl}}/auth/register
Content-Type: application/json

{
  "name": "Suphi",
  "email": "yeni@ornek.com",
  "password": "gizli-sifre-123",
  "household_name": "Çakır Hanesi"
}

### Davet koduyla kayıt (mevcut haneye "member" olarak katılır; household_name yok sayılır)
# Kod büyük/küçük harf ve tireden bağımsızdır: "abcd-efgh" = "ABCDEFGH"
POST {{baseUrl}}/auth/register
Content-Type: application/json

{
  "name": "Ayşe",
  "email": "ayse@ornek.com",
  "password": "gizli-sifre-123",
  "invite_code": "BURAYA-KOD"
}

### Giriş ("remember_me": true → 30 gün, false → tarayıcı kapanınca biter)
POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "demo@ornek.com",
  "password": "gizli-sifre-123",
  "remember_me": true
}

### Kayıt politikası: yeni hane kurulabilir mi? (oturum gerektirmez)
GET {{baseUrl}}/auth/registration

### Ben kimim? (oturum yoksa 401)
GET {{baseUrl}}/auth/me

### Çıkış
POST {{baseUrl}}/auth/logout

# ─────────────────────────── Hane ve davetler ───────────────────────────

### Hane bilgisi ve üyeler
GET {{baseUrl}}/household

### Yeni davet kodu (yalnızca hane sahibi; 7 gün geçerli, tek kullanımlık)
POST {{baseUrl}}/household/invites

### Aktif davetler (yalnızca hane sahibi)
GET {{baseUrl}}/household/invites

### Daveti iptal et (yalnızca hane sahibi) — id'yi yukarıdaki listeden alın
DELETE {{baseUrl}}/household/invites/BURAYA-ID

# ─────────────────────────── Kategoriler ───────────────────────────
# Gruplar: needs (Zorunlu) · wants (İstek) · culture (Kültürel) · unexpected (Beklenmeyen)
# Silme yok; "is_active": false ile pasife alınır.

### Kategoriler (aktif olanlar; pasifler için ?include_inactive=true)
GET {{baseUrl}}/categories

### Kategori ekle (grubun sonuna eklenir)
POST {{baseUrl}}/categories
Content-Type: application/json

{
  "group": "needs",
  "name": "Aidat",
  "emoji": "🏢"
}

### Kategori düzenle / pasife al — "version": listede gördüğünüz sürüm (başkası değiştirdiyse 409)
PATCH {{baseUrl}}/categories/BURAYA-ID
Content-Type: application/json

{
  "name": "Site Aidatı",
  "is_active": true,
  "version": 1
}

### Grup içi sıralama — gruptaki TÜM kimlikler (pasifler dahil), istenen sırada
PUT {{baseUrl}}/categories/order
Content-Type: application/json

{
  "group": "culture",
  "ids": ["ID-1", "ID-2", "ID-3"]
}

# ─────────────────────────── Ödeme türleri ───────────────────────────

### Ödeme türleri
GET {{baseUrl}}/payment-methods

### Ödeme türü ekle
POST {{baseUrl}}/payment-methods
Content-Type: application/json

{
  "name": "Yemek Kartı",
  "emoji": "🍽️"
}

### Ödeme türü düzenle / pasife al
PATCH {{baseUrl}}/payment-methods/BURAYA-ID
Content-Type: application/json

{
  "is_active": false
}

### Ödeme türü sıralama — TÜM kimlikler
PUT {{baseUrl}}/payment-methods/order
Content-Type: application/json

{
  "ids": ["ID-1", "ID-2", "ID-3", "ID-4"]
}

# ─────────────────────────── Dönemler ───────────────────────────
# Bitiş tarihi HARİÇ: Aralık 2026 = "2026-12-01" → "2027-01-01". Hanede tek açık dönem.

### Açık dönem (yoksa null)
GET {{baseUrl}}/periods/current

### Tüm dönemler (en yeni başta)
GET {{baseUrl}}/periods

### Dönem aç — ad boşsa otomatik ("Aralık 2026"); savings_goal kuruş (5.000,00 ₺ = 500000)
POST {{baseUrl}}/periods
Content-Type: application/json

{
  "start_date": "2026-12-01",
  "end_date": "2027-01-01",
  "savings_goal": 500000
}

### Dönem detayı (haftalar dahil)
GET {{baseUrl}}/periods/BURAYA-ID

### Dönemi düzenle — "version": son gördüğünüz sürüm (başkası değiştirdiyse 409)
PATCH {{baseUrl}}/periods/BURAYA-ID
Content-Type: application/json

{
  "savings_goal": 750000,
  "version": 1
}

# ─────────────────────────── Plan kalemleri (sabit gelir / gider) ───────────────────────────
# kind: "income" | "expense" · amount kuruş (> 0) · date isteğe bağlı, dönem içinde

### Dönemin kalemleri (önce gelirler)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/plan-items

### Kalem ekle
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/plan-items
Content-Type: application/json

{
  "kind": "expense",
  "name": "Kira",
  "amount": 1500000,
  "date": "2026-12-05"
}

### Önceki dönemden kopyala (aynı tür + ad varsa atlanır; tarihler göreli günle taşınır)
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/plan-items/copy-previous

### Kalemi düzenle ("date": "" → tarihi kaldır)
PATCH {{baseUrl}}/plan-items/BURAYA-KALEM-ID
Content-Type: application/json

{
  "amount": 1600000,
  "version": 1
}

### Kalemi sil
DELETE {{baseUrl}}/plan-items/BURAYA-KALEM-ID

# ─────────────────────────── Notlar ───────────────────────────
# context: "planning" (Plan sayfası) | "review" (Ay sonu değerlendirmesi) · body_md: Markdown

### Notlar (?context=planning ile filtre)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/notes?context=planning

### Not ekle
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/notes
Content-Type: application/json

{
  "context": "planning",
  "title": "Tatil birikimi",
  "body_md": "- Ocak'ta **5.000 ₺** ayır\n- Dışarıda yemeği azalt"
}

### Notu düzenle
PATCH {{baseUrl}}/notes/BURAYA-NOT-ID
Content-Type: application/json

{
  "body_md": "Güncel metin",
  "version": 1
}

### Notu sil
DELETE {{baseUrl}}/notes/BURAYA-NOT-ID

# ─────────────────────────── Bütçe ve özet ───────────────────────────
# Gruplar: needs · wants · culture · unexpected · tutarlar kuruş

### Dönem özeti: gelir − sabit gider − birikim − devreden borç + devreden artı = harcanabilir
### + spent_total (gerçekleşen harcama), remaining (harcanabilir − harcanan)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/summary

### Bütçe: 4 grup, aylık + haftalık döküm (haftalar gün sayısına göre); her grup ve haftada `spent`
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/budget

### Aylık bütçeleri kaydet (4 grup birlikte)
PUT {{baseUrl}}/periods/BURAYA-DONEM-ID/budget
Content-Type: application/json

{
  "needs": 1500000,
  "wants": 600000,
  "culture": 200000,
  "unexpected": 200000
}

### Bir haftayı elle ayarla (week_start = haftanın ilk günü); "amount": null → otomatiğe döner
PUT {{baseUrl}}/periods/BURAYA-DONEM-ID/budget/weeks
Content-Type: application/json

{
  "group": "needs",
  "week_start": "2026-12-07",
  "amount": 400000
}

### Bütçe önerisi — method: default (varsayılan yüzdeler) | previous (önceki dönem) | avg3 (son 3 dönem)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/budget/suggestion?method=default

# ─────────────────────── Günlük defter (harcamalar) ───────────────────────
# Kategori / ödeme türü kimlikleri: GET /categories, GET /payment-methods · tutarlar kuruş

### Dönemin harcamaları (en yeni başta)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/entries

### Bir haftanın harcamaları (from/to dahil)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/entries?from=2026-12-07&to=2026-12-13

### Harcama ekle — amount kuruş (345,50 ₺ = 34550); grup kategoriden gelir; ödeme türü ve açıklama isteğe bağlı
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/entries
Content-Type: application/json

{
  "date": "2026-12-09",
  "amount": 34550,
  "category_id": "BURAYA-KATEGORI-ID",
  "payment_method_id": "BURAYA-ODEME-TURU-ID",
  "description": "Haftalık market"
}

### Harcamayı düzenle — "payment_method_id": "" / "description": "" → kaldır
PATCH {{baseUrl}}/entries/BURAYA-KAYIT-ID
Content-Type: application/json

{
  "amount": 36000,
  "version": 1
}

### Harcamayı sil
DELETE {{baseUrl}}/entries/BURAYA-KAYIT-ID

### Silmeyi geri al ("↩️ Geri al")
POST {{baseUrl}}/entries/BURAYA-KAYIT-ID/restore

# ─────────────────────────── Ay sonu değerlendirmesi ───────────────────────────

### Değerlendirme: 4 soru (available, savings_goal, spent_total, realized_savings) + grup/kategori/hafta
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/review

### "Nasıl daha iyi yapabilirim?" (Markdown; boş metin → kaldır; yalnızca açık dönem)
PATCH {{baseUrl}}/periods/BURAYA-DONEM-ID
Content-Type: application/json

{
  "reflection_md": "- Dışarıda yemeği haftada 1'e indir\n- Market listesiyle alışveriş"
}

### Dönemi kapat: to_savings verilmezse gerçekleşen birikimin tamamı birikime; kalanı artı, açık varsa borç devreder
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/close
Content-Type: application/json

{
  "to_savings": 500000
}

### Kapalı dönemi düzeltmeye aç (yalnızca hane sahibi) → status: correcting; düzeltince yeniden "close"
POST {{baseUrl}}/periods/BURAYA-DONEM-ID/reopen

# ─────────────────────────── Panel ───────────────────────────

### Günlük harcama: dönemin her günü, 4 grup (harcama yoksa 0)
GET {{baseUrl}}/periods/BURAYA-DONEM-ID/daily

### Son dönemler (eskiden yeniye): harcanabilir, harcanan, birikime aktarılan + toplam birikim
GET {{baseUrl}}/stats/periods?limit=12

# ─────────────────────────── Birikimler ───────────────────────────
# Miktar/fiyat × 1e6 (5 gr → 5000000), tutar kuruş. TL varlığında yalnızca total yeter.

### Varlıklar + eldeki miktar, maliyet, ortalama maliyet, gerçekleşen kâr/zarar
GET {{baseUrl}}/assets

### Döviz ekle
POST {{baseUrl}}/assets
Content-Type: application/json

{ "code": "GBP", "name": "İngiliz Sterlini", "unit_label": "£" }

### Alım (birim fiyat verilmezse tutar ÷ miktar)
POST {{baseUrl}}/assets/BURAYA-VARLIK-ID/transactions
Content-Type: application/json

{ "type": "buy", "date": "2026-11-13", "quantity_e6": 5000000, "total": 3130000, "note": "Kuyumcu" }

### İşlem geçmişi (en yeni başta)
GET {{baseUrl}}/assets/BURAYA-VARLIK-ID/transactions

### İşlemi düzenle / sil
PATCH {{baseUrl}}/asset-transactions/BURAYA-ISLEM-ID
Content-Type: application/json

{ "total": 3150000, "version": 1 }

### Portföy: varlıklar + güncel kur, değer, kâr/zarar + toplamlar + son kur çekimi
GET {{baseUrl}}/portfolio

### Elle kur (TL × 1e6; tarih boşsa bugün). Aynı gün otomatik kur varsa elle girilen geçerli.
POST {{baseUrl}}/rates
Content-Type: application/json

{ "code": "XAU_CEYREK", "rate_e6": 10250000000 }

### Elle kuru sil → otomatik kura dön
DELETE {{baseUrl}}/rates/BURAYA-KUR-ID