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 (cargo test, MongoDB açık olmalı) + frontend (vitest)
npm run lint         # clippy + oxlint
npm run types        # Rust DTO → frontend/src/types/*.ts (ts-rs; cargo test de üretir)
npm run icons        # frontend/brand/*.svg → favicon, PWA, Apple, Tauri ikonları (rsvg-convert + magick)
npm run db:backup    # kakeibo_dev → ./backups (canlı yedek: docs/DEPLOY.md §6)
npm run db:restore -- <dosya|latest> <hedef_db> [--force]

• 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). components/ui/** shadcn dosyaları.
• Frontend: Tailwind v4 (src/index.css token'ları), shadcn/ui (style radix-nova, cn paketi), @/ → src/. Renkler: bg-needs/text-needs-fg/bg-needs-soft (wants, culture, unexpected aynı), text-income/text-expense/text-warning. Tutarlarda money sınıfı. Butonlar ≥44 px (shadcn boyutları büyütüldü).
• API: lib/api.ts (api.get/post/..., hata → ApiError Türkçe message), lib/query.ts (QueryClient + queryKeys), lib/auth.ts (useMe → undefined/null/MeResponse, useLogin/useRegister/useLogout).
• Tipler: frontend/src/types/ elle düzenlenmez; backend'de DTO'ya #[derive(TS)] #[ts(export)] ekle → npm run types. İstek yapılarında optional_fields.
• Sayfalar: src/router.tsx; adresler components/layout/nav-items.ts (paths); sayfa bileşenleri features/<alan>/page.tsx; iskelet components/layout/app-layout.tsx. Sayfa başlığı PageHeader (sekme başlığını da ayarlar). Metinler lib/strings.ts (t).
• Yönlendirme: RequireAuth (oturum yok → /giris?donus=), RequireGuest (oturum var → donus ya da panel; formlar ayrıca navigate etmez). donus daima safeReturnPath ile.
• Geliştirmede tasarım önizlemesi: /dev/tasarim.
• Formlar: react-hook-form + zod (mode: 'onTouched'), alanlar components/form-field.tsx (FormField, PasswordInput, FormError); sunucu hatası setError ile ilgili alana. Bildirim: toast (sonner, components/toaster.tsx).
• Dönem verisi: lib/periods.ts (Query kancaları), tarih lib/period-dates.ts (arayüz son günü dahil gösterir, backend end_date hariç), tutar alanı MoneyInput + moneyText/toKurus (lib/money-schema.ts). İlk dönem sihirbazı /plan/donem-ac?adim=. Plan düzenleme: taslak → diffPlan → useSavePlan; haftalık önizleme lib/budget-preview.ts (backend hesabıyla aynı tutulmalı).
• Defter: /defter?hafta=N, features/ledger/ (hafta seçici, hızlı giriş), saf hesaplar lib/ledger.ts, kancalar lib/entries.ts + lib/catalog.ts. Kayıt değişince queryKeys.period(id) yenilenir (özet/bütçe spent dahil).
• Grup tanımları: lib/groups.ts; tema: lib/theme.tsx (+ index.html içindeki ilk-boya betiği); biçimlendirme: lib/format.ts.
• API örnekleri: backend/api.http
• Canlı: Dockerfile (tek imaj), docs/DEPLOY.md (ortam değişkenleri, Dokploy, MongoDB, yedek). routes::app() = API + STATIC_DIR varsa SPA (routes/spa.rs) + sıkıştırma + TraceLayer. Testler routes::router() kullanır.
• 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ı).
• Kayıt politikası: REGISTRATION=invite_only (varsayılan; ilk hane serbest, sonra yalnızca davet) | open. Backend'de zorunlu (403 registration_closed), GET /api/auth/registration arayüze bildirir. Testler TestApp::new() = open, with_registration(..).
• Biçim: Prettier (frontend/.prettierrc.json: tek tırnak, ; yok, 100 sütun); npm --prefix frontend run format. src/types/ ve components/ui/ hariç.
• 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)