From e0c97cb3b6e670abb0f452445f5ad7f8d143dc00 Mon Sep 17 00:00:00 2001 From: Consultoria AS Date: Thu, 22 Jan 2026 01:28:58 +0000 Subject: [PATCH] Initial commit: Horux360 SaaS design documentation - Complete design document with architecture, data models, and API specs - Database schema (Prisma) for multi-tenant PostgreSQL - README with project overview and plans - Support for 4 visual themes (Light, Vibrant, Corporate, Dark) - Comprehensive module specifications: - Dashboard with KPIs - CFDI management - IVA/ISR tax control - Bank reconciliation - Fiscal calendar - User management with roles Co-Authored-By: Claude Opus 4.5 --- .gitignore | 47 ++ README.md | 66 ++ docs/architecture/database-schema.prisma | 277 ++++++ docs/plans/2026-01-22-horux360-saas-design.md | 799 ++++++++++++++++++ 4 files changed, 1189 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docs/architecture/database-schema.prisma create mode 100644 docs/plans/2026-01-22-horux360-saas-design.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2b2b913 --- /dev/null +++ b/.gitignore @@ -0,0 +1,47 @@ +# Dependencies +node_modules/ +.pnp +.pnp.js + +# Build +.next/ +out/ +dist/ +build/ + +# Environment +.env +.env.local +.env.development.local +.env.test.local +.env.production.local + +# Logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.pnpm-debug.log* + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Testing +coverage/ +.nyc_output/ + +# Prisma +prisma/*.db +prisma/*.db-journal + +# Misc +*.log +*.tsbuildinfo +.turbo/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..f50f7db --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +# Horux360 SaaS + +Plataforma de análisis financiero y gestión fiscal para empresas mexicanas. + +## Descripción + +Horux360 es una aplicación SaaS que permite a las empresas mexicanas: + +- Gestionar sus CFDI (facturas electrónicas) +- Controlar IVA e ISR automáticamente +- Visualizar dashboards financieros en tiempo real +- Realizar conciliación bancaria +- Recibir alertas fiscales proactivas +- Generar reportes y proyecciones financieras + +## Stack Tecnológico + +- **Frontend:** Next.js 14 + TypeScript + Tailwind CSS +- **Backend:** Node.js + Express + TypeScript +- **Base de datos:** PostgreSQL (multi-tenant por schema) +- **Autenticación:** JWT personalizado + +## Estructura del Proyecto + +``` +horux360/ +├── apps/ +│ ├── web/ # Frontend Next.js +│ └── api/ # Backend Express +├── packages/ +│ └── shared/ # Tipos y utilidades compartidas +├── docs/ +│ └── plans/ # Documentación de diseño +└── docker-compose.yml +``` + +## Documentación + +- [Documento de Diseño](docs/plans/2026-01-22-horux360-saas-design.md) + +## 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 | +| Enterprise | Ilimitado | Ilimitado | + API, Multi-empresa | + +## Características Destacadas + +- **4 Temas visuales:** Light, Vibrant, Corporate, Dark +- **Multi-tenant:** Aislamiento de datos por empresa +- **Responsive:** Funciona en desktop y móvil +- **Tiempo real:** Dashboards actualizados al instante + +## Demo + +Credenciales de demo: +- **Admin:** admin@demo.com / demo123 +- **Contador:** contador@demo.com / demo123 +- **Visor:** visor@demo.com / demo123 + +## Licencia + +Propietario - Consultoría AS diff --git a/docs/architecture/database-schema.prisma b/docs/architecture/database-schema.prisma new file mode 100644 index 0000000..2f0eac7 --- /dev/null +++ b/docs/architecture/database-schema.prisma @@ -0,0 +1,277 @@ +// Horux360 - Database Schema +// PostgreSQL with Multi-tenant (schema per tenant) + +generator client { + provider = "prisma-client-js" +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} + +// ============================================ +// PUBLIC SCHEMA - Shared across all tenants +// ============================================ + +model Tenant { + id String @id @default(uuid()) + nombre String + rfc String @unique + plan Plan @default(starter) + schemaName String @unique @map("schema_name") + cfdiLimit Int @map("cfdi_limit") + usersLimit Int @map("users_limit") + active Boolean @default(true) + createdAt DateTime @default(now()) @map("created_at") + expiresAt DateTime? @map("expires_at") + + users User[] + + @@map("tenants") +} + +model User { + id String @id @default(uuid()) + tenantId String @map("tenant_id") + email String @unique + passwordHash String @map("password_hash") + nombre String + role Role @default(visor) + active Boolean @default(true) + lastLogin DateTime? @map("last_login") + createdAt DateTime @default(now()) @map("created_at") + + tenant Tenant @relation(fields: [tenantId], references: [id]) + + @@map("users") +} + +enum Plan { + starter + business + professional + enterprise +} + +enum Role { + admin + contador + visor +} + +// ============================================ +// TENANT SCHEMA - Isolated per tenant +// These models exist in each tenant's schema +// ============================================ + +// Note: The following models are defined for documentation +// They will be created dynamically in each tenant schema + +model Cuenta { + id Int @id @default(autoincrement()) + codigo String + nombre String + tipo TipoCuenta + padreId Int? @map("padre_id") + active Boolean @default(true) + + padre Cuenta? @relation("CuentaHijos", fields: [padreId], references: [id]) + hijos Cuenta[] @relation("CuentaHijos") + + @@map("cuentas") +} + +enum TipoCuenta { + activo + pasivo + capital + ingreso + egreso +} + +model Cfdi { + id String @id @default(uuid()) + uuidFiscal String @unique @map("uuid_fiscal") + tipo TipoCfdi + serie String? + folio String? + fechaEmision DateTime @map("fecha_emision") + fechaTimbrado DateTime @map("fecha_timbrado") + rfcEmisor String @map("rfc_emisor") + nombreEmisor String @map("nombre_emisor") + rfcReceptor String @map("rfc_receptor") + nombreReceptor String @map("nombre_receptor") + subtotal Decimal @db.Decimal(18, 2) + descuento Decimal @default(0) @db.Decimal(18, 2) + iva Decimal @default(0) @db.Decimal(18, 2) + isrRetenido Decimal @default(0) @map("isr_retenido") @db.Decimal(18, 2) + ivaRetenido Decimal @default(0) @map("iva_retenido") @db.Decimal(18, 2) + total Decimal @db.Decimal(18, 2) + moneda String @default("MXN") + tipoCambio Decimal @default(1) @map("tipo_cambio") @db.Decimal(10, 4) + metodoPago String? @map("metodo_pago") + formaPago String? @map("forma_pago") + usoCfdi String? @map("uso_cfdi") + estado EstadoCfdi @default(vigente) + xmlUrl String? @map("xml_url") + pdfUrl String? @map("pdf_url") + createdAt DateTime @default(now()) @map("created_at") + + conceptos CfdiConcepto[] + movimientos MovimientoBancario[] + + @@map("cfdis") +} + +enum TipoCfdi { + ingreso + egreso + traslado + pago + nomina +} + +enum EstadoCfdi { + vigente + cancelado +} + +model CfdiConcepto { + id Int @id @default(autoincrement()) + cfdiId String @map("cfdi_id") + claveProducto String @map("clave_producto") + descripcion String + cantidad Decimal @db.Decimal(10, 2) + unidad String + valorUnitario Decimal @map("valor_unitario") @db.Decimal(18, 2) + importe Decimal @db.Decimal(18, 2) + descuento Decimal @default(0) @db.Decimal(18, 2) + objetoImpuesto String? @map("objeto_impuesto") + + cfdi Cfdi @relation(fields: [cfdiId], references: [id]) + + @@map("cfdi_conceptos") +} + +model IvaMensual { + id Int @id @default(autoincrement()) + año Int + mes Int + ivaTrasladado Decimal @map("iva_trasladado") @db.Decimal(18, 2) + ivaAcreditable Decimal @map("iva_acreditable") @db.Decimal(18, 2) + ivaRetenido Decimal @default(0) @map("iva_retenido") @db.Decimal(18, 2) + resultado Decimal @db.Decimal(18, 2) + acumulado Decimal @db.Decimal(18, 2) + estado EstadoDeclaracion @default(pendiente) + fechaDeclaracion DateTime? @map("fecha_declaracion") + + @@unique([año, mes]) + @@map("iva_mensual") +} + +model IsrMensual { + id Int @id @default(autoincrement()) + año Int + mes Int + ingresosAcumulados Decimal @map("ingresos_acumulados") @db.Decimal(18, 2) + deducciones Decimal @db.Decimal(18, 2) + baseGravable Decimal @map("base_gravable") @db.Decimal(18, 2) + isrCausado Decimal @map("isr_causado") @db.Decimal(18, 2) + isrRetenido Decimal @map("isr_retenido") @db.Decimal(18, 2) + isrAPagar Decimal @map("isr_a_pagar") @db.Decimal(18, 2) + estado EstadoDeclaracion @default(pendiente) + fechaDeclaracion DateTime? @map("fecha_declaracion") + + @@unique([año, mes]) + @@map("isr_mensual") +} + +enum EstadoDeclaracion { + pendiente + declarado + acreditado +} + +model MovimientoBancario { + id Int @id @default(autoincrement()) + banco String + cuenta String + fecha DateTime + referencia String? + descripcion String + tipo TipoMovimiento + monto Decimal @db.Decimal(18, 2) + saldo Decimal @db.Decimal(18, 2) + cfdiId String? @map("cfdi_id") + estadoConciliacion EstadoConciliacion @default(pendiente) @map("estado_conciliacion") + notas String? + + cfdi Cfdi? @relation(fields: [cfdiId], references: [id]) + + @@map("movimientos_bancarios") +} + +enum TipoMovimiento { + cargo + abono +} + +enum EstadoConciliacion { + pendiente + conciliado + error +} + +model Alerta { + id Int @id @default(autoincrement()) + tipo TipoAlerta + titulo String + mensaje String + prioridad Prioridad @default(media) + fechaVencimiento DateTime? @map("fecha_vencimiento") + leida Boolean @default(false) + resuelta Boolean @default(false) + createdAt DateTime @default(now()) @map("created_at") + + @@map("alertas") +} + +enum TipoAlerta { + vencimiento + discrepancia + iva_favor + declaracion +} + +enum Prioridad { + alta + media + baja +} + +model CalendarioFiscal { + id Int @id @default(autoincrement()) + titulo String + descripcion String? + tipo TipoObligacion + fechaLimite DateTime @map("fecha_limite") + recurrencia Recurrencia @default(unica) + completado Boolean @default(false) + notas String? + + @@map("calendario_fiscal") +} + +enum TipoObligacion { + declaracion + pago + obligacion +} + +enum Recurrencia { + mensual + bimestral + anual + unica +} diff --git a/docs/plans/2026-01-22-horux360-saas-design.md b/docs/plans/2026-01-22-horux360-saas-design.md new file mode 100644 index 0000000..0cbdc8e --- /dev/null +++ b/docs/plans/2026-01-22-horux360-saas-design.md @@ -0,0 +1,799 @@ +# 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) + +```sql +-- 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) + +```sql +-- 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 + +```typescript +// 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) + +```typescript +// 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*