workspace-v1/orchestration/directivas/simco/SIMCO-SINCRONIZACION-BD.md

SIMCO: SINCRONIZACIÓN BASE DE DATOS

Versión: 1.0.0 Alias: @SYNC_BD Fecha: 2026-01-10 Categoría: operaciones_documentacion Obligatoria: SÍ (post-cambio DDL)

---

RESUMEN EJECUTIVO

Principio: Todo cambio en DDL DEBE reflejarse en scripts, código y documentación. Un DDL sin sincronizar es una bomba de tiempo.

Esta directiva establece el flujo obligatorio de sincronización cuando se realizan cambios en la base de datos.

---

1. Propósito

1.1 Objetivo

Garantizar coherencia completa entre:

• Archivos DDL (schemas, tablas, funciones)
• Scripts de creación/recreación de BD
• Entities y DTOs del backend
• Types del frontend
• Inventarios de base de datos
• Documentación técnica

1.2 Problemas que Resuelve

Problema	Solución
Scripts desactualizados	Actualización obligatoria post-DDL
Entities desincronizadas	Checklist de sincronización
Recreación fallida	Validación de ejecución
Inventarios obsoletos	Actualización como paso final

---

2. Triggers de Sincronización

2.1 Cuándo Aplicar

Cambio	Sincronización
Nuevo schema	OBLIGATORIA
Nueva tabla	OBLIGATORIA
Nueva columna	OBLIGATORIA
Modificación de tipo de columna	OBLIGATORIA
Nuevo constraint (FK, UK, CHECK)	OBLIGATORIA
Nuevo índice	OBLIGATORIA
Nueva función	OBLIGATORIA
Nuevo trigger	OBLIGATORIA
Nueva view	OBLIGATORIA
Modificación de RLS policy	OBLIGATORIA
Cambio en seeds	RECOMENDADA

2.2 Excepciones

• Comentarios en DDL (solo documentación)
• Cambios cosméticos (formato, espacios)

---

3. Flujo de Sincronización

3.1 Diagrama de Flujo

┌─────────────────────────────────────────────────────────────┐
│                 FLUJO DE SINCRONIZACIÓN BD                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   1. MODIFICAR DDL                                          │
│         │                                                   │
│         ▼                                                   │
│   2. ACTUALIZAR SCRIPTS ──────────────────────┐             │
│         │                                     │             │
│         ▼                                     │             │
│   3. EJECUTAR RECREACIÓN ◄────────────────────┘             │
│         │                                                   │
│         ▼                                                   │
│   4. SINCRONIZAR BACKEND                                    │
│         │   ├── Entity                                      │
│         │   ├── DTO                                         │
│         │   ├── Repository                                  │
│         │   └── Service/Controller (si aplica)              │
│         │                                                   │
│         ▼                                                   │
│   5. SINCRONIZAR FRONTEND (si API cambia)                   │
│         │   ├── Types/Interfaces                            │
│         │   └── Services                                    │
│         │                                                   │
│         ▼                                                   │
│   6. ACTUALIZAR INVENTARIOS                                 │
│         │   ├── DATABASE_INVENTORY                          │
│         │   ├── BACKEND_INVENTORY                           │
│         │   └── MASTER_INVENTORY                            │
│         │                                                   │
│         ▼                                                   │
│   7. DOCUMENTAR CAMBIO                                      │
│         │   ├── ADR (si decisión arquitectural)             │
│         │   ├── ET-* (spec técnico)                         │
│         │   └── Changelog                                   │
│         │                                                   │
│         ▼                                                   │
│   8. EJECUTAR TESTS                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3.2 Detalle por Paso

Paso 1: Modificar DDL

-- Ubicación típica: database/ddl/ o apps/database/ddl/

-- Ejemplo de cambio
ALTER TABLE schema_name.table_name
ADD COLUMN new_column VARCHAR(100) NOT NULL DEFAULT '';

-- O en archivo DDL nuevo
CREATE TABLE schema_name.new_table (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    -- ...
);

Paso 2: Actualizar Scripts

Scripts a actualizar:

Script	Ubicación Típica	Acción
create-database.sh	database/ o scripts/	Agregar nuevo DDL
recreate-database.sh	database/ o scripts/	Misma actualización
drop-database.sh	database/ o scripts/	Si es nueva tabla

Estructura esperada del script:

#!/bin/bash
# create-database.sh

# 1. Crear extensiones
psql -f ddl/00-extensions.sql

# 2. Crear schemas (en orden)
psql -f ddl/01-schema-auth.sql
psql -f ddl/02-schema-users.sql
# ... agregar nuevo schema aquí si aplica

# 3. Crear tablas (en orden de dependencias)
psql -f ddl/tables/auth/*.sql
psql -f ddl/tables/users/*.sql
# ... agregar nueva tabla aquí

# 4. Crear constraints
psql -f ddl/constraints/*.sql

# 5. Crear índices
psql -f ddl/indexes/*.sql

# 6. Crear funciones
psql -f ddl/functions/*.sql

# 7. Crear triggers
psql -f ddl/triggers/*.sql

# 8. Crear views
psql -f ddl/views/*.sql

# 9. Crear RLS policies
psql -f ddl/policies/*.sql

# 10. Seeds (opcional)
psql -f seeds/*.sql

Paso 3: Ejecutar Recreación

# Validar antes de ejecutar
./recreate-database.sh --dry-run  # Si está disponible

# Ejecutar recreación
./recreate-database.sh

# Verificar resultado
echo "Verificando schemas..."
psql -c "\dn"

echo "Verificando tablas..."
psql -c "\dt schema_name.*"

echo "Verificando funciones..."
psql -c "\df schema_name.*"

Criterios de éxito:

• Sin errores de sintaxis SQL
• Todos los objetos creados
• Constraints activos
• Índices creados
• RLS policies activas

Paso 4: Sincronizar Backend

Entity (TypeORM ejemplo):

// src/modules/module-name/entities/table-name.entity.ts

@Entity({ schema: 'schema_name', name: 'table_name' })
export class TableName {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  // Agregar nueva columna
  @Column({ type: 'varchar', length: 100, default: '' })
  newColumn: string;

  // ... resto de columnas
}

DTO:

// src/modules/module-name/dto/create-table-name.dto.ts

export class CreateTableNameDto {
  @IsString()
  @MaxLength(100)
  @IsOptional()
  newColumn?: string;

  // ... resto de campos
}

Repository (si métodos nuevos):

// src/modules/module-name/repositories/table-name.repository.ts

@Injectable()
export class TableNameRepository {
  // Agregar método si la nueva columna requiere queries específicos
  async findByNewColumn(value: string): Promise<TableName[]> {
    return this.repository.find({ where: { newColumn: value } });
  }
}

Paso 5: Sincronizar Frontend

Types:

// src/types/table-name.types.ts

export interface TableName {
  id: string;
  newColumn: string;  // Agregar nuevo campo
  // ...
}

export interface CreateTableNameDto {
  newColumn?: string;  // Agregar nuevo campo
  // ...
}

Paso 6: Actualizar Inventarios

DATABASE_INVENTORY.yml:

schemas:
  - name: schema_name
    tables:
      - name: table_name
        columns: 15  # Actualizar conteo
        last_modified: "2026-01-10"
        changes:
          - "2026-01-10: Agregada columna new_column"

BACKEND_INVENTORY.yml:

entities:
  - name: TableName
    file: "src/modules/module-name/entities/table-name.entity.ts"
    columns: 15  # Actualizar
    last_modified: "2026-01-10"

Paso 7: Documentar Cambio

Si es decisión arquitectural → ADR:

# ADR-NNNN: Agregar columna X a tabla Y

## Contexto
...

## Decisión
...

## Consecuencias
...

Actualizar spec técnico:

# ET-BD-XXX: Schema schema_name

## Cambios Recientes
- 2026-01-10: Agregada columna new_column a table_name

Paso 8: Ejecutar Tests

# Tests unitarios
npm run test -- --grep "TableName"

# Tests de integración
npm run test:e2e -- --grep "table-name"

# Verificar build
npm run build

---

4. Validación de Scripts BD

4.1 Estructura de Scripts Requeridos

Script	Obligatorio	Propósito
create-database.sh	SÍ	Crear BD desde cero
recreate-database.sh	SÍ	Drop + Create
drop-database.sh	RECOMENDADO	Solo drop
seed-database.sh	OPCIONAL	Datos iniciales
migrate.sh	SI MIGRATIONS	Ejecutar migraciones

4.2 Checklist Pre-Recreación

antes_de_recrear:
  - [ ] Backup de BD si tiene datos importantes
  - [ ] Verificar no hay conexiones activas
  - [ ] Revisar orden de scripts
  - [ ] Verificar dependencias entre schemas
  - [ ] Confirmar variables de entorno

4.3 Checklist Post-Recreación

despues_de_recrear:
  - [ ] Todos los schemas creados
  - [ ] Todas las tablas creadas
  - [ ] Todos los constraints activos
  - [ ] Todos los índices creados
  - [ ] Todas las funciones creadas
  - [ ] Todos los triggers activos
  - [ ] Todas las views creadas
  - [ ] RLS policies activas
  - [ ] Seeds ejecutados (si aplica)
  - [ ] Aplicación puede conectar

---

5. Matriz de Dependencias DDL

5.1 Dependencias de Tablas

Tabla Principal
    └── FK → Tabla Referenciada (debe existir primero)
    └── View que la usa (debe actualizarse)
    └── Trigger asociado (debe actualizarse)
    └── Función que la referencia (debe actualizarse)

5.2 Orden de Creación

1. Extensions (uuid-ossp, pg_trgm, etc.)
2. Schemas
3. Types/Enums
4. Tablas sin FK
5. Tablas con FK (orden de dependencias)
6. Constraints adicionales
7. Índices
8. Funciones
9. Triggers
10. Views
11. RLS Policies
12. Grants/Permissions

5.3 Impacto de Cambios

Cambio	Impacto
Renombrar columna	Views, funciones, triggers, código
Cambiar tipo	Validaciones, DTOs, frontend
Agregar NOT NULL	Seeds, tests, código existente
Agregar FK	Orden de inserts, deletes
Eliminar columna	ALTO - verificar uso en todo el sistema

---

6. Checklist por Tipo de Cambio

6.1 Nueva Tabla

nueva_tabla:
  ddl:
    - [ ] Archivo DDL creado en ubicación correcta
    - [ ] Schema especificado
    - [ ] PK definida (UUID recomendado)
    - [ ] Timestamps (created_at, updated_at)
    - [ ] Tenant column si multi-tenant
    - [ ] Índices necesarios definidos

  scripts:
    - [ ] create-database.sh actualizado
    - [ ] Orden de creación correcto (después de dependencias)
    - [ ] recreate-database.sh actualizado

  backend:
    - [ ] Entity creada
    - [ ] DTO Create creado
    - [ ] DTO Update creado
    - [ ] DTO Response creado
    - [ ] Repository creado
    - [ ] Service creado
    - [ ] Controller creado
    - [ ] Module actualizado

  tests:
    - [ ] Tests de entity
    - [ ] Tests de service
    - [ ] Tests e2e de endpoints

  inventarios:
    - [ ] DATABASE_INVENTORY actualizado
    - [ ] BACKEND_INVENTORY actualizado
    - [ ] MASTER_INVENTORY actualizado

6.2 Nueva Columna

nueva_columna:
  ddl:
    - [ ] Columna agregada al archivo DDL
    - [ ] Tipo de dato correcto
    - [ ] Constraints definidos (NOT NULL, DEFAULT, etc.)
    - [ ] Índice si será buscada frecuentemente

  scripts:
    - [ ] Script de creación actualizado
    - [ ] Recreación exitosa verificada

  backend:
    - [ ] Entity actualizada
    - [ ] DTOs actualizados
    - [ ] Validadores agregados si aplica

  frontend:
    - [ ] Types actualizados
    - [ ] Formularios actualizados si visible

6.3 Nueva Función/Trigger

nueva_funcion:
  ddl:
    - [ ] Función creada en archivo separado
    - [ ] Schema especificado
    - [ ] SECURITY DEFINER si accede a otras tablas
    - [ ] Documentación inline

  scripts:
    - [ ] Agregada al script de creación
    - [ ] Orden correcto (después de tablas que usa)

  trigger:
    - [ ] Trigger creado si aplica
    - [ ] Evento correcto (BEFORE/AFTER, INSERT/UPDATE/DELETE)
    - [ ] FOR EACH ROW si por fila

  tests:
    - [ ] Test de función
    - [ ] Test de trigger si aplica

---

7. Actualización de Inventarios

7.1 DATABASE_INVENTORY.yml

# Estructura mínima requerida
database:
  name: "{database_name}"
  version: "{semver}"
  updated: "{YYYY-MM-DD}"

schemas:
  - name: "{schema_name}"
    tables_count: {N}
    functions_count: {N}
    triggers_count: {N}
    views_count: {N}
    tables:
      - name: "{table_name}"
        columns: {N}
        indexes: {N}
        has_rls: {true|false}

functions:
  - name: "{function_name}"
    schema: "{schema_name}"
    returns: "{return_type}"

triggers:
  - name: "{trigger_name}"
    table: "{schema.table}"
    event: "{BEFORE|AFTER} {INSERT|UPDATE|DELETE}"

7.2 Qué Actualizar

Cambio DDL	Actualizar en Inventario
Nueva tabla	schemas[].tables[], tables_count
Nueva columna	tables[].columns
Nuevo índice	tables[].indexes
Nueva función	functions[], functions_count
Nuevo trigger	triggers[], triggers_count
Nueva view	views[], views_count
Nuevo schema	schemas[]

---

8. Documentación de Cambios

8.1 Cuándo Crear ADR

• Nuevo schema con propósito específico
• Cambio de estrategia de índices
• Implementación de RLS
• Cambio de tipos de datos masivo
• Nueva función compleja

8.2 Formato de Registro en Changelog

## [{YYYY-MM-DD}] Base de Datos

### Agregado
- Nueva tabla: `schema.nueva_tabla`
- Nueva columna: `schema.tabla.nueva_columna`
- Nueva función: `schema.nueva_funcion()`

### Modificado
- Columna: `schema.tabla.columna` - tipo VARCHAR(50) → VARCHAR(100)

### Deprecado
- Función: `schema.funcion_antigua()` - usar `schema.funcion_nueva()`

### Eliminado
- Tabla: `schema.tabla_obsoleta` (datos migrados a `schema.nueva_tabla`)

---

9. Errores Comunes

Error	Consecuencia	Prevención
Script no actualizado	Recreación falla	Actualizar SIEMPRE post-DDL
Orden incorrecto	FK violations	Respetar dependencias
Entity desincronizada	Runtime errors	Sincronizar inmediatamente
Inventario obsoleto	Documentación incorrecta	Último paso del ciclo
Sin backup	Pérdida de datos	Backup antes de recrear

---

10. Referencia: Checklist Completo

Para validación detallada usar:

Referencia: @CHK_SYNC_BD

---

11. Referencias

Alias	Directiva	Uso
@MANTENIMIENTO_DOCS	SIMCO-MANTENIMIENTO-DOCUMENTACION.md	Ciclo de mantenimiento
@CHK_SYNC_BD	CHECKLIST-SINCRONIZACION-BD.md	Checklist detallado
@OP_DDL	SIMCO-DDL.md	Operaciones de BD
@INVENTARIOS	SIMCO-INVENTARIOS.md	Estándares de inventarios
@MIGRACIONES	SIMCO-MIGRACIONES-BD.md	Migraciones de BD

---

12. Changelog

Versión	Fecha	Cambios
1.0.0	2026-01-10	Versión inicial

---

Referencia rápida:

Flujo: DDL → Scripts → Recrear → Backend → Frontend → Inventarios → Docs → Tests
Checklist: @CHK_SYNC_BD
Trigger: Cualquier cambio en DDL