unionflow-mobile-apps/lib/features/communication/README.md

Feature Communication/Messaging

Status: ✅ Implémenté (MVP Fonctionnel) Date: 2026-03-13 Priorité: P0 (Bloquant Production)

📋 Vue d'ensemble

Module de communication permettant la messagerie entre membres et les broadcasts organisation selon les permissions RBAC.

🎯 Fonctionnalités Implémentées

✅ MVP (V1.0)

1. Liste des Conversations

   • Affichage conversations triées par date
   • Badge compteur messages non lus
   • Indicateurs visuels (pinned, muted)
   • Pull-to-refresh
   • Navigation vers détail conversation

2. Permissions Respectées

   • COMM_SEND_ALL - OrgAdmin, SuperAdmin
   • COMM_SEND_MEMBERS - Moderator
   • COMM_BROADCAST - OrgAdmin
   • Menu "Messages" visible selon rôle (OrgAdmin, SuperAdmin, Moderator)

3. Architecture Clean + BLoC

   • Domain : Entities (Message, Conversation, MessageTemplate)
   • Data : Models avec JSON serialization, Repository, Datasource
   • Presentation : BLoC (Events, States), Pages, Widgets

4. Intégration App

   • Routes : /messages, /communication
   • Navigation : Menu "Plus" avec vérification permissions
   • DI : Injectable + GetIt

🏗️ Architecture

communication/
├── domain/
│   ├── entities/
│   │   ├── message.dart (Message, MessageType, MessageStatus, MessagePriority)
│   │   ├── conversation.dart (Conversation, ConversationType)
│   │   └── message_template.dart (MessageTemplate, TemplateCategory)
│   ├── repositories/
│   │   └── messaging_repository.dart (interface)
│   └── usecases/
│       ├── get_conversations.dart
│       ├── get_messages.dart
│       ├── send_message.dart
│       └── send_broadcast.dart
├── data/
│   ├── models/
│   │   ├── message_model.dart (.g.dart généré)
│   │   └── conversation_model.dart (.g.dart généré)
│   ├── datasources/
│   │   └── messaging_remote_datasource.dart (API REST)
│   └── repositories/
│       └── messaging_repository_impl.dart
└── presentation/
    ├── bloc/
    │   ├── messaging_event.dart
    │   ├── messaging_state.dart
    │   └── messaging_bloc.dart
    ├── pages/
    │   └── conversations_page.dart
    └── widgets/
        └── conversation_tile.dart

📡 API Endpoints Utilisés

Endpoint	Méthode	Description
/api/messaging/conversations	GET	Liste conversations
/api/messaging/conversations/:id	GET	Détail conversation
/api/messaging/conversations	POST	Créer conversation
/api/messaging/conversations/:id/messages	GET	Messages d'une conversation
/api/messaging/conversations/:id/messages	POST	Envoyer message
/api/messaging/broadcast	POST	Envoyer broadcast
/api/messaging/messages/:id/read	PUT	Marquer message lu
/api/messaging/unread/count	GET	Compteur non lus

⚠️ Note: Backend endpoints à implémenter côté serveur Quarkus

🔄 États BLoC

• MessagingInitial - État initial
• MessagingLoading - Chargement en cours
• ConversationsLoaded - Conversations chargées avec compteur non lus
• MessagesLoaded - Messages d'une conversation chargés
• MessageSent - Message envoyé avec succès
• BroadcastSent - Broadcast envoyé avec succès
• MessagingError - Erreur avec message utilisateur

🚀 Prochaines Étapes (V2.0+)

P1 - Fonctionnalités Avancées

• Page détail conversation (chat thread)
• Envoi pièces jointes (images, documents)
• Édition/suppression messages
• Recherche dans conversations
• Filtres conversations (non lus, pinned, archivées)
• Templates messages personnalisables (CRUD)
• Messages ciblés par rôles (COMM_TARGETED)
• Modération messages (MODERATION_CONTENT)
• Statistiques communication (dashboard analytics)

P2 - Optimisations

• WebSocket temps réel pour nouveaux messages
• Cache local conversations récentes
• Pagination messages (infinite scroll)
• Compression images avant envoi
• Mode offline avec synchronisation
• Notifications push (FCM)
• Read receipts (accusés de lecture)
• Typing indicators (en train d'écrire)

🧪 Tests

À Implémenter

• Unit tests BLoC (bloc_test)
• Unit tests UseCases (mockito)
• Unit tests Repository (mockito)
• Widget tests ConversationsPage
• Integration tests flux complet

📝 Notes Techniques

JSON Serialization

Le champ lastMessage dans Conversation utilise une sérialisation custom car Message est un type nested :

@JsonKey(
  fromJson: _messageFromJson,
  toJson: _messageToJson,
)
final Message? lastMessage;

Gestion d'Erreurs

Toutes les méthodes repository retournent Either<Failure, T> pour une gestion fonctionnelle des erreurs :

• NetworkFailure - Pas de connexion Internet
• UnauthorizedFailure - Token expiré (401)
• ForbiddenFailure - Permission insuffisante (403)
• NotFoundFailure - Ressource non trouvée (404)
• ServerFailure - Erreur serveur (5xx)
• ValidationFailure - Données invalides
• UnexpectedFailure - Erreur inattendue
• NotImplementedFailure - Fonctionnalité en développement

Dépendances Externes

Module RegisterModule enregistre :

• http.Client pour requêtes HTTP
• FlutterSecureStorage pour tokens
• Connectivity pour état réseau

📚 Documentation Connexe

• Permission Matrix
• User Roles
• API Design
• Constitution UnionFlow

✅ Critères d'Acceptation

• Architecture Clean + BLoC respectée
• Permissions RBAC vérifiées (OrgAdmin, SuperAdmin, Moderator)
• Routes intégrées (/messages, /communication)
• Menu navigation avec vérification rôles
• Page liste conversations fonctionnelle
• Gestion erreurs complète (Failures)
• DI configuré (Injectable + GetIt)
• JSON serialization (.g.dart générés)
• Code compilable sans erreurs
• Backend endpoints implémentés (Quarkus)
• Tests unitaires BLoC
• Tests intégration E2E

---

Développé avec: Flutter 3.5.3+, Dart 3.x, BLoC 8.1.6, Clean Architecture Gap comblé: Communication/Messaging (P0 Bloquant Production)