osm-labo/README.md

# OSM Commerces
dépot pour faire une démo de "OSM mon commerce", permettant de modifier des commerces sans avoir de compte OSM.
Ce projet permet d'avoir un tableau de bord pour une zone donnée concernant la completion de commerces et autres lieux d'intérêt amenés à être mis à jour en autonomie par les personnes qui y travaillent.

Configurer .env.local pour mettre le token bearer d'un compte dédié
installer les dépendances avec composer
déployer sur un serveur ayant du php 8

# Dépendances

- PHP 8.1 ou supérieur
- Composer
- PostgreSQL 13 ou supériesdfsdffgdfgfdgur, ou Mysql / MariaDB
- Symfony 7.2
- Extensions PHP requises :
  - pdo_pgsql
  - xml
  - intl
  - mbstring

# Base de données

créer un utilisateur et sa base

## en postgresql
```shell
sudo -u postgres psql -c "CREATE USER sf WITH PASSWORD 'sfrgdHYJi56631lyshFSQGfd45452ùwdf54f8fg5dfhg5_tyfdgthIOPHFUGH';"
sudo -u postgres psql -c "CREATE DATABASE \"osm-my-commerce\" OWNER sf;"
```

## en mysql

```shell
mysql -u root -p
CREATE USER 'sf'@'localhost' IDENTIFIED BY 'sfrgdHYJi56631lyshFSQGfd45452ùwdf54f8fg5dfhg5_tyfdgthIOPHFUGH';
CREATE DATABASE `osm-my-commerce`;
GRANT ALL PRIVILEGES ON `osm-my-commerce`.* TO 'sf'@'localhost';
FLUSH PRIVILEGES;
```

# Installation et configuration

## 1. Installation des dépendances
```shell
composer install
npm install
```

## 2. Configuration de l'environnement
Créer un fichier `.env.local` avec les variables suivantes :
```env
DATABASE_URL="mysql://sf:sfrgdHYJi56631lyshFSQGfd45452ùwdf54f8fg5dfhg5_tyfdgthIOPHFUGH@127.0.0.1:3306/osm-my-commerce?serverVersion=8.0.32&charset=utf8mb4"
# ou pour PostgreSQL :
# DATABASE_URL="postgresql://sf:sfrgdHYJi56631lyshFSQGfd45452ùwdf54f8fg5dfhg5_tyfdgthIOPHFUGH@127.0.0.1:5432/osm-my-commerce?serverVersion=15&charset=utf8"

# Token OSM pour les modifications
OSM_TOKEN="votre_token_osm_ici"
```

## 3. Migrations de base de données

### Créer une nouvelle migration
```shell
php bin/console make:migration
```

### Exécuter les migrations
```shell
php bin/console doctrine:migrations:migrate
```

### Voir le statut des migrations
```shell
php bin/console doctrine:migrations:status
```

### Annuler la dernière migration
```shell
php bin/console doctrine:migrations:migrate prev
```

# Commandes custom Symfony

## Commandes de gestion des données

### Mise à jour des coordonnées des villes
Récupère et stocke les coordonnées lat/lon pour toutes les villes dans la base de données :
```shell
php bin/console app:update-city-coordinates
```

### Mise à jour des Stats avec kind vide
Change les Stats qui ont un kind vide (NULL) pour leur mettre "user" en kind et les enregistre :
```shell
php bin/console app:update-empty-stats-kind
```

### Test du budget
Teste le calcul du budget pour une ville donnée :
```shell
php bin/console app:test-budget [insee_code]
```

### Labourage d'une ville
Ajoute une nouvelle ville à la base de données avec son code INSEE :
```shell
php bin/console app:labourage [insee_code]
```

### Création des Stats manquantes à partir du CSV
Examine le fichier CSV des communes et crée des objets Stats pour les communes qui n'en ont pas encore :
```shell
php bin/console app:create-missing-stats-from-csv [options]
```

Options disponibles :
- `--limit=N` ou `-l N` : Limite le nombre de communes à traiter
- `--dry-run` : Simule sans modifier la base de données

Cette commande utilise le fichier `communes_france.csv` à la racine du projet et crée des objets Stats pour les communes qui n'en ont pas encore. Les objets sont créés avec les informations du CSV et complétés avec des données supplémentaires (coordonnées, budget, etc.). Les objets sont sauvegardés par paquets de 100 pour optimiser les performances.

## Génération de statistiques pour toute la France

Le projet inclut un ensemble de commandes Symfony qui permettent de générer des statistiques de complétion pour toutes les communes de France. Ces commandes doivent être exécutées dans l'ordre suivant :

### 1. Récupération des polygones des villes
Récupère les polygones des villes selon leur zone donnée par le code INSEE :
```shell
php bin/console app:retrieve-city-polygons [insee-code] [options]
```

Arguments :
- `insee-code` : (Optionnel) Code INSEE spécifique à traiter

Options :
- `--limit=N` ou `-l N` : Limite le nombre de villes à traiter
- `--force` ou `-f` : Force la récupération même si le polygone existe déjà

Cette commande :
- Crée le dossier `counting_osm_objects/polygons` s'il n'existe pas
- Utilise le script Python `get_poly.py` pour récupérer les polygones des communes
- Affiche une barre de progression et un résumé des résultats

### 2. Extraction des données OSM pour chaque zone INSEE
Extrait les données OSM pour chaque zone INSEE à partir du fichier france-latest.osm.pbf :
```shell
php bin/console app:extract-insee-zones [insee-code] [options]
```

Arguments :
- `insee-code` : (Optionnel) Code INSEE spécifique à traiter

Options :
- `--limit=N` ou `-l N` : Limite le nombre de villes à traiter
- `--force` ou `-f` : Force l'extraction même si le fichier JSON existe déjà
- `--keep-pbf` ou `-k` : Conserve les fichiers PBF intermédiaires

Cette commande :
- Télécharge automatiquement le fichier france-latest.osm.pbf depuis Geofabrik s'il n'existe pas
- Crée le dossier `insee_extracts` s'il n'existe pas
- Utilise osmium pour extraire les données OSM pour chaque zone INSEE
- Convertit les données extraites en format JSON
- Affiche une barre de progression et un résumé des résultats

### 3. Traitement des extraits JSON pour calculer les mesures de thèmes
Traite les extraits JSON des zones INSEE pour calculer les mesures de thèmes :
```shell
php bin/console app:process-insee-extracts [insee-code] [options]
```

Arguments :
- `insee-code` : (Optionnel) Code INSEE spécifique à traiter

Options :
- `--limit=N` ou `-l N` : Limite le nombre de villes à traiter
- `--force` ou `-f` : Force le traitement même si déjà effectué

Cette commande :
- Utilise le service Motocultrice pour traiter les données
- Met à jour la date de labourage dans l'entité Stats
- Affiche une barre de progression et un résumé des résultats

### Exemple d'utilisation pour générer des statistiques pour toute la France

```shell
# 1. Récupérer les polygones de toutes les communes
php bin/console app:retrieve-city-polygons

# 2. Extraire les données OSM pour chaque zone INSEE
php bin/console app:extract-insee-zones

# 3. Traiter les extraits JSON pour calculer les mesures de thèmes
php bin/console app:process-insee-extracts
```

Pour traiter une seule commune (par exemple avec le code INSEE 75056 pour Paris) :
```shell
php bin/console app:retrieve-city-polygons 75056
php bin/console app:extract-insee-zones 75056
php bin/console app:process-insee-extracts 75056
```

### Dépendances

Pour exécuter ces commandes, vous aurez besoin de :
- Python 3 avec les bibliothèques requises pour `get_poly.py`
- Osmium Tool (`osmium`) installé sur votre système
- Suffisamment d'espace disque pour stocker le fichier france-latest.osm.pbf (~4 Go) et les extraits JSON

# Routes d'administration

## Création des Stats manquantes à partir du CSV
Examine le fichier CSV des communes et crée des objets Stats pour les communes manquantes :
```
/admin/create-missing-stats-from-csv
```
Cette route lit le fichier `communes_france.csv` à la racine du projet et crée des objets Stats pour les communes qui n'en ont pas encore. Les objets sont créés avec les informations du CSV uniquement (sans labourage) et sont sauvegardés par paquets de 100.

Pour plus de détails, consultez la [documentation dédiée](docs/create_missing_stats.md).

## Commandes de maintenance

### Nettoyage du cache
```shell
php bin/console cache:clear
```

### Validation du schéma de base de données
```shell
php bin/console doctrine:schema:validate
```

### Mise à jour du schéma de base de données
```shell
php bin/console doctrine:schema:update --force
```

# Fonctionnalités principales

## Interface publique
- **Page d'accueil** : Carte interactive des villes avec taux de complétion
- **Ajouter ma ville** : Formulaire pour ajouter une nouvelle ville
- **Statistiques par ville** : Graphiques détaillés de progression
- **Graphiques thématiques** : Suivi spécifique par type d'objet (ex: arrêts de bus, bornes de recharge, etc.)

## Interface d'administration
- **Tableau de bord** : Vue d'ensemble des statistiques
- **Gestion des villes** : Ajout, modification, suppression
- **Suivi des modifications** : Historique des changements
- **Export de données** : CSV, JSON, API Overpass

## API et intégrations
- **API Overpass** : Récupération de données OSM
- **Nominatim** : Géocodage des adresses
- **Addok** : Service de géocodage alternatif

# Structure du projet

```
src/
├── Command/           # Commandes custom Symfony
├── Controller/        # Contrôleurs (public et admin)
├── Entity/           # Entités Doctrine
├── Repository/       # Repositories Doctrine
├── Service/          # Services métier
└── Kernel.php        # Configuration du kernel

templates/
├── admin/           # Templates d'administration
├── public/          # Templates publics
└── base.html.twig   # Template de base

assets/              # Assets frontend (JS, CSS)
config/              # Configuration Symfony
migrations/          # Migrations de base de données
```

# Développement

## Ajouter une nouvelle commande
```shell
php bin/console make:command NomCommande
```

## Ajouter une nouvelle entité
```shell
php bin/console make:entity NomEntite
```

## Ajouter un nouveau contrôleur
```shell
php bin/console make:controller NomController
```

## Tests
```shell
php bin/phpunit
```

# Déploiement

## Variables d'environnement de production
- `APP_ENV=prod`
- `APP_SECRET=clé_secrète_ici`
- `DATABASE_URL=url_de_la_base_production`
- `OSM_TOKEN=token_osm_production`

## Optimisations
```shell
composer install --no-dev --optimize-autoloader
php bin/console cache:clear --env=prod
```

## Labourage différé des villes

Depuis la version X, le labourage (mise à jour des lieux OSM pour une ville) peut être différé automatiquement si le serveur manque de RAM.

- Lorsqu'un admin demande un labourage, la date de requête (`date_labourage_requested`) est enregistrée.
- Si le serveur dispose d'au moins 1 Go de RAM libre, le labourage est effectué immédiatement (création/mise à jour des objets Place).
- Sinon, seul le suivi (CityFollowUp) est mis à jour, et un message informe que la mise à jour des lieux sera différée.
- Une commande cron (`php bin/console app:process-labourage-queue`) traite les villes en attente dès que possible, en respectant la RAM disponible.

### Lancer le cron de labourage

Ajoutez dans votre crontab :

```
* * * * * cd /chemin/vers/le/projet && php bin/console app:process-labourage-queue >> var/log/labourage_cron.log 2>&1
```

La commande traite la ville la plus ancienne en attente de labourage, si les ressources le permettent.

### Exemple de cron pour traiter 300 villes par jour

Pour labourer environ 300 villes par jour, il faut lancer la commande toutes les 5 minutes (24h * 60min / 5 = 288 passages par jour) :

```
*/5 * * * * cd /poule/encrypted/www/osm-commerces && php bin/console app:process-labourage-queue >> var/log/labourage_cron.log 2>&1
```

Chaque exécution traite une ville si les ressources le permettent. En adaptant la fréquence, vous pouvez ajuster le débit de traitement.

### Propriétés Stats
- `date_labourage_requested` : date de la dernière demande de labourage
- `date_labourage_done` : date du dernier labourage effectif

### Remarques
- Les CityFollowUp ne sont plus supprimés lors des labourages.
- Le système garantit que les villes sont mises à jour dès que possible sans surcharger le serveur.

# Analyses complémentaires
## Analyse de l'historique des objets dans les villes

dossier counting_osm_objects

## Inspection de la fraîcheur des traductions de wiki

Le dossier `wiki_compare` contient des scripts pour analyser les pages wiki d'OpenStreetMap, identifier celles qui ont besoin de mises à jour ou de traductions, et publier des suggestions sur Mastodon.

### Scripts disponibles

- **wiki_compare.py** : Récupère les 10 clés OSM les plus utilisées, compare leurs pages wiki en anglais et en français, et identifie celles qui ont besoin de mises à jour.
- **post_outdated_page.py** : Sélectionne aléatoirement une page wiki française qui n'est pas à jour et publie un message sur Mastodon pour suggérer sa mise à jour.
- **suggest_translation.py** : Identifie les pages wiki anglaises qui n'ont pas de traduction française et publie une suggestion de traduction sur Mastodon.

### Utilisation

Consultez le [README du dossier wiki_compare](wiki_compare/README.md) pour plus de détails sur l'installation, la configuration et l'utilisation de ces scripts.