🗺️ SQL GeoParquet Explorer

Une plateforme web moderne pour exécuter des requêtes SQL sur des fichiers géospatiaux et visualiser les résultats sur une carte interactive.

📋 Table des matières

• Fonctionnalités
• Démarrage rapide
• Installation
• Utilisation
• Exemples de requêtes
• Formats supportés
• Architecture
• Tests
• Qualité du code
• Accessibilité
• Technologies
• Contribuer
• Licence

✨ Fonctionnalités

🎯 Fonctionnalités principales

• ✅ Exécution SQL dans le navigateur avec DuckDB-WASM (aucun serveur requis)
• ✅ Support multi-formats : GeoParquet, GeoPackage, GeoJSON, Shapefile (ZIP)
• ✅ Visualisation cartographique interactive avec Leaflet
• ✅ Éditeur SQL avancé avec CodeMirror (coloration syntaxique, autocomplétion)
• ✅ Tableau de résultats interactif avec pagination
• ✅ Export en CSV et GeoJSON
• ✅ Export/Import de bases DuckDB complètes

🚀 Nouveautés v2.0

• 🎨 Thèmes : Mode clair/sombre avec détection automatique
• 📂 Drag & Drop : Glissez-déposez vos fichiers
• 📜 Historique des requêtes : Sauvegarde, favoris, recherche
• 📄 Pagination : Navigation fluide dans les gros résultats
• 🛡️ Sécurité renforcée : Validation et sanitization des entrées
• ♿ Accessibilité : Navigation clavier, contrastes améliorés
• 🧪 Tests : Suite de tests unitaires complète
• 📊 Logging : Système de logging centralisé

📸 Captures d'écran

Interface principale

Mode sombre

Historique des requêtes

🚀 Démarrage rapide

# Cloner le repository
git clone https://github.com/votre-repo/plateforme-sql.git
cd plateforme-sql

# Installer les dépendances
npm install

# Lancer le serveur de développement
npm run dev

L'application s'ouvre automatiquement sur http://localhost:8000

📦 Installation

Prérequis

• Node.js >= 16.0.0
• npm >= 7.0.0

Installation complète

# Installation des dépendances
npm install

# Installation des dépendances de développement (inclus dans npm install)
npm install --include=dev

Build de production

# Créer le build de production
npm run build

# Prévisualiser le build
npm run preview

Les fichiers de production sont générés dans le dossier dist/.

🎮 Utilisation

Chargement de fichiers

1. Via l'interface : Cliquez sur "Importer fichier(s)" dans la barre d'outils
2. Drag & Drop : Glissez-déposez vos fichiers sur la zone de dépôt
3. Fichier SQL : Importez un fichier .sql pour charger une requête dans l'éditeur

Exécution de requêtes

1. Tapez votre requête SQL dans l'éditeur de gauche
2. Cliquez sur "▶ Exécuter" ou utilisez Ctrl/Cmd + Enter
3. Les résultats s'affichent dans le tableau (bas) et sur la carte (haut)

Raccourcis clavier

Raccourci	Action
Ctrl/Cmd + Enter	Exécuter la requête
Ctrl/Cmd + S	Sauvegarder la requête (historique)
Ctrl/Cmd + D	Toggle mode sombre/clair

Export des résultats

• CSV : Cliquez sur "Exporter CSV" (disponible si pas de géométries)
• GeoJSON : Cliquez sur "Exporter GeoJSON" (disponible si géométries détectées)
• Base DuckDB : Cliquez sur "Exporter DB" pour télécharger la base complète

💡 Exemples de requêtes

Requêtes basiques

-- Sélectionner toutes les données
SELECT * FROM ma_table LIMIT 100;

-- Filtrer par attribut
SELECT * FROM ma_table WHERE nom LIKE '%Paris%';

-- Trier et limiter
SELECT * FROM ma_table 
ORDER BY population DESC 
LIMIT 10;

Statistiques

-- Compter les enregistrements
SELECT COUNT(*) as total FROM ma_table;

-- Calculer des statistiques
SELECT 
  COUNT(*) as total,
  AVG(population) as pop_moyenne,
  MAX(population) as pop_max,
  MIN(population) as pop_min
FROM ma_table;

-- Grouper par catégorie
SELECT categorie, COUNT(*) as nombre
FROM ma_table
GROUP BY categorie
ORDER BY nombre DESC;

Requêtes spatiales

-- Calculer des surfaces
SELECT nom, ST_Area(geometry) as surface
FROM ma_table
ORDER BY surface DESC
LIMIT 10;

-- Filtrer par superficie
SELECT * FROM ma_table
WHERE ST_Area(geometry) > 1000;

-- Buffer autour d'une géométrie
SELECT nom, ST_Buffer(geometry, 100) as buffer
FROM ma_table
WHERE nom = 'Paris';

-- Intersection
SELECT a.nom, b.nom
FROM table_a a, table_b b
WHERE ST_Intersects(a.geometry, b.geometry);

Jointures

-- Jointure entre tables
SELECT a.*, b.info
FROM table_a a
JOIN table_b b ON a.id = b.a_id;

-- Auto-jointure spatiale
SELECT a.nom as ville1, b.nom as ville2,
  ST_Distance(a.geometry, b.geometry) as distance
FROM villes a, villes b
WHERE a.id < b.id
ORDER BY distance
LIMIT 10;

📁 Formats supportés

Format	Extension	Import	Export
GeoParquet	.parquet	✅	✅
GeoPackage	.gpkg, .geopackage	✅	-
GeoJSON	.geojson, .json	✅	✅
Shapefile	.zip (contenant .shp, .shx, .dbf)	✅	-
DuckDB	.duckdb, .db	✅	✅
SQL	.sql	✅ (requête)	-
CSV	-	-	✅

🏗️ Architecture

src/
├── js/
│   ├── main.js              # Point d'entrée
│   └── modules/
│       ├── logger.js        # Logging centralisé
│       ├── state.js         # Gestionnaire d'état
│       ├── eventBus.js      # Communication inter-modules
│       ├── utils.js         # Utilitaires et validation
│       ├── duckdb.js        # Gestion DuckDB
│       ├── map.js           # Carte Leaflet
│       ├── editor.js        # Éditeur CodeMirror
│       ├── table.js         # Tableau de résultats
│       ├── schema.js        # Affichage schéma
│       ├── fileLoader.js    # Chargement fichiers
│       ├── geometry.js      # Parsing géométries
│       ├── projection.js    # Gestion projections
│       ├── dragDrop.js      # Drag & drop
│       ├── queryHistory.js  # Historique requêtes
│       ├── theme.js         # Gestion thèmes
│       ├── pagination.js    # Pagination résultats
│       └── responsive.js    # UI responsive
└── css/
    ├── main.css             # Styles principaux
    ├── enhancements.css     # Améliorations v2.0
    └── ...                  # Autres fichiers CSS

Design Patterns utilisés

• Singleton : Pour les gestionnaires (logger, state, eventBus)
• Observer : Pour la réactivité avec state et eventBus
• Module : Architecture modulaire ES6
• Pub/Sub : Communication découplée via eventBus

🧪 Tests

# Exécuter les tests
npm run test

# Interface visuelle des tests
npm run test:ui

# Couverture de code
npm run test:coverage

Tests disponibles

• Logger : Logging, niveaux, historique, export
• State Manager : Get/set, subscriptions, historique
• Event Bus : Emit/on, once, désabonnement
• Utils : Validation fichiers, SQL, sanitization

🔍 Qualité du code

Linting

# Vérifier le code
npm run lint

# Corriger automatiquement
npm run lint:fix

Formatage

# Formater le code
npm run format

# Vérifier le formatage
npm run format:check

Configuration

• ESLint : Règles JavaScript ES6+ (.eslintrc.json)
• Prettier : Formatage automatique (.prettierrc)
• EditorConfig : Configuration éditeurs (.editorconfig)

♿ Accessibilité

• ✅ Navigation clavier complète
• ✅ Focus visible sur tous les éléments interactifs
• ✅ Contrastes de couleurs conformes WCAG AA
• ✅ Skip links pour navigation
• ✅ Tailles minimales pour cibles tactiles (44px)
• ✅ Labels pour tous les contrôles de formulaire
• ✅ Messages d'erreur accessibles
• ✅ Support lecteurs d'écran (ARIA)

🛠️ Technologies

Frontend

• Vite 5.0+ - Build tool moderne
• DuckDB-WASM - Moteur SQL dans le navigateur
• Leaflet - Cartographie interactive
• CodeMirror - Éditeur de code
• Proj4js - Projections cartographiques
• DOMPurify - Sanitization HTML

Tests

• Vitest - Framework de test
• Testing Library - Utilitaires de test DOM
• JSDOM - Environnement DOM

Qualité

• ESLint - Linting JavaScript
• Prettier - Formatage de code

🤝 Contribuer

Les contributions sont les bienvenues ! Voici comment contribuer :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité (git checkout -b feature/ma-fonctionnalite)
3. Commiter vos changements (git commit -m 'Ajout de ma fonctionnalité')
4. Pousser vers la branche (git push origin feature/ma-fonctionnalite)
5. Ouvrir une Pull Request

Guidelines

• ✅ Suivre les conventions de code existantes
• ✅ Ajouter des tests pour les nouvelles fonctionnalités
• ✅ Mettre à jour la documentation
• ✅ Vérifier que tous les tests passent
• ✅ Vérifier le linting

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

• DuckDB pour le moteur SQL
• Leaflet pour la cartographie
• CodeMirror pour l'éditeur
• Tous les contributeurs du projet

---

Fait avec ❤️ pour la communauté géospatiale