# Arquitectura de Base de Datos - MiChangarrito

**Última actualización**: 2026-01-05

---

## Resumen

| Métrica | Valor |
|---------|-------|
| Motor | PostgreSQL 15 |
| Schemas | 9 |
| Tablas | 27 |
| Extensiones | 4 |

---

## Schemas

| Schema | Tablas | Descripción |
|--------|--------|-------------|
| `public` | 2 | Tenants y configuración global |
| `auth` | 3 | Autenticación y sesiones |
| `catalog` | 3 | Productos y categorías |
| `sales` | 4 | Ventas y pagos |
| `inventory` | 2 | Stock y movimientos |
| `customers` | 3 | Clientes y fiados |
| `orders` | 2 | Pedidos WhatsApp |
| `subscriptions` | 5 | Planes y tokens |
| `messaging` | 3 | Conversaciones y mensajes |

---

## Estructura por Schema

### public
```
tenants           - Negocios registrados
tenant_configs    - Configuración por tenant
```

### auth
```
users             - Usuarios del sistema
sessions          - Sesiones activas
otp_codes         - Códigos de verificación
```

### catalog
```
categories        - Categorías de productos
products          - Catálogo de productos
product_templates - Templates predefinidos
```

### sales
```
sales             - Ventas realizadas
sale_items        - Items de cada venta
payments          - Pagos recibidos
daily_closures    - Cortes de caja
```

### inventory
```
inventory_movements - Entradas/salidas de stock
stock_alerts        - Alertas de stock bajo
```

### customers
```
customers         - Clientes registrados
fiados            - Cuentas de crédito
fiado_payments    - Abonos a fiados
```

### orders
```
orders            - Pedidos de WhatsApp
order_items       - Items de cada pedido
```

### subscriptions
```
plans                 - Planes disponibles
subscriptions         - Suscripciones activas
tenant_token_balance  - Saldo de tokens
token_packages        - Paquetes de recarga
token_usage           - Consumo de tokens
```

### messaging
```
conversations     - Sesiones de chat
messages          - Mensajes individuales
notifications     - Notificaciones push
```

---

## Extensiones

- `uuid-ossp`: Generación de UUIDs
- `pgcrypto`: Encriptación
- `pg_trgm`: Búsqueda por similitud
- `btree_gin`: Índices GIN para búsquedas

---

## Multi-tenancy

Todas las tablas excepto `public.tenants` incluyen:
- Columna `tenant_id UUID NOT NULL`
- Índice en `tenant_id`
- Trigger automático para asignar tenant

---

## Convenciones

### Columnas Comunes
- `id`: UUID PRIMARY KEY
- `tenant_id`: UUID NOT NULL (multi-tenant)
- `created_at`: TIMESTAMPTZ DEFAULT NOW()
- `updated_at`: TIMESTAMPTZ DEFAULT NOW()
- `is_active`: BOOLEAN DEFAULT TRUE

### Índices
- PK en `id`
- Índice en `tenant_id`
- Índices en FKs
- Índices en columnas de búsqueda frecuente

### Triggers
- `set_updated_at`: Actualiza `updated_at` automáticamente

---

## Conexión

```
Host:     localhost (dev)
Puerto:   5432
Database: michangarrito_dev
Usuario:  michangarrito_dev
```

---

## Scripts

| Script | Descripción |
|--------|-------------|
| `database/scripts/create-database.sh` | Crear BD desde cero |
| `database/scripts/recreate-database.sh` | Recrear BD (destructivo) |

---

## Referencias

- [Environment Inventory](../../orchestration/environment/ENVIRONMENT-INVENTORY.yml)
- [Contexto del Proyecto](../../orchestration/00-guidelines/CONTEXTO-PROYECTO.md)