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

Import / Export Pattern

Canonical file transfer UX patterns for Go web applications:

• file import forms (CSV/JSON and similar)
• validation preview tables before confirm
• confirm step with human-readable summary
• export controls (format + scope + options)
• predictable file download behavior and filenames

This pattern covers UI and UX contracts. Business-specific validation and file schemas remain in the host project's own architecture docs.

Export Handler Sketch

func ExportCSV(c *gin.Context) {
    c.Header("Content-Type", "text/csv; charset=utf-8")
    c.Header("Content-Disposition", `attachment; filename="export.csv"`)
    c.Writer.Write([]byte{0xEF, 0xBB, 0xBF})

    w := csv.NewWriter(c.Writer)
    w.Comma = ';'
    w.Write([]string{"ID", "Name", "Price"})

    err := svc.StreamRows(ctx, filters, func(row Row) error {
        return w.Write([]string{row.ID, row.Name, formatPrice(row.Price)})
    })
    w.Flush()
    if err != nil {
        slog.Error("csv export failed mid-stream", "err", err)
    }
}

Locale Notes

• BOM avoids broken UTF-8 in Excel on Windows.
• Semicolon avoids single-column imports in RU/EU locales.
• Decimal comma keeps numbers numeric in Excel.
• DD.MM.YYYY is preferred over ISO dates for user-facing spreadsheet exports.