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

Horux Strategy Platform - Plan de Implementación

Fecha: 2025-01-31 Documento de diseño: 2025-01-31-horux-strategy-design.md

---

Fases de Implementación

FASE 1: Fundamentos (Backend)

1.1 Configuración del proyecto Laravel

• Crear proyecto Laravel 11
• Configurar base de datos (MySQL/PostgreSQL)
• Instalar y configurar Laravel Sanctum
• Configurar CORS para React

1.2 Migraciones de base de datos

• Tabla users (con campo role)
• Tabla clientes
• Tabla giros
• Tabla permisos_empleado
• Tabla reportes_contables
• Tabla categorias_contables
• Tabla umbrales
• Tabla balanzas
• Tabla cuentas
• Tabla reglas_mapeo
• Tabla mapeo_cuentas
• Tabla reportes
• Seeders para catálogos iniciales (giros, categorías, reglas CONTPAQi)

1.3 Modelos y relaciones

• User (con roles)
• Cliente
• Giro
• PermisoEmpleado
• Umbral
• Balanza
• Cuenta
• ReglaMappeo
• Reporte

1.4 Sistema de autenticación

• Login / Logout
• Registro (solo admin puede crear usuarios)
• Middleware por rol
• Policies para autorización

---

FASE 2: Parser de Balanzas

2.1 Arquitectura de parsers

• Crear ParserInterface.php
• Crear DetectorFormato.php
• Implementar ContpaqiParser.php
• Crear ParserGenerico.php (CSV/Excel)

2.2 Procesamiento de archivos

• Endpoint para upload de archivos
• Extracción de texto de PDF
• Parsing de estructura CONTPAQi
• Normalización a formato interno
• Almacenamiento en tabla cuentas

2.3 Clasificación automática

• Crear ClasificadorCuentas.php
• Aplicar reglas de mapeo
• Detectar anomalías
• Marcar cuentas que requieren revisión

---

FASE 3: Motor de Cálculo

3.1 Calculador de estados financieros

• Crear CalculadorMetricas.php
• Calcular Balance General
• Calcular Estado de Resultados
• Calcular Flujo de Efectivo (método indirecto)

3.2 Cálculo de métricas

• Métricas de márgenes (7 métricas)
• Métricas de retorno (4 métricas)
• Métricas de eficiencia (6 métricas)
• Métricas de liquidez (3 métricas)
• Métricas de solvencia (3 métricas)
• Métricas de gestión (4 métricas)

3.3 Comparativos

• Calcular promedio 3 periodos
• Comparar con periodo anterior
• Comparar con año anterior
• Calcular variaciones
• Determinar tendencia según umbrales

---

FASE 4: API REST

4.1 Endpoints de autenticación

• POST /api/login
• POST /api/logout
• GET /api/user

4.2 Endpoints de clientes

• GET /api/clientes
• POST /api/clientes
• GET /api/clientes/{id}
• PUT /api/clientes/{id}
• DELETE /api/clientes/{id}

4.3 Endpoints de balanzas

• POST /api/clientes/{id}/balanzas (upload)
• GET /api/clientes/{id}/balanzas
• GET /api/balanzas/{id}/cuentas
• PUT /api/balanzas/{id}/cuentas (actualizar exclusiones)
• PUT /api/cuentas/{id}/clasificacion (corregir anomalía)

4.4 Endpoints de reportes

• POST /api/clientes/{id}/reportes (generar)
• GET /api/clientes/{id}/reportes
• GET /api/reportes/{id}
• GET /api/reportes/{id}/pdf

4.5 Endpoints administrativos

• CRUD /api/admin/usuarios
• CRUD /api/admin/giros
• CRUD /api/admin/umbrales
• CRUD /api/admin/reglas-mapeo

---

FASE 5: Frontend - Fundamentos

5.1 Configuración del proyecto React

• Crear proyecto con Vite + TypeScript
• Configurar React Router
• Configurar Axios para API
• Configurar Recharts
• Configurar Tailwind CSS

5.2 Autenticación

• Página de Login
• Context de autenticación
• Rutas protegidas por rol
• Interceptor para tokens

5.3 Layout base

• Sidebar de navegación
• Header con usuario
• Layout para admin
• Layout para cliente

---

FASE 6: Frontend - Flujo Principal

6.1 Gestión de clientes

• Lista de clientes
• Formulario crear/editar cliente
• Subida de logo

6.2 Subida de balanzas

• Componente de upload (drag & drop)
• Preview de archivos
• Indicador de progreso
• Detección de sistema origen

6.3 Revisión y limpieza

• Vista de anomalías con corrección
• Lista de cuentas con checkboxes
• Filtros y búsqueda
• Guardar exclusiones

---

FASE 7: Frontend - Dashboard

7.1 Componentes de gráficas

• BarChart
• LineChart
• StackedBarChart
• WaterfallChart
• ComboChart

7.2 Componentes de cards

• KPICard (con semáforo)
• InsightCard
• MetricTable

7.3 Secciones del dashboard

• Mensajes Destacados
• Resumen Mensual
• Resumen 12m
• Márgenes
• Márgenes Deep Dive
• Resultados
• Balance
• Capital de Trabajo
• Flujo de Efectivo
• Métricas
• Indicadores
• Negocios
• Estados Financieros

---

FASE 8: Generación de PDF

8.1 Backend

• Instalar Browsershot
• Crear GeneradorPdf.php
• Endpoint GET /api/reportes/{id}/pdf

8.2 Frontend

• Vista PdfView con todas las páginas
• Estilos específicos para impresión
• Separadores de sección
• Portada y contraportada

---

FASE 9: Panel Administrativo

9.1 Dashboard admin

• Estadísticas generales
• Alertas pendientes

9.2 Gestión de usuarios

• CRUD de usuarios
• Asignación de roles

9.3 Configuración

• Editor de umbrales
• Editor de reglas de mapeo
• Editor de giros

---

FASE 10: Funcionalidades de Cliente

10.1 Gestión de empleados

• Lista de empleados
• Crear empleado
• Configurar permisos

10.2 Configuración

• Exclusiones guardadas
• Preferencias de reporte

---

FASE 11: Testing y Refinamiento

11.1 Testing

• Tests unitarios del motor de cálculo
• Tests de parsers
• Tests de API
• Tests E2E del flujo principal

11.2 Refinamiento

• Optimización de rendimiento
• Manejo de errores
• Validaciones
• UX/UI polish

---

Prioridad de Implementación

1. MVP (Fases 1-4, 5-7): Sistema funcional con CONTPAQi, dashboard básico
2. PDF (Fase 8): Exportación de reportes
3. Admin (Fase 9): Panel de configuración
4. Multi-usuario (Fase 10): Funcionalidades de cliente
5. Calidad (Fase 11): Testing y refinamiento

---

Archivos Clave a Crear

Backend (Laravel)

app/
├── Http/Controllers/
│   ├── AuthController.php
│   ├── ClienteController.php
│   ├── BalanzaController.php
│   ├── CuentaController.php
│   ├── ReporteController.php
│   └── Admin/
│       ├── UsuarioController.php
│       ├── UmbralController.php
│       └── ReglaMappeoController.php
├── Models/
│   ├── User.php
│   ├── Cliente.php
│   ├── Balanza.php
│   ├── Cuenta.php
│   ├── Reporte.php
│   └── ...
├── Services/
│   ├── Parsers/
│   │   ├── ParserInterface.php
│   │   ├── ContpaqiParser.php
│   │   └── DetectorFormato.php
│   ├── ClasificadorCuentas.php
│   ├── CalculadorMetricas.php
│   └── GeneradorPdf.php
└── ...

Frontend (React)

src/
├── components/
│   ├── charts/
│   │   ├── BarChart.tsx
│   │   ├── LineChart.tsx
│   │   ├── StackedBarChart.tsx
│   │   ├── WaterfallChart.tsx
│   │   └── ComboChart.tsx
│   ├── cards/
│   │   ├── KPICard.tsx
│   │   └── InsightCard.tsx
│   ├── forms/
│   │   ├── ClienteForm.tsx
│   │   └── UploadBalanza.tsx
│   └── layout/
│       ├── Sidebar.tsx
│       └── Header.tsx
├── pages/
│   ├── Login.tsx
│   ├── Dashboard/
│   │   ├── index.tsx
│   │   ├── Resumen.tsx
│   │   ├── Margenes.tsx
│   │   └── ...
│   ├── Admin/
│   │   ├── Usuarios.tsx
│   │   └── Umbrales.tsx
│   └── PdfView/
│       └── index.tsx
├── hooks/
│   ├── useAuth.ts
│   ├── useCliente.ts
│   └── useReporte.ts
├── services/
│   └── api.ts
└── types/
    └── index.ts