197 lines
6.9 KiB
Markdown
197 lines
6.9 KiB
Markdown
# 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) |
|
|
| Email | Nodemailer + SMTP |
|
|
| Facturación | Facturapi (cuenta maestra broker) |
|
|
|
|
## Setup local
|
|
|
|
```bash
|
|
# Requisitos: Node 20+, pnpm 9+, PostgreSQL 16+
|
|
pnpm install
|
|
cp apps/api/.env.example apps/api/.env # rellenar con secrets reales
|
|
echo "NEXT_PUBLIC_API_URL=http://localhost:4000/api" > apps/web/.env.local
|
|
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
|
|
```
|
|
|
|
## Deploy a producción
|
|
|
|
### Pre-requisitos del servidor
|
|
- Ubuntu 22.04+ (probado en 24.04)
|
|
- Node 20+, pnpm 9+
|
|
- PostgreSQL 16+ (con extensión `pg_trgm` para búsquedas full-text)
|
|
- Nginx (proxy + SSL Let's Encrypt)
|
|
- PM2 (process manager) — `npm i -g pm2`
|
|
- Playwright dependencies para SAT scrapers (`npx playwright install-deps chromium`)
|
|
|
|
### Procedimiento de deploy fresco
|
|
|
|
```bash
|
|
# 1. Clonar
|
|
git clone https://github.com/Torch2196/Horux_despachos_NL.git /root/Horux
|
|
cd /root/Horux
|
|
|
|
# 2. Configurar env vars
|
|
cp apps/api/.env.example apps/api/.env
|
|
nano apps/api/.env # rellenar con secrets
|
|
echo "NEXT_PUBLIC_API_URL=https://api.horuxfin.com/api" > apps/web/.env.local
|
|
|
|
# 3. Instalar deps con versiones exactas
|
|
pnpm install --frozen-lockfile
|
|
|
|
# 4. BD central — schema y catálogos
|
|
pnpm db:generate
|
|
cd apps/api && npx prisma migrate deploy && cd ../..
|
|
pnpm db:seed
|
|
|
|
# 5. BD tenant — migraciones de cada tenant existente (idempotente)
|
|
pnpm --filter @horux/api db:migrate-tenants
|
|
|
|
# 6. Tenant admin global (Horux 360 — RFC HTS240708LJA)
|
|
pnpm --filter @horux/api bootstrap:admin-global
|
|
# ↑ imprime password temporal del admin en consola — guardarla
|
|
|
|
# 7. Lista negra del SAT (opcional, ~1MB de RFCs)
|
|
pnpm --filter @horux/api import:lista-negra
|
|
|
|
# 8. Build de producción
|
|
pnpm build
|
|
|
|
# 9. Configurar Nginx + SSL
|
|
sudo cp deploy/nginx/horux360.conf /etc/nginx/sites-available/
|
|
sudo ln -s /etc/nginx/sites-available/horux360.conf /etc/nginx/sites-enabled/
|
|
sudo certbot --nginx -d horuxfin.com -d api.horuxfin.com
|
|
sudo systemctl reload nginx
|
|
|
|
# 10. Levantar con PM2
|
|
pm2 start ecosystem.config.js
|
|
pm2 save
|
|
pm2 startup # autostart al boot
|
|
```
|
|
|
|
### Updates posteriores
|
|
|
|
```bash
|
|
cd /root/Horux
|
|
git pull
|
|
pnpm install --frozen-lockfile
|
|
pnpm db:generate
|
|
cd apps/api && npx prisma migrate deploy && cd ../..
|
|
pnpm --filter @horux/api db:migrate-tenants # si hay nuevas migraciones tenant
|
|
pnpm build
|
|
pm2 restart all
|
|
```
|
|
|
|
### Crons en producción
|
|
|
|
Los crons internos arrancan automáticamente en `NODE_ENV=production`:
|
|
- **SAT sync diario** — 03:00 AM (todos los planes)
|
|
- **SAT incremental** — 11:00, 15:00, 19:00 (solo Enterprise)
|
|
- **Subscription lifecycle** — 02:30 AM (apply pending changes, expire trials, purge)
|
|
- **Reporte semanal email** — Lunes 08:00 AM
|
|
- **Opinión cumplimiento** — Domingos 04:00 AM
|
|
- **CSF mensual** — Día 1 cada mes 04:00 AM
|
|
- **SAT retry cron** — cada hora (reintentos jobs `pending`)
|
|
- **Watchdog jobs SAT** — cada 2h (mata jobs zombies)
|
|
|
|
Si necesitás simular crons en dev: `ENABLE_CRONS_IN_DEV=1` en `apps/api/.env`.
|
|
|
|
## 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)**
|
|
|
|
---
|