← Tutti i modelli

Caricamento, validazione di ogni riga, anteprima degli errori, importazione in background.

Spec — CSV import

Status: draft · Created: 2026-11-10

1. Context and goal

People bring existing records in from a spreadsheet, see every problem before anything is saved, and keep working while large files import.

2. Functional requirements (EARS)

  • FR-1: WHEN a file is uploaded, THE SYSTEM SHALL accept UTF-8 CSV with comma or semicolon separators up to 50 MB and 100,000 rows, and answer 413 for a larger file and 422 for another format.
  • FR-2: WHEN the header row is read, THE SYSTEM SHALL map columns to fields by name, ignoring case and spaces, and let the person change the mapping before validation.
  • FR-3: THE SYSTEM SHALL validate every row with the same rules as the create endpoint, and also flag duplicates within the file and against existing records.
  • FR-4: WHEN validation ends, THE SYSTEM SHALL show the counts of valid and invalid rows and a preview of the first 100 errors with row number, column and reason.
  • FR-5: WHEN the person asks for it, THE SYSTEM SHALL return a CSV of the invalid rows with an added error column, ready to fix and upload again.
  • FR-6: WHEN the person confirms, THE SYSTEM SHALL import the valid rows in a background job and answer 202 with the job id at once.
  • FR-7: WHILE the job runs, THE SYSTEM SHALL report progress at least every 5 seconds, and notify the person when it ends.
  • FR-8: IF the job is interrupted, THEN THE SYSTEM SHALL resume after the last committed batch of 1,000 rows without creating duplicates.
  • FR-9: WHEN an import finishes, THE SYSTEM SHALL keep the file, the person and the created records together for 30 days, and let the person undo the whole import within that time.

3. Out of scope

  • Excel and other spreadsheet formats.
  • Updating existing records from the file.