horux-strategy-platform/docs/06-base-de-datos.md

# 6. Base de Datos

## Diagrama Entidad-Relación

```
┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│    giros    │       │   clientes  │       │    users    │
├─────────────┤       ├─────────────┤       ├─────────────┤
│ id          │◄──────┤ giro_id     │       │ id          │
│ nombre      │       │ id          │◄──────┤ cliente_id  │
│ activo      │       │ nombre_emp  │       │ nombre      │
└─────────────┘       │ logo        │       │ email       │
                      │ moneda      │       │ password    │
                      │ config      │       │ role        │
                      └──────┬──────┘       └─────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
       ┌─────────────┐┌─────────────┐┌─────────────┐
       │  balanzas   ││  reportes   ││mapeo_cuentas│
       ├─────────────┤├─────────────┤├─────────────┤
       │ id          ││ id          ││ id          │
       │ cliente_id  ││ cliente_id  ││ cliente_id  │
       │ periodo_ini ││ nombre      ││ codigo_pat  │
       │ periodo_fin ││ periodo_tipo││ categoria_id│
       │ sistema_orig││ data_calc   │└─────────────┘
       │ status      ││ pdf_path    │
       └──────┬──────┘└─────────────┘
              │
              ▼
       ┌─────────────┐
       │   cuentas   │
       ├─────────────┤
       │ id          │
       │ balanza_id  │
       │ codigo      │
       │ nombre      │
       │ nivel       │
       │ saldos...   │
       │ excluida    │
       │ categoria_id│
       └─────────────┘

┌─────────────────┐     ┌─────────────────┐
│reportes_contable│     │categorias_contab│
├─────────────────┤     ├─────────────────┤
│ id              │◄────┤ reporte_cont_id │
│ nombre          │     │ id              │
└─────────────────┘     │ nombre          │
                        │ orden           │
                        └────────┬────────┘
                                 │
                        ┌────────┴────────┐
                        ▼                 ▼
                 ┌─────────────┐   ┌─────────────┐
                 │reglas_mapeo │   │  umbrales   │
                 ├─────────────┤   ├─────────────┤
                 │ sistema_orig│   │ metrica     │
                 │ rango_ini   │   │ muy_positivo│
                 │ rango_fin   │   │ positivo    │
                 │ categoria_id│   │ neutral     │
                 │ prioridad   │   │ negativo    │
                 └─────────────┘   │ muy_negativo│
                                   │ giro_id     │
                                   └─────────────┘
```

---

## Tablas

### users
Usuarios del sistema.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| nombre | varchar(255) | Nombre completo |
| email | varchar(255) | Email único |
| password | varchar(255) | Hash de contraseña |
| role | enum | admin, analista, cliente, empleado |
| cliente_id | bigint | FK a clientes (nullable) |

### clientes
Empresas registradas.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| nombre_empresa | varchar(255) | Nombre de la empresa |
| logo | varchar(255) | Path al logo |
| giro_id | bigint | FK a giros |
| moneda | varchar(3) | MXN, USD, EUR |
| configuracion | json | Configuración adicional |

### giros
Catálogo de giros de negocio.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| nombre | varchar(255) | Nombre del giro |
| activo | boolean | Estado |

### balanzas
Archivos de balanza subidos.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| cliente_id | bigint | FK a clientes |
| periodo_inicio | date | Inicio del periodo |
| periodo_fin | date | Fin del periodo |
| sistema_origen | varchar(50) | contpaqi, aspel, etc. |
| archivo_original | varchar(255) | Path al archivo |
| status | enum | pendiente, procesando, completado, error |
| error_mensaje | text | Mensaje de error si aplica |

### cuentas
Cuentas extraídas de balanzas.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| balanza_id | bigint | FK a balanzas |
| codigo | varchar(20) | Código de cuenta (ej: 001-100-000) |
| nombre | varchar(255) | Nombre de la cuenta |
| nivel | int | Nivel jerárquico (1, 2, 3) |
| reporte_contable_id | bigint | FK a reportes_contables |
| categoria_contable_id | bigint | FK a categorias_contables |
| cuenta_padre_id | bigint | FK a cuentas (self-reference) |
| saldo_inicial_deudor | decimal(18,2) | |
| saldo_inicial_acreedor | decimal(18,2) | |
| cargos | decimal(18,2) | |
| abonos | decimal(18,2) | |
| saldo_final_deudor | decimal(18,2) | |
| saldo_final_acreedor | decimal(18,2) | |
| excluida | boolean | Excluida del cálculo |
| es_cuenta_padre | boolean | Es cuenta padre |
| requiere_revision | boolean | Necesita revisión manual |
| nota_revision | text | Nota sobre la anomalía |

### reportes_contables
Tipos de reporte (Balance, Estado de Resultados).

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| nombre | varchar(255) | "Balance General", "Estado de Resultados" |

### categorias_contables
Categorías dentro de cada reporte.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| reporte_contable_id | bigint | FK a reportes_contables |
| nombre | varchar(255) | Nombre de la categoría |
| orden | int | Orden de aparición |

**Categorías de Balance General:**
1. Activos Circulantes
2. Activos No Circulantes
3. Pasivo Circulante
4. Pasivo No Circulante
5. Capital Social
6. Pérdidas Ejercicios Anteriores
7. Utilidades Ejercicios Anteriores

**Categorías de Estado de Resultados:**
1. Ingresos
2. Costo de Venta
3. Gastos Operativos
4. Otros Gastos
5. Gastos Financieros

### reglas_mapeo
Reglas para clasificar cuentas automáticamente.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| sistema_origen | varchar(50) | contpaqi, aspel, etc. |
| cuenta_padre_codigo | varchar(20) | Código de cuenta padre |
| rango_inicio | varchar(20) | Inicio del rango de códigos |
| rango_fin | varchar(20) | Fin del rango |
| patron_regex | varchar(255) | Patrón regex alternativo |
| reporte_contable_id | bigint | FK |
| categoria_contable_id | bigint | FK |
| prioridad | int | Mayor = se evalúa primero |
| activo | boolean | Regla activa |

### umbrales
Umbrales para semáforos de métricas.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| metrica | varchar(100) | Nombre de la métrica |
| muy_positivo | decimal(10,4) | Umbral muy positivo |
| positivo | decimal(10,4) | Umbral positivo |
| neutral | decimal(10,4) | Umbral neutral |
| negativo | decimal(10,4) | Umbral negativo |
| muy_negativo | decimal(10,4) | Umbral muy negativo |
| giro_id | bigint | FK a giros (nullable = general) |

### reportes
Reportes generados.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | bigint | PK |
| cliente_id | bigint | FK a clientes |
| nombre | varchar(255) | Nombre del reporte |
| periodo_tipo | enum | mensual, trimestral, anual |
| periodo_inicio | date | |
| periodo_fin | date | |
| fecha_generacion | timestamp | |
| data_calculada | json | Métricas y estados financieros |
| pdf_path | varchar(255) | Path al PDF generado |
| status | enum | pendiente, procesando, completado, error |

### reporte_balanza
Tabla pivote reporte-balanza.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| reporte_id | bigint | FK a reportes |
| balanza_id | bigint | FK a balanzas |

---

## Seeders

Los seeders iniciales crean:

1. **GirosSeeder** - 24 giros de negocio
2. **ReportesContablesSeeder** - 2 reportes + 12 categorías
3. **ReglasMapeeoContpaqiSeeder** - 12 reglas para CONTPAQi
4. **UmbralesSeeder** - 24 umbrales por defecto
5. **AdminUserSeeder** - Usuario admin inicial