bible/rules/patterns/import-export/contract.md

Contract: Import / Export Workflows

Version: 1.0

See README.md for the reference export handler and locale examples.

Import Rules

• Recommended flow: Upload -> Preview / Validate -> Confirm -> Execute -> Result summary.
• Validation preview must be human-readable.
• Warnings and errors should be visible per row and in aggregate.
• The confirm step must communicate scope and side effects clearly.

Export Rules

• The user must explicitly choose export scope when ambiguity exists, such as selected, filtered, or all.
• Export format must be explicit.
• Download responses must set Content-Type and Content-Disposition correctly.

CSV Rules

• For spreadsheet-facing CSV, write UTF-8 BOM as the first bytes.
• Use semicolon ; as the CSV delimiter.
• Use comma as the decimal separator for user-facing numeric values.
• Use DD.MM.YYYY for user-facing dates.
• Use encoding/csv with csv.Writer.Comma = ';' so quoting and escaping stay correct.

Streaming Rules

• Large exports must stream rows directly to the response. Do not load the full dataset into memory first.
• Use the canonical flow: Handler -> Service -> Repository callback -> csv.Writer
• Repository queries should avoid N+1 by using JOINs or another batched shape.
• Always call csv.Writer.Flush() after writing rows.

Error Handling

• Import errors must map to clear user-facing messages.
• Once streaming has started, export failures are logged server-side only. Do not try to change the HTTP status after headers/body bytes were already sent.