# 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