Site Audit (Crawler + LLM Citation Readiness)

Site Audit crawle ton domaine (BFS ou via sitemap.xml), génère pour chaque URL trouvée un rapport d'issues (SEO technique + hygiène de contenu) et déclenche directement à la suite un batch de Grounding-Audit automatique sur jusqu'à 100 pages. Les findings sont injectés comme issues supplémentaires avec le préfixe grounding_* dans la même liste d'issues — une seule vue dashboard pour SEO technique + LLM-Citation-Readiness.

Ce qu'il permet

• Modes de crawl — bfs (découverte de liens depuis start_url, limité en profondeur) OU sitemap (charge toutes les URLs depuis sitemap.xml, de façon récursive y compris index de sitemap, ignore crawl_depth). Plafond strict : 10 000 seeds, max_pages appliqué.
• Classification des issues — triée par priorité de correction, filtrée par severity (critical|high|medium|low|notice), issue_type et status (open|fixed|dismissed). url chargée en eager-loading par issue.
• Pont Auto-Grounding — automatiquement après la fin du crawl : batch Grounding-Audit sur jusqu'à 100 pages → les findings arrivent comme issues grounding_* dans le même crawl. Aucun crédit supplémentaire. Idempotent (le re-run dédoublonne).
• Close-the-Loop — marquer les issues en un clic (UI) ou via l'API comme fixed/dismissed — individuellement OU en masse par issue_type. Étape obligatoire après chaque correction pour que la métrique de comparaison delta (« corrigé depuis le dernier crawl ») fonctionne correctement.
• AI-Brief (5 crédits par brief) — explication narrative LLM par issue en un clic.
• Horodatages du pont — bridge_dispatched_at (batch déclenché) et bridge_completed_at (toutes les issues grounding_* finalisées). Condition de polling déterministe au lieu d'attendre aveuglément 1-3 min.

Quand l'utiliser

• Bilan SEO technique à l'échelle du site.
• Vérifier la LLM-Citation-Readiness de tout le domaine sans 340× appels Single-Audit.
• Avant un relaunch : ce qu'il reste à retirer / corriger.
• Contrôle de santé mensuel pour les parties prenantes.

Workflow dans l'UI

1. Démarrage — formulaire sous /site-audit (start_url, max_pages, crawl_depth, crawl_mode, tracking_project_id optionnel).
2. Polling — la page de détail /site-audit/{crawl} affiche un compteur en direct (pages_crawled, total_issues). Auto-rafraîchissement.
3. Close-the-Loop — chaque issue a 2 boutons : ✓ Corrigé et ⊘ Rejeter. Au-dessus du tableau, une barre d'outils d'action en masse avec un dropdown « Choisir le type d'issue » + Marquer tout comme corrigé / Rejeter tout pour les corrections en masse après des changements de layout/template.
4. Re-crawl — une fois les critical+high résolus, un nouveau crawl → le bloc de tendance affiche « corrigé depuis le dernier crawl » / « nouveau depuis le dernier crawl ».

Workflow via l'API (appelant Skill)

Séquence obligatoire après correction :

# 1. Issues holen
ISSUES=$(curl -sH "Authorization: Bearer $TOKEN" \
    "$BASE/v1/site-audit/$CRAWL/issues?status=open&per_page=100" | jq '.data')

# 2. Pro Issue: Fix anwenden (Layout-Edit / Content-Update / Migration)

# 3. PFLICHT: Issue als fixed markieren — sonst weiß die Plattform nicht
#    dass die Arbeit done ist und die Delta-Metrik wird wertlos:
curl -X PATCH \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"status":"fixed"}' \
    "$BASE/v1/site-audit/issues/$ISSUE_ID"

# 4. Bei Layout-/Template-Fixes: Bulk-Mark statt 50× Single-PATCH:
curl -X PATCH \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"filter":{"issue_type":"missing_alt_text","status":"open"},"new_status":"fixed"}' \
    "$BASE/v1/site-audit/$CRAWL/issues/bulk"

Pattern de polling (déterministe depuis le 2026-05-14) :

while true; do
    R=$(curl -sH "Authorization: Bearer $TOKEN" "$BASE/v1/site-audit/$CRAWL" | jq '.data')
    STATUS=$(echo "$R" | jq -r .status)
    BRIDGE=$(echo "$R" | jq -r .bridge_completed_at)
    [ "$STATUS" = "completed" ] && [ "$BRIDGE" != "null" ] && break
    sleep 30
done
# → JETZT sind alle Issues final, auch die grounding_*

Anti-patterns

• Appliquer un fix sans PATCH /issues/{id} avec status=fixed → l'issue reste « open » dans le dashboard, la métrique de comparaison delta de la prochaine itération de crawl devient inutile.
• Récupérer les issues directement après status='completed' sans vérifier bridge_completed_at → les issues grounding_* manquent (le pont tourne encore).
• Marquage en masse sans filter.issue_type → marque des centaines d'issues non liées. Le serveur renvoie meta.applied_filter ; l'appelant DOIT le vérifier avant de passer à l'étape suivante.
• AI-Brief en boucle pour 100+ issues — 5 crédits par brief. Réserver aux éléments critiques sélectionnés.

Modules associés

• Content Audit (Site Crawl) — scanner de qualité de contenu (ce que dit la page, pas ce qu'elle a). Complémentaire.
• Grounding Audit — LLM-Citation-Readiness sur une seule URL. Appel direct sans surcharge de crawl.
• [[modules/page-audit]] — Conversion Audit par URL (Lighthouse + Vision + Persona-Fit). Plus granulaire, par URL.