📢 Trade Announcements - Annonces utilisateur

Le module Announcements permet aux utilisateurs de consulter les annonces officielles importantes diffusées par l'administration.

🎯 Objectif

Diffuser des informations officielles importantes aux utilisateurs avec un système de ciblage et de gestion des statuts optimisé.

✨ Fonctionnalités principales

• Annonces officielles : Communications importantes de l'administration
• Support d'images : Illustrations pour les annonces
• Gestion des statuts : Brouillon, Publié, Archivé
• Ciblage : Possibilité de cibler par région ou type d'utilisateur
• Cache optimisé : Chargement rapide des annonces fréquemment consultées

📋 Types d'annonces typiques

• Nouvelles réglementations : Changements dans la législation transport
• Maintenance programmée : Interruptions de service planifiées
• Événements importants : Conférences, formations, salons
• Mises à jour du service : Nouvelles fonctionnalités, améliorations

🔌 Endpoints disponibles

Lister les annonces

GET /trade/announcements?page=1&limit=10&categoryId=1&status=PUBLISHED

Paramètres de requête :

• page : Numéro de page (défaut: 1)
• limit : Éléments par page (défaut: 10, max: 50)
• categoryId : Filtrer par catégorie
• status : Filtrer par statut (PUBLISHED uniquement pour les utilisateurs)
• priority : Filtrer par priorité (HIGH, MEDIUM, LOW)
• search : Recherche textuelle dans titre/contenu
• startDate : Date de début de publication
• endDate : Date de fin de publication

Réponse :

{
  "success": true,
  "message": "Liste des annonces",
  "result": {
    "meta": {
      "total": 25,
      "total_pages": 3,
      "current_page": 1,
      "limit": 10
    },
    "data": [
      {
        "id": 123,
        "publicId": "announcement-abc-123",
        "title": "Nouvelle réglementation transport 2025",
        "summary": "Mise à jour des règles de transport de marchandises",
        "content": "À partir du 1er janvier 2025, de nouvelles règles...",
        "status": "PUBLISHED",
        "priority": "HIGH",
        "category": {
          "id": 1,
          "name": "Réglementation",
          "color": "#dc3545",
          "icon": "⚖️"
        },
        "featuredImage": {
          "url": "/uploads/announcements/regulation-2025.jpg",
          "alt": "Nouvelle réglementation 2025"
        },
        "author": {
          "id": 456,
          "firstName": "Admin",
          "lastName": "OFR",
          "role": "ADMINISTRATOR"
        },
        "viewsCount": 1250,
        "likesCount": 89,
        "publishedAt": "2025-01-01T00:00:00Z",
        "expiresAt": "2025-12-31T23:59:59Z",
        "createdAt": "2024-12-15T10:00:00Z"
      },
      {
        "id": 124,
        "title": "Maintenance programmée - 25 juillet",
        "summary": "Interruption de service prévue pour maintenance",
        "status": "PUBLISHED",
        "priority": "MEDIUM",
        "category": {
          "id": 2,
          "name": "Maintenance",
          "color": "#ffc107",
          "icon": "🔧"
        },
        "publishedAt": "2025-07-20T08:00:00Z",
        "expiresAt": "2025-07-26T00:00:00Z",
        "createdAt": "2025-07-19T15:30:00Z"
      }
    ]
  }
}

Détail d'une annonce

GET /trade/announcements/{id}

Réponse :

{
  "success": true,
  "message": "Détail de l'annonce",
  "result": {
    "id": 123,
    "publicId": "announcement-abc-123",
    "title": "Nouvelle réglementation transport 2025",
    "summary": "Mise à jour des règles de transport de marchandises",
    "content": "À partir du 1er janvier 2025, de nouvelles règles entrent en vigueur pour le transport de marchandises...\n\n## Points clés\n\n- Obligation de déclaration préalable\n- Nouveaux documents requis\n- Contrôles renforcés\n\n## Impact sur les transporteurs\n\nLes transporteurs devront s'adapter aux nouvelles exigences...",
    "status": "PUBLISHED",
    "priority": "HIGH",
    "category": {
      "id": 1,
      "name": "Réglementation",
      "description": "Annonces relatives à la réglementation",
      "color": "#dc3545",
      "icon": "⚖️"
    },
    "featuredImage": {
      "url": "/uploads/announcements/regulation-2025.jpg",
      "alt": "Nouvelle réglementation 2025",
      "width": 1200,
      "height": 630
    },
    "attachments": [
      {
        "id": 1,
        "filename": "reglement_transport_2025.pdf",
        "type": "application/pdf",
        "size": 2048576,
        "url": "/uploads/announcements/reglement_transport_2025.pdf",
        "description": "Texte complet de la réglementation"
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "réglementation",
        "color": "#007bff"
      },
      {
        "id": 2,
        "name": "transport",
        "color": "#28a745"
      }
    ],
    "author": {
      "id": 456,
      "firstName": "Admin",
      "lastName": "OFR",
      "role": "ADMINISTRATOR",
      "avatar": "/avatars/admin-ofr.jpg"
    },
    "targeting": {
      "userTypes": ["TRANSPORTER", "AGENT"],
      "regions": ["CENTRE", "LITTORAL"],
      "isGlobal": false
    },
    "statistics": {
      "viewsCount": 1250,
      "likesCount": 89,
      "sharesCount": 23,
      "commentsCount": 15
    },
    "publishedAt": "2025-01-01T00:00:00Z",
    "expiresAt": "2025-12-31T23:59:59Z",
    "createdAt": "2024-12-15T10:00:00Z",
    "updatedAt": "2024-12-20T14:30:00Z"
  }
}

Marquer comme lu

POST /trade/announcements/{id}/mark-read

Réponse :

{
  "success": true,
  "message": "Annonce marquée comme lue",
  "result": {
    "announcementId": 123,
    "userId": 789,
    "readAt": "2025-07-21T16:30:00Z"
  }
}

Liker une annonce

POST /trade/announcements/{id}/like

Paramètres :

{
  "action": "LIKE"
}

Actions possibles :

• LIKE : J'aime
• REMOVE : Supprimer le like

Réponse :

{
  "success": true,
  "message": "Like enregistré",
  "result": {
    "announcementId": 123,
    "action": "LIKE",
    "likesCount": 90,
    "userLiked": true
  }
}

Catégories d'annonces

GET /trade/announcements/categories

Réponse :

{
  "success": true,
  "message": "Catégories d'annonces",
  "result": [
    {
      "id": 1,
      "name": "Réglementation",
      "description": "Annonces relatives à la réglementation",
      "color": "#dc3545",
      "icon": "⚖️",
      "announcementsCount": 12,
      "isActive": true
    },
    {
      "id": 2,
      "name": "Maintenance",
      "description": "Informations de maintenance système",
      "color": "#ffc107",
      "icon": "🔧",
      "announcementsCount": 8,
      "isActive": true
    },
    {
      "id": 3,
      "name": "Événements",
      "description": "Événements et formations",
      "color": "#17a2b8",
      "icon": "📅",
      "announcementsCount": 5,
      "isActive": true
    }
  ]
}

Annonces importantes (non lues)

GET /trade/announcements/important?unread=true

Paramètres de requête :

• unread : Filtrer les annonces non lues (true/false)
• priority : Filtrer par priorité (HIGH uniquement par défaut)

Réponse :

{
  "success": true,
  "message": "Annonces importantes non lues",
  "result": {
    "count": 3,
    "announcements": [
      {
        "id": 123,
        "title": "Nouvelle réglementation transport 2025",
        "summary": "Mise à jour des règles de transport",
        "priority": "HIGH",
        "category": {
          "name": "Réglementation",
          "color": "#dc3545",
          "icon": "⚖️"
        },
        "publishedAt": "2025-01-01T00:00:00Z",
        "expiresAt": "2025-12-31T23:59:59Z"
      }
    ]
  }
}

📊 Statuts des annonces

Statut	Description	Visible par utilisateurs
DRAFT	Brouillon	❌ Non
PUBLISHED	Publié	✅ Oui
ARCHIVED	Archivé	❌ Non
EXPIRED	Expiré	❌ Non

🎯 Priorités des annonces

Priorité	Description	Affichage
HIGH	Haute priorité	Badge rouge, notification
MEDIUM	Priorité moyenne	Badge orange
LOW	Priorité basse	Badge gris

🔒 Règles d'accès

Visibilité

• Seules les annonces PUBLISHED sont visibles
• Les annonces expirées ne sont plus affichées
• Le ciblage par région/type d'utilisateur est respecté

Interactions

• Tous les utilisateurs authentifiés peuvent liker
• Le marquage comme "lu" est automatique lors de la consultation
• Les statistiques de vues sont mises à jour en temps réel

❌ Gestion des erreurs

Annonce non trouvée

{
  "success": false,
  "message": "Annonce non trouvée",
  "errors": {
    "code": "ANNOUNCEMENT_NOT_FOUND",
    "announcementId": 999
  }
}

Annonce expirée

{
  "success": false,
  "message": "Cette annonce a expiré",
  "errors": {
    "code": "ANNOUNCEMENT_EXPIRED",
    "announcementId": 123,
    "expiresAt": "2025-07-20T23:59:59Z"
  }
}

Accès non autorisé

{
  "success": false,
  "message": "Vous n'êtes pas autorisé à voir cette annonce",
  "errors": {
    "code": "ACCESS_DENIED",
    "reason": "Annonce ciblée pour d'autres types d'utilisateurs"
  }
}

Like déjà existant

{
  "success": false,
  "message": "Vous avez déjà liké cette annonce",
  "errors": {
    "code": "LIKE_ALREADY_EXISTS",
    "announcementId": 123
  }
}

🚀 Optimisations

Cache

• Listes d'annonces : Cache de 10 minutes
• Détails d'annonce : Cache de 30 minutes
• Catégories : Cache de 1 heure
• Invalidation automatique lors des mises à jour

Performance

• Images optimisées : Compression automatique
• Pagination : Limitation à 50 éléments maximum
• Chargement différé : Images et pièces jointes
• CDN : Distribution des médias

---

Prochaine section : Tutoriels Trade