geo/app/lib/chat/README.md

# Module Chat Autonome pour GEOSECTOR

## Description
Module de chat **totalement autonome et portable** pour l'application GEOSECTOR. 
- **100% indépendant** : Peut être réutilisé dans n'importe quelle application Flutter
- **API REST uniquement** : Plus de dépendance MQTT
- **Architecture simple** : Code maintenable et facilement compréhensible
- **Cache local Hive** : Fonctionnement offline avec synchronisation automatique
- **Gestion des rôles** : Permissions configurables via YAML
- **Autocomplete intelligent** : Sélection des destinataires selon les permissions

## Architecture simplifiée

### Structure minimale
```
lib/chat/
├── models/           # 2 modèles simples
│   ├── room.dart
│   └── message.dart
├── services/         # Services de gestion
│   ├── chat_service.dart       # Service principal
│   └── chat_config_loader.dart # Chargeur de configuration
├── widgets/          # Composants réutilisables
│   └── recipient_selector.dart # Sélecteur de destinataires
├── pages/            # 2 pages essentielles
│   ├── rooms_page.dart
│   └── chat_page.dart
├── chat_config.yaml  # Configuration des permissions
└── chat_module.dart  # Point d'entrée
```

## Intégration dans votre application

### 1. Installation
```yaml
# pubspec.yaml
dependencies:
  dio: ^5.4.0
  hive: ^2.2.3
  hive_flutter: ^1.1.0
  yaml: ^3.1.2
```

### 2. Initialisation
```dart
await ChatModule.init(
  apiUrl: 'https://api.geosector.fr',
  userId: currentUser.id,
  userName: currentUser.name,
  userRole: currentUser.fkRole,    // 1, 2 ou 9
  userEntite: currentUser.entiteId, // ID de l'amicale
  authToken: authToken,              // Optionnel
);
```

### 3. Utilisation
```dart
// Ouvrir le chat
ChatModule.openChat(context);

// Ou obtenir directement une page
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => ChatModule.getRoomsPage(),
  ),
);
```

## Gestion des permissions par rôle

### Configuration (chat_config.yaml)
Les permissions sont définies dans un fichier YAML facilement modifiable :

#### Rôle 1 (Membre)
- Peut discuter avec les membres de son amicale (rôle 1)
- Peut discuter avec l'admin de son amicale (rôle 2)
- Restriction : même entité uniquement

#### Rôle 2 (Admin Amicale)
- Peut discuter avec tous les membres de son amicale
- Peut discuter avec les superadmins (rôle 9)
- Peut créer des groupes de discussion

#### Rôle 9 (Super Admin)
- Peut envoyer des messages à tous les admins d'amicale
- Peut sélectionner des destinataires spécifiques
- Peut faire du broadcast à tous les admins

## API Backend requise

### Endpoints REST
- `GET /api/chat/rooms` - Liste des conversations filtrées par rôle
- `POST /api/chat/rooms` - Créer une conversation avec vérification des permissions
- `GET /api/chat/rooms/{id}/messages` - Messages d'une conversation
- `POST /api/chat/rooms/{id}/messages` - Envoyer un message
- `POST /api/chat/rooms/{id}/read` - Marquer comme lu
- `GET /api/chat/recipients` - Liste des destinataires possibles selon le rôle

### Structure base de données
```sql
-- Tables préfixées "chat_"
CREATE TABLE chat_rooms (
  id VARCHAR(36) PRIMARY KEY,
  title VARCHAR(255),
  type ENUM('private', 'group', 'broadcast'),
  created_at TIMESTAMP,
  created_by INT
);

CREATE TABLE chat_messages (
  id VARCHAR(36) PRIMARY KEY,
  room_id VARCHAR(36),
  content TEXT,
  sender_id INT,
  sent_at TIMESTAMP,
  FOREIGN KEY (room_id) REFERENCES chat_rooms(id)
);

CREATE TABLE chat_participants (
  room_id VARCHAR(36),
  user_id INT,
  role INT,
  entite_id INT,
  joined_at TIMESTAMP,
  PRIMARY KEY (room_id, user_id)
);

CREATE TABLE chat_read_receipts (
  message_id VARCHAR(36),
  user_id INT,
  read_at TIMESTAMP,
  PRIMARY KEY (message_id, user_id)
);
```

## Stockage local Hive

### TypeIds réservés
- TypeId 50: Room
- TypeId 51: Message
- TypeIds 52-60: Réservés pour extensions futures

### Boxes Hive
- `chat_rooms`: Conversations en cache
- `chat_messages`: Messages en cache

## Interface utilisateur

### Design minimaliste et professionnel
- Palette de couleurs sobre (blanc, gris, bleu accent)
- Pas d'animations superflues
- Focus sur la lisibilité et l'efficacité
- Interface responsive pour toutes les plateformes

### Composants principaux
1. **Liste des conversations** : Vue simple avec badges non-lus
2. **Page de chat** : Messages avec bulles, input simple
3. **Sélecteur de destinataires** : Autocomplete avec filtrage par rôle

## Planning de développement (2 sessions)

### Session 1 : Architecture de base ✅
- [x] Nettoyage et suppression du MQTT
- [x] Création des modèles simples (Room, Message)
- [x] Service unique ChatService
- [x] Pages minimales (RoomsPage, ChatPage)
- [x] Module d'entrée ChatModule
- [x] Gestion des rôles et permissions via YAML
- [x] Widget autocomplete pour sélection des destinataires
- [x] Adaptation de l'UI selon les permissions

### Session 2 : Finalisation
- [ ] Tests d'intégration avec l'API
- [ ] Documentation API complète
- [ ] Optimisations performances
- [ ] Gestion erreurs robuste

## Points d'attention

### Sécurité
- Authentification via token JWT
- Vérification des permissions côté serveur
- Validation des inputs

### Performance
- Cache Hive pour mode offline
- Pagination des messages
- Lazy loading des conversations

### Maintenance
- Code simple et documenté
- Architecture modulaire
- Configuration externalisée (YAML)

## Support

Pour toute question ou problème, consulter la documentation principale de l'application GEOSECTOR.