# Mise à jour des indices (INSEE) — ICC / ILAT / IRL

Ce document décrit la fonctionnalité de **synchronisation automatique** des indices de référence INSEE (BDM) et son intégration côté API et UI.

## Objectif

- Récupérer les **N derniers points** (par défaut **10**) pour chaque série INSEE (ICC / ILAT / IRL).
- Stocker ces valeurs dans la table `indexes` (modèle `App\Models\Index`) avec les clés composées:
  - `index_code` (ex: `ICC`, `ILAT`, `IRL`)
  - `period_code` (format UpImo: `YYYYQn`, ex: `2026Q1`)
- Fournir une option pour **forcer l’écrasement** des valeurs existantes.
- Sinon, **ne pas écraser** et retourner une liste d’**écarts** (différences entre valeur existante et valeur INSEE).

## Mapping des séries INSEE (idbank)

Le mapping entre `index_code` (UpImo) et `idbank` (INSEE) est stocké dans:

- `resources/assets/js/data/insee_index_series.json`

Exemple (actuel):

- `ICC` → `000008630` (insee.fr: [ICC](https://www.insee.fr/fr/statistiques/serie/000008630))
- `ILAT` → `001617112` (insee.fr: [ILAT](https://www.insee.fr/fr/statistiques/serie/001617112))
- `IRL` → `001515333`

## Endpoint API

Route:

- `GET /api/indexes/insee/sync`

Paramètres query:

- `lastN` *(défaut: 10)*: nombre de points les plus récents à récupérer par série.
- `force` *(défaut: 0)*:
  - `force=0`: ne modifie pas une valeur existante différente, et remonte un écart dans `discrepancies`
  - `force=1`: écrase les valeurs existantes différentes

Réponse (shape):

- `inserted`, `updated`, `skipped`
- `series[]` (par série: `index_code`, `idbank`, `title_fr`, `last_update`, `count`)
- `discrepancies[]` (par écart: `index_code`, `period_code`, `existing`, `incoming`, `idbank`, `title_fr`)

Contrôleur:

- `app/Http/Controllers/API/InseeIndexSyncController.php`

## Stockage en base (`indexes`)

Les observations INSEE contiennent un `TIME_PERIOD` (ex: `2026-Q1`), converti en:

- `period_code`: `2026Q1`

Champs alimentés:

- `index_code`: `ICC` / `ILAT` / `IRL`
- `period_code`: `YYYYQn`
- `index_value_n`: valeur INSEE (`OBS_VALUE`)
- `publication_date`: date de publication JO (`DATE_JO`) quand disponible
- `index_date`: fin de trimestre (calculée via `App\Services\Period`)
- `data`: trace JSON (source, idbank, titre INSEE, last_update, observation brute)

## Accès INSEE (sans token par défaut)

Le client essaie d’abord un endpoint **public** SDMX (sans OAuth):

- `https://bdm.insee.fr/series/sdmx/data/SERIES_BDM/{idbank}?lastNObservations=...`

Si l’appel public échoue et que des identifiants OAuth sont configurés, il tente ensuite l’endpoint `api.insee.fr` avec token.

Configuration:

- fichier: `config/insee.php`
- variables `.env` optionnelles:
  - `INSEE_PUBLIC_BASE_URL` (défaut: `https://bdm.insee.fr/series/sdmx`)
  - `INSEE_BASE_URL` (défaut: `https://api.insee.fr`)
  - `INSEE_TOKEN_URL` (défaut: `https://api.insee.fr/token`)
  - `INSEE_CLIENT_ID` *(optionnel, pour fallback OAuth uniquement)*
  - `INSEE_CLIENT_SECRET` *(optionnel, pour fallback OAuth uniquement)*

Client:

- `app/Services/Insee/InseeBdmClient.php`

## UI (page “Indices”)

Sur la page web “Indices” (liste), un bouton permet de lancer la synchro INSEE:

- libellé: **“Mise à jour avec les derniers indices”**
- option: switch **“Forcer”**

Après l’exécution:

- un récapitulatif est affiché (insérés / mis à jour / ignorés, séries traitées, écarts)
- la `smart-table` est **rafraîchie automatiquement** (appel de `loadData(true)` via un `ref`)

Implémentation front:

- `resources/assets/js/components/models/indexes/table.vue`