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