commit 204c120f4fd26ed4f5c4709eb512c85df7974891 Author: suphicakir Date: Wed Nov 11 22:52:33 2026 +0300 chore: proje iskeleti, VS Code yapılandırması ve hafıza dosyaları - .vscode: eklenti önerileri, ayarlar, görevler, debug yapılandırması - Monorepo klasör yapısı (backend, frontend, docs, templates, scripts) - CLAUDE.md, docs/MEMORY.md, docs/PHASES.md - .gitignore ve .env.example Co-Authored-By: Claude Opus 5.5 diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..97e8987 --- /dev/null +++ b/.env.example @@ -0,0 +1,16 @@ +# Bu dosyayı .env olarak kopyalayın: cp .env.example .env + +# Yerel MongoDB (docker-compose.dev.yml, tek düğümlü replica set) +MONGODB_URI=mongodb://localhost:27017/kakeibo_dev?replicaSet=rs0&directConnection=true + +# JWT imzalama anahtarı (en az 32 karakter; üretmek için: openssl rand -hex 32) +JWT_SECRET=degistir-beni-en-az-32-karakterlik-gizli-anahtar + +# Uygulamanın erişildiği adres +APP_URL=http://localhost:5173 + +# Backend portu +PORT=8080 + +# Log seviyesi +RUST_LOG=kakeibo=debug,tower_http=info diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b2086af --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# Rust +target/ + +# Node +node_modules/ +dist/ + +# Ortam değişkenleri (gizli bilgiler) +.env +.env.* +!.env.example + +# Editör / sistem +.DS_Store +*.log +.vscode/*.local.json + +# Yedekler +backups/ diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..34a104a --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,15 @@ +{ + "recommendations": [ + "rust-lang.rust-analyzer", + "tamasfe.even-better-toml", + "vadimcn.vscode-lldb", + "fill-labs.dependi", + "usernamehw.errorlens", + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "bradlc.vscode-tailwindcss", + "mongodb.mongodb-vscode", + "ms-azuretools.vscode-docker", + "humao.rest-client" + ] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..f28b2bf --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,27 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "lldb", + "request": "launch", + "name": "Backend: Debug", + "cargo": { + "args": ["build", "--manifest-path", "backend/Cargo.toml"], + "filter": { "kind": "bin" } + }, + "cwd": "${workspaceFolder}", + "envFile": "${workspaceFolder}/.env" + }, + { + "type": "lldb", + "request": "launch", + "name": "Backend: Testleri Debug", + "cargo": { + "args": ["test", "--no-run", "--manifest-path", "backend/Cargo.toml"], + "filter": { "kind": "bin" } + }, + "cwd": "${workspaceFolder}", + "envFile": "${workspaceFolder}/.env" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..6b2d9d7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,39 @@ +{ + "editor.formatOnSave": true, + "[rust]": { + "editor.defaultFormatter": "rust-lang.rust-analyzer" + }, + "[typescript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[typescriptreact]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[json][jsonc]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[css]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "rust-analyzer.linkedProjects": ["backend/Cargo.toml"], + "rust-analyzer.check.command": "clippy", + "files.exclude": { + "**/target": true, + "**/node_modules": true, + "**/dist": true + }, + "search.exclude": { + "**/target": true, + "**/node_modules": true, + "**/dist": true, + "**/*.lock": true, + "**/package-lock.json": true + }, + "files.watcherExclude": { + "**/target/**": true, + "**/node_modules/**": true + }, + "rest-client.environmentVariables": { + "local": { "baseUrl": "http://localhost:8080/api" } + } +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..be4daae --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,44 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Dev: Tümünü Başlat", + "type": "shell", + "command": "npm run dev", + "isBackground": true, + "problemMatcher": [], + "group": { "kind": "build", "isDefault": true } + }, + { + "label": "DB: Başlat", + "type": "shell", + "command": "npm run db:up", + "problemMatcher": [] + }, + { + "label": "DB: Durdur", + "type": "shell", + "command": "npm run db:down", + "problemMatcher": [] + }, + { + "label": "DB: Seed", + "type": "shell", + "command": "npm run db:seed", + "problemMatcher": [] + }, + { + "label": "DB: Sıfırla", + "type": "shell", + "command": "npm run db:reset", + "problemMatcher": [] + }, + { + "label": "Test: Tümü", + "type": "shell", + "command": "npm test", + "problemMatcher": [], + "group": { "kind": "test", "isDefault": true } + } + ] +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..649461d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,63 @@ +# 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 faz sonunda commit + `git push origin main` (Claude yapar). +- 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 / db:reset +npm test +``` +*(Komutlar Faz 0 – Adım 4'te tanımlanacak.)* + +## Ortam +- Geliştirme makinesi: CachyOS (Arch), fish kabuğu, VS Code +- Git remote: `https://gitea.ta1sph.info/suphicakir/kakeibo.git` (Gitea, dal: `main`) diff --git a/KAKEIBO_PROMPT.md b/KAKEIBO_PROMPT.md new file mode 100644 index 0000000..f7549be --- /dev/null +++ b/KAKEIBO_PROMPT.md @@ -0,0 +1,444 @@ +# 📒 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://: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:@: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**. diff --git a/backend/src/auth/.gitkeep b/backend/src/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/backend/src/models/.gitkeep b/backend/src/models/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/backend/src/routes/.gitkeep b/backend/src/routes/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/backend/src/services/.gitkeep b/backend/src/services/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/MEMORY.md b/docs/MEMORY.md new file mode 100644 index 0000000..5a2304a --- /dev/null +++ b/docs/MEMORY.md @@ -0,0 +1,23 @@ +# 🧠 Proje Hafızası + +## ▶️ Sıradaki Adım +**Faz 0 – Adım 4:** `docker-compose.dev.yml` (MongoDB 7, replica set), backend (Axum) ve frontend (Vite) iskeleti, kök `package.json` ile `npm run dev`. +Ön koşul: Rust kurulumu (`rustup`, `cargo-watch`) tamamlanmalı. + +## 📌 Alınan Kararlar +- Sürüm kontrolü: Gitea (`https://gitea.ta1sph.info/suphicakir/kakeibo.git`), dal `main`. +- Her faz sonunda Claude commit + push yapar (kullanıcı onayı verildi). +- Node v26 (LTS) sistemde mevcut; ayrı kurulum gerekmedi. + +## ❓ Açık Konular +- Rust kurulumu kullanıcı tarafında bekliyor (`sudo pacman -S rustup`, `rustup default stable`, `cargo install cargo-watch`). +- Altın kuru için veri kaynağı seçimi (Faz 8). +- Aylık değerlendirme çıktı formatı kullanıcıdan gelecek (Faz 9). +- Canlı MongoDB kurulum şekli (konteyner mi, doğrudan mı) Faz 3'te birlikte kontrol edilecek. + +## 📝 İlerleme Günlüğü + +### 2026-11-11 — Faz 0 +- **Adım 1:** Ortam kontrol edildi. CachyOS, fish. Node 26, npm 12, Docker 29 + Compose 5, Git, VS Code, gcc mevcut. Rust ve cargo-watch eksik; kurulum komutları verildi. +- **Adım 2:** `.vscode/` (extensions, settings, tasks, launch), `.gitignore`, `.env.example` ve monorepo klasörleri oluşturuldu. `git init -b main`. +- **Adım 3:** `CLAUDE.md`, `docs/MEMORY.md`, `docs/PHASES.md` oluşturuldu. Gitea remote eklendi, ilk commit push edildi. diff --git a/docs/PHASES.md b/docs/PHASES.md new file mode 100644 index 0000000..9679173 --- /dev/null +++ b/docs/PHASES.md @@ -0,0 +1,25 @@ +# 🗺️ Fazlar + +✅ tamam · 🔄 devam · ⏳ bekliyor + +| Faz | Kapsam | Çıktı | Durum | +|---|---|---|---| +| **Faz 0** | Ortam kurulumu, 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, tema, logo/ikonlar, layout, navigasyon, giriş/kayıt | Giriş yapılabilen, temalı iskelet uygulama | ⏳ | +| **Faz 3** | 🚀 İlk canlıya alma: Dockerfile, Dokploy, canlı MongoDB, domain + HTTPS, yedekleme | Giriş ekranı canlıda çalışıyor | ⏳ | +| **Faz 4** | Dönem açma + aylık planlama + notlar | Plan ekranı | ⏳ | +| **Faz 5** | Günlük defter | 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 grafikler | Ana ekran | ⏳ | +| **Faz 8** | Birikimler/varlıklar, 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, UI cilası | Telefona kurulabilir web uygulaması | ⏳ | +| **Faz 11+** | Tauri 2: Windows, Linux, Android (çevrimdışı + senkronizasyon) | Masaüstü ve mobil uygulamalar | ⏳ | + +## Faz 0 Adımları +- ✅ 1. Ortam kontrolü ve kurulum yönergeleri +- ✅ 2. `.vscode/` yapılandırması ve monorepo iskeleti +- ✅ 3. Hafıza dosyaları (`CLAUDE.md`, `MEMORY.md`, `PHASES.md`) + Git remote +- ⏳ 4. Yerel MongoDB (Docker, replica set) + `npm run dev` +- ⏳ 5. Veri modeli taslağı (`docs/DATA_MODEL.md`) → onay diff --git a/frontend/src/components/ui/.gitkeep b/frontend/src/components/ui/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/features/.gitkeep b/frontend/src/features/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/lib/.gitkeep b/frontend/src/lib/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/types/.gitkeep b/frontend/src/types/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/.gitkeep b/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/templates/.gitkeep b/templates/.gitkeep new file mode 100644 index 0000000..e69de29