# Guide utilisateur - FlexImport kView INVESTOR

FlexImport permet de créer ou mettre à jour des données kView INVESTOR depuis un fichier Excel `.xlsx`, sans installer d'add-in Excel. Excel sert uniquement à préparer la grille de données. Toute la validation, la comparaison avec la base et l'import réel sont faits côté kView INVESTOR.

## Principe général

Un import se fait en deux étapes :

1. **Preview** : kView INVESTOR lit le fichier Excel et indique ce qui sera créé, modifié, ignoré ou rejeté.
2. **Apply** : l'utilisateur confirme, puis kView INVESTOR écrit les changements en base.

Tant que l'étape **Apply** n'est pas lancée, aucune donnée n'est modifiée.

## Structure minimale du fichier Excel

Le classeur doit contenir au minimum trois plages nommées :

| Nom de plage | Obligatoire | Description |
| --- | --- | --- |
| `kImportTable` | Oui | Nom métier de la table à importer. Exemple : `funds`, `investors`, `exchange_rates`. |
| `kImportData` | Oui | Tableau de données à importer, avec les noms de colonnes en première ligne. |
| `FlexImportSettings` | Non | Paramètres avancés, notamment les clés d'identification des lignes. |

Les plages nommées peuvent être locales à une feuille Excel. C'est même recommandé si un classeur contient plusieurs imports.

## Exemple simple

### Plage `kImportTable`

Une cellule contenant :

```text
exchange_rates
```

### Plage `kImportData`

| cur1 | cur2 | rate_date | source | rate |
| --- | --- | --- | --- | --- |
| EUR | USD | 2026-01-15 | ECB | 1.12 |
| EUR | GBP | 2026-01-15 | ECB | 0.88 |
| EUR | CHF | 2026-01-15 | ECB | 0.94 |

La première ligne contient les noms de champs. Les lignes suivantes contiennent les valeurs à importer.

## Tables supportées

La liste exacte est contrôlée côté serveur dans `config/flex_import.php`. Au démarrage, les alias suivants sont prévus :

| Alias Excel | Table kView INVESTOR |
| --- | --- |
| `gp`, `gps` | General Partners |
| `investor`, `investors` | Investors |
| `fund`, `funds` | Funds |
| `investment`, `investments` | Investments |
| `call_distrib`, `call_distribs` | Calls & distributions |
| `capital_account`, `capital_accounts` | Capital accounts |
| `exchange_rate`, `exchange_rates` | Exchange rates |

Pour des raisons de sécurité, un fichier Excel ne peut pas choisir librement une table SQL. Seules les tables déclarées côté serveur sont acceptées.

## Clés d'identification

FlexImport doit savoir comment retrouver une ligne existante.

Par défaut, les clés sont définies côté serveur. Exemples :

| Table | Clés par défaut |
| --- | --- |
| `gps` | `name` |
| `investors` | `name` |
| `funds` | `name` |
| `investments` | `investor_id`, `fund_id` |
| `exchange_rates` | `cur1`, `cur2`, `rate_date`, `source` |

Il est possible de préciser les clés dans `FlexImportSettings`.

### Exemple `FlexImportSettings`

| Paramètre | Valeur |
| --- | --- |
| `key_fields` | `cur1,cur2,rate_date,source` |

Si `key_fields` est absent, kView INVESTOR utilise les clés par défaut de la table.

## Champs autorisés

Pour chaque table, kView INVESTOR limite les champs importables. Un champ non autorisé dans Excel est ignoré.

Exemple pour `exchange_rates` :

```text
cur1, cur2, rate, rate_date, source
```

Exemple pour `funds` :

```text
name, full_name, gp_id, alias_names
```

Cette restriction évite qu'un fichier Excel modifie accidentellement ou volontairement des colonnes techniques.

## Résultat de la preview

La preview classe chaque ligne dans une action :

| Action | Signification |
| --- | --- |
| `create` | La ligne n'existe pas encore et sera créée. |
| `update` | La ligne existe et certains champs seront modifiés. |
| `unchanged` | La ligne existe déjà avec les mêmes valeurs. Rien ne sera écrit. |
| `error` | La ligne ne peut pas être importée. |

Une ligne en erreur bloque l'import complet. Il faut corriger le fichier ou les paramètres, puis relancer la preview.

## Flags optionnels

Les flags reprennent l'esprit du FlexImport TIEKASY.

| Flag | Valeur par défaut | Effet |
| --- | --- | --- |
| `Disable_Base_Compare` | `false` | Si `true`, kView INVESTOR importe même si les valeurs semblent identiques. |
| `ignore_empty_cells` | `true` | Si `true`, une cellule vide ne remplace pas la valeur existante. |
| `import_disable_duplicate_check` | `false` | Si `true`, désactive l'erreur sur doublons internes au fichier. |

Les flags sont des plages nommées contenant une valeur booléenne : `true`, `false`, `1`, `0`, `yes`, `no`.

## Gestion des cellules vides

Par défaut :

```text
ignore_empty_cells = true
```

Cela signifie qu'une cellule vide dans Excel est ignorée pour les lignes existantes. Elle ne supprime pas la valeur en base.

Pour forcer l'effacement d'une valeur, il faudra prévoir un comportement explicite séparé, par exemple une valeur spéciale comme `n.a.` ou un mode dédié. Ce comportement doit être confirmé avant usage métier large.

## Doublons dans le fichier

Si deux lignes Excel ont la même clé, FlexImport renvoie une erreur par défaut.

Exemple de doublon pour `exchange_rates` :

| cur1 | cur2 | rate_date | source | rate |
| --- | --- | --- | --- | --- |
| EUR | USD | 2026-01-15 | ECB | 1.12 |
| EUR | USD | 2026-01-15 | ECB | 1.13 |

Ces deux lignes ciblent le même record. kView INVESTOR bloque l'import pour éviter une ambiguïté.

## Bonnes pratiques Excel

- Utiliser une feuille par import.
- Donner des noms de colonnes simples, proches des champs kView INVESTOR.
- Toujours lancer une preview avant de confirmer l'import.
- Garder les clés visibles dans les premières colonnes.
- Eviter les formules dans les colonnes importées si le résultat peut changer après sauvegarde.
- Ne pas mélanger plusieurs tables dans une même plage `kImportData`.
- Garder un onglet `README` dans les modèles Excel métier pour expliquer les clés et les champs attendus.

## Exemple complet pour `exchange_rates`

### `kImportTable`

```text
exchange_rates
```

### `FlexImportSettings`

| Paramètre | Valeur |
| --- | --- |
| `key_fields` | `cur1,cur2,rate_date,source` |

### `kImportData`

| cur1 | cur2 | rate_date | source | rate |
| --- | --- | --- | --- | --- |
| EUR | USD | 2026-01-15 | ECB | 1.12 |
| EUR | GBP | 2026-01-15 | ECB | 0.88 |
| EUR | CHF | 2026-01-15 | ECB | 0.94 |

## API technique

L'interface kView INVESTOR peut appeler les endpoints suivants :

```text
POST /api/v1/flex-import/preview
POST /api/v1/flex-import/apply
```

Deux formats sont acceptés :

1. Upload d'un fichier `.xlsx` via le champ `workbook`.
2. Payload JSON contenant `table`, `rows`, `settings` et `flags`.

### Exemple JSON de preview

```json
{
  "table": "exchange_rates",
  "rows": [
    ["cur1", "cur2", "rate_date", "source", "rate"],
    ["EUR", "USD", "2026-01-15", "ECB", "1.12"],
    ["EUR", "GBP", "2026-01-15", "ECB", "0.88"]
  ],
  "settings": {
    "key_fields": "cur1,cur2,rate_date,source"
  },
  "flags": {
    "ignore_empty_cells": true
  }
}
```

## Limites actuelles

Cette première version pose le socle serveur. Les points suivants restent à décider ou compléter selon les besoins métier :

- interface web d'upload et d'affichage preview ;
- modèles Excel prêts à l'emploi par table ;
- résolution automatique des noms métiers vers UUID, par exemple `fund_name` vers `fund_id` ;
- historique complet des imports confirmés ;
- mode explicite pour vider une valeur existante ;
- règles spécifiques par table pour les champs dynamiques.