4.2 KiB
Horux Despachos
Plataforma SaaS para despachos profesionales mexicanos. Gestión fiscal multi-RFC con roles jerárquicos (Owner/Supervisor/Auxiliar/Cliente), carteras de contribuyentes, y arquitectura BYO-DB.
Autor: Carlos e Ivan (Horux 360)
Qué es
Horux Despachos permite a despachos contables gestionar múltiples contribuyentes (RFCs) desde una sola cuenta. Cada contribuyente tiene su propia FIEL, CSD, y organización Facturapi. Los supervisores organizan contribuyentes en carteras y delegan trabajo a auxiliares.
Arquitectura
Monorepo (pnpm + Turborepo)
├── apps/api → Express + TypeScript (puerto 4000)
├── apps/web → Next.js 14 + App Router (puerto 3000)
└── packages/
├── core → Auth (JWT), email transport, crypto (AES-256-GCM)
├── shared → Tipos, constantes, interfaces compartidas
├── shared-ui → Componentes UI (Button, Card, Dialog, selectors, hooks)
└── vertical-contable → (scaffold) Lógica fiscal compartida
Funcionalidades implementadas
Gestión de despachos
- Signup multi-paso (formulario → vertical → plan)
- Onboarding wizard (6 pasos)
- Planes: Trial (30 días), Business Control (BYO-DB), Business Cloud (Managed)
Contribuyentes (RFCs)
- CRUD de contribuyentes por despacho
- FIEL per contribuyente (almacenada en BD tenant, cifrada AES-256-GCM)
- Facturapi org per contribuyente (CSD independiente)
- Emisión de CFDI con contribuyente_id
Roles y autorización
- Owner: acceso total, actúa como supervisor implícito
- Supervisor: titular de RFCs, crea carteras, gestiona auxiliares
- Auxiliar: accede solo a RFCs en carteras asignadas
- Cliente: visor externo read-only de sus RFCs
getEntidadesVisibles(): cascada de permisos automática
Carteras
- CRUD completo (crear, editar, eliminar)
- Asignar/remover contribuyentes
- Asignar/remover auxiliares
- Cascada: si supervisor pierde RFC → auxiliares pierden acceso
Pricing
- Catálogo de planes (Business Control $21,000/año, Business Cloud $15,000/año + $45/RFC/mes)
- Add-ons recurrentes con multi-preapproval MercadoPago
- Paquetes de timbres one-shot
Connector BYO-DB
- Provisioning de tunnel (Cloudflare Tunnel ready)
- Heartbeat cada 30s con status en UI
- getPool() refactorizado para decrypt de conexiones BYO
Admin global
- Dashboard cross-despacho (métricas, lista despachos, actividad)
- Impersonación con motivo obligatorio + audit log
- Audit log expuesto al owner del despacho
Métricas pre-calculadas
- Hot/cold: año actual on-the-fly, años pasados pre-calculados
- Invalidación dirigida por cambios retroactivos en CFDIs
- Tablas: metricas_mensuales, acumuladas_anuales, contraparte, invalidaciones
Stack técnico
| Capa | Tecnología |
|---|---|
| Frontend | Next.js 14, React 18, Tailwind, shadcn/ui, Zustand, React Query |
| Backend | Node.js 20+, Express 4, TypeScript 5, Prisma 5.22 |
| BD Central | PostgreSQL 16 (Prisma ORM) |
| BD Tenant | PostgreSQL 16 (pg Pool + SQL raw + 17 migraciones numeradas) |
| Auth | JWT (15min) + refresh (7d) + bcrypt + magic link ready |
| Pagos | MercadoPago (preapproval + webhooks) |
| Nodemailer + SMTP | |
| Facturación | Facturapi (cuenta maestra broker) |
Setup local
# Requisitos: Node 20+, pnpm 9+, PostgreSQL 16+
pnpm install
cd apps/api && npx prisma generate
cd apps/api && npx prisma migrate deploy
cd apps/api && pnpm db:seed
pnpm dev # API :4000 + Web :3000
Estructura de BD
BD Central (Prisma)
Tenant, User, TenantMembership, Rol, Subscription, SubscriptionAddon, Payment, PlanCatalogo, PlanAddonCatalogo, FielCredential, ConnectorHeartbeat, AuditLog, TimbreSuscripcion, TimbrePaquete, catálogos SAT.
BD Tenant (SQL migrations 001-017)
001-005: Schema base (rfcs, cfdis, conciliaciones, alertas, opiniones, declaraciones, constancias) 006: tenant_migrations tracking 007-009: Core (entidades_gestionadas, carteras, cliente_accesos) 010-013: Vertical contable (contribuyentes, fiel_contribuyente, facturapi_orgs, cfdi contribuyente_id) 014-017: Métricas (mensuales, acumuladas, contraparte, invalidaciones)
Autor
Carlos e Ivan (Horux 360)