webcarto/plan.md

Plan de développement — WebCarto

Plan incrémental suivant l'ordre défini dans la consigne : carte → import GeoJSON → édition point → import KML → persistance → export

---

Phase 0 — Scaffolding & Infrastructure

Objectif : structure du repo, Docker, CI minimal, tout tourne à vide.

• Créer l'arborescence projet (frontend/, backend/, samples/)
• Initialiser le frontend : Vite + React + TypeScript, TailwindCSS, Zustand
• Configurer le thème gruvbox dark vintage (tokens CSS / Tailwind)
• Initialiser le backend : FastAPI, SQLModel, Alembic, structure app/
• Créer les Dockerfiles (frontend Nginx, backend uvicorn)
• Créer docker-compose.yml + .env.example
• Configurer linting : ruff + black (backend), ESLint + Prettier (frontend)
• Vérifier que docker-compose up --build lance les 2 services

Livrable : page blanche frontend servie par Nginx, backend répond sur /api/health.

---

Phase 1 — Carte & fonds de plan

Objectif : carte plein écran avec 3 fonds commutables.

• Installer MapLibre GL JS
• Composant <MapView> : carte plein écran
• Configurer 3 fonds : Satellite (raster), Hybride (satellite + labels), Vecteur (OSM)
• Abstraction BaseLayerProvider : URL template + attribution + type, configurable via .env
• Sélecteur de fond (contrôle UI sur la carte)
• Affichage correct des attributions

Livrable : carte navigable avec switch entre les 3 fonds.

---

Phase 2 — Layout UI & thème

Objectif : structure de l'interface complète (vide mais fonctionnelle).

• Header : nom projet + boutons Import / Export / Save / Settings (désactivés pour l'instant)
• Volet gauche : panneau couches (vide) avec recherche + filtres (placeholder)
• Volet droit : panneau propriétés (vide)
• Système de toasts + barre de statut
• Panneaux repliables / redimensionnables
• Appliquer thème gruvbox sur tous les composants

Livrable : layout 3 colonnes avec carte centrale, panneaux latéraux, header.

---

Phase 3 — Import GeoJSON

Objectif : importer un fichier GeoJSON, l'afficher sur la carte, le persister.

Frontend

• Bouton Import + zone drag & drop (accepte .geojson, .json)
• Parser et valider le GeoJSON côté client
• Envoyer le GeoJSON normalisé au backend via POST /api/datasets/import
• Afficher les features sur la carte (source + layer MapLibre)
• Remplir le volet gauche : liste des couches importées

Backend

• Modèle Dataset (SQLModel) : id, name, created_at, feature_count, bbox
• Modèle Feature : id, dataset_id, geometry (JSON), properties (JSON)
• Migration Alembic initiale
• Route POST /api/datasets/import : validation Pydantic, stockage raw + features
• Route GET /api/datasets : liste des datasets
• Route GET /api/datasets/{id} : dataset + features
• Stockage du fichier raw original sur le volume /data

Tests

• Backend : test import GeoJSON valide, test rejet fichier invalide, test listing
• Frontend : test parsing GeoJSON (unitaire)

Données exemple

• Créer samples/example.geojson (quelques points/lignes/polygones)

Livrable : import drag & drop d'un GeoJSON → affiché sur la carte → persisté en base.

---

Phase 4 — Sélection & édition des points

Objectif : cliquer sur un point, voir ses propriétés, le déplacer, modifier ses attributs.

Sélection

• Clic sur feature → sélection visuelle (highlight)
• Affichage des propriétés dans le volet droit
• Liste des features dans le volet gauche (clic → centrer sur la carte)
• Affichage rich content (HTML safe sanitisé) dans le viewer propriétés
• Affichage des images si URL http(s) détectée dans les propriétés

Édition

• Installer MapLibre Draw (ou équivalent)
• Drag & drop des points sur la carte
• Édition des propriétés : name, description, champs libres
• Undo (au moins 1 niveau) pour le déplacement
• Bouton Save → PUT /api/features/{id}

Backend

• Route PUT /api/features/{id} : update geometry + properties
• Table feature_versions : timestamp, feature_id, before (JSON), after (JSON)
• Enregistrer chaque modification dans l'historique

Tests

• Backend : test update feature, test versioning
• Frontend : test sélection, test undo

Livrable : sélection d'un point → voir/modifier propriétés → déplacer → sauvegarder avec historique.

---

Phase 5 — Import KML

Objectif : importer des fichiers KML, les convertir et les traiter comme des GeoJSON.

• Installer @tmcw/togeojson
• Bouton Import accepte aussi .kml
• Parsing KML → GeoJSON côté frontend (togeojson)
• Extraction des images depuis CDATA / descriptions KML
• Envoyer le GeoJSON résultant au backend (même route d'import)
• Stockage du KML raw original sur le volume

Tests

• Frontend : test conversion KML → GeoJSON
• Backend : test import d'un dataset originellement KML

Données exemple

• Créer samples/example.kml (points avec descriptions, images)

Livrable : import KML → conversion → affichage + édition identique au GeoJSON.

---

Phase 6 — Export

Objectif : exporter un dataset édité en GeoJSON.

• Route backend POST /api/datasets/{id}/export?format=geojson
• Générer le GeoJSON depuis les features en base (version courante)
• Bouton Export dans le header → téléchargement du fichier
• Option de re-téléchargement du fichier raw original

Tests

• Backend : test export GeoJSON, vérifier cohérence avec les éditions

Livrable : export fonctionnel du dataset modifié en GeoJSON.

---

Phase 7 — Polish & finalisation MVP

Objectif : stabiliser, documenter, préparer le déploiement.

• Gestion d'erreurs cohérente (toasts pour les erreurs réseau, parsing, etc.)
• Clustering des points si dataset volumineux (>1000 points)
• Performance : vérifier avec un dataset de ~5k points
• README.md : installation, variables .env, limites connues, roadmap
• Vérifier que docker-compose up fonctionne from scratch
• Passe finale sur le thème gruvbox (cohérence, contrastes, accessibilité)

Livrable : MVP complet, documenté, déployable en un docker-compose up.

---

Post-MVP (roadmap)

Ces éléments ne sont pas dans le scope MVP mais sont prévus :

1. Support KMZ (unzip + parsing KML interne)
2. Styles KML (icônes, couleurs) appliqués sur la carte
3. Édition lignes / polygones
4. Export KML
5. Auth (OIDC / reverse proxy)
6. Multi-utilisateurs, permissions
7. Import grands datasets (streaming, Web Worker)
8. Serveur tuiles interne / mode offline