# 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 :

```dart
@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](../../features/authentication/data/models/permission_matrix.dart)
- [User Roles](../../features/authentication/data/models/user_role.dart)
- [API Design](../../specs/000-unionflow-baseline/spec.md)
- [Constitution UnionFlow](../../../../.specify/memory/constitution.md)

## ✅ Critères d'Acceptation

- [x] Architecture Clean + BLoC respectée
- [x] Permissions RBAC vérifiées (OrgAdmin, SuperAdmin, Moderator)
- [x] Routes intégrées (/messages, /communication)
- [x] Menu navigation avec vérification rôles
- [x] Page liste conversations fonctionnelle
- [x] Gestion erreurs complète (Failures)
- [x] DI configuré (Injectable + GetIt)
- [x] JSON serialization (.g.dart générés)
- [x] 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)