kakeibo/KAKEIBO_PROMPT.md

# 📒 Kakeibo — Kişisel Ev Finans Defteri
## Claude Code Geliştirme Promptu (v2)

> **Rolün:** Kıdemli full-stack geliştirici, UI/UX tasarımcısı ve mentor.
> **Kullanıcı profili:** Daha önce Rust ile uygulama geliştirmedim. VS Code ve Claude Code eklentisi kurulu. Her adımda beni yönlendir; kurulumları ve komutları kısa, pratik şekilde açıkla.
> **Çalışma şekli:** Faz bazlı, adım adım. Bir adım bitmeden ve onayımı almadan diğerine geçme.

---

## 0. ⚙️ Session ve Token Yönetimi (ÖNCELİKLİ)

1. **Tek seferde tek faz, her fazda küçük adımlar.** Her adımın sonunda dur, kısa özet ver, onayımı bekle.
2. **Hafıza dosyaları** (proje kökünde oluştur, sürekli güncel tut):
   - `CLAUDE.md` → Proje özeti, teknoloji yığını, klasör yapısı, kodlama kuralları, sık kullanılan komutlar. **Kısa tut (≤150 satır).**
   - `docs/MEMORY.md` → Alınan kararlar, tamamlanan adımlar, açık konular, **sıradaki adım**.
   - `docs/PHASES.md` → Faz listesi ve durumları (✅ tamam / 🔄 devam / ⏳ bekliyor).
   - `docs/DATA_MODEL.md` → Veritabanı şeması.
   - `docs/DEPLOY.md` → Canlıya alma adımları ve ortam değişkenleri.
3. **Yeni session'da** önce yalnızca `CLAUDE.md` ve `docs/MEMORY.md` dosyalarını oku. Tüm projeyi tarama.
4. `target/`, `node_modules/`, `dist/`, `*.lock` dosyalarını **asla okuma**.
5. Yalnızca ilgili dosyaları oku; büyük dosyalarda ilgili satır aralığını oku.
6. Değişikliklerde dosyanın tamamını yeniden yazma; yalnızca değişen kısmı düzenle.
7. **Yanıtların kısa olsun:** ne yapıldı → nasıl test edilir → sıradaki adım.
8. Her adım sonunda `docs/MEMORY.md` dosyasına 3–5 satır ilerleme notu ekle ve anlamlı bir **git commit** mesajı öner.
9. Context dolmaya yaklaşınca uyar; `MEMORY.md` güncellendikten sonra `/compact` veya yeni session öner.
10. Bir hatayı 2 denemede çözemezsen dur, durumu özetle ve bana seçenek sun.

---

## 1. 🎯 Proje Tanımı

- **Uygulama adı:** Kakeibo
- **Konu:** Japon Kakeibo yöntemine **tamamen** dayalı, hane bazlı kişisel ev finans defteri (kâğıt defterin dijital hali).
- **Platformlar:**
  - **1. öncelik:** Web uygulaması (mobile-first, responsive, **PWA** — telefona "uygulama gibi" kurulabilir).
  - **Sonraki aşama:** Windows, Linux ve Android uygulamaları.
- **Veritabanı:** MongoDB
- **Canlı ortam:** Atlas homeserver üzerinde **Dokploy**. Sunucuda MongoDB hâlihazırda kurulu.
- **Tasarım ilkeleri:** Sade, basit, profesyonel, kullanıcı dostu, ferah, modern.

---

## 2. 🧱 Teknoloji Yığını

| Katman | Seçim | Gerekçe |
|---|---|---|
| Backend API | **Rust** + **Axum** + resmi `mongodb` sürücüsü + `tokio` | Hızlı, güvenli; tek API tüm platformlara hizmet eder |
| Doğrulama (backend) | `validator`, `serde` | Girdi kontrolü |
| Kimlik doğrulama | `argon2` (şifre hash) + JWT, **httpOnly cookie** | Güvenli, platformdan bağımsız |
| Frontend | **React + TypeScript + Vite** | Geniş ekosistem, hızlı geliştirme, Tauri ile uyumlu |
| Stil | **TailwindCSS** | Tutarlı tasarım, kolay karanlık tema |
| UI bileşenleri | **shadcn/ui** (Radix tabanlı) | Erişilebilir, modern, özelleştirilebilir |
| İkonlar | **lucide-react** (+ yerinde emoji) | Tutarlı, sade ikon seti |
| Grafikler | **Recharts** | React ile uyumlu çizgi/pasta/çubuk grafikler |
| Sunucu verisi | **TanStack Query** | Önbellek, yükleniyor/hata durumları, otomatik yenileme |
| Formlar | **react-hook-form + zod** | Hızlı, doğrulamalı formlar |
| Markdown | `react-markdown` + `remark-gfm` | Not içerikleri |
| Bildirimler | `sonner` (toast) | İşlem geri bildirimi, "Geri al" |
| Tarih | `date-fns` (tr locale) | Hafta/dönem hesapları |
| PWA | `vite-plugin-pwa` | Telefona kurulum, ikon, splash |
| Masaüstü & Android | **Tauri 2** (Faz 10+) | Aynı React arayüzü ile Windows, Linux, Android |
| Paylaşılan tipler | `ts-rs` (Rust → TypeScript tip üretimi) | Backend ve frontend tipleri hep senkron |
| Dağıtım | **Tek Docker imajı** + Dokploy | Axum, derlenmiş frontend'i de sunar: tek servis, tek domain, CORS yok |

> Rust'a yeni başladığım için: kavramları (ownership, `Result`, `async`) yalnızca ihtiyaç anında, kısa örnekle açıkla. Daha uygun bir alternatif görürsen gerekçesiyle öner, kararı ben veririm.

---

## 3. 📁 Proje Yapısı (Monorepo)

```
kakeibo/
├── CLAUDE.md
├── docs/                  # MEMORY, PHASES, DATA_MODEL, DEPLOY
├── backend/               # Rust (Axum) API
│   ├── src/
│   │   ├── main.rs
│   │   ├── config.rs      # .env okuma
│   │   ├── db.rs          # MongoDB bağlantısı + indeksler
│   │   ├── auth/
│   │   ├── models/
│   │   ├── routes/
│   │   └── services/      # iş mantığı (bütçe, devir, kâr/zarar)
│   └── Cargo.toml
├── frontend/              # React + Vite
│   ├── src/
│   │   ├── components/ui/ # shadcn bileşenleri
│   │   ├── features/      # dashboard, planning, ledger, review, savings, reports
│   │   ├── lib/           # api, format (para/tarih), utils
│   │   └── types/         # ts-rs ile üretilen tipler
│   └── package.json
├── templates/             # monthly_report.md (aylık değerlendirme şablonu)
├── scripts/               # seed, reset, backup
├── .vscode/               # settings, extensions, tasks, launch
├── docker-compose.dev.yml # yerel MongoDB
├── Dockerfile             # canlı ortam (çok aşamalı build)
├── .env.example
└── package.json           # kök: `npm run dev` ile her şeyi başlatır
```

---

## 4. 💻 Geliştirme Ortamı ve VS Code Yapılandırması

### 4.1 Kurulacaklar (Faz 0'da işletim sistemime göre adım adım yönlendir)
- **Rust:** `rustup` (Windows ise *Visual Studio Build Tools – C++* gereklidir)
- **Node.js LTS** + npm
- **Docker Desktop** (Windows/macOS) veya Docker Engine (Linux)
- **Git** + GitHub hesabı/deposu
- Cargo araçları: `cargo install cargo-watch`

### 4.2 VS Code eklentileri → `.vscode/extensions.json` (önerilen eklentiler)
- `rust-lang.rust-analyzer` — Rust dil desteği
- `tamasfe.even-better-toml` — Cargo.toml
- `vadimcn.vscode-lldb` — Rust debug
- `fill-labs.dependi` — bağımlılık sürümleri
- `usernamehw.errorlens` — hataları satırda göster
- `dbaeumer.vscode-eslint`, `esbenp.prettier-vscode`
- `bradlc.vscode-tailwindcss`
- `mongodb.mongodb-vscode` — veritabanını VS Code içinden görüntüleme
- `ms-azuretools.vscode-docker`
- `humao.rest-client` — API'yi `.http` dosyalarıyla test etme

### 4.3 `.vscode/settings.json`
- Kaydederken otomatik format (Rust: rustfmt, TS: Prettier)
- `rust-analyzer.check.command = clippy`
- `files.exclude` ve `search.exclude` ile `target/`, `node_modules/`, `dist/` gizlensin

### 4.4 `.vscode/tasks.json` ve `launch.json`
- Görevler: **Dev: Tümünü Başlat**, **DB: Başlat/Durdur**, **DB: Seed**, **DB: Sıfırla**, **Test: Tümü**
- Rust backend için debug yapılandırması (breakpoint ile)

### 4.5 Canlı takip (hot reload)
- Kökte tek komut: **`npm run dev`** (`concurrently` ile)
  - Frontend: Vite → `http://localhost:5173` (kaydedince anında güncellenir)
  - Backend: `cargo watch -x run` → `http://localhost:8080` (kaydedince yeniden derlenir)
  - Vite proxy: `/api` istekleri backend'e yönlenir (CORS yok)
- **Telefondan test:** `npm run dev:host` → aynı ağdaki telefondan `http://<bilgisayar-ip>:5173`
- `backend/api.http` dosyasında örnek API istekleri

### 4.6 Yerel MongoDB (sunucuya bağlanmadan geliştirme)
- `docker-compose.dev.yml` ile **MongoDB 7, tek düğümlü replica set** (transaction desteği için zorunlu).
- Veriler Docker volume'unda kalıcı.
- Bağlantı yalnızca `.env` ile yönetilir:
  ```env
  MONGODB_URI=mongodb://localhost:27017/kakeibo_dev?replicaSet=rs0&directConnection=true
  ```
- `scripts/` altında: **seed** (örnek hane, dönem, kategori, harcama, birikim), **reset** (veritabanını sıfırla).

---

## 5. 🏠 Hane (Household) Yapısı

- Uygulama **hane bazlı** çalışır; her hane yalnızca kendi verisini görür, haneler tamamen bağımsızdır.
- Tüm sorgular backend'de zorunlu olarak `household_id` ile filtrelenir (ortak middleware).
- İlk kayıtta hane oluşturulur; hane sahibi aynı haneye başka üye davet edebilir (davet kodu).
- Roller: `owner`, `member`.

---

## 6. 📅 Dönem (Period) Mantığı

- Dönem **başlangıç ve bitiş tarihiyle** açılır. Örnek: `01.12.2026` – `01.01.2027`.
- Aynı anda yalnızca **bir açık dönem** olur; girişler yalnızca açık döneme yapılır.
- **Haftalar:** Pazartesi başlangıçlı. Dönemin başı/sonundaki kısmi haftalar ayrı hafta sayılır ve bütçeleri gün sayısına göre orantılanır.
- **Dönem kapatma** (sihirbaz adımları):
  1. Özet ve planlanan/gerçekleşen karşılaştırması gösterilir.
  2. Kalan bakiye ve borç hesaplanır.
  3. Onay → dönem salt okunur olur.
  4. **Borç** veya **artı bakiye** bir sonraki döneme devredilir; gerçekleşen birikim birikim modülüne eklenir.
  5. Yeni dönem önceki dönemin sabit gelir/gider kalemleri ve kategori bütçeleri kopyalanarak açılabilir.
- Devreden borç yeni dönem planında ayrı kalem olarak görünür ve harcanabilir tutardan düşülür; uygulama borcun kapatılması için uyarır/öneride bulunur.
- Kapanış işlemi **MongoDB transaction** ile yapılır (yarım kalırsa hiçbir şey değişmez).
- Hane sahibi kapalı bir dönemi **yeniden açabilir** (düzeltme için; devirler yeniden hesaplanır). Tüm değerler sonradan değiştirilebilir.

---

## 7. 🗂️ Kategoriler ve Ödeme Türleri

**4 sabit ana grup** (değiştirilemez, silinemez; her birinin sabit rengi ve ikonu var):

| Grup | Emoji | Anlamı |
|---|---|---|
| **Zorunlu** | 🏠 | Temel ihtiyaçlar (market, fatura, ulaşım) |
| **İstek** | 🛍️ | Arzular (dışarıda yemek, alışveriş) |
| **Kültürel** | 📚 | Kitap, eğitim, sinema, konser |
| **Beklenmeyen** | ⚡ | Öngörülmeyen giderler (tamir, sağlık, hediye) |

- Her ana grubun altına **alt kategori** eklenebilir, düzenlenebilir, sıralanabilir, pasife alınabilir (geçmiş kayıtlar bozulmasın diye silmek yerine pasife alma).
- İlk kurulumda her grup için örnek alt kategoriler gelsin.
- **Ödeme türleri** tanımlanabilir: 💵 Nakit, 💳 Kredi Kartı, 🏧 Banka Kartı, 🔁 Havale/EFT (eklenebilir/düzenlenebilir).

---

## 8. 📄 Ekranlar ve Özellikler

### 8.1 🔐 Giriş / Kayıt
- Sade giriş ekranı (logo, e-posta, şifre, "Beni hatırla").
- Kayıt → hane oluşturma → **ilk dönemi açma sihirbazı** (onboarding: gelir, sabit giderler, birikim hedefi, bütçe dağıtımı).
- Giriş sonrası **Dashboard**.

### 8.2 📊 Dashboard
Uygulamayı açtığımda tek bakışta: aylık gelirim, planladığım harcama, sabit giderlerim, anlık mali durumum ve toplam birikimim.

**Üst bölüm — özet kartları (sırayla):**
1. 💰 Toplam gelir
2. 📌 Sabit giderler
3. 🐷 Toplam birikim (varlıkların güncel değeriyle)
4. ⚠️ Devreden borç (varsa)
5. 🎯 Grup bazlı planlanan / gerçekleşen (haftalık ve aylık, ilerleme çubuklu)
6. 📍 **Anlık durum:** Kalan harcanabilir tutar (en belirgin kart)

**Grafikler (Günlük / Haftalık / Aylık sekmeli):**
1. **Harcanabilir gelir vs. gerçekleşen harcama** — kümülatif çizgi grafik
2. **4 ana grup + harcanabilir gelir** kırılımlı çizgi grafik

**Hızlı eylem:** "➕ Harcama Ekle" butonu (mobilde sağ altta yüzen buton).

### 8.3 🗓️ Aylık Planlama
- Varsayılan **görüntüleme modu** (salt okunur); "✏️ Düzenle" ile düzenleme moduna geçilir, "Kaydet / Vazgeç".
- **Sabit gelirler:** Birden fazla kalem (ad, tutar, tarih); eklenebilir/kaldırılabilir.
- **Sabit giderler:** Birden fazla kalem; eklenebilir/kaldırılabilir; "Önceki aydan kopyala".
- **Birikim hedefi:** Tutarı ben girerim.
- **Devreden borç:** Önceki dönemden otomatik gelir.
- **Özet satırı** — tek satırda belirgin kutucuklar (mobilde 2×2):
  `Gelir` − `Sabit Giderler` − `Birikim` − `Devreden Borç` = **`Harcanabilir Tutar`**
- **Bütçe dağıtımı (4 ana grup, aylık ve haftalık):**
  - Uygulama öneri sunar; seçenekler:
    - a) Önceki ayın **gerçekleşen** harcamalarına göre
    - b) Son 3 ayın ortalamasına göre
    - c) Varsayılan yüzde dağılımı (ayarlardan değiştirilebilir)
  - Öneri tek tıkla uygulanır; tüm rakamları ben değiştiririm.
  - Haftalık bütçe, aylık bütçeden hafta gün sayısına göre otomatik hesaplanır (elle değiştirilebilir).
  - Dağıtılan toplam, harcanabilir tutarı aşarsa uyarı.
- **Notlar** (bkz. 8.6)

### 8.4 ✍️ Günlük Defter
- Küçük defter mantığı; üstte **hafta seçici** (◀ önceki hafta | Bu hafta | sonraki hafta ▶).
- **Hızlı giriş formu:** tutar (büyük, sayısal klavye), ana grup (4 büyük renkli buton), alt kategori, ödeme türü, tarih (varsayılan bugün), açıklama.
- Son kullanılan kategori/ödeme türü hatırlanır.
- Formun altında **o haftanın girişleri** gün gün gruplanmış liste halinde.
- Her satırda düzenle / sil; silmede "↩️ Geri al" toast'ı.
- Haftalık özet: grup bazlı bütçe / harcanan / kalan.

### 8.5 📝 Ay Sonu Değerlendirmesi
- **Ayrı sayfa.** Tüm işlemler en baştan otomatik yansır (hesaplamalar sorgu anında yapılır, ayrıca kopya tutulmaz).
- Kakeibo'nun dört sorusu ve cevapları:
  1. Ne kadar param vardı?
  2. Ne kadar biriktirmek istedim?
  3. Ne kadar harcadım?
  4. Ne kadar biriktirdim?
- **"Nasıl daha iyi yapabilirim?"** — serbest metin (Markdown).
- Planlanan vs. gerçekleşen (grup ve alt kategori bazlı), en çok harcanan kategoriler, haftalık dağılım.
- **Notlar:** Sayfanın en altında **yalnızca başlık** olarak listelenir; tıklayınca açılır.
- **"🔒 Dönemi Kapat"** butonu → dönem kapatma sihirbazı.
- **Aylık değerlendirme çıktısı:** Formatı ben ayrıca vereceğim. `templates/monthly_report.md` şablonu üzerinden üretilsin; Markdown ve **yazdırılabilir/PDF** çıktı.

### 8.6 🗒️ Notlar (Ortak Yapı)
- Notlar **döneme özeldir**; yalnızca ilgili dönemde görünür.
- Notun bağlı olduğu yer: `planning` veya `review`.
- Yapı: **Başlık + Metin**; metin **Markdown** destekler (Düzenle / Önizle sekmeleri).

### 8.7 🐷 Birikimler / Varlıklar
- **Ayrı modül.** Varlık türleri: 🇹🇷 TL, 🥇 Altın (gram, çeyrek, yarım, tam, ons), 💵 USD, 💶 EUR ve eklenebilir diğer dövizler.
- Her **alım/satım** kaydı: varlık, miktar, birim fiyat/kur, tarih, toplam tutar, not.
- Her varlık için: toplam miktar, **ortalama maliyet**, güncel kur, **güncel değer**, **kâr/zarar** (tutar ve %).
- Portföy özeti: toplam maliyet, toplam güncel değer, toplam kazanç; varlık dağılımı (halka grafik).
- **Kurlar:** Güvenilir ve ücretsiz bir kaynaktan (döviz için TCMB, altın için uygun bir kaynak — öner) periyodik çekilsin ve önbelleğe alınsın; kaynak erişilemezse son kur + "son güncelleme zamanı" gösterilsin. **Manuel kur girişi** her zaman mümkün.
- Dönem kapanışındaki gerçekleşen birikim buraya otomatik eklenebilsin (onaylı).

### 8.8 📈 Raporlama
- Filtreler: dönem, tarih aralığı, ana grup, alt kategori, ödeme türü.
- Raporlar:
  - **Gelir–gider karşılaştırması** (aylık ve dönemler arası, çubuk grafik)
  - **Kategori kırılımlı** gelir–gider raporu (tablo + grafik)
  - Planlanan vs. gerçekleşen **bütçe sapma** raporu
  - Ödeme türüne göre harcama dağılımı
  - Birikim oranı trendi (gelirin yüzde kaçı birikti)
  - Birikim/varlık performansı
- Her rapor CSV olarak dışa aktarılabilir ve yazdırılabilir.

### 8.9 🔄 İçe / Dışa Aktarma
- **JSON:** Tam hane yedeği ve geri yükleme (sürüm bilgisi içersin; içe aktarmadan önce önizleme ve onay).
- **CSV:** Harcama girişleri, plan kalemleri, varlık işlemleri (UTF-8, `;` ayırıcı — Türkçe Excel uyumlu).
- İçe aktarmada hatalı satırlar raporlansın; geçerli satırlar aktarılsın.

### 8.10 ⚙️ Ayarlar
- 🌓 Tema: Aydınlık / Karanlık / Sistem
- Kategori, alt kategori, ödeme türü yönetimi
- Varsayılan bütçe yüzdeleri
- Hane ve üye yönetimi, profil, şifre değiştirme
- Yedekleme (JSON dışa/içe aktarma)

---

## 9. 🎨 UI/UX İlkeleri (Best Practices)

**Genel**
- Mobile-first; tasarımı önce 375 px genişlikte yap, sonra tablet/masaüstüne genişlet.
- **Navigasyon:** Mobilde alt menü (5 öğe: 📊 Panel, ✍️ Defter, 🗓️ Plan, 🐷 Birikim, ☰ Diğer); masaüstünde sol kenar çubuğu.
- Ferah boşluklar, kart tabanlı düzen, yuvarlatılmış köşeler, hafif gölgeler.
- Arayüz dili Türkçe; metinler kısa ve anlaşılır.

**Tipografi ve sayılar**
- Font: **Inter** (veya benzeri okunaklı sans-serif), temel boyut **16 px (≈12 pt)**, başlıklar belirgin hiyerarşide.
- Tutarlarda `tabular-nums` (rakamlar alt alta hizalı).
- **Para formatı:** Para birimi rakamın **sağında**, arada **bir boşluk**; Türkçe sayı formatı:
  `1.250,00 ₺` · `300,00 €` · `150,00 $` · `12,50 gr`
- **Tarih:** `GG.AA.YYYY`
- Tüm formatlama tek bir yardımcı modülden (`lib/format.ts`) yapılsın.

**Renk**
- Tasarım token'ları (CSS değişkenleri) ile aydınlık/karanlık tema.
- 4 ana grubun sabit, ayırt edilebilir renkleri (renk körlüğüne uygun; renk yanında ikon/etiket de olsun).
- Gelir/olumlu: yeşil · Gider/aşım: kırmızı · Uyarı: turuncu. Kontrast **WCAG AA**.

**Etkileşim ve geri bildirim**
- Yükleniyor durumlarında **skeleton**; boş durumlarda açıklayıcı mesaj + eylem butonu ("Henüz harcama yok — ilkini ekle ✍️").
- Her işlemde toast bildirimi; silmede **geri al**.
- Kalıcı/riskli işlemlerde (dönem kapatma, içe aktarma, silme) onay diyaloğu.
- Formlarda satır içi doğrulama mesajları; tutar alanında sayısal klavye (`inputMode="decimal"`).
- Dokunma alanları en az 44×44 px; klavye ile tam gezinme; görünür odak halkası.
- Bütçe aşımına yaklaşınca (%80) ve aşınca görsel uyarı.
- Animasyonlar hafif ve kısa; `prefers-reduced-motion` desteklensin.

**Logo ve ikonlar**
- Logo ve uygulama ikonu tasarımı sana ait: sade, defter + yen/para temalı, **SVG**.
- Favicon, PWA ikonları (192/512, maskable), Apple touch icon ve ileride Tauri için ikon setleri üretilsin.

---

## 10. 🗄️ Veritabanı Modeli İlkeleri

İleride Windows, Linux ve Android (çevrimdışı çalışma ve senkronizasyon) desteklenecek; model buna hazır olmalı:

- Tüm kayıtlarda: `_id` (UUID v7), `household_id`, `created_at`, `updated_at`, `deleted_at` (soft delete), `version`.
- **Parasal tutarlar float olarak saklanmaz** → kuruş cinsinden tamsayı (`i64`). Altın miktarı ve kurlar için yeterli ondalık hassasiyet (`Decimal128` veya ölçekli tamsayı).
- Koleksiyonlar (taslak):
  `users`, `households`, `periods`, `categories`, `payment_methods`, `plan_items` (sabit gelir/gider), `budgets` (grup × dönem × hafta), `entries` (harcamalar), `notes`, `assets`, `asset_transactions`, `exchange_rates`, `carryovers`, `settings`
- İndeksler: `household_id`, `(household_id, period_id)`, `(household_id, date)`.
- Hesaplanan değerler (gerçekleşen toplamlar, kalan tutar) **saklanmaz**, aggregation ile hesaplanır.
- Şema sürümü (`schema_version`) ve basit migration mekanizması.
- Şemayı `docs/DATA_MODEL.md` dosyasında belgele ve **Faz 0'da onayıma sun**.

---

## 11. 🔐 Güvenlik

- Şifreler `argon2` ile hashlenir; JWT **httpOnly, Secure, SameSite** cookie'de tutulur.
- Giriş denemelerinde rate limit.
- Her istekte hane izolasyonu (başka hanenin verisine erişim imkânsız olmalı — bunun için test yaz).
- Girdi doğrulama hem frontend (zod) hem backend'de.
- Gizli bilgiler (`MONGODB_URI`, `JWT_SECRET`) yalnızca ortam değişkenlerinde; `.env` git'e eklenmez, `.env.example` tutulur.
- Hata mesajları kullanıcıya Türkçe ve sade; teknik detay yalnızca loglarda.

---

## 12. 🚀 Canlıya Alma (Atlas Homeserver + Dokploy)

### 12.1 Yaklaşım
- **Tek Docker imajı**, çok aşamalı `Dockerfile`:
  1. Node aşaması → frontend build (`dist/`)
  2. Rust aşaması → backend release build
  3. Küçük çalışma imajı → Axum hem `/api` uç noktalarını hem de frontend dosyalarını sunar
- `GET /api/health` uç noktası (uygulama + veritabanı durumu) → Dokploy health check.
- Akış: **GitHub'a push → Dokploy otomatik build ve deploy.**

### 12.2 Dokploy adımları (Faz 9'da benimle adım adım yap)
1. Dokploy'da proje oluştur → **Application** ekle → GitHub deposunu bağla, `main` dalı.
2. Build tipi: **Dockerfile**.
3. Ortam değişkenlerini Dokploy arayüzünden gir (`MONGODB_URI`, `JWT_SECRET`, `APP_URL`, `RUST_LOG`).
4. **Domain** ekle; HTTPS (Let's Encrypt) Dokploy/Traefik ile otomatik.
5. Otomatik deploy (webhook) aç; ilk deploy sonrası health check'i doğrula.
6. Geri dönüş (rollback) için önceki deploy'a dönmeyi göster.

### 12.3 Canlı ortamda MongoDB bağlantısı
Sunucudaki mevcut MongoDB'ye bağlanmadan önce **benimle birlikte kontrol et**:
1. MongoDB **Docker konteyneri mi** (Dokploy içinde mi?), yoksa **doğrudan sunucuya mı** kurulu?
   - Konteynerse → uygulama aynı Docker ağına bağlanır, host adı olarak konteyner/servis adı kullanılır.
   - Sunucuya kuruluysa → `host.docker.internal` (extra_hosts ile) veya Docker köprü IP'si (`172.17.0.1`) kullanılır; MongoDB'nin bu adresi dinlediği (`bindIp`) ayarlanır.
2. **Replica set** etkin mi? Değilse tek düğümlü replica set'e çevirme adımlarını ver (transaction için gerekli).
3. Yalnızca `kakeibo` veritabanında `readWrite` yetkili **ayrı bir kullanıcı** oluştur (admin kullanıcısı kullanılmaz).
4. MongoDB portu (27017) **internete açık olmamalı**; güvenlik duvarını kontrol et.
5. Örnek bağlantı:
   ```env
   MONGODB_URI=mongodb://kakeibo_app:<sifre>@<host>:27017/kakeibo?authSource=kakeibo&replicaSet=rs0
   ```
6. Uygulama açılışında indeksleri otomatik oluştursun ve bağlantı hatasında anlaşılır log versin.

### 12.4 Yedekleme
- `mongodump` ile günlük otomatik yedek (Dokploy zamanlanmış görev veya cron), son 14 yedeği sakla.
- Geri yükleme (`mongorestore`) adımlarını `docs/DEPLOY.md` dosyasına yaz ve bir kez test et.

---

## 13. 🧪 Test ve Kalite

- Backend: kritik iş mantığı için birim testleri (bütçe önerisi, hafta hesapları, dönem devri, ortalama maliyet ve kâr/zarar, hane izolasyonu).
- Frontend: para/tarih formatlama ve kritik bileşenler için testler (Vitest).
- Her faz sonunda **elle test kontrol listesi** ver (tarayıcıda hangi adımları deneyeceğim).
- Kod kalitesi: `cargo clippy`, `cargo fmt`, ESLint, Prettier.

---

## 14. 🗺️ Fazlar

> Her fazın başında kısa plan, sonunda test adımları ve özet. Onayım olmadan sonraki faza geçme.
> **İlk canlıya alma erken yapılacak** (Faz 3), böylece deploy sorunları en baştan çözülür; sonraki her faz otomatik olarak yayına çıkar.

| Faz | Kapsam | Çıktı |
|---|---|---|
| **Faz 0** | Ortam kurulumu (Rust, Node, Docker, Git), VS Code yapılandırması, monorepo iskeleti, hafıza dosyaları, yerel MongoDB, veri modeli onayı | `npm run dev` ile boş uygulama tarayıcıda açılıyor |
| **Faz 1** | Backend temeli: config, DB bağlantısı, kimlik doğrulama, hane, kategoriler, ödeme türleri, health check | API `.http` dosyasıyla test edilebiliyor |
| **Faz 2** | Frontend temeli: tasarım sistemi (Tailwind + shadcn), tema, logo/ikonlar, layout, navigasyon, giriş/kayıt | Giriş yapılabilen, temalı iskelet uygulama |
| **Faz 3** | 🚀 **İlk canlıya alma:** Dockerfile, Dokploy kurulumu, canlı MongoDB bağlantısı, domain + HTTPS, yedekleme | Giriş ekranı canlıda çalışıyor |
| **Faz 4** | Dönem açma + aylık planlama (sabit gelir/gider, birikim, özet kutucukları, bütçe önerisi) + notlar | Plan ekranı |
| **Faz 5** | Günlük defter (haftalık giriş, liste, düzenle/sil) | Harcama girişi |
| **Faz 6** | Ay sonu değerlendirmesi + dönem kapatma/devir sihirbazı | Tam dönem döngüsü |
| **Faz 7** | Dashboard: özet kartları ve çizgi grafikler | Ana ekran |
| **Faz 8** | Birikimler/varlıklar: altın, döviz, kur entegrasyonu, kâr/zarar | Birikim modülü |
| **Faz 9** | Raporlama + JSON/CSV içe–dışa aktarma + aylık değerlendirme çıktısı | Raporlar |
| **Faz 10** | PWA, performans, erişilebilirlik ve son UI cilası | Telefona kurulabilir web uygulaması |
| **Faz 11+** | Tauri 2 ile Windows, Linux, Android uygulamaları (çevrimdışı mod ve senkronizasyon) | Masaüstü ve mobil uygulamalar |

---

## 15. ✅ Genel Kodlama Kuralları

- Temiz, modüler, okunabilir kod; anlamlı isimlendirme (kod İngilizce, arayüz metinleri Türkçe).
- Arayüz metinleri tek bir dosyada toplansın (ileride çok dil desteği için).
- Tekrar eden mantık backend'de `services/`, frontend'de `lib/` altında.
- Her yeni bağımlılığı eklemeden önce kısaca nedenini söyle.
- Commit mesajları Türkçe ve açıklayıcı (ör. `feat(defter): haftalık giriş listesi eklendi`).

---

## ▶️ Başlangıç

**Faz 0 ile başla:**
1. İşletim sistemimi sor ve kurulumları adım adım listele.
2. `.vscode/` yapılandırmalarını ve monorepo iskeletini oluştur.
3. `CLAUDE.md`, `docs/MEMORY.md`, `docs/PHASES.md` dosyalarını oluştur.
4. Yerel MongoDB'yi (Docker, replica set) kur ve `npm run dev` ile frontend + backend'i birlikte çalıştır.
5. Veri modeli taslağını `docs/DATA_MODEL.md` olarak hazırla ve **onayımı bekle**.