Reports & Cross-Module Correlation

Reports & Cross-Module Correlation ist Rankions Konsolidierungs-Layer. Statt drei Tabs offen zu halten und zwischen AVI-Tracking, Site-Audit und Backlinks-Analyse hin- und herzuspringen, dispatched dieses Modul einen Job, der einen narrativen Markdown-Report über alle relevanten Module eines Tracking-Projects erzeugt — Executive Summary, KPI-Highlights, Wins, Risks. Plus: ein synchroner Korrelations-Endpoint, der Site-Audit × Rank-Tracker × Backlinks × AVI in einem Roundtrip zu Risk-Map, Backlink-AVI-Korrelation und Smart-Todos verknüpft.

Was es kann

• Auto-Generated Reports — GenerateTrackingProjectReportJob bündelt alle Project-Daten zu einem Markdown-Dokument inklusive summary_json mit Headline-KPIs, Wins, Risks.
• Markdown-Export — der markdown_content ist direkt verwendbar in Notion, GitHub, E-Mail oder als Vorstufe für PDF.
• Report-History — pro Project bis zu 50 letzte Reports, sortiert nach created_at.
• Cross-Module-Korrelation — Risk-Map (welche Top-10-Keywords haben kritische Site-Audit-Issues?), Backlink-Velocity × AVI-Trend (Pearson-Korrelation, 30-Tage-Fenster), Smart-Todos mit priority_score.
• Smart-Todos — priorisierte Action-Items mit Begründung, Reference-IDs und Impact-Schätzung — direkt umsetzbar.

Wann nutzen

• Wöchentliches/monatliches Stakeholder-Update — der Report ist als Standalone-Dokument lesbar.
• Du willst wissen welche deiner rankenden URLs Site-Audit-Issues haben (Risk-Map).
• Du willst statistisch belegen ob deine Backlink-Aktivität tatsächlich AVI bewegt — die Pearson-Korrelation gibt dir den Koeffizienten plus Beobachtung.
• Du brauchst eine priorisierte Todo-Liste die Cross-Module argumentiert ist, statt 4 Modul-Tabs einzeln zu sichten.

Workflow

Reports sind asynchron — Pattern wie alle Long-Running-Jobs in Rankion: Dispatch, Pollen, Konsumieren.

1. Report dispatchen — POST /tracking-projects/{id}/generate-report. Antwort: 202 mit report_id und status: "pending". Rate-Limit: 1 Request / 30 Min / Project.
2. Pollen bis completed — GET /reports/{id} alle 5 Sekunden, bis status von pending → generating → completed (oder failed).
3. Markdown extrahieren — markdown_content aus dem Detail-Response. Direkt in Notion paste-bar oder per pandoc zu 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

Cross-Module-Korrelation läuft synchron — kein Polling.

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

API

Response — GET /reports/{id} (gekürzt).

{
  "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"
}

Korrelations-Response liefert drei Blöcke: site_audit_ranking_risks[] (Top-Ranking-URLs mit Site-Audit-Issues, sortiert nach risk_score), backlinks_av_correlation (Pearson-Koeffizient mit observation-Text), smart_todos[] (priorisierte Action-Items mit priority_score, Reference-IDs).

Credits & Limits

• Report-Generierung: 10 Credits pro Run (POST /tracking-projects/{id}/generate-report).
• Rate-Limit: 1 Report / 30 Minuten pro Project. 429 mit {error: "rate_limited"} bei Verstoß.
• Korrelation: kostenfrei, synchron, keine Limits außer Standard-Auth-Throttle.
• Status-Codes: 202 (Dispatch), 200 (List/Detail/Correlation), 403 (Cross-Team / Cross-Project), 404 (Report/Project nicht gefunden), 429 (Rate-Limit).
• Datenquellen: Report aggregiert über alle aktiven Module des Projects — Werte sind so aktuell wie der letzte Tracking-Run / Audit / Backlink-Pull.

Verwandte Module

• AI-Visibility Tracking — liefert AVI-Score und Delta-30d für die Headline-KPIs.
• Content Audit — liefert Site-Audit-Issues für die Risk-Map.
• Competitor & Backlinks Analyse — liefert Backlink-Velocity für die Korrelations-Berechnung.
• Agentic Chat — kann Reports per Frage dispatchen und Smart-Todos in Action-Items umwandeln.