horux-strategy-platform/docs/plans/2025-01-31-horux-strategy-design.md

# Horux Strategy Platform - Diseño de Sistema

**Fecha:** 2025-01-31
**Proyecto:** Plataforma de Reportes Financieros
**Cliente:** Horux 360

---

## 1. Resumen Ejecutivo

Plataforma web para generar reportes financieros automatizados a partir de balanzas de comprobación. Permite a empresas subir sus datos contables de múltiples sistemas (CONTPAQi, Aspel, SAP, etc.) y obtener dashboards interactivos con métricas financieras y exportación a PDF profesional.

---

## 2. Stack Tecnológico

| Componente | Tecnología |
|------------|------------|
| Backend | Laravel 11 (API REST) |
| Autenticación | Laravel Sanctum |
| Frontend | React 18 + TypeScript |
| Base de datos | MySQL / PostgreSQL |
| Gráficas | Recharts |
| Generación PDF | Puppeteer / Browsershot |
| Parsing PDFs | spatie/pdf-to-text + regex |

---

## 3. Roles de Usuario

| Rol | Permisos |
|-----|----------|
| **Administrador** | Acceso total, configuración global, gestión de umbrales |
| **Analista** | Gestionar clientes asignados, procesar balanzas, generar reportes |
| **Cliente** | Ver dashboard propio, descargar PDFs, gestionar empleados |
| **Empleado** | Permisos configurables por el cliente |

---

## 4. Sistemas Contables Soportados

- CONTPAQi (inicial, con ejemplos)
- Aspel
- Alegra
- SAP
- Odoo
- Parser genérico (CSV/Excel configurable)

### 4.1 Arquitectura de Parsers

```
Upload archivo → Detector de formato → Parser específico → Formato normalizado
```

Cada parser normaliza los datos a una estructura estándar interna, permitiendo agregar nuevos sistemas sin modificar el resto del código.

---

## 5. Modelo de Datos

### 5.1 Usuarios y Acceso

```sql
-- users
id, nombre, email, password, role, cliente_id (nullable)

-- clientes
id, nombre_empresa, logo, giro_id, moneda, configuracion (JSON)

-- permisos_empleado
user_id, cliente_id, permisos (JSON)
```

### 5.2 Catálogos

```sql
-- giros
id, nombre, activo

-- umbrales
id, metrica, muy_positivo, positivo, neutral, negativo, muy_negativo, giro_id

-- reportes_contables
id, nombre ("Balance General", "Estado de Resultados")

-- categorias_contables
id, reporte_contable_id, nombre, orden
```

### 5.3 Categorías Contables

**Balance General:**
| ID | Categoría |
|----|-----------|
| 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 |

**Estado de Resultados:**
| ID | Categoría |
|----|-----------|
| 8 | Ingresos |
| 9 | Costo de Venta |
| 10 | Gastos Operativos |
| 11 | Otros Gastos |
| 12 | Gastos Financieros |

### 5.4 Balanzas y Cuentas

```sql
-- balanzas
id, cliente_id, periodo_inicio, periodo_fin, sistema_origen, archivo_original, status

-- cuentas
id, balanza_id, codigo, nombre, nivel,
reporte_contable_id, categoria_contable_id, cuenta_padre_id,
saldo_inicial_deudor, saldo_inicial_acreedor,
cargos, abonos,
saldo_final_deudor, saldo_final_acreedor,
excluida (boolean)

-- reglas_mapeo
id, sistema_origen, cuenta_padre_codigo,
rango_hijo_inicio, rango_hijo_fin,
reporte_contable_id, categoria_contable_id, prioridad

-- mapeo_cuentas (excepciones por cliente)
cliente_id, codigo_patron, categoria_destino, notas
```

### 5.5 Reportes

```sql
-- reportes
id, cliente_id, nombre, periodo_tipo, fecha_generacion, data_calculada (JSON), pdf_path
```

---

## 6. Reglas de Mapeo Contable (CONTPAQi)

| Cuenta Padre | Rango Hijos | Reporte | Categoría |
|--------------|-------------|---------|-----------|
| 001-100-000 | 101-000-000 a 154-999-999 | Balance | Activos Circulantes |
| 001-200-000 | 155-000-000 a 199-999-999 | Balance | Activos No Circulantes |
| 002-100-000 | 200-000-000 a 209-999-999 | Balance | Pasivo Circulante |
| 002-200-000 | 210-000-000 a 220-999-999 | Balance | Pasivo No Circulante |
| 300-000-000 | - | Balance | Capital Social |
| 310-000-000 | - | Balance | Pérdidas Ejercicios Anteriores |
| 311-000-000 | - | Balance | Utilidades Ejercicios Anteriores |
| 40X-000-000 | 401 a 409 | Edo. Resultados | Ingresos |
| 5XX-000-000 | 500 a 599 | Edo. Resultados | Gastos Operativos |
| 6XX-000-000 | 600 a 699 | Edo. Resultados | Otros Gastos |
| 70X-000-000 | 700 a 799 | Edo. Resultados | Gastos Financieros |

---

## 7. Flujo de Usuario

1. **Crear/seleccionar cliente** - Nombre, logo, giro, moneda
2. **Subir balanzas** - 2+ archivos PDF/Excel/CSV
3. **Detección automática** - Sistema identifica origen (CONTPAQi, etc.)
4. **Clasificación automática** - Mapeo a categorías contables
5. **Revisión de anomalías** - Corregir cuentas mal clasificadas
6. **Limpieza de cuentas** - Desmarcar cuentas a excluir
7. **Procesamiento** - Cálculo de métricas
8. **Dashboard** - Visualización interactiva
9. **Exportar PDF** - Descarga de reporte

---

## 8. Métricas Financieras

### 8.1 Estados Financieros Calculados

- Balance General
- Estado de Resultados
- Flujo de Efectivo (método indirecto)

### 8.2 Métricas por Categoría

**Márgenes:**
- Margen Bruto = Utilidad Bruta / Ingresos
- Margen EBITDA = EBITDA / Ingresos
- Margen Operativo = EBIT / Ingresos
- Margen Neto = Utilidad Neta / Ingresos
- Margen NOPAT = NOPAT / Ingresos
- Margen OCF = Flujo Operación / Ingresos
- Margen FCF = Flujo Libre / Ingresos

**Retorno:**
- ROIC = NOPAT / Capital Invertido
- ROE = Utilidad Neta / Capital
- ROA = Utilidad Neta / Activo Total
- ROCE = EBIT / Capital Empleado

**Eficiencia:**
- Asset Turnover = Ingresos / Activo Total
- Inventory Turnover = Costo Venta / Inventario
- Días Clientes = (Clientes / Ingresos) × 365
- Días Proveedores = (Proveedores / Costo) × 365
- Días Inventario = (Inventario / Costo) × 365
- Ciclo Conversión = Días Clientes + Días Inv. - Días Prov.

**Liquidez:**
- Current Ratio = Activo Circ. / Pasivo Circ.
- Quick Ratio = (Activo Circ. - Inventario) / Pasivo Circ.
- Cash Ratio = Efectivo / Pasivo Circ.

**Solvencia:**
- Net Debt / EBITDA = (Deuda Total - Efectivo) / EBITDA
- Interest Coverage = EBITDA / Gastos Financieros
- Debt Ratio = Deuda Total / Activo Total

**Gestión:**
- Revenue Growth = (Ingreso Actual - Anterior) / Anterior
- Key Score = Crecimiento Ingreso 12m + Margen EBITDA 12m
- CapEx / Revenue = CAPEX / Ingresos
- Effective Tax Rate = Impuestos / EBT

### 8.3 Comparativos

Para cada métrica:
- Valor actual
- Promedio 3 periodos
- Periodo anterior
- Mismo periodo año anterior
- Variación absoluta y porcentual
- Tendencia (Muy positiva → Muy negativa)

---

## 9. Dashboard

### 9.1 Secciones

1. Mensajes Destacados (KPIs + insights)
2. Resumen Mensual
3. Resumen 12m
4. Márgenes
5. Márgenes Deep Dive
6. Resultados
7. Balance
8. Capital de Trabajo
9. Flujo de Efectivo
10. Métricas
11. Indicadores
12. Negocios (por unidad)
13. Estados Financieros

### 9.2 Componentes React

```
components/
├── charts/
│   ├── BarChart.tsx
│   ├── LineChart.tsx
│   ├── StackedBarChart.tsx
│   ├── WaterfallChart.tsx
│   └── ComboChart.tsx
├── cards/
│   ├── KPICard.tsx
│   ├── InsightCard.tsx
│   └── MetricTable.tsx
├── tables/
│   ├── FinancialStatement.tsx
│   └── MetricsGrid.tsx
└── layout/
    ├── DashboardNav.tsx
    ├── PeriodSelector.tsx
    └── ExportButton.tsx
```

---

## 10. Panel Administrativo

### 10.1 Módulos

1. Dashboard admin (estadísticas)
2. Gestión de usuarios
3. Gestión de clientes
4. Catálogo de giros
5. Configuración de umbrales
6. Reglas de mapeo contable
7. Parsers de sistemas
8. Configuración general

### 10.2 Gestión de Empleados (Cliente)

El cliente puede:
- Agregar empleados
- Configurar permisos granulares por empleado
- Permisos disponibles: ver dashboard, ver estados financieros, exportar PDF, etc.

---

## 11. Generación de PDF

### 11.1 Enfoque

Usar Puppeteer/Browsershot para renderizar el dashboard de React a PDF, manteniendo el mismo diseño pixel-perfect.

### 11.2 Estructura (32 páginas)

1. Portada
2. Mensajes Destacados
3. Separador "Resumen"
4. Resumen Mensual
5. Resumen 12m
6. Márgenes
7. Márgenes Deep Dive
8. Separador "Resultados"
9. Resultados
10. Separador "Balance"
11. Balance
12. Capital de Trabajo
13. Separador "Flujo"
14. Flujo de Efectivo
15. Separador "Métricas"
16-17. Métricas
18. Separador "Indicadores"
19. Indicadores
20. Separador "Negocios"
21-22. Negocios por unidad
23. Separador "Estados Financieros"
24-25. Tabla de Métricas
26-27. Estado de Resultados
28-29. Subcategorías Costo/Gasto
30. Balance General
31. Flujo de Efectivo
32. Contraportada

---

## 12. Estructura del Proyecto

```
monthly-platform/
├── backend/                    # Laravel
│   ├── app/
│   │   ├── Http/Controllers/
│   │   ├── Models/
│   │   ├── Services/
│   │   │   ├── Parsers/
│   │   │   │   ├── ParserInterface.php
│   │   │   │   ├── ContpaqiParser.php
│   │   │   │   ├── AspelParser.php
│   │   │   │   └── GenericoParser.php
│   │   │   ├── DetectorFormato.php
│   │   │   ├── ClasificadorCuentas.php
│   │   │   ├── CalculadorMetricas.php
│   │   │   └── GeneradorPdf.php
│   │   └── ...
│   ├── database/migrations/
│   └── routes/api.php
│
└── frontend/                   # React
    ├── src/
    │   ├── components/
    │   ├── pages/
    │   │   ├── Dashboard/
    │   │   ├── Admin/
    │   │   ├── Cliente/
    │   │   └── PdfView/
    │   ├── hooks/
    │   ├── services/
    │   └── utils/
    └── ...
```

---

## 13. Consideraciones Futuras

- Integración directa con APIs de sistemas contables
- Generación de insights con IA
- Comparativas con benchmarks de industria (datos reales)
- App móvil para consulta de reportes
- Alertas automáticas por email cuando métricas salen de rango