# Horux360 SaaS

Plataforma de análisis financiero y gestión fiscal para empresas mexicanas.

## Descripción

Horux360 es una aplicación SaaS multi-tenant que permite a las empresas mexicanas:

- Gestionar sus CFDI (facturas electrónicas) con carga masiva de XML
- Controlar IVA e ISR automáticamente
- Sincronizar CFDIs directamente con el SAT usando FIEL
- Visualizar dashboards financieros en tiempo real
- Realizar conciliación bancaria
- Recibir alertas fiscales proactivas
- Generar reportes y proyecciones financieras
- Calendario de obligaciones fiscales

## Stack Tecnológico

| Capa | Tecnología |
|------|-----------|
| **Frontend** | Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui |
| **Backend** | Node.js + Express + TypeScript + tsx |
| **Base de datos** | PostgreSQL 16 (database-per-tenant) |
| **ORM** | Prisma (central DB) + pg (tenant DBs con raw SQL) |
| **Autenticación** | JWT (access 15min + refresh 7d) |
| **Estado** | Zustand con persistencia |
| **Proceso** | PM2 (fork mode) |
| **Proxy** | Nginx con SSL (Let's Encrypt) |
| **Email** | Nodemailer + Gmail Workspace (STARTTLS) |
| **Pagos** | MercadoPago (suscripciones) |

## Estructura del Proyecto

```
horux360/
├── apps/
│   ├── web/              # Frontend Next.js 14
│   │   ├── app/          # Pages (App Router)
│   │   ├── components/   # Componentes UI
│   │   ├── lib/api/      # Cliente API
│   │   └── stores/       # Zustand stores
│   └── api/              # Backend Express
│       ├── src/
│       │   ├── config/       # ENV, database connections
│       │   ├── controllers/  # Request handlers
│       │   ├── middlewares/  # Auth, tenant, rate-limit, plan-limits
│       │   ├── routes/       # Express routes
│       │   ├── services/     # Business logic
│       │   │   ├── email/    # Templates + Nodemailer
│       │   │   ├── payment/  # MercadoPago
│       │   │   └── sat/      # SAT sync + FIEL crypto
│       │   ├── utils/        # Helpers (token, password, global-admin)
│       │   └── jobs/         # SAT sync cron job
│       └── prisma/           # Schema + migrations
├── packages/
│   └── shared/           # Tipos y constantes compartidas
├── deploy/
│   └── nginx/            # Configuración de Nginx
├── scripts/
│   └── backup.sh         # Script de backup PostgreSQL
├── docs/
│   ├── architecture/     # Docs técnicos
│   ├── security/         # Auditorías de seguridad
│   └── plans/            # Documentación de diseño
└── ecosystem.config.js   # PM2 config
```

## Arquitectura Multi-Tenant

Cada cliente tiene su propia base de datos PostgreSQL, asegurando aislamiento completo de datos:

```
horux360 (central)          ← Tenants, Users, Subscriptions, RefreshTokens
horux_<rfc_cliente_1>       ← CFDIs, Alertas, Calendario, IVA del cliente 1
horux_<rfc_cliente_2>       ← CFDIs, Alertas, Calendario, IVA del cliente 2
...
```

El middleware de tenant resuelve la base de datos del cliente desde el `tenantId` del JWT, usando un caché de 5 minutos.

## Planes

| Plan | CFDI/mes | Usuarios | Características |
|------|----------|----------|-----------------|
| Starter | 100 | 1 | Dashboard, IVA/ISR, CFDI básico |
| Business | 500 | 3 | + Reportes, Alertas, Calendario |
| Professional | 2,000 | 10 | + Conciliación, Forecasting, SAT Sync |
| Enterprise | Ilimitado | Ilimitado | + API, Multi-empresa |

## Seguridad

- JWT con access token (15min) y refresh token rotation (7d)
- bcrypt con 12 salt rounds para passwords
- Rate limiting en auth (10 login/15min, 3 register/hora)
- FIEL encriptada con AES-256-GCM
- CSP, HSTS, y security headers vía Nginx + Helmet
- Admin global verificado por RFC (no solo por rol)
- Webhooks de MercadoPago con verificación HMAC-SHA256
- Body limits diferenciados (10MB general, 50MB bulk CFDI)
- TLS obligatorio para SMTP

Ver [Auditoría de Seguridad](docs/security/2026-03-18-security-audit-remediation.md) para detalles completos.

## Documentación

| Documento | Descripción |
|-----------|-------------|
| [Diseño SaaS](docs/plans/2026-01-22-horux360-saas-design.md) | Arquitectura original y decisiones de diseño |
| [Deployment](docs/architecture/deployment.md) | Guía completa de despliegue en producción |
| [API Reference](docs/architecture/api-reference.md) | Referencia de todos los endpoints |
| [Security Audit](docs/security/2026-03-18-security-audit-remediation.md) | Auditoría de seguridad y remediaciones |
| [SAT Sync](docs/SAT-SYNC-IMPLEMENTATION.md) | Implementación de sincronización con el SAT |

## Configuración Local

### Requisitos
- Node.js 20+
- pnpm 9+
- PostgreSQL 16

### Setup
```bash
# Instalar dependencias
pnpm install

# Configurar variables de entorno
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env.local

# Ejecutar migraciones
cd apps/api && pnpm prisma migrate dev

# Desarrollo
pnpm dev
```

### Variables de Entorno (API)

```env
NODE_ENV=development
PORT=4000
DATABASE_URL="postgresql://user:pass@localhost:5432/horux360"
JWT_SECRET=<min-32-chars>
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
CORS_ORIGIN=http://localhost:3000
FRONTEND_URL=http://localhost:3000
FIEL_ENCRYPTION_KEY=<min-32-chars>
FIEL_STORAGE_PATH=/var/horux/fiel
```

### Variables de Entorno (Web)
```env
NEXT_PUBLIC_API_URL=http://localhost:4000/api
```

## Roles

| Rol | Acceso |
|-----|--------|
| **admin** | Todo dentro de su tenant + invitar usuarios |
| **contador** | CFDI, impuestos, reportes, dashboard |
| **visor** | Solo lectura |
| **admin global** | Admin del tenant CAS2408138W2 — gestión de clientes, suscripciones, SAT cron |

## Producción

- **URL:** https://horuxfin.com
- **Hosting:** Servidor dedicado
- **SSL:** Let's Encrypt (auto-renewal)
- **Process:** PM2 con auto-restart
- **Backups:** Diarios a las 01:00 AM

Ver [Guía de Deployment](docs/architecture/deployment.md) para instrucciones completas.

## Changelog

### v0.5.0 (2026-03-18)
- Auditoría de seguridad completa y remediación de 20 vulnerabilidades
- Rate limiting en endpoints de autenticación
- Content Security Policy (CSP) y headers de seguridad mejorados
- `databaseName` removido del JWT (resolución server-side)
- Restricción de impersonación a admin global únicamente
- Autorización en endpoints de suscripción y SAT cron
- Verificación obligatoria de firma en webhooks
- Body limits reducidos (10MB default, 50MB bulk)
- Passwords temporales criptográficamente seguros
- Validación de tamaño en upload de FIEL
- SMTP con TLS obligatorio
- Documentación completa de producción

### v0.4.0 (2026-01-22)
- Carga masiva de XML CFDI (hasta 50MB)
- Selector de período mes/año en dashboards
- Fix: Persistencia de sesión en refresh de página
- Fix: Clasificación ingreso/egreso basada en RFC
- Fix: Cálculo de IVA desde XML
- Mejoras en reportes con manejo de errores
- Soporte CORS para múltiples orígenes

### v0.3.0 (2026-01-22)
- Sistema multi-tenant con gestión de clientes
- Temas visuales (4 layouts diferentes)

### v0.2.0 (2026-01-22)
- Dashboard principal con KPIs
- Módulo de CFDI
- Control de IVA/ISR
- Calendario fiscal
- Sistema de alertas

### v0.1.0 (2026-01-22)
- Autenticación JWT
- Estructura multi-tenant
- Configuración inicial del proyecto

## Licencia

Propietario - Consultoría AS