Reports & Cross-Module Correlation

Reports & Cross-Module Correlation est la couche de consolidation de Rankion. Au lieu de garder trois onglets ouverts et de basculer entre AVI Tracking, Site Audit et analyse de backlinks, ce module dispatch un job qui génère un document Markdown narratif sur tous les modules pertinents d'un tracking project — executive summary, KPI highlights, wins, risks. Plus : un endpoint de corrélation synchrone qui lie Site Audit × Rank Tracker × Backlinks × AVI en un round-trip vers risk map, corrélation backlink-AVI et smart todos.

Ce qu'il peut faire

• Documents auto-générés — GenerateTrackingProjectReportJob regroupe toutes les données du projet dans un document Markdown incluant summary_json avec headline KPIs, wins, risks.
• Export Markdown — le markdown_content est directement utilisable dans Notion, GitHub, e-mail ou comme étape préalable au PDF.
• Historique — par projet jusqu'aux 50 derniers documents, triés par created_at.
• Corrélation cross-module — risk map (quels top-10 mots-clés ont des issues critiques de Site Audit ?), Backlink Velocity × tendance AVI (corrélation Pearson, fenêtre 30 jours), smart todos avec priority_score.
• Smart todos — action items priorisés avec justification, reference IDs et estimation d'impact — directement actionnables.

Quand l'utiliser

• Update stakeholder hebdomadaire/mensuel — le document est lisible comme standalone.
• Tu veux savoir lesquelles de tes URLs en ranking ont des issues de Site Audit (risk map).
• Tu veux prouver statistiquement si ton activité de backlink bouge effectivement l'AVI — la corrélation Pearson te donne le coefficient plus une observation.
• Tu as besoin d'une todo list priorisée argumentée cross-module, plutôt que d'examiner 4 onglets de modules individuellement.

Workflow

Les documents sont asynchrones — pattern comme tous les long-running jobs dans Rankion : dispatch, poller, consommer.

1. Dispatcher le document — POST /tracking-projects/{id}/generate-report. Réponse : 202 avec report_id et status: "pending". Rate-limit : 1 requête / 30 min / projet.
2. Poller jusqu'à completed — GET /reports/{id} toutes les 5 secondes, jusqu'à ce que status passe de pending → generating → completed (ou failed).
3. Extraire le Markdown — markdown_content depuis la réponse de détail. Directement collable dans Notion ou via pandoc vers PDF.

RID=$(curl -s -X POST $BASE/tracking-projects/$PID/generate-report \
  -H "Authorization: Bearer $TOKEN" | jq -r '.report_id')

while true; do
  S=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID | jq -r '.status')
  [ "$S" = completed ] && break
  [ "$S" = failed ] && exit 1
  sleep 5
done

curl -s -H "Authorization: Bearer $TOKEN" $BASE/reports/$RID \
  | jq -r '.markdown_content' > report.md

La corrélation cross-module tourne synchrone — pas de polling.

curl "$BASE/tracking-projects/$PID/correlation" \
  -H "Authorization: Bearer $TOKEN"

API

Réponse — GET /reports/{id} (raccourci).

{
  "id": 42,
  "tracking_project_id": 7,
  "status": "completed",
  "markdown_content": "# Tracking-Report Project XY\n\n## Executive Summary\n…",
  "summary_json": {
    "headline_kpis": { "avi_score": 64, "delta_30d": "+8", "top10_keywords": 14 },
    "wins": ["…"],
    "risks": ["…"]
  },
  "credits_used": 10,
  "generated_at": "2026-04-27T18:14:22+00:00"
}

La réponse de corrélation livre trois blocs : site_audit_ranking_risks[] (top URLs en ranking avec issues Site Audit, triés par risk_score), backlinks_av_correlation (coefficient Pearson avec texte d'observation), smart_todos[] (action items priorisés avec priority_score, reference IDs).

Crédits et limites

• Génération : 10 crédits par run (POST /tracking-projects/{id}/generate-report).
• Rate-limit : 1 / 30 minutes par projet. 429 avec {error: "rate_limited"} en cas de violation.
• Corrélation : gratuite, synchrone, pas de limites au-delà du throttle d'auth standard.
• Status codes : 202 (dispatch), 200 (list/detail/correlation), 403 (cross-team / cross-project), 404 (non trouvé), 429 (rate-limit).
• Sources de données : agrégation sur tous les modules actifs du projet — les valeurs sont aussi à jour que le dernier tracking-run / audit / backlink pull.

Modules associés

• AI-Visibility Tracking — livre score AVI et delta-30d pour les headline KPIs.
• Content Audit — livre les issues Site Audit pour la risk map.
• Competitor & Backlinks Analyse — livre la velocity backlink pour le calcul de corrélation.
• Agentic Chat — peut dispatcher des documents par question et transformer les smart todos en action items.