feat(borç): borç takibi backend (ölçümler, taksit planları, yol haritası, dönem borcu, içe aktarma)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/BORC_TAKIBI.md

@@ -0,0 +1,60 @@
+# Borç takibi (Kakeibo uyarlaması)
+
+Kaynak: `butcem/docs/BORC_TAKIBI.md` (kullanıcının özellik tanımı). Kişisel rakamlar (seed) bu repoya
+**girmez**; canlıya "İçe aktar (JSON)" ile yüklenir (dosya repoda tutulmaz).
+
+## Amaç
+Gerçek banka borcu (KMH + kredi kartı + ekstreye gelmemiş taksitler) Panel'in en üstünde görünsün ve
+her ay küçülmesi izlensin. Hedef: toplam borcu yol haritasındaki son aya kadar sıfırlamak.
+
+## Kararlar (kullanıcı, 2026-11-14)
+- **Ayrı "Borç" modülü.** Kakeibo'daki "devreden borç" (bütçe aşımının devri, `carryovers`) ile
+  karıştırılmaz; banka borcu **harcanabilir tutarı düşürmez** (aylara yayılarak birikimle ödenir).
+  Borç sıfırlanana kadar dönemin birikim hedefi (C) "Borç ödemesi" olarak etiketlenir.
+- Başlangıç verisi canlıya **içe aktarma dosyasıyla** (önizleme → onay).
+
+## Formüller (tutarlar kuruş, `i64`)
+```
+toplam borç       = KMH eksi bakiyesi + kart borcu (provizyon dahil) + kalan taksitler − maaş hesabı artı bakiyesi
+devreden borç     = toplam borç − kalan taksitler                    (aylık planda gösterilen)
+taksit yükü(ay)   = Σ aylık tutar  (ilk taksit ayı ≤ ay ≤ son taksit ayı)
+kalan taksit(ay)  = Σ aylık tutar × (ay'dan SONRAKİ taksit sayısı)   (ölçümün ayına göre önerilir)
+ay sonu hedefi    = ay başı toplam borç − birikim (C) − o ayın taksit yükü
+aylık başarı      = ay başı toplam − ay sonu toplam ≥ C + o ayın taksit yükü
+```
+- Toplam **saklanmaz**, her okumada hesaplanır.
+- Taksit planı "ödenen taksit sayısı" yerine **ilk taksit ayı** (`first_month`) ile saklanır; ödenen /
+  kalan sayılar her ay kendiliğinden hesaplanır. İçe aktarmada `asOf` ayı + `paidCount` →
+  `first_month = asOf − paidCount + 1`.
+- Ay başı borç: dönemin başlangıcından önceki (≤ başlangıç günü) son ölçüm; dönemde elle düzeltilebilir.
+
+## Veri modeli (MongoDB, ortak alanlar: `_id` UUID v7, `household_id`, zaman damgaları, `deleted_at`, `version`)
+- `debt_snapshots`: `date`, `kmh`, `positive_balance`, `card_balance`, `remaining_installments`,
+  `note`, `source` (`manual` | `import`)
+- `installment_plans`: `merchant`, `total_amount`, `monthly_amount`, `total_count`, `first_month` (`YYYY-MM`)
+- `debt_targets`: `month` (`YYYY-MM`), `closing_target` (yol haritası, toplam borç cinsinden)
+- `periods.opening_debt` (isteğe bağlı elle ay başı toplam borç)
+
+**Güvenlik:** IBAN, kart ve müşteri numarası saklanmaz; açıklama/işyeri alanlarında 12+ haneli sayı
+dizisi reddedilir.
+
+## Ekranlar
+1. Panel en üstü: güncel toplam borç, geçen aya göre değişim, başlangıç → 0 ilerleme, tahmini bitiş,
+   KMH · Kart · Kalan taksit dökümü.
+2. `/borc`: gerçek (ölçümler) + hedef (yol haritası, kesikli) çizgi grafik, ölçüm tablosu, "Yeni ölçüm"
+   (toplam canlı hesaplanır, kalan taksit önerilir), hedefleri düzenleme, içe aktarma.
+3. Aylık plan: ay başı borç (otomatik, düzenlenebilir), devreden borç, "Borç ödemesi" (C), taksit yükü,
+   hedef ay sonu borç (salt okunur); taksit yükü Sabit giderlere "Taksitler" olarak önerilir.
+4. `/taksitler`: açık planlar, önümüzdeki 6 ayın taksit yükü (çubuk); yeni taksitte uyarı
+   "Borç sıfırlanana kadar yeni taksit planı yok."
+
+## Kabul ölçütleri (kaynak belgeyle aynı)
+- Ölçüm toplamları kaynak belgedeki iki ölçümle birebir (78.530,48 ve 79.078,85).
+- Kasım planında devreden borç 64.352,79.
+- Taksit yükü: Kasım ve Aralık 4.311,82 · Ocak 3.724,44 · Şubat 887,38 · Mart 760,21 · Nisan 182,02.
+- Gerçek ve hedef aynı grafikte; hiçbir yerde IBAN / kart numarası yok.
+
+## Adımlar
+- B1 backend (modeller, hesaplar, uç noktalar, içe aktarma, testler)
+- B2 arayüz: Panel kartı, `/borc`, `/taksitler`
+- B3 aylık plan entegrasyonu + içe aktarma dosyasının hazırlanması (kullanıcıya, repo dışı)