geo/app/lib/chat/services/notifications/README_MQTT.md

# Notifications MQTT pour le Chat GEOSECTOR

## Vue d'ensemble

Ce système de notifications utilise MQTT pour fournir des notifications push en temps réel pour le module chat. Il offre une alternative légère à Firebase Cloud Messaging (FCM) et peut être auto-hébergé dans votre infrastructure.

## Architecture

### Composants principaux

1. **MqttNotificationService** (Flutter)
   - Service de notification côté client
   - Gère la connexion au broker MQTT
   - Traite les messages entrants
   - Affiche les notifications locales

2. **MqttConfig** (Flutter)
   - Configuration centralisée pour MQTT
   - Gestion des topics
   - Paramètres de connexion

3. **MqttNotificationSender** (PHP)
   - Service backend pour envoyer les notifications
   - Interface avec la base de données
   - Gestion des cibles d'audience

## Configuration du broker MQTT

### Container Incus

Le broker MQTT (Eclipse Mosquitto recommandé) doit être installé dans votre container Incus :

```bash
# Installer Mosquitto
apt-get update
apt-get install mosquitto mosquitto-clients

# Configurer Mosquitto
vi /etc/mosquitto/mosquitto.conf
```

Configuration recommandée :
```
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

# Pour SSL/TLS
listener 8883
cafile /etc/mosquitto/ca.crt
certfile /etc/mosquitto/server.crt
keyfile /etc/mosquitto/server.key
```

### Sécurité

Pour un environnement de production, il est fortement recommandé :

1. D'utiliser SSL/TLS (port 8883)
2. De configurer l'authentification par mot de passe
3. De limiter les IPs pouvant se connecter
4. De configurer des ACLs pour restreindre l'accès aux topics

## Structure des topics MQTT

### Topics utilisateur
- `chat/user/{userId}/messages` - Messages personnels pour l'utilisateur
- `chat/user/{userId}/groups/{groupId}` - Messages des groupes de l'utilisateur

### Topics globaux
- `chat/announcement` - Annonces générales
- `chat/broadcast` - Diffusions à grande échelle

### Topics conversation
- `chat/conversation/{conversationId}` - Messages spécifiques à une conversation

## Intégration Flutter

### Dépendances requises

Ajoutez ces dépendances à votre `pubspec.yaml` :

```yaml
dependencies:
  mqtt5_client: ^4.0.0  # ou mqtt_client selon votre préférence
  flutter_local_notifications: ^17.0.0
```

### Initialisation

```dart
// Dans main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final notificationService = MqttNotificationService();
  await notificationService.initialize(userId: currentUserId);
  
  runApp(const GeoSectorApp());
}
```

### Utilisation

```dart
// Écouter les messages
notificationService.onMessageTap = (messageId) {
  // Naviguer vers le message
  Navigator.pushNamed(context, '/chat/$messageId');
};

// Publier un message
await notificationService.publishMessage(
  'chat/user/$userId/messages',
  {'content': 'Test message'},
);
```

## Gestion des notifications

### Paramètres utilisateur

Les utilisateurs peuvent configurer :
- Activation/désactivation des notifications
- Conversations en silencieux
- Mode "Ne pas déranger"
- Aperçu du contenu

### Persistance des notifications

Les notifications sont enregistrées dans la table `chat_notifications` pour :
- Traçabilité
- Statistiques
- Synchronisation

## Tests

### Test de connexion

```dart
final service = MqttNotificationService();
await service.initialize(userId: 'test_user');
// Vérifie les logs pour confirmer la connexion
```

### Test d'envoi

```php
$sender = new MqttNotificationSender($db, $mqttConfig);
$result = $sender->sendMessageNotification(
  'receiver_id',
  'sender_id',
  'message_id',
  'Test message',
  'conversation_id'
);
```

## Surveillance et maintenance

### Logs

Les logs sont disponibles dans :
- Logs Flutter (console debug)
- Logs Mosquitto (`/var/log/mosquitto/mosquitto.log`)
- Logs PHP (selon configuration)

### Métriques à surveiller

- Nombre de connexions actives
- Latence des messages
- Taux d'échec des notifications
- Consommation mémoire/CPU du broker

## Comparaison avec Firebase

### Avantages MQTT

1. **Auto-hébergé** : Contrôle total de l'infrastructure
2. **Léger** : Moins de ressources que Firebase
3. **Coût** : Gratuit (uniquement coûts d'infrastructure)
4. **Personnalisable** : Configuration fine du broker

### Inconvénients

1. **Maintenance** : Nécessite une gestion du broker
2. **Évolutivité** : Requiert dimensionnement et clustering
3. **Fonctionnalités** : Moins de services intégrés que Firebase

## Évolutions futures

1. **WebSocket** : Ajout optionnel pour temps réel strict
2. **Clustering** : Pour haute disponibilité
3. **Analytics** : Dashboard de monitoring
4. **Webhooks** : Intégration avec d'autres services

## Dépannage

### Problèmes courants

1. **Connexion échouée**
   - Vérifier username/password
   - Vérifier port/hostname
   - Vérifier firewall

2. **Messages non reçus**
   - Vérifier abonnement aux topics
   - Vérifier QoS
   - Vérifier paramètres notifications

3. **Performance dégradée**
   - Augmenter keepAlive
   - Ajuster reconnectInterval
   - Vérifier charge serveur