📢 Announcements

📋 Vue d'ensemble

Le module Announcements gère toutes les annonces du système pour les administrateurs. Il utilise NATS pour la communication inter-microservices avec la queue admin-service.

🏗️ Architecture

• Queue NATS : admin-service
• Patterns : announcements.*
• Upload d'images : Intégré avec validation
• Opérations en lot : Actions groupées
• Cache : Architecture prête pour Redis

📡 Message Patterns NATS

1. Lister les Annonces

Pattern : announcements.all

Payload (AnnouncementQueryDto)

{
  "page": 1,
  "limit": 10,
  "status": "PUBLISHED",
  "categoryId": 1,
  "search": "nouvelle fonctionnalité",
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

Filtres Disponibles

Filtre	Type	Description
status	String	Statut de l'annonce (DRAFT, PUBLISHED, ARCHIVED, DELETED)
categoryId	Number	ID de la catégorie (pour usage futur)
search	String	Recherche dans le titre et le contenu
sortBy	String	Champ de tri (createdAt, title, etc.)
sortOrder	String	Ordre de tri (asc, desc)

2. Détails d'une Annonce

Pattern : announcements.details

Payload

{
  "id": "announcement-uuid"
}

3. Créer une Annonce

Pattern : announcements.create

Option 1 : Avec URL d'image existante

{
  "title": "Nouvelle fonctionnalité disponible",
  "content": "Nous sommes heureux d'annoncer le lancement de notre nouvelle fonctionnalité...",
  "image": "/uploads/announcements/existing-image.jpg",
  "status": "DRAFT",
  "categoryId": 1
}

Option 2 : Avec upload d'image intégré

{
  "title": "Nouvelle fonctionnalité disponible",
  "content": "Nous sommes heureux d'annoncer le lancement de notre nouvelle fonctionnalité...",
  "status": "DRAFT",
  "categoryId": 1,
  "imageData": {
    "fileName": "announcement-image.jpg",
    "fileType": "image/jpeg",
    "base64Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}

Champs Obligatoires

• title : Titre de l'annonce
• content : Contenu de l'annonce

Champs Optionnels

• image : URL ou chemin vers une image existante
• imageData : Données pour upload d'une nouvelle image
• status : Statut (défaut: DRAFT)
• categoryId : Catégorie (pour usage futur)

Note : Si imageData est fourni, l'image sera automatiquement sauvegardée et image sera ignoré.

4. Mettre à jour une Annonce

Pattern : announcements.update

Option 1 : Mise à jour simple

{
  "id": "announcement-uuid",
  "updateData": {
    "title": "Titre mis à jour",
    "content": "Contenu mis à jour",
    "status": "PUBLISHED"
  }
}

Option 2 : Avec changement d'image

{
  "id": "announcement-uuid",
  "updateData": {
    "title": "Titre mis à jour",
    "content": "Contenu mis à jour",
    "imageData": {
      "fileName": "new-image.jpg",
      "fileType": "image/jpeg",
      "base64Data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
    }
  }
}

Note : Si imageData est fourni, l'ancienne image sera automatiquement supprimée et remplacée.

5. Supprimer une Annonce

Pattern : announcements.delete

Payload

{
  "id": "announcement-uuid"
}

Note : Suppression logique (soft delete) - le statut devient DELETED.

6. Publier/Dépublier une Annonce

Pattern : announcements.publish

Payload

{
  "id": "announcement-uuid",
  "publishData": {
    "status": "PUBLISHED"
  }
}

Statuts Disponibles

• PUBLISHED : Publier l'annonce
• DRAFT : Dépublier l'annonce

7. Opérations en Lot

Pattern : announcements.bulk-action

Payload

{
  "ids": ["uuid1", "uuid2", "uuid3"],
  "action": "publish"
}

Actions Disponibles

• publish : Publier les annonces sélectionnées
• unpublish : Dépublier les annonces sélectionnées
• archive : Archiver les annonces sélectionnées
• delete : Supprimer les annonces sélectionnées

8. Statistiques des Annonces

Pattern : announcements.stats

Payload

{}

Réponse

{
  "success": true,
  "message": "Announcement statistics retrieved successfully",
  "result": {
    "totalAnnouncements": 50,
    "publishedAnnouncements": 30,
    "draftAnnouncements": 15,
    "archivedAnnouncements": 3,
    "deletedAnnouncements": 2,
    "announcementsByStatus": [
      {"status": "PUBLISHED", "count": 30},
      {"status": "DRAFT", "count": 15}
    ],
    "recentAnnouncements": [
      {
        "id": 1,
        "publicId": "uuid",
        "title": "Dernière annonce",
        "content": "Contenu...",
        "status": "PUBLISHED",
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

📊 Enums et Statuts

Statuts d'Annonce (AnnouncementStatus)

enum AnnouncementStatus {
    DRAFT = 'DRAFT',           // Brouillon
    PUBLISHED = 'PUBLISHED',   // Publié
    ARCHIVED = 'ARCHIVED',     // Archivé
    DELETED = 'DELETED'        // Supprimé
}

Statut	Description	Actions Possibles
DRAFT	Brouillon en cours de rédaction	Publier, Modifier, Supprimer
PUBLISHED	Annonce visible publiquement	Dépublier, Archiver, Modifier
ARCHIVED	Annonce archivée	Republier, Supprimer
DELETED	Annonce supprimée	Restaurer

🚀 Fonctionnalités Avancées

1. Gestion des Images

• Upload sécurisé : Validation du type de fichier (JPG, PNG, GIF, WebP)
• Limite de taille : 5MB maximum
• Stockage local : Fichiers sauvés dans /uploads/announcements/
• Noms uniques : UUID pour éviter les conflits
• Support Base64 : Upload direct depuis le frontend
• Gestion automatique : Suppression des anciennes images lors des mises à jour

2. Opérations en Lot

• Sélection multiple : Actions sur plusieurs annonces
• Actions groupées : Publier, archiver, supprimer en une fois
• Retour détaillé : Nombre d'éléments affectés
• Validation : Vérification avant exécution
• Rollback : Annulation en cas d'erreur

3. Recherche et Filtrage

• Recherche textuelle : Dans titre et contenu
• Filtres par statut : Affichage conditionnel
• Tri personnalisé : Par date, titre, etc.
• Pagination : Performance optimisée
• Cache intelligent : Réduction des accès DB

💡 Exemples d'Utilisation

Créer une Annonce avec Image

{
  "title": "Mise à jour importante du système",
  "content": "Nous avons déployé une mise à jour majeure qui améliore les performances...",
  "status": "DRAFT",
  "imageData": {
    "fileName": "update-banner.jpg",
    "fileType": "image/jpeg",
    "base64Data": "data:image/jpeg;base64,/9j/4AAQ..."
  }
}

Publication en Lot

{
  "ids": ["ann-001", "ann-002", "ann-003"],
  "action": "publish"
}

Recherche d'Annonces

{
  "page": 1,
  "limit": 20,
  "search": "maintenance",
  "status": "PUBLISHED",
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

---

🎯 Le module Announcements offre une gestion complète des annonces avec upload d'images, opérations en lot et recherche avancée pour une communication efficace avec les utilisateurs.