Skip to main content

Pla de Redisseny de Base de Dades

Objectiu: preparar un esquema de dades sòlid per donar suport a events, venues, locations, classes i un model de dances més ric, mantenint compatibilitat progressiva amb l’MVP actual.

Aquest pla no és una migració concreta, sinó un full de ruta tècnic per a la BD.

1. Abast del redisseny​

1.1. Domini d’ubicacions i events​

  • Introduir una entitat clara d’event i una cadena:
    • event → venue → location.
  • Revisar el model actual de venues i locations:
    • claus forànies,
    • normalització (evitar duplicats de ciutats/països),
    • polítiques ON DELETE coherents,
    • índexs per cerca i filtres (ciutat, país, tipus, etc.).

1.2. Dances (balls)​

  • Revisar i completar els camps de dances:
    • tècnics: counts, walls, level, tags, style, bpm?, year?.
    • metadades: origen, país, notes, referències externes.
  • Decidir on van les etiquetes i camps flexibles:
    • camps simples (TEXT/VARCHAR),
    • o taules auxiliars (p. ex. dance_tags),
    • o bé un camp metadata JSONB per dades molt obertes.
  • Clarificar noms i tipus:
    • evitar abreviatures confuses,
    • triar tipus adequats (TEXT vs VARCHAR(n), TIMESTAMPTZ, etc.).

1.3. Classes​

Nova entitat classes per gestionar classes en venues:

classes( id, venue_id, instructor_id?, -- futur: relació amb persona/usuari dance_id?, -- ball principal o focus start_at, end_at, capacity?, notes? )

Punts a decidir:

  • política d’eliminació (ON DELETE SET NULL vs RESTRICT),
  • índexs per data (start_at, end_at) i venue_id,
  • futur suport per recurrència (classes setmanals).

1.4. Revisió global d’índexs i constraints​

  • Índexs per:
    • cerques de text (noms de balls, cançons, coreògrafs, ciutats…),
    • filtres freqüents (nivell, any, país).
  • Claus forànies consistents:
    • totes amb índex implícit o explícit.
  • Nullability ben definida:
    • només NULL on tingui sentit.
  • Timestamps consistents:
    • created_at i updated_at a totes les entitats principals,
    • triggers o lògica d’aplicació per mantenir updated_at.

2. Model proposat (esborrany)​

Nota: això no és un DDL definitiu, sinó una guia conceptual per al disseny ERD i les futures migracions.

2.1. Location i Venue​

locations(
  id,
  country,
  region?,
  city,
  state?,
  lat?,
  lng?,
  created_at,
  updated_at
)

venues(
  id,
  name,
  location_id,
  address?,
  postal_code?,
  venue_type?,   -- sala de ball, bar, club, festival venue...
  notes?,
  created_at,
  updated_at
)

Relacions:

  • venues.location_id → locations.id (ON DELETE RESTRICT o ON DELETE SET NULL).

Índexs recomanats:

  • idx_locations_city_country,
  • idx_venues_location_id.

2.2. Events​

events(
  id,
  venue_id,
  name,
  description?,
  event_type?,         -- social, festival, workshop...
  start_at,
  end_at?,
  website_url?,
  created_at,
  updated_at
)

Relacions:

  • events.venue_id → venues.id (ON DELETE RESTRICT).

Futur:

  • taula d’occurrences si un event té múltiples dates/slots.

2.3. Classes​

classes(
  id,
  venue_id,
  instructor_id?,   -- pot apuntar a persona/usuari
  dance_id?,        -- ball principal
  start_at,
  end_at,
  capacity?,
  notes?,
  created_at,
  updated_at
)

Relacions:

  • classes.venue_id → venues.id (ON DELETE RESTRICT),
  • classes.dance_id → dances.id (ON DELETE SET NULL).

Índexs recomanats:

  • idx_classes_venue_date (venue_id, start_at).

2.4. Dances (refinament)​

Conceptes a fixar:

  • camps obligatoris (nom, nivell),
  • camps tècnics (counts, walls, tags, bpm, year),
  • relació amb coreògraf (si no està ja clar).

Exemple simplificat:

dances(
  id,
  name,
  level,
  walls?,
  counts?,
  bpm?,
  year?,
  choreographer_id?,
  tags?,             -- p. ex. array de TEXT o taula auxiliar
  style?,
  notes?,
  created_at,
  updated_at
)

Relació:

  • dances.choreographer_id → choreographers.id (ON DELETE SET NULL).

Les decisions concretes (tipus, longituds, constraints) s’acabaran de definir a:

  • l’ERD detallat,
  • els scripts Flyway corresponents.

3. Estratègia de migració (Flyway)​

Objectius:

  • no trencar l’MVP actual,
  • aplicar canvis de forma incremental,
  • permetre backfill de dades.

3.1. Fases proposades​

  • V19__add_locations_and_venues.sql
    • crear taules locations i venues,
    • opcionalment, migrar dades existents de “local”/“ciutat” si n’hi ha.
  • V20__add_events.sql
    • crear taula events vinculada a venues.
  • V21__add_classes.sql
    • crear taula classes,
    • afegir índexs bàsics per data i venue.
  • V22__refine_dances.sql
    • afegir/ajustar camps de dances,
    • posar valors per defecte i fer backfill si cal.
  • V23__indexes_and_constraints.sql
    • afegir índexs de cerca (pg_trgm),
    • afinar constraints (NOT NULL, ON DELETE, etc.).

3.2. Backfill i compatibilitat​

Si hi ha dades existents:

  • scripts per agrupar venues per ciutat/país,
  • assignar location_id on sigui possible,
  • deixar location_id a NULL quan no es pugui inferir.

Compatibilitat:

  • les API que només llegeixen dances i songs han de continuar funcionant,
  • els nous camps de dances han de tenir defaults raonables (0, NULL, etc.),
  • els nous endpoints per events / classes es poden introduir progressivament.

4. Índexs i rendiment​

Criteris generals:

  • Totes les claus forànies han d’estar indexades (explícitament o implícitament).
  • Afegir índexs específics per:
    • cerques de text, p. ex.:
      • pg_trgm sobre dances.name, choreographers.name, locations.city, etc.;
    • filtres per dates (events.start_at, classes.start_at);
    • combinacions freqüents (venue_id + start_at).

5. Criteris d’acceptació​

Es considera que el redisseny està “acceptat” quan:

  • Esquemes i relacions definits i consensuats:
    • ERD actualitzat (p. ex. diagrams/architecture/entity-relationship.mmd).
  • Migracions Flyway noves (V19+) creades i testejades en local.
  • Cap regressió funcional a:
    • llistats i fitxes de dances i songs,
    • parts de l’MVP ja presents en test/producció.
  • Documentació actualitzada:
    • aquest document,
    • architecture/architecture-overview.md,
    • qualsevol diagrama afectat.

6. Riscos i mitigacions​

6.1. Canvis de FK que bloquegin eliminacions​

  • Definir ON DELETE clarament (RESTRICT vs SET NULL).
  • Preparar scripts per:
    • netejar registres orfes,
    • o reassociar registres abans d’enforçar constraints.

6.2. Registres existents amb valors inconsistents​

  • Revisar dades abans d’imposar NOT NULL.
  • Identificar registres problemàtics amb queries d’auditoria.

6.3. Rendiment​

  • Fer proves de càrrega bàsiques un cop aplicats els índexs.
  • Monitoritzar queries lentes (p. ex. amb pg_stat_statements).

7. Estat i properes decisions​

Punts que s’han de tancar abans de passar a implementació:

  • Definir completament els camps per a events i classes.
  • Tancar el model de dances refinat (nivells, tags, camps tècnics).
  • Aprovar polítiques ON DELETE per a totes les FKs noves.
  • Definir l’ordre final i dependències de les migracions Flyway.
  • Actualitzar ERD i diagrames un cop aprovades les decisions.

Quan aquest pla estigui aprovat, el següent pas serà implementar les migracions Flyway i revisar que tot s’alinea amb:

  • el model funcional,
  • el roadmap tècnic,
  • i les necessitats reals de dades del producte.