geo/app/docs/chat.md

Solution de Chat pour Applications Flutter

Présentation générale

Cette solution propose un système de chat personnalisé et autonome pour des applications Flutter, avec possibilité d'intégration web. Elle est conçue pour fonctionner dans deux contextes différents :

1. Chat entre utilisateurs authentifiés (cas Geosector) : communications one-to-one ou en groupe entre utilisateurs déjà enregistrés dans la base de données.
2. Chat entre professionnels et visiteurs anonymes (cas Resalice) : communications initiées par des visiteurs anonymes qui peuvent ensuite être convertis en clients référencés.

Architecture technique

1. Structure générale

La solution s'articule autour de trois composants principaux :

• Module Flutter : Widgets et logique pour l'interface utilisateur mobile
• Module Web : Composants pour l'intégration web (compatible avec Flutter Web ou sites traditionnels)
• API Backend : Endpoints REST pour la gestion des messages et la synchronisation

2. Modèle de données

Entités principales

Conversation
  ├── id : Identifiant unique
  ├── type : Type de conversation (one_to_one, group, anonymous, broadcast, announcement)
  ├── title : Titre facultatif pour les groupes et obligatoire pour les annonces
  ├── reply_permission : Niveau de permission pour répondre (all, admins_only, sender_only, none)
  ├── created_at : Date de création
  ├── updated_at : Dernière mise à jour
  ├── is_pinned : Indique si la conversation est épinglée (pour annonces importantes)
  ├── expiry_date : Date d'expiration optionnelle (pour annonces temporaires)
  └── participants : Liste des participants

Message
  ├── id : Identifiant unique
  ├── conversation_id : ID de la conversation
  ├── sender_id : ID de l'expéditeur (null pour anonyme)
  ├── sender_type : Type d'expéditeur (user, anonymous, system)
  ├── content : Contenu du message
  ├── content_type : Type de contenu (text, image, file)
  ├── created_at : Date d'envoi
  ├── delivered_at : Date de réception
  ├── read_at : Date de lecture
  ├── status : Statut du message (sent, delivered, read, error)
  └── is_announcement : Indique s'il s'agit d'une annonce officielle

Participant
  ├── id : Identifiant unique
  ├── conversation_id : ID de la conversation
  ├── user_id : ID de l'utilisateur (si authentifié)
  ├── anonymous_id : ID anonyme (pour Resalice)
  ├── role : Rôle (admin, member, read_only)
  ├── joined_at : Date d'ajout à la conversation
  ├── via_target : Indique si l'utilisateur est inclus via un AudienceTarget
  ├── can_reply : Possibilité explicite de répondre (override de reply_permission)
  └── last_read_message_id : ID du dernier message lu

AudienceTarget
  ├── id : Identifiant unique
  ├── conversation_id : ID de la conversation
  ├── target_type : Type de cible (role, entity, all, combined)
  ├── target_id : ID du rôle ou de l'entité ciblée (pour compatibility)
  ├── role_filter : Filtre de rôle pour le ciblage combiné ('all', '1', '2', etc.)
  ├── entity_filter : Filtre d'entité pour le ciblage combiné ('all', 'id_entité')
  └── created_at : Date de création

AnonymousUser (pour Resalice)
  ├── id : Identifiant unique
  ├── device_id : Identifiant du dispositif
  ├── name : Nom temporaire (si fourni)
  ├── email : Email (si fourni)
  ├── created_at : Date de création
  ├── converted_to_user_id : ID utilisateur après conversion
  └── metadata : Informations supplémentaires

Adaptations pour Hive

Ces modèles seront adaptés pour Hive avec leurs adaptateurs respectifs :

@HiveType(typeId: 20)
class ConversationModel extends HiveObject {
  @HiveField(0)
  final String id;

  @HiveField(1)
  final String type;

  @HiveField(2)
  final String? title;

  @HiveField(3)
  final DateTime createdAt;

  @HiveField(4)
  final DateTime updatedAt;

  @HiveField(5)
  final List<ParticipantModel> participants;

  @HiveField(6)
  final bool isSynced;

  @HiveField(7)
  final String replyPermission;

  @HiveField(8)
  final bool isPinned;

  @HiveField(9)
  final DateTime? expiryDate;

  // ... autres propriétés et méthodes
}

@HiveType(typeId: 21)
class MessageModel extends HiveObject {
  @HiveField(0)
  final String id;

  @HiveField(1)
  final String conversationId;

  @HiveField(2)
  final String? senderId;

  @HiveField(3)
  final String senderType;

  @HiveField(4)
  final String content;

  @HiveField(5)
  final String contentType;

  @HiveField(6)
  final DateTime createdAt;

  @HiveField(7)
  final DateTime? deliveredAt;

  @HiveField(8)
  final DateTime? readAt;

  @HiveField(9)
  final String status;

  @HiveField(10)
  final bool isAnnouncement;

  // ... autres propriétés et méthodes
}

@HiveType(typeId: 22)
class ParticipantModel extends HiveObject {
  @HiveField(0)
  final String id;

  @HiveField(1)
  final String conversationId;

  @HiveField(2)
  final String? userId;

  @HiveField(3)
  final String? anonymousId;

  @HiveField(4)
  final String role;

  @HiveField(5)
  final DateTime joinedAt;

  @HiveField(6)
  final String? lastReadMessageId;

  @HiveField(7)
  final bool viaTarget;

  @HiveField(8)
  final bool? canReply;

  // ... autres propriétés et méthodes
}

@HiveType(typeId: 23)
class AudienceTargetModel extends HiveObject {
  @HiveField(0)
  final String id;

  @HiveField(1)
  final String conversationId;

  @HiveField(2)
  final String targetType;

  @HiveField(3)
  final String? targetId;

  @HiveField(4)
  final DateTime createdAt;

  @HiveField(5)
  final String? roleFilter;  // 'all' ou ID de rôle

  @HiveField(6)
  final String? entityFilter; // 'all' ou ID d'entité

  // ... autres propriétés et méthodes
}

3. Backend et API

Structure de l'API

L'API sera développée en PHP 8.3 pour s'intégrer avec vos systèmes existants :

/api/chat/conversations
  GET    - Liste des conversations de l'utilisateur
  POST   - Créer une nouvelle conversation

/api/chat/conversations/{id}
  GET    - Détails d'une conversation
  PUT    - Mettre à jour une conversation
  DELETE - Supprimer une conversation

/api/chat/conversations/{id}/messages
  GET    - Messages d'une conversation (pagination)
  POST   - Envoyer un message

/api/chat/conversations/{id}/participants
  GET    - Liste des participants
  POST   - Ajouter un participant
  DELETE - Retirer un participant

/api/chat/messages/{id}
  PUT    - Mettre à jour un message (ex: marquer comme lu)
  DELETE - Supprimer un message

/api/chat/anonymous
  POST   - Démarrer une conversation anonyme

# Nouveaux endpoints pour les annonces
/api/chat/announcements
  GET    - Liste des annonces pour l'utilisateur
  POST   - Créer une nouvelle annonce

/api/chat/announcements/{id}/stats
  GET    - Obtenir les statistiques de lecture (qui a lu/non lu)

/api/chat/audience-targets
  GET    - Obtenir les cibles disponibles pour l'utilisateur actuel

/api/chat/conversations/{id}/pin
  PUT    - Épingler/désépingler une conversation

/api/chat/conversations/{id}/reply-permission
  PUT    - Modifier les permissions de réponse

Synchronisation

Le système supportera :

• Synchronisation en temps réel via WebSockets (optionnel)
• Synchronisation par polling avec gestion des messages non lus
• Enregistrement local des messages avec Hive pour le fonctionnement hors ligne

4. Widgets Flutter

Widgets principaux

1. ChatScreen : Écran principal d'une conversation

   ChatScreen({
     required String conversationId,
     String? title,
     Widget? header,
     Widget? footer,
     bool enableAttachments = true,
     bool showTypingIndicator = true,
     bool enableReadReceipts = true,
     bool isAnnouncement = false,
     bool canReply = true,
   })
   

2. ConversationsList : Liste des conversations

   ConversationsList({
     List<ConversationModel>? conversations,
     bool loadFromHive = true,
     Function(ConversationModel)? onConversationSelected,
     bool showLastMessage = true,
     bool showUnreadCount = true,
     bool showAnnouncementBadge = true,
     bool showPinnedFirst = true,
     Widget? emptyStateWidget,
   })
   

3. MessageBubble : Bulle de message

   MessageBubble({
     required MessageModel message,
     bool showSenderInfo = true,
     bool showTimestamp = true,
     bool showStatus = true,
     bool isAnnouncement = false,
     double maxWidth = 300,
   })
   

4. ChatInput : Zone de saisie de message

   ChatInput({
     required Function(String) onSendText,
     Function(File)? onSendFile,
     Function(File)? onSendImage,
     bool enableAttachments = true,
     bool enabled = true,
     String hintText = 'Saisissez votre message...',
     String? disabledMessage = 'Vous ne pouvez pas répondre à cette annonce',
     int? maxLength,
   })
   

5. AnonymousChatStarter : Widget pour démarrer un chat anonyme (Resalice)

   AnonymousChatStarter({
     required Function(String?) onChatStarted,
     bool requireName = false,
     bool requireEmail = false,
     String buttonLabel = 'Démarrer une conversation',
     Widget? customForm,
   })
   

6. AnnouncementComposer : Widget pour créer des annonces (Geosector uniquement)

   AnnouncementComposer({
     required Function(Map<String, dynamic>) onSend,
     List<Map<String, dynamic>>? availableTargets,
     String? initialTitle,
     String? initialMessage,
     bool allowAttachments = true,
     bool allowPinning = true,
     List<String> replyPermissionOptions = const ['all', 'admins_only', 'sender_only', 'none'],
     String defaultReplyPermission = 'none',
     DateTime? expiryDate,
     bool isGeosector = true, // Active la sélection des destinataires
   })
   

7. AnnouncementTargetSelector : Sélecteur de destinataires pour annonces (Geosector uniquement)

   AnnouncementTargetSelector({
     required Function(AudienceTargetModel) onTargetSelected,
     required List<EntityModel> availableEntities,
     bool showRoleFilter = true,
     bool showEntityFilter = true,
     String defaultRole = 'all',
     String defaultEntity = 'all',
   })
   

8. AnnouncementBanner : Bannière pour afficher une annonce importante

   AnnouncementBanner({
     required MessageModel announcement,
     required Function() onView,
     Function()? onDismiss,
     bool isDismissible = true,
     Duration? autoDismissAfter,
     Color? backgroundColor,
     Widget? icon,
   })
   

Fonctionnalités des widgets

• Design adaptatif (mobile/web)
• Support des thèmes clairs/sombres
• Gestion des messages non lus
• Indicateurs de frappe
• Accusés de réception et de lecture
• Support des pièces jointes (fichiers, images)
• Recherche dans les conversations
• Conversion d'utilisateurs anonymes en clients (Resalice)

5. Gestion des données locales (Hive)

Organisation des boîtes Hive

// Noms des boîtes Hive
static const String conversationsBoxName = 'chat_conversations';
static const String messagesBoxName = 'chat_messages';
static const String participantsBoxName = 'chat_participants';
static const String anonymousUsersBoxName = 'chat_anonymous_users';

Stratégie de synchronisation

1. Ouverture sélective : Ouverture des boîtes à la demande
2. Gestion de conflit : Stratégie pour résoudre les conflits entre données locales et serveur
3. Nettoyage intelligent : Suppression des messages anciens selon des règles configurables
4. Marqueurs de synchronisation : Tracking des messages synchronisés/non-synchronisés

Implémentation technique

1. Structure des repositories

class ChatRepository {
  // Gestion des conversations
  Future<List<ConversationModel>> getConversations({bool forceRefresh = false});
  Future<ConversationModel> getConversation(String id);
  Future<ConversationModel> createConversation(Map<String, dynamic> data);
  Future<void> deleteConversation(String id);
  Future<void> pinConversation(String id, bool isPinned);
  Future<void> updateReplyPermission(String id, String replyPermission);

  // Gestion des messages
  Future<List<MessageModel>> getMessages(String conversationId, {int page = 1, int limit = 50});
  Future<MessageModel> sendMessage(String conversationId, Map<String, dynamic> messageData);
  Future<void> markMessageAsRead(String messageId);

  // Gestion des participants
  Future<void> addParticipant(String conversationId, Map<String, dynamic> participantData);
  Future<void> removeParticipant(String conversationId, String participantId);

  // Gestion des utilisateurs anonymes (Resalice)
  Future<String> createAnonymousUser({String? name, String? email});
  Future<void> convertAnonymousToUser(String anonymousId, String userId);

  // Gestion des annonces
  Future<List<ConversationModel>> getAnnouncements({bool forceRefresh = false});
  Future<ConversationModel> createAnnouncement(Map<String, dynamic> data);
  Future<Map<String, dynamic>> getAnnouncementStats(String conversationId);

  // Gestion des cibles d'audience
  Future<List<Map<String, dynamic>>> getAvailableAudienceTargets();
  Future<void> addAudienceTarget(String conversationId, Map<String, dynamic> targetData);
  Future<void> removeAudienceTarget(String conversationId, String targetId);
}

2. Intégration avec l'API

class ChatApiService {
  final String baseUrl;
  final String? authToken;

  // Constructeur avec paramètres pour l'URL et l'authentification
  ChatApiService({
    required this.baseUrl,
    this.authToken,
  });

  // Méthodes HTTP pour communiquer avec l'API
  Future<Map<String, dynamic>> fetchConversations();
  Future<Map<String, dynamic>> fetchMessages(String conversationId, {int page = 1, int limit = 50});
  Future<Map<String, dynamic>> createConversation(Map<String, dynamic> data);
  Future<Map<String, dynamic>> sendMessage(String conversationId, Map<String, dynamic> messageData);
  // ...autres méthodes
}

3. Gestion hors ligne

class OfflineQueueService {
  // Ajouter des opérations en attente
  Future<void> addPendingOperation(String operationType, Map<String, dynamic> data);

  // Traiter les opérations en attente
  Future<void> processPendingOperations();

  // Écouter les changements de connectivité
  void listenToConnectivityChanges();
}

4. Stockage des fichiers

Le système supportera le téléchargement et le partage de fichiers :

1. Côté serveur : Stockage dans un répertoire sécurisé avec restriction d'accès
2. Côté client : Mise en cache des fichiers pour éviter des téléchargements redondants
3. Types supportés : Images, documents, autres fichiers selon configuration

Cas d'utilisation spécifiques

1. Geosector

• Utilisateurs authentifiés uniquement
• Groupes par équipe avec administrateurs pour les communications internes
• Historique complet des conversations
• Intégration avec la structure existante des amicales et équipes
• Annonces et broadcasts:
  • Super admin → tous les admins d'entités
  • Admin d'entité → tous les utilisateurs de son entité
  • Communications descendantes sans possibilité de réponse
  • Statistiques de lecture des annonces importantes
  • Ciblage flexible des destinataires :
    • Par entité (toutes ou une spécifique)
    • Par rôle (tous, membres, administrateurs)
    • Combinaison entité + rôle (ex: admins de l'entité 5)
    • Sélection via le widget AnnouncementTargetSelector

2. Resalice

• Chats initiés par des anonymes
• Conversation one-to-one uniquement entre professionnel et client/prospect
• Conversion client : Processus pour transformer un utilisateur anonyme en client référencé
• Conservation des historiques après conversion
• Interface professionnelle adaptée aux échanges client/professionnel
• Pas de fonctionnalité d'annonce - uniquement des conversations directes
• Annonces non pertinentes pour ce cas d'usage (pas de widget AnnouncementTargetSelector)

Adaptations par projet

La solution de chat doit être adaptable selon le contexte :

1. Configuration globale : Un système de configuration permet de définir quelles fonctionnalités sont activées

   // Configuration pour Geosector
   const chatConfig = ChatConfig(
     enableAnnouncements: true,
     enableTargetSelection: true,
     showAnnouncementStats: true,
     defaultReplyPermission: 'none',
   );
   
   // Configuration pour Resalice
   const chatConfig = ChatConfig(
     enableAnnouncements: false,
     enableTargetSelection: false,
     showAnnouncementStats: false,
     defaultReplyPermission: 'all',
   );
   

2. Interfaces conditionnelles : Les widgets adaptent leur affichage selon la configuration

   // Dans AnnouncementComposer
   if (config.enableTargetSelection) {
     children.add(AnnouncementTargetSelector(...));
   }
   

3. Types de conversation limités : La création de certains types de conversation est restreinte

   // Dans Resalice, seuls les types one_to_one et anonymous sont autorisés
   if (!config.enableAnnouncements && type == 'announcement') {
     throw UnsupportedConversationType();
   }
   

Adaptabilité et extensibilité

1. Options de personnalisation

• Thèmes : Adaptation aux couleurs et styles de l'application
• Fonctionnalités : Activation/désactivation de certaines fonctionnalités
• Comportements : Configuration des notifications, comportement hors ligne, etc.

2. Extensions possibles

• Chatbot : Possibilité d'intégrer des réponses automatiques
• Transfert : Transfert de conversations entre professionnels
• Intégration CRM : Liaison avec des systèmes CRM pour le suivi client
• Analyse : Statistiques sur les conversations, temps de réponse, etc.

Étapes d'implémentation suggérées

1. Phase 1 : Base du système (3-4 semaines)

   • Modèles de données et adaptateurs Hive
   • Configuration de l'API backend
   • Widgets de base pour affichage/envoi de messages
   • Structure de base pour les annonces et broadcasts

2. Phase 2 : Fonctionnalités avancées (2-3 semaines)

   • Gestion hors ligne et synchronisation
   • Support des fichiers et images
   • Indicateurs de lecture et d'écriture
   • Système de ciblage d'audience pour les annonces

3. Phase 3 : Cas spécifiques (2-3 semaines)

   • Support des conversations anonymes (Resalice)
   • Groupes et permissions avancées (Geosector)
   • Statistiques de lecture des annonces
   • Interface administrateur pour les annonces globales
   • Intégration web complète

Le temps total d'implémentation pour Geosector est estimé à 6-9 semaines pour un développeur expérimenté en Flutter et PHP. L'adaptation ultérieure à Resalice devrait prendre environ 2-3 semaines supplémentaires grâce à la conception modulaire du système.

Conclusion

Cette solution de chat personnalisée offre un équilibre entre robustesse et simplicité d'intégration. Elle répond aux besoins spécifiques de vos applications tout en restant suffisamment flexible pour s'adapter à d'autres contextes.

Le système prend en charge non seulement les conversations classiques (one-to-one, groupes) mais aussi les communications de type annonce/broadcast où un administrateur peut communiquer des informations importantes à des groupes d'utilisateurs définis par rôle ou entité, avec ou sans possibilité de réponse. Cette fonctionnalité est particulièrement adaptée aux cas d'usage mentionnés pour Geosector, où l'admin général souhaite communiquer avec tous les admins d'entités, ou un admin d'entité avec tous les utilisateurs de son entité.

En développant cette solution en interne, vous gardez un contrôle total sur les fonctionnalités et l'expérience utilisateur, tout en assurant une cohérence avec le reste de vos applications. La conception modulaire et réutilisable permettra également un déploiement efficace sur vos différentes plateformes et applications.