Open-source personal finance manager. Self-hosted, privacy-first.
feat: customizable CSV column mapping for imports (#201) (#206)
Tássio Noronhafefc7c26aed9
diff --git a/backend/app/api/import_transactions.py b/backend/app/api/import_transactions.pyindex ba9733ac..ad015713 100644--- a/backend/app/api/import_transactions.py+++ b/backend/app/api/import_transactions.py@@ -1,3 +1,4 @@+import jsonimport loggingfrom typing import Optional@@ -23,6 +24,7 @@ async def preview_import(flip_amount: bool = Form(False),inflow_column: Optional[str] = Form(None),outflow_column: Optional[str] = Form(None),+ column_mapping: Optional[str] = Form(None),session: AsyncSession = Depends(get_async_session),user: User = Depends(current_active_user),):@@ -34,6 +36,23 @@ async def preview_import(filename, len(content), file.content_type,)+ # column_mapping arrives as a JSON-encoded form field (Securo field -> CSV header)+ parsed_mapping: Optional[dict] = None+ if column_mapping:+ try:+ parsed_mapping = json.loads(column_mapping)+ except json.JSONDecodeError:+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail="Invalid column_mapping: must be a JSON object",+ )+ if not isinstance(parsed_mapping, dict):+ raise HTTPException(+ status_code=status.HTTP_400_BAD_REQUEST,+ detail="Invalid column_mapping: must be a JSON object",+ )++ parse_error: Optional[str] = Nonetry:if filename.lower().endswith('.ofx') or filename.lower().endswith('.qfx'):transactions = import_service.parse_ofx(content)@@ -45,14 +64,24 @@ async def preview_import(transactions = import_service.parse_camt(content)detected_format = "camt"elif filename.lower().endswith('.csv'):- transactions = import_service.parse_csv(- content,- date_format=date_format,- flip_amount=flip_amount,- inflow_column=inflow_column,- outflow_column=outflow_column,- )detected_format = "csv"+ try:+ transactions = import_service.parse_csv(+ content,+ date_format=date_format,+ flip_amount=flip_amount,+ inflow_column=inflow_column,+ outflow_column=outflow_column,+ column_mapping=parsed_mapping,+ )+ except ValueError as csv_err:+ # The CSV's columns couldn't be auto-mapped. As long as we can+ # still read its headers, return a soft failure so the UI can+ # show the column-mapping dropdowns instead of a hard error.+ if not import_service.detect_csv_columns(content):+ raise+ transactions = []+ parse_error = str(csv_err)else:# Try to detect formattry:@@ -91,7 +120,20 @@ async def preview_import(session, user.id, transactions,)- return TransactionImportPreview(transactions=transactions, detected_format=detected_format)+ # Expose CSV headers so the UI can offer accurate column-mapping dropdowns.+ csv_columns: list[str] = []+ if detected_format == "csv":+ try:+ csv_columns = import_service.detect_csv_columns(content)+ except Exception:+ csv_columns = []++ return TransactionImportPreview(+ transactions=transactions,+ detected_format=detected_format,+ csv_columns=csv_columns,+ parse_error=parse_error,+ )@router.post("/import", status_code=status.HTTP_201_CREATED)diff --git a/backend/app/schemas/transaction.py b/backend/app/schemas/transaction.pyindex 20504082..d556ca13 100644--- a/backend/app/schemas/transaction.py+++ b/backend/app/schemas/transaction.py@@ -152,6 +152,12 @@ class TransactionImport(TransactionBase):class TransactionImportPreview(BaseModel):transactions: list[TransactionImport]detected_format: str+ # CSV header column names, exposed so the UI can offer column-mapping+ # dropdowns. Empty for non-CSV formats.+ csv_columns: list[str] = []+ # Set when a CSV's columns could not be auto-detected. The preview still+ # succeeds (with no transactions) so the UI can show the mapping dropdowns.+ parse_error: Optional[str] = Noneclass TransactionImportRequest(BaseModel):diff --git a/backend/app/services/import_service.py b/backend/app/services/import_service.pyindex 514fcf24..0b7742e8 100644--- a/backend/app/services/import_service.py+++ b/backend/app/services/import_service.py@@ -266,6 +266,33 @@ DATE_FORMAT_MAP = {'YYYY-MM-DD': '%Y-%m-%d',}+# Securo fields a CSV column can be mapped to. Used to validate the+# user-supplied column_mapping and to drive the import-UI dropdowns.+CSV_MAPPABLE_FIELDS = (+ 'date', 'description', 'amount', 'type',+ 'category', 'currency', 'fx_rate', 'inflow', 'outflow',+)+++def _sniff_csv_dialect(text: str):+ """Detect the CSV dialect (delimiter/quoting), falling back to comma."""+ try:+ return csv.Sniffer().sniff(text[:4096], delimiters=',;\t|')+ except csv.Error:+ return csv.excel+++def detect_csv_columns(content: bytes) -> list[str]:+ """Return the CSV header column names exactly as they appear in the file.++ Used by the import preview so the UI can offer accurate column-mapping+ dropdowns instead of guessing headers client-side.+ """+ text = content.decode('utf-8-sig') # Handle BOM+ dialect = _sniff_csv_dialect(text)+ reader = csv.DictReader(io.StringIO(text), dialect=dialect)+ return [f.strip() for f in (reader.fieldnames or []) if f and f.strip()]+def parse_csv(content: bytes,@@ -273,6 +300,7 @@ def parse_csv(flip_amount: bool = False,inflow_column: str | None = None,outflow_column: str | None = None,+ column_mapping: dict[str, str] | None = None,) -> list[TransactionImport]:"""Parse CSV file content and return transactions.@@ -284,13 +312,11 @@ def parse_csv(- date_format: explicit date format (DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD)- flip_amount: negate all parsed amounts- inflow_column/outflow_column: use split columns instead of single amount+ - column_mapping: explicit Securo-field -> CSV-header map. Any field+ present here overrides auto-detection; unmapped fields still auto-detect."""text = content.decode('utf-8-sig') # Handle BOM- sample = text[:4096]- try:- dialect = csv.Sniffer().sniff(sample, delimiters=',;\t|')- except csv.Error:- dialect = csv.excel # fallback to comma+ dialect = _sniff_csv_dialect(text)reader = csv.DictReader(io.StringIO(text), dialect=dialect)# Normalize field names@@ -305,31 +331,55 @@ def parse_csv(currency_cols = ['currency', 'moeda', 'currency_code']fx_rate_cols = ['fx_rate', 'fx_rate_used', 'taxa_cambio', 'exchange_rate', 'taxa']+ # Normalize the user-supplied column mapping (Securo field -> CSV header).+ mapping = {+ field: value.lower().strip()+ for field, value in (column_mapping or {}).items()+ if field in CSV_MAPPABLE_FIELDS and value and value.strip()+ }+def find_col(candidates):for c in candidates:if c in fieldnames:return creturn None- date_col = find_col(date_cols)- desc_col = find_col(desc_cols)+ def resolve_col(field, candidates):+ """Resolve a CSV column for a Securo field.++ An explicit user mapping always wins; otherwise fall back to+ auto-detection against the known column-name candidates.+ """+ mapped = mapping.get(field)+ if mapped:+ if mapped not in fieldnames:+ raise ValueError(+ f"Mapped column '{mapped}' for field '{field}' not found in CSV. "+ f"Available columns: {', '.join(fieldnames)}"+ )+ return mapped+ return find_col(candidates)++ date_col = resolve_col('date', date_cols)+ desc_col = resolve_col('description', desc_cols)- # In split mode, we don't require a single amount column- use_split = inflow_column and outflow_column- inflow_col = inflow_column.lower().strip() if inflow_column else None- outflow_col = outflow_column.lower().strip() if outflow_column else None+ # In split mode, we don't require a single amount column. The inflow/outflow+ # columns may come from the explicit args or from the column mapping.+ inflow_col = (inflow_column or mapping.get('inflow') or '').lower().strip() or None+ outflow_col = (outflow_column or mapping.get('outflow') or '').lower().strip() or None+ use_split = bool(inflow_col and outflow_col)if use_split:if inflow_col not in fieldnames or outflow_col not in fieldnames:raise ValueError(f"Inflow/outflow columns not found in CSV. Available columns: {', '.join(fieldnames)}")amount_col = Noneelse:- amount_col = find_col(amount_cols)+ amount_col = resolve_col('amount', amount_cols)- type_col = find_col(type_cols)- category_col = find_col(category_cols)- currency_col = find_col(currency_cols)- fx_rate_col = find_col(fx_rate_cols)+ type_col = resolve_col('type', type_cols)+ category_col = resolve_col('category', category_cols)+ currency_col = resolve_col('currency', currency_cols)+ fx_rate_col = resolve_col('fx_rate', fx_rate_cols)if not date_col or not desc_col:raise ValueError(diff --git a/backend/tests/test_import_api.py b/backend/tests/test_import_api.pyindex da126fbe..6d7fbbdd 100644--- a/backend/tests/test_import_api.py+++ b/backend/tests/test_import_api.py@@ -1,3 +1,5 @@+import json+import pytestfrom httpx import AsyncClient@@ -22,34 +24,109 @@ async def test_preview_csv_import(client: AsyncClient, auth_headers, test_accoun@pytest.mark.asyncio-async def test_preview_invalid_file(client: AsyncClient, auth_headers, test_account):+async def test_preview_csv_returns_columns(client: AsyncClient, auth_headers, test_account):+ """The preview response exposes the CSV header columns for the mapping UI."""+ csv_content = b"Posted On,Memo Line,Movement\n2026-01-10,COFFEE,-12.50\n"response = await client.post("/api/transactions/import/preview",headers=auth_headers,- files={"file": ("bad.csv", b"col1,col2,col3\na,b,c\n", "text/csv")},+ files={"file": ("bank.csv", csv_content, "text/csv")},+ data={"column_mapping": json.dumps({+ "date": "Posted On",+ "description": "Memo Line",+ "amount": "Movement",+ })},+ )+ assert response.status_code == 200+ data = response.json()+ assert data["csv_columns"] == ["Posted On", "Memo Line", "Movement"]+ assert len(data["transactions"]) == 1+ assert data["transactions"][0]["description"] == "COFFEE"+ assert data["transactions"][0]["amount"] == "12.50"+++async def test_preview_csv_with_column_mapping(client: AsyncClient, auth_headers, test_account):+ """A CSV with non-standard headers parses once columns are mapped."""+ csv_content = b"transaction_date,details,value\n15/02/2026,GROCERY STORE,-80.00\n"+ # Without a mapping the description column can't be auto-detected: the+ # preview soft-fails (200) with a parse_error and no transactions.+ fail = await client.post(+ "/api/transactions/import/preview",+ headers=auth_headers,+ files={"file": ("export.csv", csv_content, "text/csv")},+ )+ assert fail.status_code == 200+ assert fail.json()["parse_error"]+ assert fail.json()["transactions"] == []++ # With a mapping it parses successfully.+ ok = await client.post(+ "/api/transactions/import/preview",+ headers=auth_headers,+ files={"file": ("export.csv", csv_content, "text/csv")},+ data={"column_mapping": json.dumps({+ "date": "transaction_date",+ "description": "details",+ "amount": "value",+ })},+ )+ assert ok.status_code == 200+ data = ok.json()+ assert len(data["transactions"]) == 1+ assert data["transactions"][0]["description"] == "GROCERY STORE"+ assert data["transactions"][0]["type"] == "debit"+++async def test_preview_invalid_column_mapping_json(client: AsyncClient, auth_headers, test_account):+ """A malformed column_mapping payload returns a 400 instead of a 500."""+ csv_content = b"date,description,amount\n2026-01-10,X,-1.00\n"+ response = await client.post(+ "/api/transactions/import/preview",+ headers=auth_headers,+ files={"file": ("export.csv", csv_content, "text/csv")},+ data={"column_mapping": "{not valid json"},)assert response.status_code == 400+ assert "column_mapping" in response.json()["detail"]+++async def test_preview_unrecognized_csv_soft_fails_with_columns(+ client: AsyncClient, auth_headers, test_account+):+ """A CSV whose columns can't be auto-detected returns a soft failure (200)+ with the detected columns, so the UI can offer column mapping."""+ response = await client.post(+ "/api/transactions/import/preview",+ headers=auth_headers,+ files={"file": ("bad.csv", b"col1,col2,col3\na,b,c\n", "text/csv")},+ )+ assert response.status_code == 200data = response.json()- assert "detail" in data- assert data["detail"] # must not be empty+ assert data["detected_format"] == "csv"+ assert data["transactions"] == []+ assert data["csv_columns"] == ["col1", "col2", "col3"]+ assert data["parse_error"] # must not be empty@pytest.mark.asyncio-async def test_preview_invalid_file_returns_specific_error(+async def test_preview_unrecognized_csv_parse_error_is_specific(client: AsyncClient, auth_headers, test_account):- """Error response should tell the user what columns were found and what is expected."""+ """The parse_error should tell the user what columns were found and what is expected."""response = await client.post("/api/transactions/import/preview",headers=auth_headers,files={"file": ("bad.csv", b"foo,bar,baz\n1,2,3\n", "text/csv")},)- assert response.status_code == 400- detail = response.json()["detail"]+ assert response.status_code == 200+ parse_error = response.json()["parse_error"]# Should mention what columns were found in the file- assert "foo" in detail+ assert "foo" in parse_error# Should mention what columns are expected- assert "date" in detail and "description" in detail and "amount" in detail+ assert "date" in parse_error and "description" in parse_error and "amount" in parse_error@pytest.mark.asynciodiff --git a/backend/tests/test_import_service.py b/backend/tests/test_import_service.pyindex 7497524a..678ec4e6 100644--- a/backend/tests/test_import_service.py+++ b/backend/tests/test_import_service.py@@ -9,7 +9,14 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom app.models.account import Accountfrom app.models.fx_rate import FxRatefrom app.models.user import User-from app.services.import_service import parse_csv, parse_ofx, parse_qif, parse_camt, import_transactions+from app.services.import_service import (+ detect_csv_columns,+ parse_csv,+ parse_ofx,+ parse_qif,+ parse_camt,+ import_transactions,+)class TestParseCsv:@@ -249,6 +256,214 @@ class TestParseCsv:assert transactions[1].amount == Decimal("1200.00")+class TestParseCsvColumnMapping:+ """Tests for customizable CSV column mapping (issue #201)."""++ def test_column_mapping_unrecognized_headers(self):+ """A CSV with headers Securo can't auto-detect parses with an explicit mapping."""+ csv_content = (+ "Posted On,Memo Line,Movement\n"+ "2026-01-10,COFFEE SHOP,-12.50\n"+ "2026-01-11,PAYCHECK,3000.00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={+ "date": "Posted On",+ "description": "Memo Line",+ "amount": "Movement",+ },+ )+ assert len(transactions) == 2+ assert transactions[0].description == "COFFEE SHOP"+ assert transactions[0].amount == Decimal("12.50")+ assert transactions[0].type == "debit"+ assert transactions[1].description == "PAYCHECK"+ assert transactions[1].type == "credit"++ def test_column_mapping_without_mapping_raises(self):+ """The same unrecognized CSV fails without a mapping — proving the mapping is what fixes it."""+ csv_content = "Posted On,Memo Line,Movement\n2026-01-10,COFFEE SHOP,-12.50\n"+ with pytest.raises(ValueError):+ parse_csv(csv_content.encode("utf-8"))++ def test_column_mapping_overrides_autodetection(self):+ """An explicit mapping wins over a column that would otherwise auto-detect."""+ # Both `description` and `details` exist; mapping forces `details`.+ csv_content = (+ "date,description,details,amount\n"+ "2026-01-10,WRONG,RIGHT,-10.00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"description": "details"},+ )+ assert len(transactions) == 1+ assert transactions[0].description == "RIGHT"++ def test_column_mapping_partial_falls_back_to_autodetect(self):+ """Unmapped fields still auto-detect; only mapped fields are overridden."""+ csv_content = (+ "txn_date,description,amount\n"+ "2026-01-10,GROCERIES,-55.00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"date": "txn_date"},+ )+ assert len(transactions) == 1+ assert transactions[0].date == date(2026, 1, 10)+ assert transactions[0].description == "GROCERIES"+ assert transactions[0].amount == Decimal("55.00")++ def test_column_mapping_missing_column_raises(self):+ """Mapping a field to a column that doesn't exist raises a helpful error."""+ csv_content = "date,description,amount\n2026-01-10,X,-1.00\n"+ with pytest.raises(ValueError, match="nonexistent"):+ parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"amount": "nonexistent"},+ )++ def test_column_mapping_case_insensitive(self):+ """Mapping values are matched case-insensitively against CSV headers."""+ csv_content = "Date,Description,Amount\n2026-01-10,X,-1.00\n"+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"date": "DATE", "description": "Description", "amount": "amount"},+ )+ assert len(transactions) == 1+ assert transactions[0].amount == Decimal("1.00")++ def test_column_mapping_split_inflow_outflow(self):+ """Inflow/outflow split columns can be supplied via column_mapping."""+ csv_content = (+ "Posted On,Memo,Credits,Debits\n"+ "2026-01-10,SALARY,5000.00,\n"+ "2026-01-11,RENT,,1200.00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={+ "date": "Posted On",+ "description": "Memo",+ "inflow": "Credits",+ "outflow": "Debits",+ },+ )+ assert len(transactions) == 2+ assert transactions[0].type == "credit"+ assert transactions[0].amount == Decimal("5000.00")+ assert transactions[1].type == "debit"+ assert transactions[1].amount == Decimal("1200.00")++ def test_column_mapping_currency_and_fx_rate(self):+ """Currency and fx_rate columns can be mapped from non-standard headers."""+ csv_content = (+ "date,description,amount,ccy,exch\n"+ "2026-01-10,HOTEL,-100.00,EUR,1.08\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"currency": "ccy", "fx_rate": "exch"},+ )+ assert len(transactions) == 1+ assert transactions[0].currency == "EUR"+ assert transactions[0].fx_rate == Decimal("1.08")++ def test_column_mapping_ignores_empty_values(self):+ """Empty mapping values are ignored and fall back to auto-detection."""+ csv_content = "date,description,amount\n2026-01-10,X,-1.00\n"+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={"date": "", "description": " "},+ )+ assert len(transactions) == 1+ assert transactions[0].description == "X"++ def test_column_mapping_type_column_drives_credit_debit(self):+ """A mapped type column overrides the amount sign for credit/debit."""+ # All amounts are positive — only the Direction column distinguishes them.+ csv_content = (+ "Booking Date,Counterparty,Net,Direction\n"+ "2026-04-01,Whole Foods,55.00,debit\n"+ "2026-04-02,Employer Inc,4200.00,credit\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={+ "date": "Booking Date",+ "description": "Counterparty",+ "amount": "Net",+ "type": "Direction",+ },+ )+ assert len(transactions) == 2+ assert transactions[0].type == "debit"+ assert transactions[0].amount == Decimal("55.00")+ assert transactions[1].type == "credit"+ assert transactions[1].amount == Decimal("4200.00")++ def test_column_mapping_with_explicit_date_format(self):+ """Column mapping composes with an explicit date_format."""+ csv_content = (+ "Posting Date,Details,Amount\n"+ "22/03/2026,Gym Membership,-60.00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ date_format="DD/MM/YYYY",+ column_mapping={+ "date": "Posting Date",+ "description": "Details",+ "amount": "Amount",+ },+ )+ assert len(transactions) == 1+ assert transactions[0].date == date(2026, 3, 22)+ assert transactions[0].description == "Gym Membership"++ def test_column_mapping_semicolon_delimiter(self):+ """Column mapping works on semicolon-delimited CSVs with comma decimals."""+ csv_content = (+ "Fecha;Concepto;Importe\n"+ "2026-07-02;Nomina;3.500,00\n"+ "2026-07-03;Hotel;-200,00\n"+ )+ transactions = parse_csv(+ csv_content.encode("utf-8"),+ column_mapping={+ "date": "Fecha",+ "description": "Concepto",+ "amount": "Importe",+ },+ )+ assert len(transactions) == 2+ assert transactions[0].amount == Decimal("3500.00")+ assert transactions[0].type == "credit"+ assert transactions[1].amount == Decimal("200.00")+ assert transactions[1].type == "debit"+++class TestDetectCsvColumns:+ """Tests for detect_csv_columns — used to drive the import-UI mapping dropdowns."""++ def test_detect_basic(self):+ csv_content = b"Posted On,Memo Line,Movement\n2026-01-10,COFFEE,-12.50\n"+ assert detect_csv_columns(csv_content) == ["Posted On", "Memo Line", "Movement"]++ def test_detect_semicolon_delimiter(self):+ csv_content = b"date;description;amount\n2026-01-10;COFFEE;-12.50\n"+ assert detect_csv_columns(csv_content) == ["date", "description", "amount"]++ def test_detect_strips_whitespace_and_bom(self):+ csv_content = " date , description , amount \n2026-01-10,X,-1.00\n".encode("utf-8-sig")+ assert detect_csv_columns(csv_content) == ["date", "description", "amount"]++ def test_detect_empty_file(self):+ assert detect_csv_columns(b"") == []++class TestParseQif:"""Tests for the parse_qif function."""diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 2d534c93..94c146cc 100644--- a/frontend/src/lib/api.ts+++ b/frontend/src/lib/api.ts@@ -367,13 +367,17 @@ export const transactions = {flip_amount?: booleaninflow_column?: stringoutflow_column?: string- }): Promise<{ transactions: ImportPreviewTransaction[]; detected_format: string }> => {+ column_mapping?: Record<string, string>+ }): Promise<{ transactions: ImportPreviewTransaction[]; detected_format: string; csv_columns?: string[]; parse_error?: string | null }> => {const formData = new FormData()formData.append('file', file)if (options?.date_format) formData.append('date_format', options.date_format)if (options?.flip_amount) formData.append('flip_amount', 'true')if (options?.inflow_column) formData.append('inflow_column', options.inflow_column)if (options?.outflow_column) formData.append('outflow_column', options.outflow_column)+ if (options?.column_mapping && Object.keys(options.column_mapping).length > 0) {+ formData.append('column_mapping', JSON.stringify(options.column_mapping))+ }const { data } = await api.post('/transactions/import/preview', formData)return data},diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex a7d84574..e4ee803c 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -647,6 +647,17 @@"inflowColumn": "Inflow column","outflowColumn": "Outflow column","selectColumn": "Select column...",+ "columnMapping": "Column mapping",+ "columnMappingHint": "Map your CSV columns to Securo fields. Leave on auto-detect to keep the detected column.",+ "columnAutoDetect": "Auto-detect",+ "mappingNeeded": "We couldn't recognize your CSV columns automatically. Map them to Securo fields below to continue.",+ "mapDate": "Date column",+ "mapDescription": "Description column",+ "mapAmount": "Amount column",+ "mapType": "Type column",+ "mapCategory": "Category column",+ "mapCurrency": "Currency column",+ "mapFxRate": "FX rate column","title": "Import","subtitle": "Bank statement","processing": "Processing file…",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex f481298f..cb1921be 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -647,6 +647,17 @@"inflowColumn": "Coluna de entrada","outflowColumn": "Coluna de saída","selectColumn": "Selecionar coluna...",+ "columnMapping": "Mapeamento de colunas",+ "columnMappingHint": "Associe as colunas do seu CSV aos campos do Securo. Deixe em automático para manter a coluna detectada.",+ "columnAutoDetect": "Detectar automaticamente",+ "mappingNeeded": "Não reconhecemos as colunas do seu CSV automaticamente. Associe-as aos campos do Securo abaixo para continuar.",+ "mapDate": "Coluna de data",+ "mapDescription": "Coluna de descrição",+ "mapAmount": "Coluna de valor",+ "mapType": "Coluna de tipo",+ "mapCategory": "Coluna de categoria",+ "mapCurrency": "Coluna de moeda",+ "mapFxRate": "Coluna de câmbio","title": "Importar","subtitle": "Extrato bancário","processing": "Processando arquivo…",diff --git a/frontend/src/pages/import.tsx b/frontend/src/pages/import.tsxindex aa0406d9..716381b7 100644--- a/frontend/src/pages/import.tsx+++ b/frontend/src/pages/import.tsx@@ -23,6 +23,17 @@ const TYPE_LABELS: Record<string, string> = {investment: 'accounts.typeInvestment',}+// Securo fields a CSV column can be mapped to, in display order.+const CSV_MAPPING_FIELDS = [+ { key: 'date', label: 'import.mapDate' },+ { key: 'description', label: 'import.mapDescription' },+ { key: 'amount', label: 'import.mapAmount' },+ { key: 'type', label: 'import.mapType' },+ { key: 'category', label: 'import.mapCategory' },+ { key: 'currency', label: 'import.mapCurrency' },+ { key: 'fx_rate', label: 'import.mapFxRate' },+] as const+function toReviewTransactions(txns: ImportPreviewTransaction[]): ImportReviewTransaction[] {return txns.map((tx, i) => ({...tx,@@ -39,7 +50,7 @@ export default function ImportPage() {const locale = i18n.language === 'en' ? 'en-US' : i18n.languageconst queryClient = useQueryClient()const fileInputRef = useRef<HTMLInputElement>(null)- const [previewData, setPreviewData] = useState<{ transactions: ImportPreviewTransaction[]; detected_format: string } | null>(null)+ const [previewData, setPreviewData] = useState<{ transactions: ImportPreviewTransaction[]; detected_format: string; csv_columns?: string[]; parse_error?: string | null } | null>(null)const [reviewTransactions, setReviewTransactions] = useState<ImportReviewTransaction[]>([])const [selectedAccount, setSelectedAccount] = useState('')const [dragOver, setDragOver] = useState(false)@@ -60,6 +71,7 @@ export default function ImportPage() {const [csvSplitColumns, setCsvSplitColumns] = useState(false)const [csvInflowColumn, setCsvInflowColumn] = useState('')const [csvOutflowColumn, setCsvOutflowColumn] = useState('')+ const [csvColumnMapping, setCsvColumnMapping] = useState<Record<string, string>>({})const { data: accountsList } = useQuery({queryKey: ['accounts'],@@ -82,10 +94,11 @@ export default function ImportPage() {})const previewMutation = useMutation({- mutationFn: ({ file, options }: { file: File; options?: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string } }) =>+ mutationFn: ({ file, options }: { file: File; options?: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string; column_mapping?: Record<string, string> } }) =>transactionsApi.previewImport(file, options),onSuccess: (data) => {setPreviewData(data)+ setCsvHeaders(data.csv_columns ?? [])setReviewTransactions(toReviewTransactions(data.transactions))setSearchQuery('')setFilterCategoryIds([])@@ -163,6 +176,7 @@ export default function ImportPage() {setCsvSplitColumns(false)setCsvInflowColumn('')setCsvOutflowColumn('')+ setCsvColumnMapping({})setCsvHeaders([])}@@ -170,35 +184,50 @@ export default function ImportPage() {setFileName(file.name)setCurrentFile(file)resetCsvOptions()-- // Extract CSV headers for column mapping- if (file.name.toLowerCase().endsWith('.csv')) {- const reader = new FileReader()- reader.onload = (e) => {- const text = e.target?.result as string- const firstLine = text.split('\n')[0]- if (firstLine) {- setCsvHeaders(firstLine.split(',').map(h => h.trim()))- }- }- reader.readAsText(file)- }-+ // CSV headers come back from the preview response (csv_columns), which+ // parses the file server-side and handles any delimiter/quoting.previewMutation.mutate({ file })}- const rePreview = useCallback(() => {+ // Re-run the preview with the current CSV options. Accepts overrides so a+ // change handler can pass its new value synchronously instead of waiting+ // for the corresponding state update to flush.+ const rePreview = useCallback((overrides?: {+ date_format?: string+ flip_amount?: boolean+ split?: boolean+ inflow?: string+ outflow?: string+ mapping?: Record<string, string>+ }) => {if (!currentFile) return- const options: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string } = {}- if (csvDateFormat) options.date_format = csvDateFormat- if (csvFlipAmount) options.flip_amount = true- if (csvSplitColumns && csvInflowColumn && csvOutflowColumn) {- options.inflow_column = csvInflowColumn- options.outflow_column = csvOutflowColumn+ const dateFormat = overrides?.date_format ?? csvDateFormat+ const flip = overrides?.flip_amount ?? csvFlipAmount+ const split = overrides?.split ?? csvSplitColumns+ const inflow = overrides?.inflow ?? csvInflowColumn+ const outflow = overrides?.outflow ?? csvOutflowColumn+ const mapping = overrides?.mapping ?? csvColumnMapping++ const options: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string; column_mapping?: Record<string, string> } = {}+ if (dateFormat) options.date_format = dateFormat+ if (flip) options.flip_amount = true+ if (split && inflow && outflow) {+ options.inflow_column = inflow+ options.outflow_column = outflow}+ const cleanMapping = Object.fromEntries(Object.entries(mapping).filter(([, v]) => v))+ if (Object.keys(cleanMapping).length > 0) options.column_mapping = cleanMappingpreviewMutation.mutate({ file: currentFile, options })// eslint-disable-next-line react-hooks/exhaustive-deps- }, [currentFile, csvDateFormat, csvFlipAmount, csvSplitColumns, csvInflowColumn, csvOutflowColumn])+ }, [currentFile, csvDateFormat, csvFlipAmount, csvSplitColumns, csvInflowColumn, csvOutflowColumn, csvColumnMapping])++ const handleMappingChange = useCallback((field: string, column: string) => {+ setCsvColumnMapping(prev => {+ const next = { ...prev, [field]: column }+ rePreview({ mapping: next })+ return next+ })+ }, [rePreview])const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {const file = e.target.files?.[0]@@ -371,13 +400,20 @@ export default function ImportPage() {<Settings2 size={14} className="text-muted-foreground" /><p className="text-xs font-medium text-muted-foreground">{t('import.csvOptions')}</p></div>++ {previewData.parse_error && (+ <div className="flex items-start gap-2 text-xs text-amber-700 bg-amber-50 border border-amber-200 px-3 py-2 rounded-lg mb-3">+ <AlertCircle size={14} className="shrink-0 mt-0.5" />+ <span>{t('import.mappingNeeded')}</span>+ </div>+ )}<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4"><div><Label className="text-xs text-muted-foreground mb-1 block">{t('import.dateFormat')}</Label><selectclassName="w-full border border-border rounded-lg px-3 py-1.5 text-sm bg-card text-foreground focus:outline-none focus:ring-2 focus:ring-primary"value={csvDateFormat}- onChange={(e) => { setCsvDateFormat(e.target.value); setTimeout(rePreview, 0) }}+ onChange={(e) => { setCsvDateFormat(e.target.value); rePreview({ date_format: e.target.value }) }}><option value="">{t('import.dateFormatAuto')}</option><option value="DD/MM/YYYY">DD/MM/YYYY</option>@@ -390,7 +426,7 @@ export default function ImportPage() {type="checkbox"id="flip-amount"checked={csvFlipAmount}- onChange={(e) => { setCsvFlipAmount(e.target.checked); setTimeout(rePreview, 0) }}+ onChange={(e) => { setCsvFlipAmount(e.target.checked); rePreview({ flip_amount: e.target.checked }) }}className="rounded border-border text-primary focus:ring-primary"/><Label htmlFor="flip-amount" className="text-sm text-muted-foreground cursor-pointer">@@ -402,7 +438,7 @@ export default function ImportPage() {type="checkbox"id="split-columns"checked={csvSplitColumns}- onChange={(e) => setCsvSplitColumns(e.target.checked)}+ onChange={(e) => { setCsvSplitColumns(e.target.checked); rePreview({ split: e.target.checked }) }}className="rounded border-border text-primary focus:ring-primary"/><Label htmlFor="split-columns" className="text-sm text-muted-foreground cursor-pointer">@@ -430,7 +466,7 @@ export default function ImportPage() {<selectclassName="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"value={csvInflowColumn}- onChange={(e) => { setCsvInflowColumn(e.target.value); setTimeout(rePreview, 0) }}+ onChange={(e) => { setCsvInflowColumn(e.target.value); rePreview({ inflow: e.target.value }) }}><option value="">{t('import.selectColumn')}</option>{csvHeaders.map(h => <option key={h} value={h}>{h}</option>)}@@ -441,7 +477,7 @@ export default function ImportPage() {<selectclassName="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"value={csvOutflowColumn}- onChange={(e) => { setCsvOutflowColumn(e.target.value); setTimeout(rePreview, 0) }}+ onChange={(e) => { setCsvOutflowColumn(e.target.value); rePreview({ outflow: e.target.value }) }}><option value="">{t('import.selectColumn')}</option>{csvHeaders.map(h => <option key={h} value={h}>{h}</option>)}@@ -449,6 +485,31 @@ export default function ImportPage() {</div></div>)}++ {/* Column mapping — map CSV headers to Securo fields */}+ {csvHeaders.length > 0 && (+ <div className="mt-4 pt-4 border-t border-border">+ <p className="text-xs font-medium text-muted-foreground">{t('import.columnMapping')}</p>+ <p className="text-xs text-muted-foreground mt-0.5 mb-3">{t('import.columnMappingHint')}</p>+ <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">+ {CSV_MAPPING_FIELDS+ .filter((f) => !(csvSplitColumns && f.key === 'amount'))+ .map((f) => (+ <div key={f.key}>+ <Label className="text-xs text-muted-foreground mb-1 block">{t(f.label)}</Label>+ <select+ className="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"+ value={csvColumnMapping[f.key] ?? ''}+ onChange={(e) => handleMappingChange(f.key, e.target.value)}+ >+ <option value="">{t('import.columnAutoDetect')}</option>+ {csvHeaders.map((h) => <option key={h} value={h}>{h}</option>)}+ </select>+ </div>+ ))}+ </div>+ </div>+ )}</div>)}@@ -490,7 +551,7 @@ export default function ImportPage() {</button><ButtononClick={() => importMutation.mutate()}- disabled={!selectedAccount || importMutation.isPending}+ disabled={!selectedAccount || importMutation.isPending || reviewTransactions.length === 0}className="gap-2"><Upload size={14} />