# 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.