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 dönemin günlerine göre: 1–8, 9–15, 16–22, 23–son gün (28–31 günlük dönem = 4 hafta; genel: `max(1, gün/7)` hafta, ilk 8 gün, ara 7, son kalan). Bütçe haftalara gün sayısıyla orantılanır. Tek kaynak: `calendar::weeks`.
- 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`. SVG/JS'te (Recharts vb.) ham değişken kullan: `var(--needs)`, `var(--primary)` — `@theme inline` yüzünden `--color-*` derlenmiş CSS'te olmayabilir. 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` her açılışta bugünün haftası (hafta adrese yazılmaz), `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(..)`.
- Excel okuma: SheetJS **yerel paket** `frontend/vendor/xlsx-0.20.3.tgz` (npm 12 uzak tarball'u engeller; npm'deki `xlsx` eski/açıklı). Güncellerken: cdn.sheetjs.com'dan indir, içeriği/sha256'yı kontrol et, `npm i ./vendor/…`; Dockerfile `vendor/`'u `npm ci`'den önce kopyalar. Lazy yüklenir.
- Biçim: Prettier (`frontend/.prettierrc.json`: tek tırnak, `;` yok, 100 sütun); `npm --prefix frontend run format`. `src/types/` ve `components/ui/` hariç.
- JSON yedeği: `services/backup.rs` (`collect` → `to_json`; `parse` doğrular; `restore` = geri dönüş noktası + tam değiştirme tek transaction; `retarget` kimlik çevirir). Yeni hane koleksiyonu eklenirse `backup::KINDS`'a da ekle. Biçim: DATA_MODEL §3.14b. Arayüz: `features/settings/backup-section.tsx`, `lib/backup.ts` (geri yükleme/geri alma sonrası tüm sorgular yenilenir).
- Aylık rapor: `services/monthly_report.rs` (`gather` → `Facts` → saf `analyze` → `render`), şablon `templates/monthly_report.md` (`include_str!`; Dockerfile `templates/`'u kopyalar). Filtreler `tl`/`pct`/`cell`. Şablonda ham HTML yok (arayüz göstermez). Arayüz `features/review/report-page.tsx` (`/degerlendirme/rapor?donem=`), `lib/monthly-report.ts`; `api.getText`; `Markdown` tabloları `.table-wrap` içinde kayar; yazdırma `@page A4` + `PageHeader printHidden`. Cümlelerde sayıdan sonra ek kullanma ("%429'u" gibi ünlü uyumu gerekir) → "X / Y", "kullanımı %N".
- Ayarlar: `/ayarlar` menü (+ tema) → alt sayfalar `SettingsSubpage` ("‹ Ayarlar"): `/ayarlar/kategoriler`, `/odeme-turleri`, `/veri` (yedek, CSV, ekstre). Katalog yönetimi `features/settings/catalog-editor.tsx` + `lib/catalog.ts` (`useCreateCatalog`/`useUpdateCatalog`/`useReorderCatalog`, `moveId`); sıralama isteği grubun **tüm** kimlikleri (pasifler dahil); grup sonradan değişmez.
- 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`)