Import bank statements: CSV parsing, merchant rules, deduplication

[LouisBenjamin]

Import a bank CSV, auto-tag the transactions against group-wide merchant rules, and promote the shared ones into expenses. Built for the case where roommates share one card and want to split the groceries off it.

The privacy boundary

Raw statement data never reaches the server. The CSV is parsed on-device and held in screen state for the review session only — never uploaded, never written to disk. Closing the screen discards it.

Exactly two things cross the wire:

	What it holds
merchant_rules	Merchant name patterns only — no amounts, dates, references, card numbers
expenses.source_fingerprint	An opaque SHA-256 of group_id + ':' + normalized reference

The fingerprint is hashed client-side on purpose: hashing it server-side would require sending the reference number, which is the exact thing this design avoids. The server therefore can't verify it and simply trusts it — blast radius is a group the caller already belongs to.

Deduplication

Re-importing an overlapping statement never double-charges, including from a second device — which is the actual roommate scenario.

The group's existing fingerprints are fetched from Supabase rather than remembered locally. That's the key decision: your roommate's phone has no local record of what your phone imported, but it can read the group's hashes. It also means dedup works instantly on a new browser or reinstall.

A partial unique index backstops the simultaneous-import race:

create unique index expenses_source_fingerprint_key
  on expenses (group_id, source_fingerprint)
  where source_fingerprint is not null and deleted_at is null;

deleted_at is null means deleting a mis-imported expense lets you import it again. Without it, a soft-deleted row would block its own transaction forever with no visible expense to explain why. The cost — delete-then-reimport creates a second expense — is the intended trade, and is documented rather than left to surprise someone.

⚠️ The on conflict clause repeats that predicate verbatim. Postgres won't use a partial unique index as an arbiter otherwise, and the mismatch fails at runtime, not migration time.

Notable decisions

• No local database. An earlier draft used drift; dropped once it was clear dedup works better without it, avoiding build_runner codegen in a zero-codegen repo and sqlite3.wasm in web/.
• No DataTable. The app has none, a table has no mobile story, and horizontal scroll would fight the 1100px content column. Rows are Card + CheckboxListTile, like the expense list.
• Import is an app-bar action, not a fourth tab — a tab would change TabController(length: 3) and the smoke test that pins it.
• computeSplits is reused per row, so there's still exactly one definition of what a split means.
• normalizeMerchant and suggestRulePattern stay separate: the first is non-destructive so a GOOGLE rule still matches GOOGLE*Spotify Music; the second strips store codes so a saved rule covers every Costco rather than the one branch you were looking at.
• Regex rules deliberately unsupported — one roommate's bad pattern would break everyone's import.

Also included

• lib/core/dates.dart, de-duplicating the identical private _isoDate from two repositories.
• .github/workflows/test.yml — neither existing workflow ran analyze or test, so nothing enforced the suite.

Verification

• flutter analyze clean; 165 tests pass (102 new)
• flutter build web --release succeeds with both file_picker and image_picker
• Parsed against three real statements — 169 rows, two header dialects (one BOM'd and fully quoted), zero issues, counts reconciling exactly
• Migration 0011 applied and verified on the dev DB under set local role authenticated + JWT impersonation:
  • same fingerprint twice → {"inserted": 0, "skipped": 1} (proves the partial-index arbiter binds)
  • soft-delete → reimport → inserted: 1
  • sum / credit / non-member guards all raise readable sentences, not Postgres internals
  • merchant_rules RLS round-trips

Not in scope

PDF import is phase 2. The seam exists — add a parser to kStatementParsers and nothing else changes. It must stay client-side, which rules out native-only libraries like pdf_text.

See docs/statement-import.md for the threat model and the parser quirks.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BK6T2aAySsWFu27SUq6bTc