# IDEA.md – en egen utgiftsspårare för bankens kontoutdrag Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på erfarenheterna från Expenser, ett skrivbordsprogram för Windows och macOS byggt i Rust med Claude Code. ## 1. Vad som ska byggas Ett skrivbordsprogram som läser **bankens CSV-exporter** in i en **lokal databas**, kategoriserar transaktionerna automatiskt och visar vart pengarna tar vägen. Problemet: ett kalkylark per månad blir för tungt att underhålla, och det man vill veta – till exempel hur matkostnaderna ändras år för år – är svårt att få fram. Färdiga tjänster finns, men de kräver att man lämnar ut sina transaktioner. Här stannar allt på datorn: ingen server, inget konto, ingen bankkoppling. Det viktigaste är **egna kategorier som sätts automatiskt** på återkommande affärer och betalningar. Allt annat – grafer, trender, budget, prenumerationer – bygger på att kategorierna stämmer. Programmet ska kunna: - **Importera** en eller flera CSV-filer via meny eller genom att dra in dem i fönstret. Känna igen bankens format, reparera trasiga tecken, hoppa över dubbletter och en fil som redan importerats. Visa importhistorik; en import ska gå att ångra. - **Kategorisera** med regler: villkor på text eller referens (*contains*, *equals*, *starts with*, *regex*), riktning (in/ut) och beloppsintervall. Reglerna prövas i prioritetsordning. Regler kan också byta mottagarnamn. Sätter användaren en kategori för hand föreslås en regel för alla transaktioner från samma mottagare. Manuellt satta kategorier skrivs aldrig över av regler. - **Kategorier** med en nivå av underkategorier, färg och typ: *Expense*, *Income* eller *Transfer*. Transfer räknas aldrig i statistiken. Leverera ett startpaket (Expenser har 17 kategorier och 260 regler för vanliga svenska butiker). - **Transaktionslista**: virtualiserad tabell med fritextsök, filter (period, kategori, in/ut, okategoriserade), sortering, kategori direkt i raden, flerval, anteckningar, delning av en transaktion på flera kategorier (split) och export av det som visas till CSV. - **Översikt** för en vald period (månad, kvartal, år, 12 månader, allt, egen): utgifter, inkomster, netto och sparkvot jämfört med perioden innan; staplar med inkomst mot utgift per månad; utgifter per kategori som munkdiagram och lista; de största mottagarna; saldo över tid. Klick på en kategori, mottagare eller månad öppnar transaktionerna. - **Trender**: staplade utgifter per kategori och månad, en linje per vald kategori, år mot år, och en tabell med kategorier som rader och månader som kolumner. - **Budget** per kategori och månad, med en stapel som blir röd vid överdrag och snittet för 3 och 12 månader som stöd. - **Återkommande betalningar**: hittas automatiskt, med kostnad per månad och år, senaste och nästa dragning, och om de upphört. Användaren kan dölja och slå ihop. - **Flera konton**: varje transaktion hör till ett konto. Överföringar mellan egna konton känns igen och räknas aldrig. Översikt, trender, budget och lista visar alla konton eller ett. - **Flera profiler**: helt åtskilda uppsättningar, en databas per profil, som kan vara öppna i varsitt fönster. - **Säkerhetskopia** av den öppna profilens databas. Ingår **inte**: bankkoppling (bankerna erbjuder inget öppet API till privatpersoner utan en mellanhand), flera valutor, kuvertbudgetering, synkning mellan datorer, en sammanslagen vy över flera profiler, kryptering. ## 2. Stack och arkitektur Det som är **viktigt** är markerat; resten går att byta. - **Rust** (edition 2024, ≥ 1.89 för `File::try_lock`), en Cargo-workspace med en UI-fri kärna och ett fönsterprogram. - **Viktigt: kärnan utan gränssnitt** – CSV-import, databas, textnormalisering, regler, rapporter, återkommande betalningar, överföringar, profiler. Den testas utan fönster, och en del tester körs mot användarens riktiga bankfiler när de finns (och hoppas över annars). Bankfilerna checkas aldrig in. - **Viktigt: SQLite** (via `rusqlite`). En fil i användarens datakatalog, ingen server, samma på båda plattformarna, och aggregeringarna blir SQL i stället för loopar. Kompileras in på Windows; systemets på macOS. - **Viktigt: belopp som heltal i öre (`i64`)**, aldrig flyttal utom när något ska ritas. - **eframe/egui** med **egui_plot** för staplar och linjer; munkdiagrammet ritas med egui:s egen målare. Går att byta. - `chrono` för datum, `regex` för regelvillkor, `unicode-normalization` för att vika bort diakritiska tecken i jämförelser. - **Menyn som data** (egui i fönstret på Windows, systemets menyrad på macOS via `muda`), och tangentgenvägar från en enda källa. Meny och tangentbord ger samma `Action` genom en enda `apply`. - **Flera fönster är flera processer**: *Open in new window* startar programmet igen med `--profile `. Enklare än flera viewports, och en krasch tar inte de andra med sig. - Paketering: Windows korskompileras från WSL med `cargo xwin` (SQLite byggs då som C och kräver `llvm-lib` i `PATH`), NSIS-installerare och portabel zip; macOS `aarch64-apple-darwin`, `.app` och dmg. Datamodell (förenklad): ``` accounts id, name, number imports id, file_name, sha256, format, imported_at, rows_total, rows_added, account_id transactions id, date, booked, amount, text, raw_text, reference, balance, payee, category_id, category_source, rule_id, note, import_id, dedupe_key, account_id, transfer_account_id, pair_id splits id, txn_id, category_id, amount, note categories id, name, parent_id, color, kind, budget, sort rules id, pattern, op, amount_dir, min_amount, max_amount, category_id, rename, priority, enabled ``` `category_source`: 0 ingen, 1 satt av regel, 2 satt för hand. En vy (`entries`) slår ihop odelade transaktioner och delar, så att rapporterna bara ser en sorts rad. Rapporterna summerar underkategorier till huvudkategorin. ## 3. Beslut som visade sig avgörande **Undersök bankens riktiga filer först.** Allt det svåra i projektet kom ur filerna, inte ur programmet. Läs varje format, räkna rader, leta efter trasiga tecken, överlapp och konstigheter innan något byggs, och skriv ner det. **Känn igen formatet på kolumnernas antal och position, inte på deras namn.** I ett av bankens format var å, ä och ö ersatta med U+FFFD redan i filen, även i rubrikraden. Hoppa över inledande rader (`* Transaktioner Period …`) före rubriken. Gissa avgränsare ur rubrikraden (`;` eller `,`). Avkoda Windows-1252 när filen inte är giltig UTF-8. Var beredd på flera format från samma bank: datum + text + belopp med svenska belopp (`"−4 000,00"`, U+2212 som minus, hårt mellanslag som tusentalsavgränsare); ett format med radnummer, bokförings-, transaktions- och valutadag, referens, beskrivning, belopp och saldo (punkt som decimaltecken, nyaste raden först); och ett med clearing- och kontonummer på varje rad. **Reparera texten, men låt aldrig reparationen påverka dubblettkontrollen.** Kortkvitton skriver `#` för Ä och `¦`/`@` för Ö, och banken kapar texten efter 16 tecken. Reparera mot en inbyggd ordlista plus alla hela texter som redan finns i databasen: slå upp hela ord, ord inuti ord och början på kända ord. Spara både den reparerade och den råa texten. **Dubblettkontroll som räknar förekomster.** Nyckeln är *(konto, transaktionsdag, belopp, text utan tecken utanför ASCII)*. För varje nyckel läggs bara så många rader in som filen har *utöver* dem som redan finns. Då blir samma köp i två överlappande filer ett köp, medan två likadana köp samma dag i samma fil blir två. En fil med samma SHA-256 som en tidigare import hoppas över helt. **Regler matchar på vikt text.** Gemener, diakritiska tecken bort (`Hemköp` = `HEMKOP`), blanksteg hopslagna – för både mönstret och texten. Matcha mot texten **eller** referensen. Den första regeln som sätter en kategori vinner, och den första som sätter ett mottagarnamn vinner. Mottagarens nyckel är texten utan butiksnummer på slutet; den används för att föreslå en regel när användaren kategoriserar för hand. **Kontonumret avgör vad som är en intern överföring, inte texten.** Referensen på en överföring är motpartens kontonummer (clearing och konto hopskrivna). En transaktion vars referens är ett eget kontos nummer är intern och räknas aldrig, oavsett kategori – inte heller när ett konto visas för sig. Konton som inte importeras (ett sparkonto) läggs till med bara numret. Föreslå nummer användaren ofta för över till, men inte Swish-telefonnummer. **Lär kortkontots nummer ur datan.** Kortkontots egen export saknar kontonummer. Men det andra kontots överföringar pekar på ett okänt nummer, och när minst fyra av fem (och minst fem) har en motsvarighet på kortkontot med omvänt tecken inom tre dagar är det kortkontots nummer. Para sedan benen (samma belopp, omvänt tecken, ±3 dagar, närmast först) och varna för ett ben utan par när det andra kontot har data den dagen: en import saknas, eller pengarna gick till någon annan. **Återkommande betalningar** per mottagare (utgifter, inte överföringar): minst tre dragningar; medianen av intervallen i ett av fönstren vecka (6–8 dagar), månad (26–35), kvartal (85–95) eller år (350–380); minst 60 % av intervallen inom ±25 % av medianen och minst 60 % av beloppen inom ±20 % av medianbeloppet. Kostnad per månad ur medianbeloppet och takten; nästa dragning samma dag nästa period; avslutad efter 1,5 utebliven period. Gruppera på mottagarnamnet efter reglerna, inte på bankens text. **En profil är en egen databas.** Inget delas mellan profiler, så ingen profilkolumn behövs i varje tabell. Den första profilen ligger där databasen alltid legat (ingen fil flyttas); nya i `profiles/.sqlite`. Namnen i `profiles.toml`, som läses om före varje ändring eftersom flera fönster kan skriva i den. En profil kan bara vara öppen i ett fönster: lås med `File::try_lock` på `.lock` – operativsystemet släpper låset när processen dör, så ett kvarglömt lås kan inte uppstå. **Utvecklarhjälp från dag ett**, så att en agent kan granska gränssnittet utan att någon sitter vid skärmen: - `_DATA_DIR=dir` – egen datakatalog (måste finnas) - `_IMPORT=fil;fil` – importera vid start - `_TAB=overview|transactions|trends|budget|recurring|categories|rules|imports` - `_WINDOW=1240x820`, `_SCREENSHOT=fil.ppm`, `_SCREENSHOT_DELAY=N` - `_DEBUG_STATE=…` – steg i ordning: `period=last12`, `trend=lines|yoy`, `search=…`, `select=…`, `set-category=…`, `create-rule`, `year=2026`, `profile=p2` … - `_DEBUG_MENU=File`, `_DEBUG_POINTER=600x300` (håll pekaren där så att hovring syns) ## 4. Fallgropar - **Gör inte "överföring via internet" till en överföringsregel.** En överföring till någon annans konto är en utgift. Låt kontonumret avgöra (se avsnitt 3), och ta bort sådana textregler vid uppgradering. - **Glöm inte kontot i dubblettnyckeln.** Annars slås samma köp samma dag på två konton ihop till ett. - **Underkänn inte en räkning för att beloppet varierar.** En elräkning dras varje månad men varierar kraftigt; med kravet på ±20 % i belopp underkändes hela gruppen, och en slumpvis delgrupp visades som avslutad. Godta en grupp med jämn takt (minst 6 dragningar och 4 av 5 intervall inom ±25 %) även när beloppet varierar, markera den *varies* och låt den kosta snittet av de senaste 12 dragningarna. Undanta årliga betalningar – där är beloppet det som skiljer en räkning från en resa. Dela upp efter belopp bara när takten inte är jämn. - **Räkna med att prenumerationer byter namn** på kontoutdraget med åren. Låt användaren slå ihop dem; det ska skapa en namnbytesregel per text så att alla dragningar får samma mottagare. - **Använd inte `INSERT OR REPLACE` på en rad som andra tabeller pekar på med `ON DELETE CASCADE`.** Det tar bort raden och sätter in en ny, och kaskaden raderar allt som hörde till den. Använd `INSERT … ON CONFLICT DO UPDATE`, och testa att spara föräldern efter att barnen lagts in. - **Två fönster mot samma databas visar inaktuell data** om cachen hänger på en räknare som bara den egna anslutningen räknar upp. Lås profilen. - **Lägg inte datakatalogen på en nätverks- eller 9p-sökväg i test.** `File::try_lock` fungerar inte på `\\wsl.localhost\…` ("Incorrect function"); använd en sökväg på Windows-disken när Windows-binären körs från WSL. - **Kontrollera Windows-bygget med `cargo xwin check`, inte `cargo check --target`.** SQLite kompileras som C och stannar annars på `failed to find tool "lib.exe"`. - **Ta inte med systemets Klipp ut/Kopiera/Klistra in i macOS-menyn**; den nativa menyn tar ⌘C/⌘V från textfälten. - **`cargo fmt` formaterar om hela crate:n**, inte bara de filer du rört. ## 5. Krav och mått Riktmärken från Expenser, på riktiga bankfiler: - Import av drygt 7 000 transaktioner från fyra filer i två format: **121 ms** i Windows-binären. Enskilda filer: 5 125 rader på 74 ms, 932 på 19 ms. En redan importerad fil: 0 ms. - Överlappet mellan två format: exakt de överlappande raderna (2) togs bort; inga trasiga å/ä/ö kvar efter reparationen. - Standardreglerna kategoriserade **82,4 %** direkt. - Med ett andra konto: 0 nya dubbletter, importen 176–182 ms oavsett ordning; alla interna överföringar parade. - Windows-binär 14,6 MB, installerare 6,7 MB. - Import i olika ordning ska ge samma antal och samma summa. ## 6. Så verifieras det - **Enhetstester i kärnan** med små syntetiska filer för varje format: belopp (svenska tecken, minus, tusentalsavgränsare), avkodning, reparation, dubblettkontroll (överlapp mot likadana köp), regler (vikning, prioritet, manuella kategorier skrivs inte över), återkommande betalningar (vecka, månad, år, varierande belopp, avslutad), överföringar (lära nummer, para, varna), profiler (namn, låset) och uppgradering av databasschemat. - **Tester mot de riktiga filerna** när de finns: antal rader, dubbletter i överlappet, inga trasiga tecken kvar, samma resultat i båda importordningarna. - **Lint och korskontroll**: `cargo clippy --workspace --all-targets` utan varningar, `cargo test --workspace --release`, `cargo xwin check` för Windows. - **Gränssnittet granskas med skärmbilder** från den riktiga Windows-binären med utvecklarhjälpen. Använd **påhittad data** till allt som ska visas för andra – aldrig de riktiga kontoutdragen. - Det som kräver en människa – installeraren, fildialogen, dra och släpp, macOS – blir ett eget verifieringsärende. ## 7. Arbetssätt - **Plan först**: gå igenom liknande program (Actual Budget, Firefly III, HomeBank, Monarch, Copilot, MoneyMoney) för att se vad som brukar ingå, och användarens bankfiler för att se vad som faktiskt krävs. Skriv en plan med milstolpar och vad som medvetet inte ingår. - **Fråga om det bara användaren vet**: vilka kontonummer som är egna, om en återkommande inbetalning är inkomst eller överföring, vad en mottagare är. Lista frågorna samlat, med det datan redan säger. - **Ett ärende i taget**, med mätningen i avslutskommentaren. - **Bankfilerna är privata**: de checkas aldrig in, och de syns aldrig i skärmbilder eller texter som delas. ## 8. Prompten > Bygg ett skrivbordsprogram för [Windows och macOS] i [Rust med eframe/egui och SQLite] som läser min banks CSV-exporter in i en lokal databas, kategoriserar transaktionerna automatiskt med regler som lär sig av det jag kategoriserar för hand, och visar vart pengarna tar vägen: översikt, transaktionslista, trender år mot år, budget och återkommande betalningar. Inget får lämna datorn. > > Mina bankfiler ligger i [katalog]. De är privata: checka aldrig in dem och visa dem aldrig i skärmbilder. > > Läs hela IDEA.md nedan först. Den beskriver funktionerna, arkitekturen, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Undersök mina bankfiler: format, kolumner, teckenkodning, trasiga tecken, överlapp. Gå igenom liknande program. Skriv en plan med milstolpar. > 2. Bygg kärnan utan gränssnitt först, med tester mot små syntetiska filer och mot mina riktiga filer när de finns. > 3. Bygg utvecklarhjälpen (datakatalog, import vid start, flik, skärmbild, debugsteg) tidigt, och granska varje gränssnittsändring med en skärmbild med påhittad data. > 4. Fråga mig om det bara jag vet, till exempel [vilka konton som är mina egna, vad återkommande inbetalningar är]. > 5. Mät importen och redovisa tid, antal rader, dubbletter och andel kategoriserade. > > Min bank: [namn, och vilka exportformat den ger]. Mina kategorier: [lista, eller använd ett startpaket för vanliga butiker i [land]]. > > [klistra in IDEA.md här]