# Conversion KPI en EUR - Guide développeur

## Objectif
Cette fonctionnalité remplit (ou reconstruit) des valeurs KPI en EUR dans `kpis.data` à partir des taux BCE stockés dans `exchange_rates`.

Implémentation :

- Commande : `app/Console/Commands/TkoConvertKpisToEuroCommand.php` (`tko:convert-kpis-euro`)
- Service : `app/Services/KpiEuroConversionService.php`

## Périmètre (lignes traitées)

Uniquement les KPI :

- `report_type = ACTUAL`
- `report_period IN (LTM, M)`

Mapping des clés :

- **LTM** : `SALES → SALES_EURO`, `EBITDA → EBITDA_EURO`, `EBIT → EBIT_EURO`
- **M** : `EV → EV_EURO`, `RISKEV → RISKEV_EURO`

## Résolution de la devise

Ordre de résolution (première valeur non vide) :

1. `kpis.data['Currency']`
2. `kpis.currency`
3. `companies.data['Currency']` (via la relation `Kpi->company`)

Si aucune devise n’est trouvée, la ligne est ignorée (`skipped_no_currency`).

## Recherche du taux FX (important)

Les taux sont attendus comme suit :

- `exchange_rates.cur1 = EUR`
- `exchange_rates.cur2 = <DEVISE_LOCALE>`
- `exchange_rates.source = ECB`
- `exchange_rates.rate = unités de cur2 pour 1 EUR`

Pour une `report_date`, le service cherche un taux à cette date puis remonte jusqu’à **7 jours** (inclus). S’il n’y a pas de taux dans cette fenêtre, la ligne est ignorée (`skipped_no_rate`).

Formule :

- \( EUR = \frac{LOCAL}{rate} \)

Si la devise est déjà `EUR`, la valeur est conservée telle quelle.

## Champs dynamiques requis

Toutes les clés cibles `*_EURO` doivent exister dans `dynamic_fields` pour le modèle `App\Models\Kpi` :

- `SALES_EURO`
- `EBITDA_EURO`
- `EBIT_EURO`
- `EV_EURO`
- `RISKEV_EURO`

Le service valide cela au démarrage et lève une erreur si un champ manque.

## Modes

- **Par défaut (remplir les champs manquants)** : n’écrit que les clés `*_EURO` absentes sur la ligne.
- **Reconstruire (`--rebuild`)** : supprime d’abord toutes les clés `*_EURO` ciblées, puis recalcule.
  - Si la devise / le taux n’est pas disponible, les clés restent supprimées pour cette ligne.

## Utilisation de la commande

```bash
php artisan tko:convert-kpis-euro [--rebuild] [--company=<uuid>] [--progress]
```

Options :

- `--rebuild` : suppression puis recalcul des champs EUR.
- `--company=<uuid>` : limite à une seule société (UUID).
- `--progress` : affiche une barre de progression (également en mode verbose).

## Sortie + logs

La commande affiche un résumé (durée, lignes scannées/mises à jour, champs écrits, compteurs “skipped”).

Logs job :

- `storage/logs/job_logs.log`
  - Début : `lnc:convert-kpis-to-euro started`
  - Fin : `lnc:convert-kpis-to-euro finished`
  - Erreur : `lnc:convert-kpis-to-euro failed`

## Flux d’exploitation recommandé

1. Vérifier/mettre à jour les taux :
   - `php artisan lnc:sync-ecb-exchange-rates` (voir `dev_guide/exchange_rates_developer_fr.md`)
2. Lancer la conversion en mode “fill missing” régulièrement.
3. Utiliser `--rebuild` après modification du mapping/champs dynamiques ou correction d’un trou historique de taux.