commit c1321c3f0c6defb7469978554a8b148eb106f7bb Author: HORUX360 Date: Sat Jan 31 09:50:44 2026 +0000 Initial commit: Horux Strategy project setup - Add project design document with complete specifications - Configure Turborepo monorepo structure - Add README with project overview and setup instructions - Configure .gitignore for Node.js/TypeScript project - Set up pnpm workspace configuration Co-Authored-By: Claude Opus 4.5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ea15509 --- /dev/null +++ b/.gitignore @@ -0,0 +1,70 @@ +# Dependencies +node_modules/ +.pnpm-store/ + +# Build outputs +dist/ +build/ +.next/ +out/ + +# Environment files +.env +.env.local +.env.*.local +*.env + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + +# Testing +coverage/ +.nyc_output/ + +# Turbo +.turbo/ + +# Cache +.cache/ +*.cache + +# Temp files +tmp/ +temp/ +*.tmp + +# Secrets (NEVER commit these) +*.pem +*.key +*.cer +credentials*.json +secrets*.json + +# Database +*.db +*.sqlite +*.sqlite3 + +# Uploads +uploads/ +storage/ + +# Generated files +generated/ +*.generated.* diff --git a/README.md b/README.md new file mode 100644 index 0000000..cf477fe --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# Horux Strategy + +**CFO Digital para Empresas Mexicanas** + +Plataforma SaaS de inteligencia financiera que transforma datos fiscales y contables en insights estratégicos accionables. + +## Características Principales + +- 📊 **Dashboards en tiempo real** - KPIs financieros actualizados automáticamente +- 📄 **Reportes ejecutivos con IA** - Narrativas inteligentes generadas con DeepSeek +- 🔗 **Integraciones automáticas** - SAT (FIEL), CONTPAQi, Aspel, Odoo, Alegra, SAP +- 📈 **+50 métricas financieras** - Core, Startup (MRR, CAC, LTV), Enterprise (EBITDA, ROI) +- 🔔 **Alertas inteligentes** - Detección automática de anomalías y riesgos +- 💰 **50% más económico** que la competencia + +## Stack Tecnológico + +- **Frontend**: Next.js 14, TypeScript, Tailwind CSS, Zustand +- **Backend**: Node.js, Express, TypeScript +- **Base de datos**: PostgreSQL (multi-tenant por schema) +- **Cache/Colas**: Redis, BullMQ +- **Storage**: MinIO / AWS S3 +- **Monorepo**: Turborepo + pnpm +- **IA**: DeepSeek API + +## Estructura del Proyecto + +``` +horux-strategy/ +├── apps/ +│ ├── web/ # Frontend Next.js +│ └── api/ # Backend Express +├── packages/ +│ ├── shared/ # Tipos y utilidades compartidas +│ ├── database/ # Schemas y migraciones +│ └── ui/ # Componentes UI reutilizables +├── docs/ +│ └── plans/ # Documentos de diseño +├── docker/ # Configuración Docker +└── scripts/ # Scripts de utilidad +``` + +## Requisitos + +- Node.js 20+ +- pnpm 8+ +- PostgreSQL 15+ +- Redis 7+ +- Docker (opcional, recomendado) + +## Instalación + +```bash +# Clonar repositorio +git clone https://git.consultoria-as.com/consultoria-as/HoruxStrategy.git +cd HoruxStrategy + +# Instalar dependencias +pnpm install + +# Configurar variables de entorno +cp .env.example .env +# Editar .env con tus credenciales + +# Iniciar servicios (Docker) +docker-compose up -d + +# Ejecutar migraciones +pnpm db:migrate + +# Iniciar desarrollo +pnpm dev +``` + +## Scripts Disponibles + +| Script | Descripción | +|--------|-------------| +| `pnpm dev` | Iniciar todos los servicios en modo desarrollo | +| `pnpm build` | Compilar todos los paquetes | +| `pnpm test` | Ejecutar tests | +| `pnpm lint` | Ejecutar linter | +| `pnpm db:migrate` | Ejecutar migraciones de BD | +| `pnpm db:seed` | Poblar BD con datos de prueba | + +## Documentación + +- [Documento de Diseño](./docs/plans/2026-01-31-horux-strategy-design.md) +- [API Documentation](./docs/api/) (próximamente) +- [Guía de Contribución](./CONTRIBUTING.md) (próximamente) + +## Planes y Precios + +| Plan | Precio | Para empresas con ingresos | +|------|--------|---------------------------| +| Startup | $5,999 MXN/mes | < $100M MXN/año | +| PYME | $6,499 MXN/mes | < $400M MXN/año | +| Enterprise | $8,499 MXN/mes | < $1,000M MXN/año | +| Corporativo | $9,999 MXN/mes | > $1,000M MXN/año | + +## Licencia + +Propietario - HORUX360 © 2026 + +--- + +Desarrollado por [HORUX360](https://horux360.com) diff --git a/docs/plans/2026-01-31-horux-strategy-design.md b/docs/plans/2026-01-31-horux-strategy-design.md new file mode 100644 index 0000000..22e32d2 --- /dev/null +++ b/docs/plans/2026-01-31-horux-strategy-design.md @@ -0,0 +1,701 @@ +# Horux Strategy - Documento de Diseño + +**Versión:** 1.0 +**Fecha:** 31 de Enero, 2026 +**Autor:** HORUX360 +**Estado:** Aprobado para implementación + +--- + +## Tabla de Contenidos + +1. [Resumen Ejecutivo](#1-resumen-ejecutivo) +2. [Decisiones de Producto](#2-decisiones-de-producto) +3. [Arquitectura General](#3-arquitectura-general) +4. [Métricas y KPIs](#4-métricas-y-kpis) +5. [Pipeline de Reportes con IA](#5-pipeline-de-reportes-con-ia) +6. [Integraciones](#6-integraciones) +7. [Estructura de Base de Datos](#7-estructura-de-base-de-datos) +8. [Planes y Pricing](#8-planes-y-pricing) +9. [Flujos de Usuario](#9-flujos-de-usuario) +10. [Roadmap de Implementación](#10-roadmap-de-implementación) + +--- + +## 1. Resumen Ejecutivo + +### 1.1 Visión del Producto + +Horux Strategy es una plataforma SaaS de inteligencia financiera que transforma datos fiscales y contables en insights estratégicos accionables. Combina dashboards en tiempo real con reportes ejecutivos generados por IA, posicionándose como el "CFO Digital" para empresas mexicanas. + +### 1.2 Propuesta de Valor + +- **50% más económico que Monthly.la** (competidor principal) +- **Automatización completa**: Conexión directa con SAT y 5 sistemas contables +- **Dashboards en tiempo real** + **Reportes ejecutivos con IA** +- **+50 métricas financieras** organizadas en módulos (Core, Startup, Enterprise) +- **Plataforma modular** que se adapta a PYMES, startups y empresas medianas + +### 1.3 Diferenciadores Clave + +| Aspecto | Monthly.la | Horux Strategy | +|---------|------------|----------------| +| Precio | $11,999 - $19,999/mes | $5,999 - $9,999/mes | +| Dashboards | No (solo reportes) | Sí, tiempo real | +| Integraciones | Manual | Automáticas (5 sistemas) | +| Frecuencia reportes | Mensual | Bajo demanda | +| Alertas | No | Sí, automáticas | +| API | No | Sí (planes Pro+) | + +--- + +## 2. Decisiones de Producto + +### 2.1 Resumen de Decisiones + +| Aspecto | Decisión | +|---------|----------| +| **Público objetivo** | Modular: PYMES, startups, empresas medianas | +| **Fuentes de datos** | SAT (FIEL) + Sistemas contables (5) | +| **Core value** | Dashboards live + Reportes ejecutivos con IA | +| **Relación con Horux360** | Productos completamente separados | +| **Modelo de pricing** | Suscripción mensual por tamaño de empresa | +| **Stack tecnológico** | Next.js 14 + Express + PostgreSQL + Turborepo | +| **IA** | DeepSeek API | +| **Timeline** | Máxima velocidad (16 semanas) | + +### 2.2 Público Objetivo + +#### Segmento 1: PYMES Tradicionales +- Restaurantes, comercios, servicios +- Necesitan visibilidad básica de flujo de caja y rentabilidad +- Buscan evitar sorpresas fiscales + +#### Segmento 2: Startups con Inversionistas +- Empresas tecnológicas en crecimiento +- Necesitan métricas de crecimiento (MRR, CAC, LTV, runway) +- Reportes para inversionistas + +#### Segmento 3: Empresas Medianas +- Operaciones establecidas +- Necesitan estados financieros completos, presupuestos, comparativos +- Reportes para junta directiva + +--- + +## 3. Arquitectura General + +### 3.1 Diagrama de Arquitectura + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ HORUX STRATEGY │ +├─────────────────────────────────────────────────────────────────┤ +│ FRONTEND (Next.js 14) │ +│ ├── Dashboard Hub (métricas en tiempo real) │ +│ ├── Centro de Reportes (generación y descarga) │ +│ ├── Configuración de Empresa │ +│ └── Gestión de Integraciones │ +├─────────────────────────────────────────────────────────────────┤ +│ BACKEND (Express + TypeScript) │ +│ ├── Auth Service (JWT + roles) │ +│ ├── Integration Service (SAT, contables) │ +│ ├── Analytics Engine (cálculo de métricas) │ +│ ├── Report Generator (plantillas + IA) │ +│ └── Scheduler (sync automático, alertas) │ +├─────────────────────────────────────────────────────────────────┤ +│ DATA LAYER │ +│ ├── PostgreSQL (multi-tenant por schema) │ +│ ├── Redis (cache de métricas, colas) │ +│ └── S3/MinIO (reportes PDF generados) │ +├─────────────────────────────────────────────────────────────────┤ +│ INTEGRACIONES EXTERNAS │ +│ ├── SAT (descarga CFDI vía FIEL) │ +│ ├── Sistemas Contables (CONTPAQi, Aspel, Odoo, Alegra, SAP) │ +│ └── DeepSeek API (generación narrativa) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 3.2 Stack Tecnológico + +| Componente | Tecnología | +|------------|------------| +| Frontend | Next.js 14, TypeScript, Tailwind CSS, Zustand | +| Backend | Node.js, Express, TypeScript | +| Base de datos | PostgreSQL (multi-tenant por schema) | +| Cache/Colas | Redis, BullMQ | +| Storage | MinIO / AWS S3 | +| Monorepo | Turborepo + pnpm | +| Contenedores | Docker Compose | +| IA | DeepSeek API | +| Gráficas | Recharts (frontend), Chart.js (server-side) | +| PDF | Puppeteer | + +### 3.3 Arquitectura Multi-tenant + +- **Estrategia**: Schema por tenant en PostgreSQL +- **Beneficios**: + - Aislamiento de datos garantizado a nivel BD + - Facilita backups y restauración por cliente + - Performance consistente + - Cumplimiento de privacidad + +--- + +## 4. Métricas y KPIs + +### 4.1 Módulo Core (Todos los planes) + +| Métrica | Fuente | Requisitos Usuario | Cálculo | +|---------|--------|-------------------|---------| +| Ingresos totales | SAT | Conectar FIEL | Σ CFDIs emitidos tipo "I" | +| Gastos totales | SAT | Conectar FIEL | Σ CFDIs recibidos | +| Utilidad bruta | SAT | Clasificar costos | Ingresos - Costo de ventas | +| Utilidad neta | SAT + Contable | Clasificar gastos | Utilidad bruta - Gastos - Impuestos | +| Flujo de caja | SAT | Ninguno | Complementos de pago recibidos - pagados | +| Cuentas por cobrar | SAT | Ninguno | Facturas emitidas sin pago | +| Cuentas por pagar | SAT | Ninguno | Facturas recibidas sin pago | +| Antigüedad CxC | SAT | Ninguno | Días desde emisión, agrupado 0-30, 31-60, 61-90, 90+ | +| Antigüedad CxP | SAT | Ninguno | Días desde recepción sin pago | +| IVA por pagar | SAT | Ninguno | IVA trasladado - IVA acreditable | +| IVA a favor | SAT | Ninguno | Cuando acreditable > trasladado | + +### 4.2 Módulo Startup (Plan PYME+) + +| Métrica | Fuente | Requisitos Usuario | Cálculo | +|---------|--------|-------------------|---------| +| MRR | SAT + Config | Marcar clientes recurrentes | Σ ingresos recurrentes mensuales | +| ARR | Derivado | Igual que MRR | MRR × 12 | +| Runway | SAT + Config | Ingresar saldo bancario | Saldo ÷ Burn rate | +| Burn rate | SAT | Ninguno | Promedio (Gastos - Ingresos) mensual | +| Net Burn | SAT | Ninguno | Gastos - Ingresos mensual | +| Gross Burn | SAT | Ninguno | Solo gastos mensuales | +| CAC | Config | Gasto marketing + clientes nuevos | Gasto MKT ÷ Clientes nuevos | +| LTV | SAT + Config | Marcar recurrentes + histórico | (ARPU × Margen) ÷ Churn | +| Churn rate | Config | Registrar clientes activos/cancelados | Perdidos ÷ Inicio período | +| Growth rate MoM | SAT | Ninguno | (Actual - Anterior) ÷ Anterior | +| Growth rate YoY | SAT | Ninguno | (Año actual - Año anterior) ÷ Año anterior | +| LTV:CAC Ratio | Derivado | Igual que LTV y CAC | LTV ÷ CAC | +| Months to recover CAC | Derivado | Igual que CAC | CAC ÷ (ARPU × Margen) | + +### 4.3 Módulo Enterprise (Plan Enterprise+) + +| Métrica | Fuente | Requisitos Usuario | Cálculo | +|---------|--------|-------------------|---------| +| EBITDA | Contable | Conectar sistema contable | Utilidad + Depreciación + Amortización | +| Margen EBITDA | Derivado | Igual que EBITDA | EBITDA ÷ Ingresos | +| ROI | Contable + Config | Ingresar inversión | (Ganancia - Inversión) ÷ Inversión | +| ROE | Contable | Conectar contable | Utilidad neta ÷ Capital contable | +| ROA | Contable | Conectar contable | Utilidad neta ÷ Activos totales | +| Razón corriente | Contable | Conectar contable | Activos circulantes ÷ Pasivos circulantes | +| Prueba ácida | Contable | Conectar contable | (AC - Inventarios) ÷ PC | +| Endeudamiento | Contable | Conectar contable | Pasivos ÷ Activos | +| Apalancamiento | Contable | Conectar contable | Pasivos ÷ Capital | +| Punto equilibrio | SAT + Config | Clasificar costos fijos/variables | Fijos ÷ (1 - Variables/Ventas) | +| Margen contribución | SAT + Config | Clasificar variables | Ventas - Costos variables | +| Presupuesto vs Real | Config | Cargar presupuesto | Variación absoluta y % | +| Forecast | SAT + IA | Histórico 6+ meses | Proyección estadística + IA | +| Working capital | Contable | Conectar contable | AC - PC | +| DSO | SAT | Ninguno | (CxC ÷ Ventas crédito) × Días | +| DPO | SAT | Ninguno | (CxP ÷ Compras crédito) × Días | +| Cash Conversion Cycle | Derivado | Ninguno | DSO + Days Inventory - DPO | + +--- + +## 5. Pipeline de Reportes con IA + +### 5.1 Tipos de Reportes + +| Reporte | Frecuencia | Audiencia | Contenido | +|---------|------------|-----------|-----------| +| Ejecutivo Mensual | Mensual | CEO/Dueño | Resumen, tendencias, alertas, recomendaciones | +| Para Inversionistas | Mensual/Trimestral | Inversionistas | Métricas startup, runway, crecimiento | +| Junta Directiva | Trimestral | Consejo | Análisis profundo, comparativos, proyecciones | +| Flash Semanal | Semanal | Operaciones | KPIs clave, alertas urgentes | +| Fiscal | Mensual | Contador/CFO | IVA, retenciones, cumplimiento | + +### 5.2 Pipeline de Generación (10 Fases) + +#### FASE 1: Trigger y Scheduling +- Disparadores: Cron, manual, evento, fecha programada +- Cola de trabajos con BullMQ +- Prioridades y reintentos + +#### FASE 2: Extracción de Datos +- Datos del período actual +- Datos históricos (YoY, MoM) +- Contexto del cliente (industria, tamaño, metas) +- Datos del sistema contable + +#### FASE 3: Cálculo de Métricas +- Ejecutar fórmulas de métricas +- Calcular variaciones +- Detectar anomalías (reglas) +- Clasificar insights (positivo, neutral, negativo) + +#### FASE 4: Preparación de Contexto para IA +- Construcción de JSON estructurado +- Selección de plantilla de prompt +- Personalización por tipo de reporte + +#### FASE 5: Llamadas a DeepSeek API +- Llamadas paralelas por sección +- Configuración: temperature=0.3, max_tokens variable +- Manejo de errores y fallbacks +- Validación de respuestas (anti-alucinación) + +#### FASE 6: Generación de Visualizaciones +- Gráficas con Chart.js server-side +- Output PNG/SVG para PDF +- Temas consistentes con branding + +#### FASE 7: Composición del Documento +- Motor de plantillas (Puppeteer HTML→PDF) +- Inyección de textos, métricas, gráficas +- Formatos: PDF, Excel, PowerPoint + +#### FASE 8: Post-procesamiento y Calidad +- Validación del PDF +- Detección de alucinaciones (segunda capa) +- Scoring de calidad + +#### FASE 9: Almacenamiento y Entrega +- Storage en S3/MinIO +- Email automático +- Notificación in-app +- Link de descarga + +#### FASE 10: Feedback y Mejora Continua +- Rating del reporte +- Feedback por sección +- Mejora de prompts +- Analytics del sistema + +### 5.3 Estructura del Reporte Ejecutivo + +``` +┌─────────────────────────────────────────────────────────────┐ +│ HORUX STRATEGY - Reporte Ejecutivo │ +│ [Nombre Empresa] | [Mes Año] │ +├─────────────────────────────────────────────────────────────┤ +│ 📊 RESUMEN EJECUTIVO (IA) │ +│ [Narrativa generada con insights principales] │ +├─────────────────────────────────────────────────────────────┤ +│ 💰 RESULTADOS DEL MES │ +│ [KPIs principales con variaciones] │ +├─────────────────────────────────────────────────────────────┤ +│ 📈 GRÁFICAS │ +│ [Visualizaciones de tendencias y composición] │ +├─────────────────────────────────────────────────────────────┤ +│ ⚠️ ALERTAS Y RIESGOS (IA) │ +│ [Problemas detectados automáticamente] │ +├─────────────────────────────────────────────────────────────┤ +│ 💡 RECOMENDACIONES (IA) │ +│ [Acciones sugeridas basadas en datos] │ +├─────────────────────────────────────────────────────────────┤ +│ 📅 PRÓXIMO MES - QUÉ ESPERAR │ +│ [Proyecciones y eventos importantes] │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 6. Integraciones + +### 6.1 SAT (Solo FIEL) + +**Autenticación**: Exclusivamente e.firma (FIEL) +- Archivos: .cer + .key + contraseña +- Contraseña NO se almacena +- .key encriptado con AES-256 + +**Seguridad**: +- Validar vigencia del certificado +- Verificar que no esté revocado +- Alertar 30 días antes de expiración + +**Sincronización**: +- Inicial: últimos 12-72 meses +- Incremental: cada 2-8 horas (según plan) +- Delta: solo CFDIs nuevos + +### 6.2 Sistemas Contables + +| Sistema | Método de Conexión | Datos | +|---------|-------------------|-------| +| **CONTPAQi** | SDK/BD directa + Agente Windows | Catálogo, pólizas, balanza, auxiliares | +| **Aspel** | Firebird/SQL Server + Agente | COI, SAE, balanza, CxC/CxP | +| **Odoo** | API XML-RPC/JSON-RPC | Cuentas, moves, payments, partners | +| **Alegra** | API REST (OAuth 2.0) | Invoices, bills, payments, contacts | +| **SAP B1** | Service Layer REST API | Chart of accounts, journals, invoices | + +### 6.3 Agente Local (Horux Sync Agent) + +Para CONTPAQi y Aspel on-premise: +- Instalador Windows (.msi) +- Servicio Windows auto-inicio +- Comunicación siempre saliente (no requiere abrir puertos) +- Datos encriptados en tránsito y reposo +- Auto-actualización + +### 6.4 Arquitectura de Conectores + +``` +┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ Conector │ │ Adapter │ │ Modelo │ +│ (por sistema) │───▶│ (normaliza) │───▶│ Unificado │ +└─────────────────┘ └──────────────────┘ └──────────────────┘ +``` + +Interfaz común: `IConnector` +- validateCredentials() +- testConnection() +- getAccounts(), getTransactions(), getJournalEntries() +- syncIncremental(), syncFull() + +--- + +## 7. Estructura de Base de Datos + +### 7.1 Schema Public (Compartido) + +**Tablas principales**: +- `tenants` - Empresas registradas +- `users` - Usuarios de la plataforma +- `user_sessions` - Sesiones activas +- `plans` - Planes de suscripción +- `subscriptions` - Relación tenant-plan +- `subscription_history` - Historial de cambios +- `payment_methods` - Métodos de pago +- `invoices` - Facturas de cobro +- `audit_log` - Log de auditoría global +- `background_jobs` - Jobs en cola +- `api_keys` - Llaves de API +- `webhooks` - Webhooks configurados +- `feature_flags` - Feature flags + +### 7.2 Schema Tenant (Por Empresa) + +**Tablas de datos fiscales**: +- `sat_credentials` - Credenciales FIEL encriptadas +- `sat_sync_history` - Historial de sincronizaciones +- `cfdis` - Comprobantes fiscales +- `complementos_pago` - Complementos de pago +- `documentos_pagados` - Relación pago-CFDI + +**Tablas de datos financieros**: +- `transactions` - Modelo unificado de transacciones +- `payments` - Pagos registrados +- `contacts` - Clientes y proveedores +- `accounts` - Cuentas contables +- `journal_entries` - Pólizas contables +- `journal_entry_lines` - Movimientos de pólizas +- `categories` - Categorías de clasificación +- `cost_centers` - Centros de costo +- `projects` - Proyectos +- `bank_accounts` - Cuentas bancarias +- `bank_transactions` - Movimientos bancarios + +**Tablas de análisis**: +- `metrics_cache` - Métricas precalculadas +- `metrics_history` - Historial para tendencias +- `goals` - Metas y objetivos +- `alerts` - Alertas generadas +- `alert_rules` - Reglas de alertas +- `budgets` - Presupuestos +- `budget_lines` - Líneas de presupuesto +- `recurring_revenue_config` - Configuración MRR + +**Tablas de reportes**: +- `reports` - Reportes generados +- `report_schedules` - Reportes programados +- `report_feedback` - Feedback de reportes + +**Tablas de configuración**: +- `integration_configs` - Configuración de integraciones +- `integration_sync_history` - Historial de sync +- `settings` - Configuración general +- `categorization_rules` - Reglas de categorización +- `dashboard_configs` - Configuración de dashboards + +**Tablas auxiliares**: +- `attachments` - Archivos adjuntos +- `notes` - Notas y comentarios +- `activity_log` - Actividad del usuario +- `user_notifications` - Notificaciones +- `exports` - Exportaciones + +--- + +## 8. Planes y Pricing + +### 8.1 Estructura de Precios + +| Plan | Precio Mensual | Precio Anual | Ingresos Anuales | +|------|---------------|--------------|------------------| +| **STARTUP** | $5,999 MXN | $59,990 MXN | < $100M MXN | +| **PYME** | $6,499 MXN | $64,990 MXN | < $400M MXN | +| **ENTERPRISE** | $8,499 MXN | $84,990 MXN | < $1,000M MXN | +| **CORPORATIVO** | $9,999 MXN | $99,990 MXN | > $1,000M MXN | + +**Comparativa con Monthly.la** (50% más económico): +- Monthly.la Pequeña: $11,999 → Horux: $5,999 +- Monthly.la Mediana: $12,999 → Horux: $6,499 +- Monthly.la Grande: $16,999 → Horux: $8,499 +- Monthly.la Extra: $19,999 → Horux: $9,999 + +### 8.2 Features por Plan + +| Feature | STARTUP | PYME | ENTERPRISE | CORPORATIVO | +|---------|---------|------|------------|-------------| +| Usuarios incluidos | 3 | 5 | 10 | Ilimitados | +| RFCs conectados | 1 | 2 | 5 | 10 | +| SAT (FIEL) | ✅ | ✅ | ✅ | ✅ | +| CONTPAQi/Aspel | ✅ | ✅ | ✅ | ✅ | +| Odoo/Alegra | ❌ | ✅ | ✅ | ✅ | +| SAP Business One | ❌ | ❌ | ✅ | ✅ | +| Métricas totales | +40 | +50 | +50 | +50 | +| Módulo Core | ✅ | ✅ | ✅ | ✅ | +| Módulo Startup | ✅ | ✅ | ✅ | ✅ | +| Módulo Enterprise | ❌ | ✅ | ✅ | ✅ | +| Reportes/mes | 5 | 15 | 30 | Ilimitados | +| Historial datos | 24 meses | 36 meses | 60 meses | Ilimitado | +| API | ❌ | Lectura | Completa | Completa | +| Soporte | Email | Chat | Prioritario | Dedicado | + +### 8.3 Trial + +- **Duración**: 14 días +- **Acceso**: Plan PYME completo +- **Tarjeta**: No requerida +- **Ofertas conversión**: 17% descuento anual, 20% primeros 3 meses + +--- + +## 9. Flujos de Usuario + +### 9.1 Mapa de Navegación + +``` +SIDEBAR: +├── 🏠 Dashboard +├── 📊 Métricas (Core, Startup, Enterprise) +├── 📄 Reportes (Generar, Historial, Programados) +├── 💰 Transacciones (Ingresos, Gastos, CxC, CxP) +├── 🧾 CFDIs (Emitidos, Recibidos, Complementos) +├── 👥 Contactos (Clientes, Proveedores) +├── 🔗 Integraciones (SAT, Contables) +├── 🔔 Alertas +├── 📈 Presupuestos +└── ⚙️ Configuración +``` + +### 9.2 Flujo de Onboarding + +1. **Registro**: Email + contraseña o OAuth +2. **Información empresa**: RFC, industria, tamaño, ingresos +3. **Conectar SAT**: Upload FIEL (.cer, .key, contraseña) +4. **Sincronización**: Descarga automática de CFDIs +5. **Sistema contable** (opcional): Seleccionar y configurar +6. **¡Listo!**: Dashboard con métricas + +### 9.3 Pantallas Principales + +- **Dashboard**: KPIs, gráficas, alertas, acciones rápidas +- **Métricas**: Tabs por módulo, gráficas de tendencia, detalles +- **Generar Reporte**: Selección tipo, período, opciones, generación +- **Transacciones**: Lista filtrable, detalles, categorización +- **CFDIs**: Lista, búsqueda, XML, complementos de pago +- **Integraciones**: Estado de conexiones, configuración, sync manual + +--- + +## 10. Roadmap de Implementación + +### 10.1 Resumen de Fases + +| Fase | Nombre | Duración | Equipos | +|------|--------|----------|---------| +| 1 | Foundation | 2 semanas | 3 | +| 2 | Core MVP | 4 semanas | 4 | +| 3 | Integraciones | 4 semanas | 5 | +| 4 | IA y Reportes | 3 semanas | 3 | +| 5 | Scale & Polish | 3 semanas | 4 | +| **Total** | | **16 semanas** | | + +### 10.2 Fase 1: Foundation (Semanas 1-2) + +**Equipo A: Infraestructura** +- Setup monorepo Turborepo +- Configurar PostgreSQL, Redis, MinIO +- Docker Compose dev +- CI/CD pipeline básico + +**Equipo B: Auth & Tenants** +- Sistema JWT + refresh tokens +- Registro, login, reset password +- Multi-tenant middleware +- Creación schemas tenant + +**Equipo C: Frontend Base** +- Setup Next.js 14 +- Tailwind + componentes UI +- Layout principal +- Sistema de rutas + +**Entregables**: +- ✅ Repo configurado y funcionando +- ✅ Auth completo con multi-tenant +- ✅ Usuario puede registrarse y ver dashboard vacío + +### 10.3 Fase 2: Core MVP (Semanas 3-6) + +**Equipo A: Integración SAT** +- Upload y validación FIEL +- Conexión Web Service SAT +- Descarga masiva CFDIs +- Parser XML, sync incremental + +**Equipo B: Motor de Métricas** +- Modelo de transacciones +- Cálculo métricas Core +- Cache de métricas +- API endpoints + +**Equipo C: Dashboard Frontend** +- Dashboard principal +- KPI cards, gráficas +- Selector período, comparativos + +**Equipo D: Gestión de Datos** +- CRUD Contactos, Categorías +- Vista transacciones, CFDIs +- Filtros, búsqueda, exportar + +**Entregables**: +- ✅ Usuario conecta SAT con FIEL +- ✅ CFDIs se descargan automáticamente +- ✅ Dashboard muestra métricas Core + +### 10.4 Fase 3: Integraciones (Semanas 7-10) + +**5 equipos paralelos**: +- Equipo A: CONTPAQi (SDK + Agente) +- Equipo B: Aspel (Firebird + Agente) +- Equipo C: Odoo (XML-RPC) +- Equipo D: Alegra (REST API) +- Equipo E: SAP B1 + Métricas avanzadas + +**Entregables**: +- ✅ 5 integraciones contables funcionando +- ✅ Agente local disponible +- ✅ Todas las métricas (+50) calculándose + +### 10.5 Fase 4: IA y Reportes (Semanas 11-13) + +**Equipo A: Pipeline IA** +- Integración DeepSeek API +- Construcción de contexto +- Prompt templates +- Validación respuestas + +**Equipo B: Generación Reportes** +- Motor gráficas server-side +- Plantillas HTML/PDF +- Generación Excel, PowerPoint +- Job queue async + +**Equipo C: UI Reportes + Alertas** +- Pantalla generar reporte +- Historial, visor PDF +- Sistema de alertas +- Centro notificaciones + +**Entregables**: +- ✅ Reportes ejecutivos con IA +- ✅ 5 tipos de reportes +- ✅ Sistema de alertas funcionando + +### 10.6 Fase 5: Scale & Polish (Semanas 14-16) + +**Equipo A: Billing & Plans** +- Integración Stripe/Conekta +- Planes y precios +- Trial, upgrade/downgrade +- Facturación CFDI + +**Equipo B: Admin & Settings** +- Gestión usuarios, roles +- Multi-RFC, presupuestos +- Reportes programados + +**Equipo C: API & Webhooks** +- API REST documentada +- API keys, rate limiting +- Webhooks salientes + +**Equipo D: QA & Launch** +- Testing E2E +- Performance, security +- Bug fixes, landing page +- Deploy producción + +**Entregables**: +- ✅ Sistema de pagos funcionando +- ✅ API documentada +- ✅ Plataforma lista para producción + +### 10.7 Hitos Clave + +| Semana | Hito | +|--------|------| +| 2 | Auth + Multi-tenant funcionando | +| 6 | MVP con SAT + Dashboard + Métricas Core | +| 10 | 5 integraciones + Métricas completas | +| 13 | Reportes con IA + Alertas | +| 16 | **LAUNCH** - Plataforma en producción | + +### 10.8 Recursos Estimados + +- 4-5 desarrolladores full-stack +- 1 diseñador UI/UX (parcial) +- 1 QA engineer (desde semana 10) +- Claude Code como multiagente para acelerar + +### 10.9 Dependencias Externas + +- API DeepSeek (cuenta y créditos) +- Procesador de pagos (Stripe/Conekta) +- Acceso APIs sistemas contables para testing +- Servidor Windows para agente (desarrollo) + +--- + +## Apéndices + +### A. Glosario + +| Término | Definición | +|---------|------------| +| CFDI | Comprobante Fiscal Digital por Internet | +| FIEL | Firma Electrónica Avanzada (e.firma del SAT) | +| MRR | Monthly Recurring Revenue | +| ARR | Annual Recurring Revenue | +| CAC | Customer Acquisition Cost | +| LTV | Lifetime Value | +| EBITDA | Earnings Before Interest, Taxes, Depreciation, Amortization | +| CxC | Cuentas por Cobrar | +| CxP | Cuentas por Pagar | + +### B. Referencias + +- Repositorio Horux360: https://git.consultoria-as.com/consultoria-as/Horux360 +- Monthly.la: https://monthly.la +- DeepSeek API: https://platform.deepseek.com +- SAT Web Services: https://www.sat.gob.mx + +--- + +**Documento aprobado para implementación** + +*Co-Authored-By: Claude Opus 4.5 * diff --git a/package.json b/package.json new file mode 100644 index 0000000..0dfde3d --- /dev/null +++ b/package.json @@ -0,0 +1,48 @@ +{ + "name": "horux-strategy", + "version": "0.1.0", + "private": true, + "description": "CFO Digital para Empresas Mexicanas - Plataforma de inteligencia financiera", + "author": "HORUX360", + "license": "UNLICENSED", + "engines": { + "node": ">=20.0.0", + "pnpm": ">=8.0.0" + }, + "packageManager": "pnpm@8.15.0", + "scripts": { + "dev": "turbo run dev", + "build": "turbo run build", + "start": "turbo run start", + "test": "turbo run test", + "test:watch": "turbo run test:watch", + "lint": "turbo run lint", + "lint:fix": "turbo run lint:fix", + "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"", + "clean": "turbo run clean && rm -rf node_modules", + "db:migrate": "pnpm --filter @horux/database migrate", + "db:migrate:dev": "pnpm --filter @horux/database migrate:dev", + "db:seed": "pnpm --filter @horux/database seed", + "db:studio": "pnpm --filter @horux/database studio", + "typecheck": "turbo run typecheck", + "prepare": "husky install" + }, + "devDependencies": { + "@types/node": "^20.11.0", + "eslint": "^8.56.0", + "husky": "^9.0.0", + "lint-staged": "^15.2.0", + "prettier": "^3.2.0", + "turbo": "^2.0.0", + "typescript": "^5.3.0" + }, + "lint-staged": { + "*.{ts,tsx,js,jsx}": [ + "eslint --fix", + "prettier --write" + ], + "*.{json,md}": [ + "prettier --write" + ] + } +} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml new file mode 100644 index 0000000..3ff5faa --- /dev/null +++ b/pnpm-workspace.yaml @@ -0,0 +1,3 @@ +packages: + - "apps/*" + - "packages/*" diff --git a/turbo.json b/turbo.json new file mode 100644 index 0000000..6b06904 --- /dev/null +++ b/turbo.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://turbo.build/schema.json", + "globalDependencies": ["**/.env.*local"], + "pipeline": { + "build": { + "dependsOn": ["^build"], + "outputs": ["dist/**", ".next/**", "!.next/cache/**"] + }, + "dev": { + "cache": false, + "persistent": true + }, + "start": { + "dependsOn": ["build"] + }, + "test": { + "dependsOn": ["build"], + "outputs": ["coverage/**"] + }, + "test:watch": { + "cache": false, + "persistent": true + }, + "lint": { + "outputs": [] + }, + "lint:fix": { + "outputs": [] + }, + "typecheck": { + "dependsOn": ["^build"], + "outputs": [] + }, + "clean": { + "cache": false + } + } +}