API Publications

Objectif

Créer, lire, modifier, modérer et signaler les publications locales DMV.

Périmètre

Mur local, publications acteur, publications commune, types de publications, modération et signalements.

Acteurs/applications consommatrices

• DMV public.
• Backoffice.
• Mairie.
• AssoSuite selon flux spécifique.
• PlayLoop comme consommateur indirect cible.

Authentification requise

• Lecture publique avec X-App-Source.
• Écriture et modération avec auth:sanctum.
• Signalement public visible sans auth dans le code, avec X-App-Source.

Permissions/RBAC

• Droits de publication selon utilisateur, acteur, commune et app source.
• Modération globale réservée à DMV/backoffice.
• Mairie limitée à ses propres contenus et supervision locale encadrée.

Règles serveur actuellement appliquées

• modification contenu publication → manage_publications
• suppression publication → manage_publications
• action d’épinglage (epingle) → publish_publications
• si une mutation combine contenu + épinglage, les deux permissions sont requises
• owner et platform_admin restent autorisés via le resolver central

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
GET	/api/v1/publications/types	Confirmé.
GET	/api/v1/publications	Confirmé.
GET	/api/v1/publications/{id}	Confirmé.
GET	/api/v1/acteurs/{acteurId}/publications	Confirmé.
GET	/api/v1/communes/{communeId}/publications	Confirmé.
POST	/api/v1/publications	Confirmé, authentifié.
PATCH	/api/v1/publications/{id}	Confirmé, authentifié.
DELETE	/api/v1/publications/{id}	Confirmé, authentifié.
PATCH	/api/v1/publications/{id}/moderate	Confirmé, authentifié.
POST	/api/v1/publications/{id}/report	Confirmé.
GET	/api/v1/admin/publications	Confirmé admin/backoffice.
PATCH	/api/v1/admin/publications/bulk/moderate	Confirmé admin/backoffice.
PATCH	/api/v1/admin/publications/{id}/moderate	Confirmé admin/backoffice.
PATCH	/api/v1/admin/publications/{id}/valide	Confirmé admin/backoffice.
PATCH	/api/v1/admin/publications/{id}/feature	Confirmé admin/backoffice.
DELETE	/api/v1/admin/publications/{id}	Confirmé admin/backoffice, soft-delete.
PATCH	/api/v1/admin/publications/{id}/restore	Confirmé admin/backoffice.
GET	/api/v1/mairie/acteurs/{acteurId}/publications	Confirmé mairie.
POST	/api/v1/mairie/acteurs/{acteurId}/publications	Confirmé mairie.
PATCH	/api/v1/mairie/acteurs/{acteurId}/publications/{publicationId}/moderate	Confirmé mairie.

Endpoints cibles proposés si utile

• Endpoint de transformation publication vers PlayLoop à définir si nécessaire.
• Endpoint de brouillons à confirmer.

Exemple de requête

POST /api/v1/publications
Authorization: Bearer <token>
X-App-Source: dmv
Content-Type: application/json

{
  "title": "Titre local",
  "body": "Contenu de la publication",
  "acteur_id": "acteur-id",
  "commune_id": "commune-id"
}

Exemple de réponse succès

{
  "data": {
    "id": "publication-id",
    "status": "published",
    "title": "Titre local"
  }
}

Exemple d’erreur

{
  "error": "scope_violation",
  "message": "Vous ne pouvez pas publier dans ce périmètre."
}

Pagination si applicable

Applicable aux listes de publications.

Pour la liste admin /api/v1/admin/publications, le backend accepte page, per_page, sort, q, commune_id, acteur_id, type_id, moderation_status, valide, deleted et duplicates.

Le backoffice utilise actuellement :

GET /api/v1/admin/publications?page=1&per_page=10&sort=created_at_desc

Réponse attendue :

{
  "data": [],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 10,
    "total": 0
  }
}

Le backoffice ouvre par défaut la vue sur les publications pending, triées par created_at_desc, avec per_page=10.

Mise en avant admin

L'endpoint PATCH /api/v1/admin/publications/{id}/feature pilote :

• en_avant : booléen de mise en avant
• featured_until : date/heure de fin optionnelle ; remise à null si en_avant=false

Recherche de doublons

La vue admin peut appeler :

GET /api/v1/admin/publications?duplicates=true&per_page=10&sort=created_at_desc
Authorization: Bearer <admin-token>
X-App-Source: backoffice

Le backend groupe les doublons potentiels via deux stratégies :

• source_url normalisée lorsqu'elle est présente
• signature normalisée acteur_id + type_id + titre + date_debut + contenu

Chaque ligne renvoyée peut inclure duplicate_key, duplicate_reason et duplicate_count.

Règle de visibilité : publie_le obligatoire

Une publication n'apparaît sur aucun frontend tant que publie_le IS NULL, quelle que soit sa valeur de valide ou moderation_status.

Champ	Valeur attendue pour être visible
valide	true
moderation_status	approved ou published
publie_le	non nul et ≤ maintenant
deleted_at	nul

À la création par import : publie_le est défini à now() uniquement si moderation_status = 'published'. Si le statut est 'pending' (ex. import sans acteur configuré), publie_le reste null et la publication est invisible.

À la validation manuelle (moderate, toggleValide, bulkModerate) : publie_le est défini à now() si la publication passe à published et que le champ est encore null. Correction appliquée le 2026-06-26 — avant cette date, la validation manuelle laissait publie_le = null et rendait les publications invisibles malgré leur statut correct.

Rate limiting si applicable

Recommandé sur création, signalement et modération.

Audit/logs si applicable

Obligatoire pour création sensible, suppression, modération et signalement.

Sécurité

• Les statuts de modération sont décidés côté Laravel.
• L’IA peut assister mais ne publie pas seule un contenu sensible.
• Les contenus publics doivent être filtrés par scope.
• Les routes admin publications restent protégées par identify.app, auth:sanctum et ensure.admin.

État actuel vs cible

Sujet	État actuel	Cible
Routes publication	Confirmées, y compris listing admin dédié.	Contrat unifié avec statuts documentés.
Scope app	Commentaires code indiquent filtrage par X-App-Source.	Règles de scope explicites.
Permissions de mutation	Distinction serveur entre édition et épinglage en place.	Couvrir explicitement tous les cas de publication avancés si le workflow s’enrichit.
Rattachement commune	Les publications peuvent être rattachées via publication_communes.	Documenter plus finement les cas multi-communes côté lecture/admin.

Points à confirmer

• Statuts définitifs.
• Payloads exacts.
• Règles de brouillon.
• Interaction PlayLoop et IA.