Admin Data Ops (Quality + Audit)

Este documento descreve os endpoints e padrões principais do “Data Ops pack” para o portal admin:

• Rádio 360º (hub por rádio)
• Programs Quality / Dedup
• Schedules Quality
• Audit Log (obrigatório)

Portal Admin (rotas)

• /radios/:id — Rádio 360º (tabs: Identity / Streams / Scraping / Relations)
• /programs/quality — Duplicados + inválidos (guardrails preview/confirm)
• /schedules/quality — Issues de schedule + normalise + bulk retry (guardrails)
• /audit — Audit Log com filtros/paginação

API (endpoints)

Rádio 360º

• GET /admin/radios/:id
• GET /admin/radios/:id/relations
• GET /admin/radios/:id/icy-history?limit=50

Nota: o portal reutiliza endpoints existentes de scraping para operações “rápidas”:

• PATCH /admin/scraping/radios/:id (update schedule URL)
• POST /admin/scraping/radios/:id/retry (retry scraping)
• GET /admin/scraping/radios/:id/history (scraping history)

Programs Quality / Dedup

• GET /admin/programs/quality?radioId=<ObjectId>
• POST /admin/programs/quality/merge
• POST /admin/programs/quality/delete-duplicates
• POST /admin/programs/quality/auto-fix

Body (merge/delete):

• canonicalId: string
• duplicateIds: string[]
• dryRun: boolean
• confirm?: boolean

Body (auto-fix):

• radioId?: string (opcional; quando presente, só afeta essa rádio)
• dryRun: boolean
• confirm?: boolean

Notas (auto-fix):

• Seleciona canonical por time-slot mais comum (start_time|end_time) em cada grupo duplicado.
• Só executa quando existe uma maioria clara (count >= 2 e sem empate no topo); caso contrário, o grupo é marcado como skipped no preview.
• Execução (dryRun=false) requer confirm=true.

Schedules Quality

• GET /admin/schedules/quality?radioId=<ObjectId>&source=<string>
• POST /admin/schedules/quality/normalise
• POST /admin/schedules/quality/retry-scraping-bulk

Body (normalise):

• radioId: string
• source?: string
• dryRun: boolean
• confirm?: boolean

Body (retry-scraping-bulk):

• radioIds: string[]
• dryRun: boolean
• confirm?: boolean

Audit Log

• GET /admin/audit?limit=50&offset=0&action=...&entityType=...&entityId=...&actorEmail=...
• GET /admin/audit/me

Guardrails (padrão)

• Preview: dryRun=true

  • Não aplica alterações
  • Retorna um summary (ex.: affected, canExecute, warnings)
  • Regista no Audit Log

• Execução: dryRun=false requer confirm=true

  • Aplica alterações
  • Regista novamente no Audit Log com ação *.execute

• Bulk retry: cap de 50 rádios no backend (retry-scraping-bulk).

Audit result: warnings

O schema de audit guarda warnings como string[] (mensagens). Quando existem warnings estruturados (ex.: overlaps de schedule), a API devolve também warningsDetail para debug.