# Rapport — Correction JSON-LD et carrousel de la page d'accueil
Date de rédaction : 22 juillet 2026.
## 1. Cause exacte du JSON-LD visible en haut de page
**Cause racine** : `resources/views/components/layout.blade.php` affichait la variable
`$structuredData` avec la syntaxe Blade `{{ $structuredData ?? '' }}` — cette syntaxe appelle
automatiquement `htmlspecialchars()` sur son contenu. Or `$structuredData`, construite dans
`home.blade.php`, était déjà une **chaîne HTML complète** (`''`). L'échappement automatique transformait donc `
@endif
```
### Validation
- Le JSON extrait du HTML servi par `http://tlt.test/` parse sans erreur avec `json_decode()`.
- Aucune séquence `é` n'apparaît dans la sortie ; les caractères accentués sont littéraux.
- Le début du `` (avant le ``) ne contient plus aucune trace de
`application/ld+json` ou `@context` — testé automatiquement (voir §6).
## 2. Modèle de données du carrousel
Nouveaux champs sur `media_items` (migration
`add_hero_carousel_fields_to_media_items_table`) :
| Champ | Rôle |
|---|---|
| `hero_candidate` (déjà existant) | Suggestion technique automatique (générée par `media:scan`) |
| `hero_active` | Sélection éditoriale réelle — l'image apparaît dans le carrousel du site |
| `hero_position` | Ordre d'affichage dans le carrousel |
| `hero_title` | Titre optionnel de la diapositive |
| `hero_caption` | Légende discrète optionnelle affichée en bas de l'image |
| `hero_focal_x` / `hero_focal_y` | Point focal (0-100), converti en `object-position` CSS |
Limite configurable : `config('media.hero_limit')` (variable d'environnement
`MEDIA_HERO_LIMIT`, par défaut **6**).
## 3. Sélection initiale des images
Quatre images ont été choisies à la main dans la médiathèque existante (voir
`database/seeders/HeroSeeder.php`), pour raconter le parcours dans l'ordre demandé :
| Ordre | Image | Titre | Légende | Justification |
|---|---|---|---|---|
| 1 | `img-05109` (`TLT_2025_web.jpg`) | Une voix pour Kinshasa | Responsabilités institutionnelles | Portrait institutionnel récent (2025), haute résolution, drapeau RDC, déjà utilisé comme portrait de référence |
| 2 | `img-00229` (`Le Bourgmestre au travail/20160419_110225...`) | Sur le terrain | Engagement sur le terrain | Action de terrain authentique (coordination avec la police lors de travaux), visage clairement identifiable, format paysage natif |
| 3 | `img-05161` (`tenge_images/WhatsApp...15.29.34.jpeg`) | Proche des habitants | Au contact de la population | Proximité directe avec une habitante, écharpe « Député Provincial Kintambo N°4 », déjà retouchée dans la médiathèque |
| 4 | `img-05144` (`tenge_images/WhatsApp...15.29.30.jpeg`) | Porter une vision | Une vision pour la ville | Intervention médiatique (« Le Débat », Top Congo FM), cadrage frontal net, activité publique/officielle |
Critères appliqués : personne clairement identifiable et non floue, diversité des contextes
(portrait / terrain / proximité / média), bonne résolution, cadrage exploitable en paysage,
absence de doublons entre les quatre choix. Un administrateur peut changer cette sélection à tout
moment depuis `/admin/media/hero` — cette sélection initiale n'est qu'un point de départ.
## 4. Interface d'administration — `/admin/media/hero`
Page dédiée « Carrousel de la page d'accueil », accessible depuis le menu admin (nouvel élément
entre « Ajouter des photos » et « Albums »). Fonctionnalités :
- Liste des images actives, dans l'ordre du carrousel réel du site.
- Réorganisation par glisser-déposer (JavaScript natif, sauvegarde immédiate via `fetch`).
- Modification du titre, de la légende et du **point focal** par simple clic sur l'aperçu (un
marqueur visuel indique le point focal actuel, converti en `object-position` sur le site public).
- Retrait du carrousel sans suppression de l'image (reste dans la médiathèque).
- Ajout de nouvelles images depuis une grille de candidates (images publiées, non déjà actives,
triées en priorité par `hero_candidate`/`featured`/résolution), avec recherche.
- Limite configurable affichée en permanence (« X / 6 images actives ») ; tentative d'ajout au-delà
de la limite bloquée avec message clair.
- Lien direct « Voir la page d'accueil ↗ » pour prévisualiser le rendu réel après chaque
changement (les actions s'appliquent immédiatement, pas de brouillon séparé).
### Routes ajoutées
```
GET /admin/media/hero admin.media.hero
POST /admin/media/hero/reorder admin.media.hero.reorder
POST /admin/media/hero/{media}/add admin.media.hero.add
DELETE /admin/media/hero/{media} admin.media.hero.remove
PUT /admin/media/hero/{media} admin.media.hero.update
```
## 5. Carrousel public (page d'accueil)
Remplace l'unique image de fond du hero par une composition **texte à gauche / carrousel à
droite** (conservée en une seule colonne empilée sur mobile). Implémentation en JavaScript léger
natif (aucune librairie ajoutée), dans `resources/js/app.js` :
- Défilement automatique toutes les 6,5 secondes, en pause au survol de la souris **et** au focus
clavier.
- Flèches précédent/suivant et indicateurs de position (`role="tablist"`), tous avec libellés
accessibles (`aria-label`).
- Navigation clavier (flèches gauche/droite) lorsque le carrousel a le focus (`tabindex="0"`,
`role="region"`, `aria-roledescription="carrousel"`).
- Gestes tactiles (balayage) sur mobile.
- Respect de `prefers-reduced-motion` : le défilement automatique est désactivé, les contrôles
manuels restent utilisables.
- **Fallback sans JavaScript** : chaque diapositive est positionnée en absolu avec opacité
0/100 gérée en CSS ; sans script, la première image reste visible normalement (aucun script
requis pour afficher un hero fonctionnel), sans saut de mise en page.
- Première image en `loading="eager"` + `fetchpriority="high"`, les suivantes en
`loading="lazy"` — cohérent avec la demande de chargement rapide et priorisé.
- Chaque image expose `width`/`height` réels (évite tout saut de mise en page/CLS) et un texte
alternatif basé sur `hero_title` ou, à défaut, le texte alternatif existant de la photo.
## 6. Protection et robustesse
- **Dépendance suivie** : `MediaItem::usageSummary()` inclut désormais `Carrousel accueil`.
Une image encore active dans le carrousel **ne peut pas être supprimée définitivement** sans
cocher « Retirer les associations », qui vide alors proprement `hero_active`/`hero_position`
avant suppression (testé, voir §7).
- **Dépublication** : reste possible, mais un message de confirmation JavaScript avertit
explicitement l'administrateur que l'image sortira du carrousel affiché aux visiteurs tant
qu'elle n'est pas republiée.
- **Corbeille** : le retrait logique (soft delete) exclut automatiquement l'image de
`MediaItem::scopeHeroActive()` (la portée `published()` et le scope global des éléments
supprimés l'excluent tous les deux) — la page d'accueil ne casse jamais.
- **Image manquante** : `HomeController` filtre les images actives dont la variante `large` n'existe
plus sur le disque avant de les transmettre à la vue ; si aucune image active n'est finalement
disponible, une image de secours est utilisée automatiquement (portrait par défaut ou première
candidate hero disponible).
- **Badges dans la médiathèque** : un badge distinct « Dans le carrousel » (grille et vue tableau)
différencie clairement une image *active* d'une simple *candidate hero* (« Candidate hero »),
conformément à la demande de ne pas se contenter d'une case à cocher unique.
## 7. Tests exécutés et résultats
```
php artisan test
56 tests, 154 assertions — 56 passed, 0 failed
```
14 nouveaux tests dédiés ([tests/Feature/HeroCarouselTest.php](../tests/Feature/HeroCarouselTest.php)) :
JSON-LD non affiché comme texte visible, JSON-LD présent et valide, absence de séquences unicode
échappées, la page d'accueil affiche au moins 4 images actives, seules les images publiées sont
utilisées, l'ordre du carrousel respecte `hero_position`, une image de secours est utilisée en
l'absence de sélection, une variante manquante est ignorée sans casser la page, ajout/retrait
depuis l'admin, respect de la limite configurée, changement de position (réorganisation),
modification du titre/légende/point focal, permissions (accès admin requis), protection contre la
suppression définitive d'une image encore active dans le carrousel (avec levée contrôlée après
retrait des associations).
Les tests écrivent dans un dossier d'archives temporaire isolé (comme pour la médiathèque) : **le
dossier `images/` réel n'a pas été touché** (vérifié après coup : toujours 5 333 fichiers).
### Vérification manuelle sur `http://tlt.test`
- Le JSON `