geo/CONTEXT-AI.md

AI_CONTEXT.md - GEOSECTOR

Informations Générales

• Nom du Projet: GEOSECTOR
• Type de Projet: Projet hybride avec un site web en Svelte 5, une application Web et mobile Flutter et une API PHP8.3 avec base de données centrale MariaDB
• Description: Gestion de la distribution des calendriers pour les amicales de pompiers
• Date de Début: 01/03/2025
• Statut Actuel: [En développement]
• Lien GitLab: [http://51.68.36.203:35788/d6soft/geosector]

Structure du Projet

Architecture Générale

• Un dossier /web pour le site web en Svelte 5 + Vite et TailwindCSS sans SvelteKit
• Un dossier /app pour l'application Flutter avec Hive pour stocker en local les données de l'utilisateur
• Un dossier /api pour l'API PHP 8.3 avec une base de données centrale MariaDB 11

Structure des Dossiers

Application Flutter (/app)

• /lib/core/data/models/ : Modèles de données avec annotations Hive pour le stockage local
• /lib/core/repositories/ : Gestion des données et communication avec l'API
• /lib/core/services/ : Services d'API, de synchronisation et utilitaires
• /lib/core/constants/ : Constantes de l'application, clés API et endpoints
• /lib/presentation/ : Interface utilisateur, pages et widgets
• /lib/chat/ : Fonctionnalités de messagerie

API PHP (/api)

• /src/Controllers/ : Contrôleurs pour les différentes fonctionnalités
• /src/Core/ : Classes de base pour la gestion des requêtes, sessions, etc.
• /src/Services/ : Services pour l'authentification, le chiffrement, etc.

Composants Principaux

Gestion des Utilisateurs et Authentification

• UserRepository : Gère les utilisateurs, l'authentification et les sessions
• ApiService : Communication avec l'API, gestion des tokens de session
• Session (PHP) : Gestion des sessions côté serveur
• LoginController (PHP) : Authentification et déconnexion

Stockage Local avec Hive

• UserModel : Modèle utilisateur avec annotations Hive (typeId: 0)
• AmicaleModel : Modèle pour les amicales (typeId: 11)
• OperationModel, SectorModel, PassageModel : Modèles pour les opérations de terrain

Interface Utilisateur

• LoginPage : Page de connexion avec détection du type d'utilisateur
• SplashPage : Page de démarrage et initialisation
• EntiteForm : Formulaire de gestion des amicales avec géolocalisation automatique

Géolocalisation et Cartographie

• MapboxMap : Widget de carte pour afficher la position des amicales
• findFireStationCoordinates : Service API pour localiser les casernes de pompiers via adresse.gouv.fr

Technologies et Frameworks

Langages de Programmation

• Dart : Pour l'application Flutter
• PHP 8.3 : Pour l'API backend
• JavaScript/TypeScript : Pour le site web Svelte

Frameworks et Bibliothèques

• Flutter : Framework UI cross-platform
• Hive : Base de données NoSQL locale pour Flutter
• Dio : Client HTTP pour les requêtes API
• GoRouter : Navigation et routage dans Flutter
• Svelte 5 : Framework UI pour le site web
• Flutter Map : Bibliothèque de cartographie pour Flutter

APIs Externes

• API Adresse.gouv.fr : Utilisée pour la géolocalisation des adresses et des casernes de pompiers
• Stripe API : Intégration pour les paiements par carte bancaire (commission de 1.4%)

Base de Données

• Type: MariaDB
• Version: 11
• Schéma: Structure principale dans docs/geo_app.dump avec tables pour utilisateurs, opérations, secteurs, passages
• Stockage Local: Hive pour le stockage local dans l'application Flutter

Outils de Développement

• Gestionnaire de Paquets: [Composer]
• Outils de Build: [Webpack / Vite / Flutter CLI]
• Outils de Test: [PHPUnit / Jest / Flutter Test]
• Linters/Formatters: [PHP_CodeSniffer / ESLint / Dart Analyzer]

Conventions de Code

Style de Code

• [PSR-12 pour PHP]

Conventions de Nommage

• Classes: [PascalCase]
• Méthodes/Fonctions: [camelCase]
• Variables: [camelCase]
• Constantes: [UPPER_SNAKE_CASE]
• Fichiers: [kebab-case.ext / PascalCase.ext]

Pratiques Spécifiques au Projet

• Chiffrement des données sensibles (noms, emails, téléphones) dans la base de données
• Mise à jour automatique des coordonnées GPS lors des changements d'adresse
• Confirmation utilisateur pour les actions ayant un impact financier (activation Stripe)

Flux de Travail et Processus de Développement

Branches GitLab

• main: Code stable prêt pour la production
• develop: Branche d'intégration pour les fonctionnalités en cours de développement
• feature/[feature-name]: Branches de développement pour les nouvelles fonctionnalités
  • Exemple: feature/geolocalisation-casernes pour l'ajout de la géolocalisation des casernes
• bugfix/[bug-name]: Branches pour les corrections de bugs
• release/[version]: Branches de préparation des versions

Processus de Merge Request

1. Créer une branche à partir de main ou develop selon la nature du changement

   git checkout -b feature/nom-de-la-fonctionnalite main
   

2. Développer la fonctionnalité ou correction avec des commits atomiques

   git add fichier1 fichier2
   git commit -m "Description claire du changement"
   

3. Pousser la branche vers le dépôt distant

   git push -u origin feature/nom-de-la-fonctionnalite
   

4. Créer une Merge Request via l'interface GitLab ou en utilisant l'URL fournie

   • URL: http://51.68.36.203/d6soft/geosector/-/merge_requests/new?merge_request%5Bsource_branch%5D=feature/nom-de-la-fonctionnalite

5. Attendre la revue de code et les validations CI/CD

6. Une fois approuvée, fusionner la branche:

   git checkout main
   git merge feature/nom-de-la-fonctionnalite
   git push origin main
   

CI/CD Pipeline

Le projet utilise un pipeline CI/CD GitLab pour automatiser les tests et le déploiement:

1. Build: Compilation du code et vérification de la syntaxe

   • PHP: Vérification de la syntaxe et des dépendances Composer
   • Flutter: Compilation et génération des assets

2. Test: Exécution des tests automatisés

   • Tests unitaires pour l'API PHP
   • Tests de widgets pour l'application Flutter

3. Deploy: Déploiement automatique vers les environnements

   • Déploiement vers DEV après chaque merge dans develop
   • Déploiement vers RECETTE après validation manuelle
   • Déploiement vers PROD après validation manuelle sur une MR vers main

Intégration avec GitLab

Issues et Kanban

• Labels:

  • feature: Nouvelles fonctionnalités
  • bug: Corrections de bugs
  • enhancement: Améliorations de fonctionnalités existantes
  • documentation: Mises à jour de la documentation
  • api: Modifications de l'API
  • ui: Modifications de l'interface utilisateur
  • priority:high: Priorité élevée
  • priority:medium: Priorité moyenne
  • priority:low: Priorité basse

• Milestones:

  • Organisées par versions majeures (1.0, 1.1, etc.)
  • Chaque milestone contient les issues prévues pour la version
  • Date d'échéance définie pour chaque milestone

• Boards:

  • Backlog: Issues à traiter dans le futur
  • To Do: Issues prêtes à être développées
  • In Progress: Issues en cours de développement
  • Review: Issues en attente de revue de code
  • Done: Issues terminées et déployées

Automatisations

• Webhooks: Notifications automatiques dans Slack pour les événements importants

  • Nouvelles Merge Requests
  • Commentaires sur les MRs
  • Builds échoués
  • Déploiements réussis

• Merge Request Templates: Templates prédéfinis pour les MRs avec:

  • Description de la fonctionnalité
  • Checklist de vérification
  • Instructions de test
  • Captures d'écran (si applicable)

• CI/CD Automatisé: Déclenchement automatique des pipelines sur:

  • Push vers une branche
  • Création d'une Merge Request
  • Mise à jour d'une Merge Request

Déploiement

Environnements

• Un environnement DEV dans un container Incus Alpine distant dva-geo
• Un environnement RECETTE dans un container Incus Alpine distant rca-geo
• Un environnement PROD dans un container Incus Alpine distant pra-geo

Processus de Déploiement

• Un script /web/deploy-web.sh pour déployer le site Web sur l'environnement DEV

• Un script /app/deploy-app.sh pour déployer l'application Flutter Web sur l'environnement DEV

• Un script /api/deploy-api.sh pour déployer l'API PHP sur l'environnement DEV

• Un script /web/livre-web.sh $0 $1 pour livrer le site web d'un environnement $0 à l'autre $1

• Un script /app/livre-app.sh $0 $1 pour livrer l'application Flutter Web d'un environnement $0 à l'autre $1

• Un script /api/livre-api.sh $0 $1 pour livrer l'API PHP d'un environnement $0 à l'autre $1

Ressources et Documentation

Documentation Interne

• [Liens vers la documentation interne]

API Documentation

• [Liens vers la documentation API (Swagger/OpenAPI)]

Ressources Externes

• [Liens vers des ressources externes pertinentes]

Contacts

Équipe Principale

• [Nom]: [Rôle] - [Email/GitLab username]

Parties Prenantes

• [Nom]: [Rôle/Organisation] - [Contact]

Historique des Versions

Version	Date	Description
1.0.0	01/03/2025	Version initiale du projet
1.1.0	16/05/2025	Ajout de la géolocalisation automatique des casernes de pompiers via API adresse.gouv.fr, amélioration du formulaire EntiteForm avec confirmation pour l'activation des paiements Stripe, mise à jour automatique des coordonnées GPS lors des changements d'adresse