kakeibo/CLAUDE.md

Kakeibo — Proje Rehberi

Japon Kakeibo yöntemine dayalı, hane bazlı kişisel ev finans defteri. Tam gereksinimler: KAKEIBO_PROMPT.md (yalnızca ilgili bölümü oku).

Çalışma Kuralları

• Faz bazlı, küçük adımlar. Her adım sonunda dur, kısa özet ver, onay bekle.
• Yeni session'da yalnızca CLAUDE.md + docs/MEMORY.md oku; tüm projeyi tarama.
• target/, node_modules/, dist/, *.lock dosyalarını asla okuma.
• Değişikliklerde dosyayı baştan yazma; yalnızca değişen kısmı düzenle.
• Yanıt formatı: ne yapıldı → nasıl test edilir → sıradaki adım.
• Her adım sonunda docs/MEMORY.md'ye 3–5 satır not ekle.
• Her adım sonunda Claude commit atar ve "push zamanı" diye haber verir; push'u kullanıcı kendi uygulamasıyla yapar (Claude git push çalıştırmaz).
• Bir hata 2 denemede çözülmezse dur, seçenek sun.
• Kullanıcı Rust'a yeni: kavramları ihtiyaç anında, kısa örnekle açıkla.
• Her yeni bağımlılık için kısa gerekçe ver.

Teknoloji Yığını

• Backend: Rust + Axum + tokio + resmi mongodb sürücüsü, serde, validator
• Auth: argon2 + JWT (httpOnly, Secure, SameSite cookie)
• Frontend: React + TypeScript + Vite, TailwindCSS, shadcn/ui, lucide-react
• Veri/Form: TanStack Query, react-hook-form + zod, date-fns (tr)
• Diğer: Recharts, sonner, react-markdown + remark-gfm, vite-plugin-pwa
• Tipler: ts-rs (Rust → frontend/src/types/)
• DB: MongoDB 7, tek düğümlü replica set (transaction için)
• Dağıtım: Tek Docker imajı (Axum frontend'i de sunar) → Dokploy (Atlas homeserver)
• Gelecek: Tauri 2 (Windows, Linux, Android)

Klasör Yapısı

backend/src/    main.rs, config.rs, db.rs, auth/, models/, routes/, services/
frontend/src/   components/ui/, features/, lib/ (api, format), types/
docs/           MEMORY, PHASES, DATA_MODEL, DEPLOY
templates/      monthly_report.md
scripts/        seed, reset, backup

Kodlama Kuralları

• Kod İngilizce; arayüz metinleri Türkçe ve tek dosyada toplanır.
• İş mantığı: backend services/, frontend lib/.
• Para: kuruş cinsinden i64 (asla float). Altın/kur: Decimal128 veya ölçekli tamsayı.
• Tüm kayıtlar: _id (UUID v7), household_id, created_at, updated_at, deleted_at, version.
• Her sorgu household_id ile filtrelenir (ortak middleware).
• Hesaplanan değerler saklanmaz; aggregation ile hesaplanır.
• Format: 1.250,00 ₺, tarih GG.AA.YYYY; tümü lib/format.ts üzerinden.
• Haftalar Pazartesi başlar; kısmi haftalar gün sayısına göre orantılanır.
• Hatalar kullanıcıya Türkçe ve sade; teknik detay yalnızca logda.
• Commit mesajları Türkçe: feat(defter): haftalık giriş listesi eklendi

Sık Kullanılan Komutlar

npm run dev          # frontend (5173) + backend (8080) birlikte, hot reload
npm run dev:host     # telefondan test için ağa aç
npm run db:up        # yerel MongoDB (Docker)
npm run db:down
npm run db:seed
npm run db:reset     # kakeibo_dev + artık kakeibo_test_* veritabanlarını siler
npm test             # backend: birim + entegrasyon (yerel MongoDB açık olmalı)
npm run lint         # clippy + oxlint

• npm run dev öncesinde DB otomatik başlar (predev).
• Yerel MongoDB host portu 27020 (27017 sistem mongod, 27018/27019 diğer projeler).
• Frontend lint: oxlint (Vite şablonu varsayılanı; ESLint yerine).
• API örnekleri: backend/api.http
• Backend = lib (src/lib.rs) + bin (src/main.rs). Entegrasyon testleri backend/tests/ (her test geçici kakeibo_test_<uuid> DB, tests/common yardımcıları).
• Hane izolasyonu: hane kimliği yalnızca AuthUser.household_id'den; sorgular scope(hid) ile başlar; başka hane → 404.

Ortam

• Geliştirme makinesi: CachyOS (Arch), fish kabuğu, VS Code
• Git remote: https://gitea.ta1sph.info/suphicakir/kakeibo.git (Gitea, dal: main)