server/docs/features/podcast_statistikk.md

Feature Spec: Podcast-Statistikk

Filsti: docs/features/podcast_statistikk.md

1. Konsept

IAB-kompatibel lytterstatistikk bygget fra bunnen av. Vi fanger all rådata via Caddy, og bruker asynkron batch-prosessering for å bygge grafer og tall uten å belaste webserveren eller databasen med sanntids-skriving.

2. Arkitektur & Dataflyt

1. Rådata (Caddy): Caddy konfigureres til å skrive access-logs for stien /media/podcast/*.mp3 til en formatert JSON-fil (f.eks. /srv/sidelinja/logs/caddy/podcast_access.log).
2. Logrotate: Standard Linux logrotate arkiverer loggene nattlig.
3. Rust Batch Processor (Jobbkø): Statistikkparseren kjøres som en stats_parse-jobb i den felles jobbkøen (se docs/features/jobbkø.md), med scheduled_for satt 1 time frem for periodisk kjøring. Workeren re-enqueuer seg selv ved fullføring.
   • Steg A (Filtrering): Leser JSON-loggen. Fjerner treff fra kjente bots ved å krysjekke User-Agent mot OPAWG (Open Podcast Analytics Working Group) sine åpne bot-lister.
   • Steg B (Deduplisering): Slår sammen byte-range forespørsler. Hvis samme IP og User-Agent har lastet ned deler av samme fil innenfor et 24-timers vindu, telles det som KUN én (1) nedlasting.
   • Steg C (Geografi/Klient): Mapper User-Agent til Podcast-klient (Spotify, Apple) basert på OPAWG-regler.
4. Lagring (PostgreSQL): Rust-programmet skriver det aggregerte resultatet inn i PostgreSQL (episode_stats tabell med felter for date, episode_id, client_name, unique_downloads).

3. Instruks for Claude Code

• Bruk Rust-biblioteket serde_json for rask parsing av Caddy-loggene.
• Dette programmet må skrives robust med tanke på at filer kan være låst av Caddy. Det bør tåle å avbrytes, og må holde styr på hvilken linje i loggfilen det prosesserte sist (f.eks. via en liten cursor-fil).
• Rålogger skal ALDRI lagres i PostgreSQL.