# Trading Platform Database

Definiciones DDL y scripts de base de datos para Trading Platform.

## Stack Tecnologico

- **DBMS:** PostgreSQL 16
- **Extension ML:** pgvector (embeddings LLM)
- **Contenedor:** Docker (pgvector/pgvector:pg16)

## Estructura del Proyecto

```
database/
├── ddl/
│   └── schemas/          # Definiciones DDL por schema
│       ├── audit/        # Logs de auditoria
│       ├── auth/         # Autenticacion y sesiones
│       ├── education/    # Cursos y gamificacion
│       ├── financial/    # Transacciones y wallets
│       ├── investment/   # Inversiones y portfolios
│       ├── llm/          # Embeddings y contextos LLM
│       ├── ml/           # Modelos y predicciones ML
│       └── trading/      # Ordenes y operaciones
├── schemas/              # _MAP.md e indices
├── scripts/              # Scripts de gestion
│   ├── create-database.sh
│   ├── drop-and-recreate-database.sh
│   └── validate-ddl.sh
└── seeds/                # Datos iniciales (dev)
```

## Schemas

| Schema | Tablas | Descripcion |
|--------|--------|-------------|
| `auth` | 12 | Usuarios, sesiones, tokens, OAuth |
| `education` | 15 | Cursos, lecciones, quizzes, progreso |
| `trading` | 18 | Ordenes, posiciones, historial |
| `investment` | 12 | Portfolios, assets, distribuciones |
| `financial` | 10 | Wallets, transacciones, pagos |
| `ml` | 8 | Modelos, predicciones, senales |
| `llm` | 6 | Embeddings, conversaciones, contextos |
| `audit` | 9 | Logs, eventos, trazabilidad |

**Total:** ~90 tablas, 102+ foreign keys

## Instalacion

### Opcion 1: Docker (Recomendado)

```bash
# Desde raiz del proyecto trading-platform
docker-compose up -d postgres

# Crear base de datos
cd apps/database/scripts
./create-database.sh
```

### Opcion 2: PostgreSQL Local

```bash
# Requiere PostgreSQL 16 con pgvector instalado
# Ubuntu/Debian:
sudo apt install postgresql-16-pgvector

# Crear base de datos
cd apps/database/scripts
./create-database.sh
```

## Scripts Disponibles

| Script | Descripcion |
|--------|-------------|
| `create-database.sh` | Crear BD y cargar DDL |
| `drop-and-recreate-database.sh` | Recrear BD desde cero |
| `validate-ddl.sh` | Validar sintaxis SQL |

## Variables de Entorno

```env
# Database connection - Instancia nativa compartida
# Ref: orchestration/inventarios/DEVENV-PORTS-INVENTORY.yml
DB_HOST=localhost
DB_PORT=5432              # Instancia NATIVA (NO Docker)
DB_NAME=trading_platform
DB_USER=trading_user
DB_PASSWORD=trading_dev_2025
```

> **IMPORTANTE:** El workspace usa arquitectura de instancia única compartida. PostgreSQL nativo en puerto 5432, NO Docker. Los proyectos se separan por DATABASE + USER.

## Uso de Scripts

### Crear Base de Datos

```bash
cd apps/database/scripts

# Con variables de entorno (instancia nativa)
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=trading_platform
export DB_USER=trading_user
export DB_PASSWORD=trading_dev_2025

./create-database.sh
```

### Recrear Base de Datos (Development)

```bash
# ADVERTENCIA: Elimina todos los datos
./drop-and-recreate-database.sh
```

## Estructura DDL

Cada schema sigue la estructura:

```
ddl/schemas/{schema}/
├── 00-extensions.sql     # Extensiones (si aplica)
├── tables/
│   ├── 01-{tabla}.sql
│   ├── 02-{tabla}.sql
│   └── ...
├── functions/
│   ├── 01-{funcion}.sql
│   └── ...
└── triggers/
    └── 01-{trigger}.sql
```

### Convencion de Nombres

- **Tablas:** snake_case plural (`users`, `trading_orders`)
- **Columnas:** snake_case (`created_at`, `user_id`)
- **Primary Keys:** `id` (UUID)
- **Foreign Keys:** `{tabla_singular}_id`
- **Indices:** `idx_{tabla}_{columna}`
- **Triggers:** `trg_{tabla}_{accion}`

## Seguridad

- Row Level Security (RLS) habilitado en tablas multi-tenant
- Funciones con `SECURITY DEFINER` donde corresponde
- Passwords hasheados con bcrypt (en aplicacion)
- Audit logs automaticos via triggers

## Migraciones

Actualmente se usa DDL directo sin sistema de migraciones.
Para cambios:

1. Modificar archivo DDL correspondiente
2. Documentar en `_MAP.md` del schema
3. Ejecutar `drop-and-recreate-database.sh` (dev)
4. En produccion: scripts de migracion manuales

## Documentacion Relacionada

- [Mapa de Schemas](./schemas/_MAP.md)
- [Inventario Database](../../docs/90-transversal/inventarios/DATABASE_INVENTORY.yml)
- [Politica de Carga Limpia](./DIRECTIVA-POLITICA-CARGA-LIMPIA.md)

---

**Proyecto:** Trading Platform
**Version:** 0.1.0
**Actualizado:** 2026-01-07