# 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

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

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

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

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

   ```bash
   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:
   ```bash
   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 |