osm-labo/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

[
  {
    "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