Initial commit - Horux Despachos NL

2026-05-03 16:47:53 -06:00
commit b00b677c54
647 changed files with 133843 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,196 @@
+# 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)**
+
+---