# Import et export des enregistrements

Sovrium déplace des données en masse vers et depuis les tables de trois manières. Le copier/coller par **presse-papiers** entre une table de données et un tableur est disponible aujourd'hui, construit sur les points de terminaison batch et list existants. L'**import CSV** (téléverser un fichier pour créer des enregistrements en masse) et l'**export** (télécharger la vue courante en CSV ou JSON) sont conçus mais pas encore disponibles. Aucune configuration n'est requise pour aucun d'entre eux.

:::callout
**Statut : le presse-papiers est disponible aujourd'hui ; l'import/export CSV est planifié.** Le copier/coller du presse-papiers repose sur les points de terminaison [batch](records-batch) et [list](records-filtering-sorting) existants et fonctionne dès maintenant. Les points de terminaison d'import/export CSV ci-dessous constituent une surface conçue mais non encore livrée (les user stories d'import/export sont `Not Started`). Cette page documente l'API d'import/export prévue ; les formes concrètes de requête/réponse seront finalisées lors de l'implémentation.
:::

## Import CSV

Téléversez un fichier CSV pour charger des enregistrements en masse, avec mappage colonne-vers-champ, gestion configurable des doublons et rapport d'erreurs par ligne en cas d'échecs partiels.

```
POST /api/tables/:tableId/import
Content-Type: multipart/form-data

Body:
  file              (CSV file)
  mapping           (JSON: { "csvColumn": "tableField" })
  duplicateStrategy ("skip" | "overwrite" | "create")
  uniqueField       (field used to detect duplicates)
```

La réponse résume le résultat et signale les erreurs par ligne sans faire échouer tout l'import :

```json
{
  "imported": 120,
  "skipped": 4,
  "updated": 11,
  "failed": 2,
  "errors": [
    { "row": 17, "field": "email", "error": "Invalid email format" },
    { "row": 92, "field": "amount", "error": "Expected a number" }
  ]
}
```

| Concept                        | Comportement                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| Mappage de colonnes            | `mapping` associe chaque colonne CSV à un champ de table ; les colonnes non mappées sont ignorées |
| `duplicateStrategy: skip`      | Ignorer les lignes dont le `uniqueField` existe déjà                                              |
| `duplicateStrategy: overwrite` | Mettre à jour l'enregistrement correspondant existant                                             |
| `duplicateStrategy: create`    | Toujours insérer un nouvel enregistrement                                                         |
| Échec partiel                  | Les lignes valides sont importées ; les lignes invalides sont signalées dans `errors`             |

Les enregistrements importés passent la même [validation](table-validation) de type de champ et les mêmes [permissions](table-permissions) au niveau des champs qu'une création normale.

## Export

Exportez la vue courante d'une table — toutes les lignes visibles, une sélection choisie à la main, ou les mêmes données au format JSON pour l'outillage développeur.

```
GET /api/tables/:tableId/export?format=csv&viewId=2&filters=JSON&fields=id,name,status
GET /api/tables/:tableId/export?format=json&fields=id,name,status
GET /api/tables/:tableId/export?format=csv&recordIds=1,2,3&fields=id,name,status
```

La réponse diffuse le fichier avec une disposition de pièce jointe :

```
Content-Type: text/csv            (or application/json)
Content-Disposition: attachment; filename="orders.csv"
```

| Paramètre   | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `format`    | `csv` (défaut) ou `json`                                                                         |
| `viewId`    | Exporter les lignes d'une [vue](table-views) enregistrée                                         |
| `filters`   | Expression de filtre JSON (même grammaire que le [filtrage de liste](records-filtering-sorting)) |
| `fields`    | Colonnes à inclure séparées par des virgules                                                     |
| `recordIds` | Exporter uniquement les ID d'enregistrements nommés (une sélection choisie à la main)            |

L'export respecte les permissions de lecture au niveau des champs — les colonnes que l'appelant ne peut pas lire sont omises du fichier.

## Presse-papiers

Le composant table de données prend en charge le copier/coller de style tableur, construit sur les points de terminaison standard des enregistrements.

| Action            | Comportement                                                                                         | Point de terminaison sous-jacent          |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Coller des lignes | Coller des données séparées par des tabulations depuis Excel/Google Sheets dans une table de données | `POST /api/tables/:tableId/records/batch` |
| Aperçu du collage | Prévisualiser les données collées avec mappage de colonnes avant validation                          | (côté client, puis création en lot)       |
| Copier des lignes | Sélectionner des lignes et les copier en valeurs séparées par des tabulations dans le presse-papiers | `GET /api/tables/:tableId/records`        |

Le collage associe les colonnes séparées par des tabulations aux champs de table (avec une étape d'aperçu/mappage pour que l'utilisateur puisse confirmer avant l'écriture), puis valide via une seule [création en lot](records-batch) — gardant l'opération atomique. La copie sérialise les colonnes visibles des lignes sélectionnées en TSV.

## Pages associées

- [Opérations en lot](records-batch) — le chemin d'écriture en masse atomique utilisé par le collage du presse-papiers
- [Filtrage, tri et pagination](records-filtering-sorting) — la grammaire de filtre/champs que l'export réutilise
- [Vues de table](table-views) — exporter une vue enregistrée par `viewId`
- [Validation de table](table-validation) — les lignes importées passent la validation de type de champ
- [Permissions de table](table-permissions) — les permissions de lecture/écriture au niveau des champs régulent l'import et l'export