Phase 3: CSV Import #45

New Issue

Closed

opened 2026-05-16 18:17:28 -05:00 by null · 0 comments

null commented

2026-05-16 18:17:28 -05:00

Owner

Goal

Let users import transaction data from CSV files. Imported transactions go into the shared transactions table from Phase 2.

Depends on: Phase 2 (#44) — needs data_sources, financial_accounts, transactions tables
Blocks: Phase 4 (#46) (matching needs imported transactions)
Parent: #42

Scope

Implement

CSV upload endpoint
CSV preview endpoint (parse headers, sample rows, suggest mappings)
Column mapping UI
Import commit endpoint
Import dedupe (hash-based if no transaction ID)
Frontend: upload → preview → map → commit

Do NOT implement

OFX/QFX
SimpleFIN
Auto matching
Background jobs

Backend API

POST /api/import/csv/preview — parse CSV, return headers, sample rows, suggested mapping, validation issues. No writes.
POST /api/import/csv/commit — commit with import_session_id + mapping, insert into transactions table, skip duplicates, return {imported, skipped, failed, details}
GET /api/import/history — list last 100 imports

All endpoints gated by DATA_IMPORT_ENABLED env var (defaults to true, returns 403 when false).

Dedupe Strategy

If CSV has transaction IDs → used as provider_transaction_id with csv:id: prefix
Otherwise → SHA-256 hash from posted_date + amount + description + payee + account_name stored as csv:hash: prefixed provider_transaction_id
Importing the same CSV twice skips duplicates

Frontend

DataPage.jsx → Import Transaction CSV section:

Upload CSV file
Preview rows with sample table
Map columns (13 mappable fields, required indicators)
Commit import
Show imported/skipped/failed counts + per-row error details

Acceptance Criteria

User can preview CSV before importing
User can map columns to fields
User can commit import
Transactions saved to shared transactions table
Duplicate imports are skipped
Import errors shown clearly
Existing manual workflows still work

Previous → Phase 2 (#44)
Next → Phase 4 (#46)

## Goal Let users import transaction data from CSV files. Imported transactions go into the shared `transactions` table from Phase 2. **Depends on:** Phase 2 (#44) — needs data_sources, financial_accounts, transactions tables **Blocks:** Phase 4 (#46) (matching needs imported transactions) **Parent:** #42 --- ## Scope ### Implement - CSV upload endpoint - CSV preview endpoint (parse headers, sample rows, suggest mappings) - Column mapping UI - Import commit endpoint - Import dedupe (hash-based if no transaction ID) - Frontend: upload → preview → map → commit ### Do NOT implement - OFX/QFX - SimpleFIN - Auto matching - Background jobs --- ## Backend API - `POST /api/import/csv/preview` — parse CSV, return headers, sample rows, suggested mapping, validation issues. No writes. - `POST /api/import/csv/commit` — commit with `import_session_id` + `mapping`, insert into `transactions` table, skip duplicates, return `{imported, skipped, failed, details}` - `GET /api/import/history` — list last 100 imports All endpoints gated by `DATA_IMPORT_ENABLED` env var (defaults to true, returns 403 when false). --- ## Dedupe Strategy - If CSV has transaction IDs → used as `provider_transaction_id` with `csv:id:` prefix - Otherwise → SHA-256 hash from `posted_date + amount + description + payee + account_name` stored as `csv:hash:` prefixed `provider_transaction_id` - Importing the same CSV twice skips duplicates --- ## Frontend `DataPage.jsx` → Import Transaction CSV section: 1. Upload CSV file 2. Preview rows with sample table 3. Map columns (13 mappable fields, required indicators) 4. Commit import 5. Show imported/skipped/failed counts + per-row error details --- ## Acceptance Criteria - [x] User can preview CSV before importing - [x] User can map columns to fields - [x] User can commit import - [x] Transactions saved to shared transactions table - [x] Duplicate imports are skipped - [x] Import errors shown clearly - [x] Existing manual workflows still work --- **Previous → Phase 2 (#44)** **Next → Phase 4 (#46)**