Initialisation du projet geosector complet (web + flutter)

This commit is contained in:
d6soft
2025-05-01 18:59:27 +02:00
commit b5aafc424b
244 changed files with 37296 additions and 0 deletions

622
docs/chat.md Normal file
View File

@@ -0,0 +1,622 @@
# 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 :
```dart
@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
```dart
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
```dart
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
```dart
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
```dart
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)
```dart
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)
```dart
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)
```dart
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
```dart
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
```dart
// 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
```dart
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
```dart
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
```dart
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
```dart
// 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
```dart
// Dans AnnouncementComposer
if (config.enableTargetSelection) {
children.add(AnnouncementTargetSelector(...));
}
```
3. **Types de conversation limités** : La création de certains types de conversation est restreinte
```dart
// 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.