# ADR-011: Estrategia de Base de Datos - Carga Limpia

**Estado:** Aceptado
**Fecha:** 2025-11-24
**Decisores:** Architecture-Analyst, Tech Lead
**Contexto:** ERP Generic - Gestión de esquema de base de datos

---

## Contexto

El proyecto ERP Generic está en fase de desarrollo activo donde la estructura de la base de datos evoluciona frecuentemente. Necesitamos definir una estrategia clara para gestionar cambios en el esquema de base de datos que sea:
- Simple de entender y ejecutar
- Reproducible en cualquier ambiente
- Sin acumulación de deuda técnica
- Adecuada para la fase actual del proyecto

## Decisión

**Adoptamos la estrategia de "Carga Limpia" (Clean Load) para la gestión de base de datos.**

### Principios

```
┌─────────────────────────────────────────────────────────────┐
│  ✅ SÍ - PERMITIDO                                          │
├─────────────────────────────────────────────────────────────┤
│  • Archivos DDL completos por schema (01-auth.sql, etc.)   │
│  • Scripts de seeds para datos iniciales                    │
│  • Scripts de recreación (drop + create)                    │
│  • Un solo punto de verdad: los archivos DDL               │
├─────────────────────────────────────────────────────────────┤
│  ❌ NO - PROHIBIDO                                          │
├─────────────────────────────────────────────────────────────┤
│  • Archivos de migración incremental (migrations)          │
│  • Archivos de fix o patch                                  │
│  • ALTER TABLE en producción sin actualizar DDL            │
│  • Scripts numerados tipo migration_001_xxx.sql            │
│  • Hotfixes directos a la base de datos                    │
└─────────────────────────────────────────────────────────────┘
```

### Estructura de Archivos

```
apps/database/
├── ddl/
│   ├── 00-prerequisites.sql    # Extensions, utilities
│   ├── 01-auth.sql             # Schema auth completo
│   ├── 02-core.sql             # Schema core completo
│   ├── ...                     # Demás schemas
│   └── 09-system.sql           # Schema system completo
├── seeds/
│   ├── dev/                    # Seeds para desarrollo
│   ├── staging/                # Seeds para staging
│   └── prod/                   # Seeds para producción (mínimos)
├── scripts/
│   ├── create-database.sh      # Crear BD desde cero
│   ├── reset-database.sh       # DROP + CREATE + DDL + Seeds
│   ├── drop-database.sh        # Solo eliminar BD
│   └── load-seeds.sh           # Cargar seeds específicos
└── docker-compose.yml
```

### Flujo de Trabajo para Cambios

```
┌─────────────────────────────────────────────────────────────┐
│  CAMBIO EN ESTRUCTURA DE BASE DE DATOS                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Editar archivo DDL correspondiente                      │
│     Ejemplo: Agregar columna a invoices                     │
│     → Editar: ddl/04-financial.sql                          │
│                                                              │
│  2. Actualizar documentación                                │
│     → INVENTARIO-OBJETOS-BD.yml                             │
│     → MATRIZ-TRAZABILIDAD-RF-ET-BD.md (si aplica)          │
│                                                              │
│  3. Actualizar seeds si es necesario                        │
│     → seeds/dev/05-sample-data.sql                          │
│                                                              │
│  4. Ejecutar reset                                          │
│     → ./scripts/reset-database.sh                           │
│                                                              │
│  5. Verificar que todo funciona                             │
│     → Conectar, validar estructura, probar queries          │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Comandos de Gestión

| Acción | Comando | Descripción |
|--------|---------|-------------|
| Primera instalación | `./scripts/create-database.sh` | Crea BD, ejecuta DDL, carga seeds |
| Después de cambios DDL | `./scripts/reset-database.sh` | Elimina y recrea todo |
| Solo eliminar | `./scripts/drop-database.sh` | Elimina BD completamente |
| Recargar datos | `./scripts/load-seeds.sh dev` | Solo carga seeds de dev |

## Consecuencias

### Positivas

1. **Simplicidad**: Un comando recrea todo el ambiente
2. **Reproducibilidad**: Cualquier desarrollador obtiene BD idéntica
3. **Sin deuda técnica**: No hay acumulación de parches
4. **Un punto de verdad**: Los DDL son la fuente autoritativa
5. **Fácil debugging**: Si algo falla, reset y listo
6. **Onboarding rápido**: Nuevos devs levantan ambiente en minutos

### Negativas (Manejables)

1. **Pérdida de datos locales**: Cada reset borra datos
   - *Mitigación*: Seeds completos para desarrollo
2. **No apto para producción con datos**: No se pueden hacer cambios incrementales
   - *Mitigación*: Ver sección "Transición a Producción"
3. **Tiempo de reset**: Puede tomar segundos/minutos
   - *Mitigación*: Aceptable en desarrollo

## Transición a Producción

Cuando el proyecto entre en producción con datos reales:

```
┌─────────────────────────────────────────────────────────────┐
│  TRIGGER: Primera versión en producción con datos reales   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. CONGELAR versión actual de DDL como "baseline v1.0"    │
│                                                              │
│  2. CREAR nuevo ADR (ADR-0XX) para estrategia de migración │
│                                                              │
│  3. IMPLEMENTAR herramienta de migraciones:                │
│     - Opción A: Prisma Migrate                              │
│     - Opción B: Flyway                                      │
│     - Opción C: golang-migrate                              │
│                                                              │
│  4. MANTENER DDL como referencia, pero usar migraciones    │
│     para cambios incrementales                              │
│                                                              │
│  5. DOCUMENTAR proceso en PLAN-MAESTRO                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Directiva para Agentes

Esta decisión es **OBLIGATORIA** para todos los agentes que trabajen con base de datos:

```
🔴 DIRECTIVA ADR-011 - CARGA LIMPIA DE BASE DE DATOS

Los agentes DEBEN:
✅ Editar archivos DDL existentes para cambios de estructura
✅ Usar reset-database.sh después de cambios
✅ Actualizar inventarios y trazabilidad
✅ Mantener seeds actualizados

Los agentes NO DEBEN:
❌ Crear archivos de migración
❌ Crear archivos de fix o patch
❌ Ejecutar ALTER TABLE directamente
❌ Crear scripts numerados incrementales
❌ Modificar BD sin actualizar DDL correspondiente
```

## Referencias

- [ADR-007: Database Design](./ADR-007-database-design.md)
- [INVENTARIO-OBJETOS-BD.yml](../02-modelado/trazabilidad/INVENTARIO-OBJETOS-BD.yml)
- [Estructura apps/database/](../../apps/database/README.md)

---

**Aprobado por:** Architecture-Analyst
**Fecha de aprobación:** 2025-11-24
