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