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érieur, 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
```

### 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]
```

## 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.