Skip to main content

Sistema d’Importació i Enriquiment de Dades

Relacionat amb: Fase 4 del roadmap (4B–4E).
Objectiu: disposar d’un sistema robust per importar, revisar i publicar dades de balls/cançons procedents de fonts externes, sense trencar l’MVP actual.

1. Context i objectius​

1.1. Problema​

  • La informació de balls i cançons està dispersa:
    • portals de stepsheets,
    • webs de coreògrafs,
    • YouTube,
    • llistes pròpies en Excel/CSV,
    • altres webs especialitzades.
  • L’MVP actual permet fer CRUD manual, però això no escala per grans volums.

1.2. Objectius​

  • Poder importar dades des de:
    • portals externs (scraping o APIs),
    • fitxers CSV proporcionats per usuaris,
    • fonts diverses amb formats heterogenis.
  • Mantenir un pipeline controlat:
    1. Ingesta
    2. Parsing i normalització
    3. Validació i deduplicació
    4. Staging (revisió manual)
    5. Publicació a taules finals
  • Assegurar:
    • control de qualitat,
    • traçabilitat (origen de la dada),
    • evitar duplicats,
    • no sobreescriure dades bones amb dades pitjors.

2. Arquitectura general del sistema​

Pipeline lògic:

  1. Ingesta
  2. Parsing & mapping
  3. Validació & deduplicació
  4. Staging (revisió manual, ADMIN)
  5. Publicació cap a taules finals (dances, songs, links, choreographers, etc.)

2.1. Ingesta​

Fonts previstes:

  • Web scraping (més endavant):
    • portals tipus CopperKnob, Kickit i similars.
  • YouTube Data API:
    • recuperar metadades de vídeos (títol, canal, URL, durada…).
  • Import CSV:
    • fitxers d’usuari amb llistes de balls/cançons (p. ex. “500 balls” d’un professor).

2.2. Parsing i mapping​

Per a cada font, es defineix un mapper que converteix dades brutes en un format intern homogeni, per exemple:

RawSource -> ImportedRow (format intern comú)

Exemples de camps d’ImportedRow:

  • dance_name
  • song_title
  • artist
  • bpm
  • level
  • step_sheet_url
  • video_url
  • source_name (p. ex. "CopperKnob", "CSV_User_X")

El resultat d’aquesta fase no escriu encara a les taules de domini, sinó a una taula de staging (veure secció 3).

2.3. Validació i deduplicació​

Abans de passar a staging:

  • Validacions bàsiques:
    • camps obligatoris (dance_name o song_title),
    • valors numèrics (bpm > 0),
    • URLs amb format correcte.
  • Deduplicació:
    • comparació per:
      • dance_name + choreographer,
      • song_title + artist,
    • similitud de cadenes (fuzzy matching),
    • assignar un nivell de confiança al match (alta / mitjana / baixa).

Les anomalies i dubtes es marquen amb flags perquè l’admin les pugui revisar a l’UI.

3. Model de staging​

La idea és tenir una taula import_staging que actuï com a “zona intermèdia”:

import_staging(
  id,
  source_name,         -- p. ex. "CSV_User_X", "CopperKnob"
  payload_json,        -- dades brutes o semi-normalitzades
  mapped_dance_name?,
  mapped_song_title?,
  mapped_artist?,
  mapped_bpm?,
  mapping_confidence?, -- percentatge o label (HIGH/MEDIUM/LOW)
  status,              -- PENDING / APPROVED / REJECTED / PUBLISHED
  error_msg?,
  created_at,
  updated_at
)

3.1. Flux d’estats​

  • PENDING → creat automàticament pel procés d’import.
  • APPROVED → marcat manualment per un admin, després de revisar/corregir.
  • REJECTED → descartat manualment (dades incorrectes o duplicades).
  • PUBLISHED → ja aplicat a les taules finals; pot quedar com a traça.

Només usuaris amb rol adequat (p. ex. ADMIN) poden:

  • editar camps mapejats,
  • canviar l’estat,
  • veure l’històric d’errors i correccions.

4. UI d’Admin per a import​

Es preveu una pantalla (o conjunt de pantalles) d’admin per:

4.1. Llista de registres de staging​

  • Veure registres d’import pendents.
  • Filtrar per:
    • source_name,
    • data,
    • estat (PENDING, APPROVED, REJECTED, PUBLISHED),
    • nivell de confiança.

4.2. Detall d’un registre​

En obrir un registre de staging, l’admin ha de poder veure:

  • Dades brutes (tal com han arribat).
  • Dades mapejades (camps interpretats).
  • Suggeriments de match amb dances i songs existents.

I ha de poder:

  • corregir valors (p. ex. BPM, títol, coreògraf),
  • decidir si es crea un nou ball/cançó o s’enllaça amb un existent,
  • aprovar (APPROVED) o rebutjar (REJECTED).

4.3. Accions típiques a la pantalla​

  • [Corregir dades]
  • [Guardar]
  • [Descartar]
  • [Veure coincidències existents] (mostrar balls similars, etc.)

Només quan un registre està en estat APPROVED passa a la fase de publicació.

5. Publicació (aplicació a les taules finals)​

Un cop un registre de staging està en estat APPROVED, entra en joc un servei de publicació que:

  1. Llegeix import_staging amb status = APPROVED.
  2. Crea o actualitza entitats:
    • dances,
    • songs,
    • links,
    • choreographers (si cal),
    • i altres entitats relacionades.
  3. Marca el registre com a PUBLISHED i guarda:
    • referències a les noves IDs creades,
    • o enllaços amb entitats existents.

5.1. Decisions clau (a definir)​

  • Quan crear un nou dance vs reutilitzar-ne un d’existent.
  • Quan crear un nou song vs associar-se’n a un existent.
  • Política de “font preferida” si hi ha conflictes:
    • p. ex. dades oficials vs dades d’usuari.

6. Fonts d’import i roadmap​

6.1. Fase 4B – Import CSV simple​

  • Importar CSV d’usuari amb capçaleres conegudes.
  • Mapping fix (poc condicionals).
  • UI d’admin mínima per staging:
    • veure registres,
    • aprovar / rebutjar,
    • crear balls/cançons bàsics.

6.2. Fase 4C – Sistema d’import complet amb staging​

  • Generalitzar el model perquè serveixi per a qualssevol font.
  • Afegir:
    • source_name,
    • payload_json,
    • camps de mapping.
  • Millorar UI:
    • vista de diff entre staging i dades existents,
    • filtres per confiança, fonts, etc.

6.3. Fase 4D – Enriquiment de dades​

  • Afegir informació extra a partir de fonts externes:
    • BPM,
    • durada,
    • etiquetes d’estil,
    • enllaços addicionals.
  • Reutilitzar la mateixa infraestructura de staging:
    • si es detecta un canvi dubtós, demanar confirmació manual.

6.4. Fase 4E – Scraping i connectors​

  • Implementar connectors específics:
    • p. ex. un scraper per a un portal de stepsheets.
  • Definir:
    • freqüència d’actualització,
    • limitació de càrrega,
    • respecte total a TOS i drets dels portals.

7. Seguretat i permisos​

Només rols alts (p. ex. ADMIN) poden:

  • fer imports massius,
  • aprovar / publicar dades,
  • configurar fonts.

El backend ha de:

  • validar JWT i rols,
  • registrar auditories:
    • qui ha aprovat què,
    • quan s’han publicat canvis.

8. Criteris d’acceptació​

Per considerar una primera versió del sistema d’import “usable”:

  • Hi ha un endpoint/API i/o UI per pujar un CSV.
  • Es creen registres a import_staging amb estat PENDING.
  • Existeix una pantalla d’admin per:
    • veure aquests registres,
    • editar camps essencials,
    • aprovar / rebutjar.
  • Existeix un procés de publicació (manual o programat) que:
    • crea balls/cançons nous o enllaça amb existents,
    • marca registres com PUBLISHED.
  • Hi ha logs suficients per entendre:
    • què ha entrat,
    • què s’ha descartat,
    • què s’ha publicat.

9. Documents relacionats​

  • Roadmap (Fase 4): roadmap/roadmap-global
  • Detalls tècnics del roadmap: roadmap/roadmap-technical-details
  • Redisseny de base de dades: architecture/db-redesign-plan
  • Seguretat i rols: architecture/security