consultoria-as/HoruxDespachos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
HoruxDespachos/docs/plans/2026-01-22-horux360-saas-design.md
consultoria-as 6b36db1403 Update: nueva version Horux Despachos
2026-04-27 22:09:36 -06:00

30 KiB
Raw Permalink Blame History

Horux360 SaaS - Documento de Diseño

Fecha: 2026-01-22 Versión: 1.0 Estado: Aprobado

1. Visión General

Horux360 es una plataforma SaaS de análisis financiero y gestión fiscal para empresas mexicanas, con enfoque en:

  • Experiencia visual superior - 4 temas con diferentes layouts
  • Control fiscal completo - IVA, ISR, CFDI en todos los planes
  • Inteligencia financiera - Dashboards, proyecciones, alertas proactivas
  • Multi-tenant - Schema por empresa en PostgreSQL

Propósito

Transformar datos financieros en decisiones estratégicas mediante análisis automatizado y reportes en tiempo real para empresas mexicanas.

Funcionalidades Core

  • Dashboard financiero con KPIs (ingresos, egresos, utilidad, ROI)
  • Gestión de CFDI (facturas electrónicas del SAT)
  • Control de IVA (trasladado vs acreditable, balance mensual)
  • Control de ISR
  • Conciliación bancaria automatizada
  • Reportes y alertas en tiempo real
  • Calendario fiscal con recordatorios
  • Proyecciones financieras (forecasting)

2. Stack Tecnológico

Capa Tecnología
Frontend Next.js 14 + TypeScript + Tailwind CSS
Backend Node.js + Express + TypeScript
Base de datos PostgreSQL (schema por tenant)
Autenticación JWT personalizado
ORM Prisma
Gráficos Recharts
Exportación xlsx + @react-pdf/renderer
Estado Zustand
Fetching TanStack Query
Forms React Hook Form + Zod
Tablas TanStack Table
UI Base Radix UI

3. Modelo de Negocio - Planes

Plan CFDI/mes Usuarios Funcionalidades
Starter 100 1 Dashboard, IVA/ISR, CFDI básico
Business 500 3 + Reportes, Alertas, Calendario fiscal
Professional 2,000 10 + Conciliación, Forecasting, XML SAT
Enterprise Ilimitado Ilimitado + API, Multi-empresa, Soporte prioritario

Nota: Control de IVA e ISR incluido en todos los planes.

4. Arquitectura del Sistema

4.1 Estructura de Carpetas

horux360/
├── apps/
│   ├── web/                    # Frontend Next.js
│   │   ├── app/
│   │   │   ├── (auth)/         # Login, registro, recuperar contraseña
│   │   │   ├── (dashboard)/    # Rutas protegidas
│   │   │   │   ├── dashboard/
│   │   │   │   ├── cfdi/
│   │   │   │   ├── impuestos/
│   │   │   │   ├── reportes/
│   │   │   │   ├── conciliacion/
│   │   │   │   ├── calendario/
│   │   │   │   ├── configuracion/
│   │   │   │   └── usuarios/
│   │   │   └── (marketing)/    # Landing, precios, contacto
│   │   ├── components/
│   │   │   ├── ui/             # Componentes base
│   │   │   ├── charts/         # Gráficos reutilizables
│   │   │   ├── layouts/        # Los 4 layouts de temas
│   │   │   └── modules/        # Componentes por módulo
│   │   ├── lib/
│   │   │   ├── api/            # Cliente API
│   │   │   ├── hooks/          # Custom hooks
│   │   │   └── utils/          # Utilidades
│   │   ├── stores/             # Estado global (Zustand)
│   │   └── themes/             # Configuración de 4 temas
│   │
│   └── api/                    # Backend Express
│       ├── src/
│       │   ├── controllers/
│       │   ├── services/
│       │   ├── models/
│       │   ├── middlewares/
│       │   │   ├── auth.ts
│       │   │   └── tenant.ts   # Middleware multi-tenant
│       │   ├── routes/
│       │   └── utils/
│       └── prisma/
│           └── schema.prisma
│
├── packages/
│   └── shared/                 # Tipos y utilidades compartidas
│
└── docker-compose.yml

4.2 Flujo Multi-Tenant

Request → Auth Middleware → Tenant Middleware → Set Schema → Controller
                ↓                   ↓
           Valida JWT        Extrae tenant_id
                            del token/header
                                    ↓
                            SET search_path TO tenant_schema

5. Modelo de Datos

5.1 Schema Público (compartido)

-- Empresas/Tenants
tenants
├── id (UUID, PK)
├── nombre
├── rfc
├── plan (starter|business|professional|enterprise)
├── schema_name (único)
├── cfdi_limit
├── users_limit
├── active
├── created_at
└── expires_at

-- Usuarios globales
users
├── id (UUID, PK)
├── tenant_id (FK)
├── email (único)
├── password_hash
├── nombre
├── role (admin|contador|visor)
├── active
├── last_login
└── created_at

5.2 Schema por Tenant (tenant_xxx)

-- Catálogo de cuentas
cuentas
├── id (PK)
├── codigo
├── nombre
├── tipo (activo|pasivo|capital|ingreso|egreso)
├── padre_id (FK, self)
└── active

-- CFDIs/Facturas
cfdis
├── id (UUID, PK)
├── uuid_fiscal
├── tipo (ingreso|egreso|traslado|pago|nomina)
├── serie
├── folio
├── fecha_emision
├── fecha_timbrado
├── rfc_emisor
├── nombre_emisor
├── rfc_receptor
├── nombre_receptor
├── subtotal
├── descuento
├── iva
├── isr_retenido
├── iva_retenido
├── total
├── moneda
├── tipo_cambio
├── metodo_pago
├── forma_pago
├── uso_cfdi
├── estado (vigente|cancelado)
├── xml_url
├── pdf_url
└── created_at

-- Conceptos de CFDI
cfdi_conceptos
├── id (PK)
├── cfdi_id (FK)
├── clave_producto
├── descripcion
├── cantidad
├── unidad
├── valor_unitario
├── importe
├── descuento
└── objeto_impuesto

-- Control de IVA mensual
iva_mensual
├── id (PK)
├── año
├── mes
├── iva_trasladado (cobrado)
├── iva_acreditable (pagado)
├── iva_retenido
├── resultado
├── acumulado
├── estado (pendiente|declarado|acreditado)
└── fecha_declaracion

-- Control de ISR mensual
isr_mensual
├── id (PK)
├── año
├── mes
├── ingresos_acumulados
├── deducciones
├── base_gravable
├── isr_causado
├── isr_retenido
├── isr_a_pagar
├── estado
└── fecha_declaracion

-- Movimientos bancarios
movimientos_bancarios
├── id (PK)
├── banco
├── cuenta
├── fecha
├── referencia
├── descripcion
├── tipo (cargo|abono)
├── monto
├── saldo
├── cfdi_id (FK, nullable)
├── estado_conciliacion (pendiente|conciliado|error)
└── notas

-- Alertas
alertas
├── id (PK)
├── tipo (vencimiento|discrepancia|iva_favor|declaracion)
├── titulo
├── mensaje
├── prioridad (alta|media|baja)
├── fecha_vencimiento
├── leida
├── resuelta
└── created_at

-- Calendario fiscal
calendario_fiscal
├── id (PK)
├── titulo
├── descripcion
├── tipo (declaracion|pago|obligacion)
├── fecha_limite
├── recurrencia (mensual|bimestral|anual|unica)
├── completado
└── notas

6. Módulos y Funcionalidades

6.1 Dashboard Principal

Componente Descripción
KPIs principales Ingresos, Egresos, Utilidad, IVA a favor/por pagar
Selector de período Semana, Mes, Trimestre, Año, Personalizado
Gráfico ingresos vs egresos Barras comparativas por mes
Métricas de rentabilidad Margen, ROI, Crecimiento %
Alertas activas Widget con alertas pendientes
Resumen fiscal Estado de declaraciones del mes

6.2 Gestión de CFDI

Funcionalidad Descripción
Lista de CFDIs Tabla con filtros (tipo, estado, fecha, RFC)
Detalle de factura Vista completa con conceptos e impuestos
Importar XML Carga manual de archivos XML
Descarga SAT Conexión automática para descargar CFDIs (Professional+)
Exportar Excel/PDF con filtros aplicados
Búsqueda Por UUID, RFC, concepto, monto

6.3 Control de Impuestos (IVA/ISR)

Funcionalidad Descripción
Balance IVA Trasladado vs Acreditable, resultado mensual
Histórico IVA Tabla mensual con acumulados
Cálculo ISR Ingresos, deducciones, base gravable, ISR a pagar
Retenciones IVA e ISR retenido por terceros
Prellenado DIOT Generación de archivo para declaración

6.4 Reportes

Reporte Descripción
Estado de resultados Ingresos - Egresos = Utilidad
Flujo de efectivo Entradas y salidas por período
Comparativo períodos Año vs año, mes vs mes
Concentrado por RFC Totales por cliente/proveedor
Proyección financiera Forecast basado en histórico (Professional+)
Exportación Excel y PDF para todos los reportes

6.5 Conciliación Bancaria (Professional+)

Funcionalidad Descripción
Importar estados Carga de archivos bancarios (CSV, OFX)
Match automático Asociar movimientos con CFDIs
Pendientes Lista de movimientos sin conciliar
Errores Discrepancias detectadas
Métricas Tasa de éxito, pendientes, conciliados

6.6 Calendario Fiscal (Business+)

Funcionalidad Descripción
Vista calendario Mensual con obligaciones marcadas
Alertas automáticas Recordatorios 7, 3 y 1 día antes
Obligaciones SAT Precargadas según régimen fiscal
Personalización Agregar eventos propios
Marcar completado Tracking de cumplimiento

6.7 Gestión de Usuarios (Business+)

Funcionalidad Descripción
Roles Admin (todo), Contador (operación), Visor (solo lectura)
Invitar usuarios Por email con rol asignado
Permisos por módulo Configuración granular
Auditoría Log de acciones por usuario

7. Sistema de Temas

7.1 Los 4 Temas

Tema Paleta Layout Ideal para
Light Blancos, grises suaves, acentos azules Sidebar fija izquierda, contenido centrado con máximo 1200px Uso diario prolongado
Vibrant Colores vivos (púrpura, cyan, coral) Sidebar colapsable, cards grandes con bordes redondeados Usuarios que prefieren color
Corporate Azul marino, grises oscuros, dorado Multi-panel denso, tablas compactas, sin espacios desperdiciados Contadores, mucha data
Dark Fondo #0a0a0a, acentos verdes/cyan Sidebar minimalista, widgets flotantes con glassmorphism Trabajo nocturno

7.2 Estructura de Layouts

┌─────────────────────────────────────────────────────────────┐
│  LIGHT THEME                                                │
├────────┬────────────────────────────────────────────────────┤
│        │  Header con breadcrumb                             │
│  Logo  ├────────────────────────────────────────────────────┤
│        │                                                    │
│  Nav   │         Contenido centrado (max 1200px)            │
│  Items │                                                    │
│        │         Cards con sombras suaves                   │
│  Fixed │                                                    │
│  240px │                                                    │
└────────┴────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  VIBRANT THEME                                              │
├──┬──────────────────────────────────────────────────────────┤
│  │  Header con selector de período                          │
│☰ ├──────────────────────────────────────────────────────────┤
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
│C │  │ KPI 1   │ │ KPI 2   │ │ KPI 3   │ │ KPI 4   │        │
│O │  │ Grande  │ │ Grande  │ │ Grande  │ │ Grande  │        │
│L │  └─────────┘ └─────────┘ └─────────┘ └─────────┘        │
│L │  ┌───────────────────────────────────────────────┐      │
│A │  │            Gráfico principal                   │      │
│P │  └───────────────────────────────────────────────┘      │
│S │                                                          │
│E │  Bordes redondeados 16px, gradientes en headers         │
└──┴──────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  CORPORATE THEME                                            │
├────────┬───────────────────────┬────────────────────────────┤
│        │  Panel Superior       │  Panel Lateral             │
│  Nav   │  KPIs compactos      │  Alertas                   │
│        ├───────────────────────┤  Lista densa              │
│ Menú   │  Tabla principal     │                            │
│ jerár- │  Muchas filas        │──────────────────────────  │
│ quico  │  Columnas compactas  │  Acciones rápidas          │
│        │  Sin paginación      │  Botones pequeños          │
│        │  Scroll virtual      │                            │
└────────┴───────────────────────┴────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  DARK THEME                                         ○ ○ ○   │
├──┬──────────────────────────────────────────────────────────┤
│  │                                                          │
│▪ │    ╭─────────╮  ╭─────────╮  ╭─────────╮                │
│▪ │    │ Widget  │  │ Widget  │  │ Widget  │   Glassmorphism│
│▪ │    │ flotante│  │ flotante│  │ flotante│   con blur     │
│▪ │    ╰─────────╯  ╰─────────╯  ╰─────────╯                │
│  │                                                          │
│  │         ╭────────────────────────────╮                  │
│  │         │    Gráfico con glow        │                  │
│  │         │    Líneas cyan/verde       │                  │
│  │         ╰────────────────────────────╯                  │
│64│                                                          │
│px│  Fondo casi negro, acentos neón, bordes sutiles         │
└──┴──────────────────────────────────────────────────────────┘

7.3 Implementación Técnica

// themes/index.ts
export const themes = {
  light: {
    name: 'Light',
    layout: 'sidebar-fixed',
    colors: {
      background: '#ffffff',
      surface: '#f8fafc',
      primary: '#3b82f6',
      text: '#1e293b',
      border: '#e2e8f0',
      success: '#22c55e',
      danger: '#ef4444',
    },
    radius: '8px',
    sidebar: { width: '240px', collapsible: false },
  },
  vibrant: {
    name: 'Vibrant',
    layout: 'sidebar-collapsible',
    colors: {
      background: '#faf5ff',
      surface: '#ffffff',
      primary: '#8b5cf6',
      secondary: '#06b6d4',
      accent: '#f97316',
      text: '#1e1b4b',
    },
    radius: '16px',
    sidebar: { width: '280px', collapsible: true },
  },
  corporate: {
    name: 'Corporate',
    layout: 'multi-panel',
    colors: {
      background: '#f1f5f9',
      surface: '#ffffff',
      primary: '#1e3a5f',
      accent: '#d4a853',
      text: '#0f172a',
    },
    radius: '4px',
    density: 'compact',
    sidebar: { width: '200px', collapsible: false },
  },
  dark: {
    name: 'Dark',
    layout: 'minimal-floating',
    colors: {
      background: '#0a0a0a',
      surface: 'rgba(255,255,255,0.05)',
      primary: '#22d3ee',
      accent: '#4ade80',
      text: '#f1f5f9',
      glow: '0 0 20px rgba(34,211,238,0.3)',
    },
    radius: '12px',
    blur: '10px',
    sidebar: { width: '64px', collapsible: false, iconsOnly: true },
  },
}

8. API y Endpoints

8.1 Autenticación

Método Endpoint Descripción
POST /api/auth/register Registrar empresa + usuario admin
POST /api/auth/login Iniciar sesión, retorna JWT
POST /api/auth/refresh Renovar token
POST /api/auth/forgot-password Solicitar reset de contraseña
POST /api/auth/reset-password Cambiar contraseña con token
GET /api/auth/me Obtener usuario actual

8.2 Tenants/Empresas

Método Endpoint Descripción
GET /api/tenant Obtener datos de la empresa actual
PUT /api/tenant Actualizar datos de la empresa
GET /api/tenant/usage Uso actual (CFDIs, usuarios) vs límites
PUT /api/tenant/plan Cambiar plan

8.3 Usuarios

Método Endpoint Descripción
GET /api/users Listar usuarios del tenant
POST /api/users Invitar nuevo usuario
GET /api/users/:id Obtener usuario
PUT /api/users/:id Actualizar usuario/rol
DELETE /api/users/:id Desactivar usuario

8.4 CFDIs

Método Endpoint Descripción
GET /api/cfdi Listar CFDIs con filtros y paginación
GET /api/cfdi/:id Detalle de CFDI con conceptos
POST /api/cfdi/import Importar XML (uno o varios)
POST /api/cfdi/sync-sat Descargar del SAT (Professional+)
GET /api/cfdi/:id/xml Descargar XML original
GET /api/cfdi/:id/pdf Generar/descargar PDF
GET /api/cfdi/export Exportar listado a Excel

Query params:

?tipo=ingreso|egreso
&estado=vigente|cancelado
&fecha_inicio=2024-01-01
&fecha_fin=2024-12-31
&rfc=XAXX010101000
&search=concepto
&page=1
&limit=50
&sort=fecha_emision
&order=desc

8.5 Impuestos

Método Endpoint Descripción
GET /api/impuestos/iva Resumen IVA del período
GET /api/impuestos/iva/mensual Desglose mensual IVA
GET /api/impuestos/isr Resumen ISR del período
GET /api/impuestos/isr/mensual Desglose mensual ISR
GET /api/impuestos/retenciones Retenciones recibidas
POST /api/impuestos/iva/:id/declarar Marcar mes como declarado
GET /api/impuestos/diot Generar archivo DIOT

8.6 Dashboard

Método Endpoint Descripción
GET /api/dashboard/kpis KPIs principales del período
GET /api/dashboard/ingresos-egresos Datos para gráfico comparativo
GET /api/dashboard/rentabilidad Métricas de rentabilidad
GET /api/dashboard/resumen-fiscal Estado de obligaciones

8.7 Reportes

Método Endpoint Descripción
GET /api/reportes/estado-resultados Estado de resultados
GET /api/reportes/flujo-efectivo Flujo de efectivo
GET /api/reportes/comparativo Comparativa entre períodos
GET /api/reportes/por-rfc Concentrado por cliente/proveedor
GET /api/reportes/proyeccion Forecast financiero (Professional+)
GET /api/reportes/:tipo/export Exportar a Excel o PDF

8.8 Conciliación Bancaria

Método Endpoint Descripción
GET /api/conciliacion Estadísticas de conciliación
GET /api/conciliacion/movimientos Listar movimientos bancarios
POST /api/conciliacion/import Importar estado de cuenta
POST /api/conciliacion/match Conciliar movimiento con CFDI
PUT /api/conciliacion/:id Actualizar movimiento
GET /api/conciliacion/pendientes Movimientos sin conciliar

8.9 Calendario Fiscal

Método Endpoint Descripción
GET /api/calendario Obligaciones del mes/año
POST /api/calendario Crear obligación personalizada
PUT /api/calendario/:id Actualizar/marcar completado
DELETE /api/calendario/:id Eliminar obligación propia
GET /api/calendario/proximas Próximas obligaciones (alertas)

8.10 Alertas

Método Endpoint Descripción
GET /api/alertas Listar alertas activas
PUT /api/alertas/:id/leer Marcar como leída
PUT /api/alertas/:id/resolver Marcar como resuelta
GET /api/alertas/count Contador para badge

8.11 Configuración

Método Endpoint Descripción
GET /api/config/theme Obtener tema actual
PUT /api/config/theme Cambiar tema
GET /api/config/preferencias Preferencias del usuario
PUT /api/config/preferencias Actualizar preferencias

9. Flujo de Pantallas

9.1 Mapa de Navegación

┌─────────────────────────────────────────────────────────────────┐
│                        PÚBLICO                                  │
├─────────────────────────────────────────────────────────────────┤
│  Landing (/)                                                    │
│    ├── Características (/features)                              │
│    ├── Precios (/pricing)                                       │
│    ├── Contacto (/contact)                                      │
│    ├── Login (/login)                                           │
│    └── Registro (/register)                                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                        [Autenticación]
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     ÁREA PRIVADA                                │
├────────────┬────────────────────────────────────────────────────┤
│  SIDEBAR   │   /app/dashboard    - KPIs, gráficos, alertas     │
│            │   /app/cfdi         - Lista, detalle, importar    │
│  Dashboard │   /app/impuestos    - IVA, ISR, Retenciones, DIOT │
│  CFDI      │   /app/reportes     - Todos los reportes          │
│  Impuestos │   /app/conciliacion - Movimientos bancarios       │
│  Reportes  │   /app/calendario   - Obligaciones fiscales       │
│  Concil.   │   /app/usuarios     - Gestión de equipo           │
│  Calendario│   /app/config       - Preferencias y tema         │
│  Config    │                                                    │
└────────────┴────────────────────────────────────────────────────┘

10. Roadmap de Implementación

Fase 1: Fundación (Core)

  • Setup del proyecto (monorepo, Next.js, Express)
  • Base de datos PostgreSQL + Prisma
  • Sistema multi-tenant (schemas)
  • Autenticación JWT
  • Sistema de temas (4 temas + layouts)
  • Componentes UI base
  • Landing page + registro + login

Fase 2: Módulos Core

  • Dashboard con KPIs
  • Gestión de CFDI (CRUD + importación XML)
  • Control de IVA (cálculos automáticos)
  • Control de ISR
  • Gráficos y visualizaciones

Fase 3: Funcionalidades Avanzadas

  • Reportes (estado resultados, flujo efectivo)
  • Exportación Excel/PDF
  • Sistema de alertas
  • Calendario fiscal
  • Gestión de usuarios y roles

Fase 4: Premium Features

  • Conciliación bancaria
  • Proyecciones/Forecasting
  • Descarga automática XML del SAT
  • Generación DIOT
  • API pública (Enterprise)

Fase 5: Producción

  • Testing completo
  • Optimización de rendimiento
  • Documentación
  • Despliegue y CI/CD
  • Monitoreo y logging

11. Datos Demo (Seed)

// Empresa demo con datos precargados
{
  tenant: {
    nombre: "Empresa Demo SA de CV",
    rfc: "EDE123456AB1",
    plan: "professional"
  },
  users: [
    { email: "admin@demo.com", role: "admin", password: "demo123" },
    { email: "contador@demo.com", role: "contador", password: "demo123" },
    { email: "visor@demo.com", role: "visor", password: "demo123" }
  ],
  cfdis: 150,           // Facturas de ejemplo (6 meses)
  movimientos: 200,     // Movimientos bancarios
  alertas: 5            // Alertas activas
}

12. Dependencias Principales

Categoría Librería Propósito
UI Components Radix UI Componentes accesibles
Estilos Tailwind CSS + clsx Utilidades CSS
Gráficos Recharts Visualizaciones
Tablas TanStack Table Tablas avanzadas
Forms React Hook Form + Zod Formularios + validación
Estado Zustand Estado global
Fetching TanStack Query Cache y fetching
Fechas date-fns Manipulación fechas
Excel xlsx (SheetJS) Exportación Excel
PDF @react-pdf/renderer Generación PDF
XML Parser fast-xml-parser Parsear CFDI
ORM Prisma Base de datos
Auth jsonwebtoken + bcrypt JWT + hashing

13. Análisis de Competencia

Principales Competidores en México

Plataforma Enfoque Precio/mes Fortaleza
Siigo Aspel ERP completo $291-$354 Líder tradicional
BIND ERP ERP PyMEs $890-$3,590 Todo integrado
CONTPAQi Contabilidad $890+ Estándar en despachos
Alegra Facturación $499+ Fácil de usar
Gigstack Automatización fiscal Variable Integración Stripe
Facturama Facturación CFDI Variable API robusta

Oportunidades de Diferenciación

  1. UX/Diseño - La mayoría tienen interfaces anticuadas
  2. Dashboards de análisis - Pocos ofrecen visualización moderna
  3. Alertas proactivas - Calendarios fiscales inteligentes son raros
  4. Forecasting - Proyecciones financieras casi inexistentes
  5. Temas personalizables - Nadie ofrece esto
  6. Precios accesibles - Competidores premium son caros

14. Consideraciones de Seguridad

  • Autenticación JWT con refresh tokens
  • Passwords hasheados con bcrypt (cost factor 12)
  • Aislamiento de datos por schema de PostgreSQL
  • Rate limiting en endpoints de auth
  • Validación de inputs con Zod
  • Sanitización de XML importados
  • HTTPS obligatorio
  • Headers de seguridad (Helmet.js)

15. Servicios Eliminados

Los siguientes servicios del backend anterior NO se incluirán:

  • ❌ Clerk (autenticación) - Reemplazado por JWT propio
  • ❌ OpenPay (pagos) - Se implementará después si es necesario
  • ❌ Syntage - En proceso de retiro

Documento generado el 2026-01-22

Reference in New Issue View Git Blame Copy Permalink