Reports & Cross-Module Correlation

Reports & Cross-Module Correlation es la capa de consolidación de Rankion. En lugar de tener tres pestañas abiertas y saltar entre AVI-Tracking, Site-Audit y análisis de Backlinks, este módulo dispatchea un job que genera un documento Markdown narrativo sobre todos los módulos relevantes de un Tracking-Project — Executive Summary, KPI highlights, wins, risks. Plus: un endpoint síncrono de correlación que conecta Site-Audit × Rank-Tracker × Backlinks × AVI en un solo roundtrip generando Risk-Map, correlación Backlink-AVI y Smart-Todos.

Qué puede hacer

• Documentos auto-generados — GenerateTrackingProjectReportJob agrupa todos los datos del proyecto en un documento Markdown con summary_json con headline-KPIs, wins y risks.
• Exportación Markdown — el markdown_content se usa directamente en Notion, GitHub, email o como paso previo a PDF.
• Histórico — por proyecto hasta los 50 últimos documentos, ordenados por created_at.
• Correlación cross-módulo — Risk-Map (¿qué top-10 keywords tienen issues críticos del Site-Audit?), Backlink-Velocity × AVI-Trend (correlación de Pearson, ventana de 30 días), Smart-Todos con priority_score.
• Smart-Todos — action-items priorizados con justificación, reference-IDs y estimación de impacto — directamente accionables.

Cuándo usarlo

• Update semanal/mensual a stakeholders — el documento se lee como contenido standalone.
• Quieres saber qué URLs en posicionamiento tienen issues del Site-Audit (Risk-Map).
• Quieres demostrar estadísticamente si tu actividad de backlinks mueve realmente el AVI — la correlación de Pearson te da el coeficiente más una observación.
• Necesitas una lista priorizada de todos argumentada cross-module, en lugar de revisar 4 pestañas de módulo individuales.

Workflow

El flujo es asíncrono — patrón como todos los long-running jobs en Rankion: dispatch, polling, consumir.

1. Dispatchea — POST /tracking-projects/{id}/generate-report. Respuesta: 202 con report_id y status: "pending". Rate-limit: 1 request / 30 min / proyecto.
2. Polling hasta completed — GET /reports/{id} cada 5 segundos hasta que status pase de pending → generating → completed (o failed).
3. Extrae el markdown — markdown_content del detail-response. Pegable directamente en Notion o convertible a PDF con pandoc.

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 correlación cross-módulo corre síncrona — sin polling.

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

API

Response — GET /reports/{id} (recortado).

{
  "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 response de correlación entrega tres bloques: site_audit_ranking_risks[] (top-ranking-URLs con issues del Site-Audit, ordenadas por risk_score), backlinks_av_correlation (coeficiente Pearson con texto de observation), smart_todos[] (action-items priorizados con priority_score, reference-IDs).

Créditos y límites

• Generación: 10 créditos por run (POST /tracking-projects/{id}/generate-report).
• Rate-limit: 1 ejecución / 30 minutos por proyecto. 429 con {error: "rate_limited"} ante violación.
• Correlación: sin coste, síncrona, sin límites más allá del throttle estándar de auth.
• Status codes: 202 (dispatch), 200 (list/detail/correlation), 403 (cross-team / cross-project), 404 (no encontrado), 429 (rate-limit).
• Fuentes de datos: la salida agrega sobre todos los módulos activos del proyecto — los valores son tan recientes como el último tracking-run / audit / backlink-pull.

Módulos relacionados

• AI-Visibility Tracking — entrega el AVI-Score y delta-30d para las headline-KPIs.
• Content Audit — entrega los issues del Site-Audit para la Risk-Map.
• Competitor & Backlinks Analysis — entrega la backlink-velocity para el cálculo de correlación.
• Agentic Chat — puede dispatchear este flujo por pregunta y convertir Smart-Todos en action-items.