ADR-0001 · Migraciones organizadas en subdirectorios numerados ejecutados por grupos

• Estado: aceptado
• Decisores:
• Fecha de la decisión: 2023-10 (aprox., primer subdirectorio en git; retroactivo)

Contexto y problema

El esquema tiene decenas de tablas con dependencias entre sí (proveedores → productos de proveedor → matching → productos unificados → canales). Laravel ejecuta las migraciones de database/migrations/ en orden de timestamp, pero el proyecto necesitaba agrupar la creación de tablas por capas de dependencia y poder ejecutarlas de forma controlada.

Opciones consideradas

1. Subdirectorios numerados (00, 01, ... 72) ejecutados en orden con php artisan migrate --path=database/migrations/NN.
2. Migraciones planas estándar de Laravel ordenadas solo por timestamp.

Decisión

Se eligió la opción 1: cada subdirectorio agrupa tablas de una misma capa, y las carpetas se ejecutan secuencialmente (la 01 crea tablas que necesita la 02, y así sucesivamente). El procedimiento completo está en desarrollo local.

Consecuencias

Positivas

• El orden de dependencias entre tablas queda explícito y agrupado.
• Se puede aplicar el esquema por etapas en entornos nuevos.

Negativas / deuda asumida

• php artisan migrate y migrate:fresh a secas no recrean el esquema (solo ven la raíz de database/migrations/). Todo tooling que asuma el layout estándar de Laravel se rompe: fue un factor del incidente de julio 2026 donde RefreshDatabase en tests dejó la base dev vacía (incidente 2026-07).
• Levantar una base desde cero requiere ejecutar ~70 carpetas a mano o con un script; no hay comando único.