osm-commerces/docs/import-stats.md

# Import d'objets Stats

Cette fonctionnalité permet d'importer des objets Stats à partir d'un fichier JSON via l'interface d'administration.

## Accès

La page d'import est accessible via :
- L'URL : `/admin/import-stats`
- Le menu de navigation : "Import Stats"

## Fonctionnalités

### Sécurité
- **Aucune modification** des objets Stats existants
- Seuls les nouveaux objets sont créés
- Vérification de l'existence par le code INSEE (`zone`)

### Validation
- Vérification du format JSON
- Validation des champs requis (`zone` et `name`)
- Gestion des erreurs par ligne
- Rapport détaillé des résultats

### Champs supportés

#### Champs requis
- `zone` : Code INSEE de la zone (ex: "75056")
- `name` : Nom de la ville/zone (ex: "Paris")

#### Champs optionnels
- `population` : Population de la zone (nombre)
- `budgetAnnuel` : Budget annuel de la collectivité (chaîne)
- `siren` : Code SIREN (nombre)
- `codeEpci` : Code EPCI (nombre)
- `codesPostaux` : Codes postaux séparés par des points-virgules (ex: "75001;75002;75003")

#### Objet `decomptes` (optionnel)
- `placesCount` : Nombre total de lieux
- `avecHoraires` : Nombre de lieux avec horaires
- `avecAdresse` : Nombre de lieux avec adresse
- `avecSite` : Nombre de lieux avec site web
- `avecAccessibilite` : Nombre de lieux avec accessibilité
- `avecNote` : Nombre de lieux avec note
- `completionPercent` : Pourcentage de complétion

## Format JSON attendu

```json
[
  {
    "zone": "75056",
    "name": "Paris",
    "population": 2161000,
    "budgetAnnuel": "8500000000",
    "siren": 200054781,
    "codeEpci": 200054781,
    "codesPostaux": "75001;75002;75003",
    "decomptes": {
      "placesCount": 1250,
      "avecHoraires": 980,
      "avecAdresse": 1200,
      "avecSite": 850,
      "avecAccessibilite": 450,
      "avecNote": 320,
      "completionPercent": 75
    }
  }
]
```

## Utilisation

1. **Préparer le fichier JSON**
   - Créer un tableau d'objets Stats
   - Inclure au minimum les champs `zone` et `name`
   - Valider le format JSON

2. **Accéder à la page d'import**
   - Aller sur `/admin/import-stats`
   - Ou cliquer sur "Import Stats" dans le menu

3. **Importer le fichier**
   - Sélectionner le fichier JSON
   - Cliquer sur "Importer"
   - Vérifier les messages de résultat

4. **Vérifier les résultats**
   - Nombre d'objets créés
   - Nombre d'objets ignorés (déjà existants)
   - Liste des erreurs éventuelles

## Messages de retour

### Succès
```
Import terminé : X objet(s) créé(s), Y objet(s) ignoré(s) (déjà existants).
```

### Erreurs possibles
- "Aucun fichier JSON n'a été fourni."
- "Le fichier doit être au format JSON."
- "Erreur lors du décodage JSON: [message]"
- "Le fichier JSON doit contenir un tableau d'objets Stats."
- "Ligne X: Champs 'zone' et 'name' requis"
- "Ligne X: [message d'erreur spécifique]"

## Logs

Toutes les actions d'import sont loggées via le service `ActionLogger` :
- `admin/import_stats` : Accès à la page
- `admin/import_stats_success` : Import réussi avec statistiques
- `admin/import_stats_error` : Erreur lors de l'import

## Exemple de fichier de test

Un fichier `test_import_stats.json` est fourni avec des exemples pour Paris, Lyon et Marseille.

## Notes importantes

- Les objets existants ne sont jamais modifiés
- Seuls les nouveaux objets sont créés
- Les dates de création et modification sont automatiquement définies
- Les erreurs sont affichées par ligne pour faciliter le débogage
- Le système est conçu pour être sûr et non destructif