trading-platform-database/DIRECTIVA-POLITICA-CARGA-LIMPIA.md

DIRECTIVA: Politica de Carga Limpia (DDL-First)

ID: DIR-DB-001 Version: 1.0.0 Fecha: 2025-12-06 Estado: ACTIVA Aplica a: Todos los agentes que trabajen con base de datos

---

OBJETIVO

Establecer una politica clara y obligatoria para la gestion del esquema de base de datos del proyecto Trading Platform (OrbiQuant IA), garantizando que la base de datos pueda ser creada o recreada completamente desde archivos DDL sin dependencia de migraciones incrementales.

---

PRINCIPIO FUNDAMENTAL

La base de datos SIEMPRE debe poder ser creada desde cero ejecutando unicamente los archivos DDL.

Esto significa:

• NO migraciones incrementales
• NO archivos de "fix" o "patch"
• NO scripts de correccion
• NO ALTER TABLE en archivos separados

---

REGLAS OBLIGATORIAS

1. Estructura de Archivos

apps/database/
├── ddl/
│   └── schemas/
│       ├── {schema}/
│       │   ├── 00-enums.sql          # Tipos enumerados
│       │   ├── tables/
│       │   │   ├── 01-{tabla}.sql    # Una tabla por archivo
│       │   │   ├── 02-{tabla}.sql
│       │   │   └── ...
│       │   ├── functions/
│       │   │   ├── 01-{funcion}.sql
│       │   │   └── ...
│       │   ├── triggers/
│       │   │   └── ...
│       │   └── views/
│       │       └── ...
├── seeds/
│   ├── prod/                         # Datos de produccion
│   └── dev/                          # Datos de desarrollo
└── scripts/
    ├── create-database.sh            # Crear BD
    └── drop-and-recreate-database.sh # Recrear BD

2. Nomenclatura de Archivos

Tipo	Patron	Ejemplo
Enums	00-enums.sql	00-enums.sql
Tablas	NN-{nombre}.sql	01-users.sql, 02-profiles.sql
Funciones	NN-{nombre}.sql	01-update_updated_at.sql
Triggers	NN-{nombre}.sql	01-audit_trigger.sql
Views	NN-{nombre}.sql	01-user_summary.sql

El numero NN indica el orden de ejecucion dentro de cada carpeta.

3. Modificaciones al Schema

CORRECTO:

-- Editar directamente el archivo DDL original
-- apps/database/ddl/schemas/auth/tables/01-users.sql

CREATE TABLE IF NOT EXISTS auth.users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    -- Agregar nuevas columnas aqui
    phone VARCHAR(20),  -- <-- Nueva columna
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

INCORRECTO:

-- NO crear archivos de migracion
-- migrations/20251206_add_phone_to_users.sql  <-- PROHIBIDO

ALTER TABLE auth.users ADD COLUMN phone VARCHAR(20);

4. Cuando Necesitas Cambiar el Schema

1. Edita el archivo DDL original de la tabla/funcion/trigger
2. Ejecuta recreacion en tu ambiente de desarrollo:

   ./scripts/drop-and-recreate-database.sh
   

3. Verifica que todo funcione correctamente
4. Commit los cambios al DDL

5. Prohibiciones Explicitas

Accion	Permitido	Razon
Crear archivo migrations/*.sql	NO	Rompe carga limpia
Crear archivo fix-*.sql	NO	Rompe carga limpia
Crear archivo patch-*.sql	NO	Rompe carga limpia
Crear archivo alter-*.sql	NO	Rompe carga limpia
Usar ALTER TABLE en archivo separado	NO	Debe estar en DDL original
Modificar DDL original directamente	SI	Es la forma correcta

---

ESTANDARES TECNICOS

Tipos de Datos

Uso	Tipo Correcto	Tipo Incorrecto
Timestamps	TIMESTAMPTZ	TIMESTAMP
UUIDs	gen_random_uuid()	uuid_generate_v4()
Moneda	DECIMAL(20,8)	FLOAT, DOUBLE
Texto variable	VARCHAR(n)	CHAR(n) para texto variable

Convenciones SQL

-- Nombres en snake_case
CREATE TABLE auth.user_profiles (  -- Correcto
CREATE TABLE auth.UserProfiles (   -- Incorrecto

-- Siempre incluir schema
CREATE TABLE auth.users (          -- Correcto
CREATE TABLE users (               -- Incorrecto (usa public)

-- IF NOT EXISTS en CREATE
CREATE TABLE IF NOT EXISTS auth.users (
CREATE TYPE IF NOT EXISTS auth.user_status AS ENUM (

-- Indices con prefijo descriptivo
CREATE INDEX idx_users_email ON auth.users(email);
CREATE INDEX idx_users_created ON auth.users(created_at DESC);

Foreign Keys

-- Siempre referenciar con schema completo
user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,

-- Nunca asumir schema
user_id UUID NOT NULL REFERENCES users(id),  -- INCORRECTO

---

ORDEN DE CARGA

El script create-database.sh ejecuta en este orden:

1. Extensiones

   • uuid-ossp
   • pgcrypto
   • pg_trgm
   • btree_gin
   • vector (si disponible)

2. Schemas (en orden)

   • auth
   • education
   • financial
   • trading
   • investment
   • ml
   • llm
   • audit

3. Por cada schema:

   • 00-enums.sql (si existe)
   • tables/*.sql (orden numerico)
   • functions/*.sql (orden numerico)
   • triggers/*.sql (orden numerico)
   • views/*.sql (orden numerico)

4. Seeds

   • prod/ o dev/ segun ambiente

---

VALIDACION

Pre-commit Checklist

Antes de hacer commit de cambios a DDL:

• No existen archivos migrations/, fix-*, patch-*, alter-*
• Todos los cambios estan en archivos DDL originales
• Se puede ejecutar drop-and-recreate-database.sh sin errores
• Todas las FKs usan schema completo (auth.users, no users)
• Todos los timestamps son TIMESTAMPTZ
• Todos los UUIDs usan gen_random_uuid()

Script de Validacion

# Verificar que no hay archivos prohibidos
find apps/database -name "fix-*.sql" -o -name "patch-*.sql" -o -name "alter-*.sql"
# Debe retornar vacio

# Verificar que no hay carpeta migrations con contenido nuevo
ls apps/database/migrations/
# Solo debe existir si hay migraciones legacy (a eliminar)

---

EXCEPCIONES

Unica Excepcion: Datos de Produccion

Si hay datos de produccion que NO pueden perderse:

1. Exportar datos antes de recrear
2. Recrear schema con DDL limpio
3. Importar datos desde backup

Esto NO es una migracion, es un proceso de backup/restore.

---

CONSECUENCIAS DE VIOLAR ESTA DIRECTIVA

1. Build fallara - CI/CD rechazara archivos prohibidos
2. PR sera rechazado - Code review detectara violaciones
3. Deuda tecnica - Se acumularan inconsistencias

---

REFERENCIAS

• _MAP.md - Database Schemas
• DECISIONES-ARQUITECTONICAS.md
• create-database.sh

---

HISTORIAL DE CAMBIOS

Version	Fecha	Cambio
1.0.0	2025-12-06	Version inicial

---

Directiva establecida por Requirements-Analyst Agent OrbiQuant IA Trading Platform