Initial commit: Horux Strategy Platform

- Laravel 11 backend with API REST - React 18 + TypeScript + Vite frontend - Multi-parser architecture for accounting systems (CONTPAQi, Aspel, SAP) - 27+ financial metrics calculation - PDF report generation with Browsershot - Complete documentation (10 documents) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 22:24:00 -06:00
commit 4c3dc94ff2
107 changed files with 10701 additions and 0 deletions
--- a/docs/plans/2025-01-31-horux-strategy-design.md
+++ b/docs/plans/2025-01-31-horux-strategy-design.md
@@ -0,0 +1,384 @@
+# 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