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

-- 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

-- 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

-- 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

-- 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
16. Separador "Indicadores"
17. Indicadores
18. Separador "Negocios" 21-22. Negocios por unidad
19. Separador "Estados Financieros" 24-25. Tabla de Métricas 26-27. Estado de Resultados 28-29. Subcategorías Costo/Gasto
20. Balance General
21. Flujo de Efectivo
22. 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