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

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

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

[Toute convention ou pratique spécifique à ce projet]

Flux de Travail et Processus de Développement

Branches GitLab

• main/master: [Production-ready code]
• develop: [Integration branch for features]
• feature/[feature-name]: [Feature development]
• bugfix/[bug-name]: [Bug fixes]
• release/[version]: [Release preparation]

Processus de Merge Request

1. [Créer une branche à partir de develop]
2. [Développer la fonctionnalité/correction]
3. [Soumettre une MR vers develop]
4. [Code review]
5. [CI/CD validation]
6. [Merge]

CI/CD Pipeline

[Description de votre pipeline CI/CD dans GitLab]

Intégration avec GitLab

Issues et Kanban

• Labels: [Liste des labels principaux et leur signification]
• Milestones: [Comment les milestones sont utilisées]
• Boards: [Description des tableaux Kanban]

Automatisations

[Description des automatisations GitLab utilisées]

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	[Date]	[Description]

Processus d'Authentification et Gestion des Sessions

Flux de Connexion

1. L'utilisateur entre ses identifiants dans la page de login (username/password)
2. L'application envoie une requête POST à /api/login avec les identifiants et le type de connexion (user/admin)
3. Le serveur vérifie les identifiants, crée une session PHP et renvoie:
   • Un session_id (utilisé comme token Bearer)
   • Une date d'expiration de session
   • Les données de l'utilisateur et les données associées (opérations, secteurs, passages)
4. L'application stocke ces données dans des boîtes Hive locales
5. Le session_id est utilisé pour toutes les requêtes API suivantes

Flux de Déconnexion

1. L'utilisateur demande une déconnexion
2. L'application envoie une requête POST à /api/logout avec le session_id dans l'en-tête
3. Le serveur détruit la session PHP avec session_unset() et session_destroy()
4. L'application:
   • Vide toutes les boîtes Hive sauf la boîte utilisateur
   • Conserve uniquement le username et le rôle de l'utilisateur pour faciliter la reconnexion
   • Réinitialise le session_id à null

Particularités

• La page de login vérifie le rôle de l'utilisateur avant de pré-remplir le champ username
• Le type de connexion (user/admin) détermine les données chargées et les droits d'accès
• Les utilisateurs avec rôle=1 sont des utilisateurs standards, ceux avec rôle>1 sont des administrateurs
• Les sessions expirent après 24 heures par défaut

Notes Spécifiques pour les Assistants IA

• Toujours vérifier les issues GitLab avant de proposer des solutions
• Respecter strictement les conventions de code mentionnées ci-dessus
• Lors de modifications des modèles Hive, s'assurer que les typeId sont uniques pour éviter les conflits
• Vérifier la compatibilité des modifications avec les trois plateformes (web, iOS, Android)
• Pour les modifications de l'API, s'assurer que la réponse reste compatible avec le format attendu par l'application