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 <noreply@anthropic.com>
This commit is contained in:
Consultoria AS
47
.gitignore
vendored
Normal file
47
.gitignore
vendored
Normal file
@@ -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/
|
||||||
66
README.md
Normal file
66
README.md
Normal file
@@ -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
|
||||||
277
docs/architecture/database-schema.prisma
Normal file
277
docs/architecture/database-schema.prisma
Normal file
@@ -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
|
||||||
|
}
|
||||||
799
docs/plans/2026-01-22-horux360-saas-design.md
Normal file
799
docs/plans/2026-01-22-horux360-saas-design.md
Normal file
@@ -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*
|
||||||
Reference in New Issue
Block a user