252 lines
10 KiB
Markdown
252 lines
10 KiB
Markdown
# Setup admin global + gestión de clientes (2026-04-26 turno tardío)
|
|
|
|
Sesión continuación del día. Foco: habilitar al admin global del fork para
|
|
que pueda operar como plataforma — gestión de clientes, edición de catálogos
|
|
(planes, add-ons), auto-facturación de pagos, y experiencia de login dedicada.
|
|
|
|
> Relacionado: `2026-04-26-session.md` (índice del día), `2026-04-26-sprints-1-2-3.md`
|
|
> (sprints anteriores), y los docs específicos de IVA y notificaciones.
|
|
|
|
---
|
|
|
|
## 1. Bootstrap admin global del fork
|
|
|
|
El fork `Horux_despacho` no tenía tenant raíz ni `platform_admin`. Ejecutado:
|
|
|
|
```bash
|
|
HORUX_ADMIN_EMAIL=carlos@horuxfin.com \
|
|
HORUX_ADMIN_NOMBRE=Carlos \
|
|
HORUX_TI_EMAIL=ivan@horuxfin.com \
|
|
HORUX_TI_NOMBRE=Ivan \
|
|
pnpm bootstrap:admin-global
|
|
```
|
|
|
|
Crea:
|
|
- Tenant `Horux 360` (RFC `HTS240708LJA`, plan enterprise, dbMode MANAGED).
|
|
- `carlos@horuxfin.com` con rol `platform_admin` (admin global).
|
|
- `ivan@horuxfin.com` con rol `platform_ti` (TI superset).
|
|
|
|
Contraseña fijada manualmente a `Admin12345!` con bcrypt cost 12 +
|
|
`tokenVersion: increment` para invalidar JWTs viejos.
|
|
|
|
**Cuentas finales del fork** (todas con `Admin12345!`):
|
|
- `carlos@horuxfin.com` — platform_admin
|
|
- `ivan@horuxfin.com` — platform_ti
|
|
- `jd@demo.com` — owner Patito
|
|
- `jf@demo.com` — owner Zorro
|
|
- `supervisor@patito.com` / `auxiliar@patito.com` / `cliente@patito.com`
|
|
|
|
---
|
|
|
|
## 2. Login y home redirect
|
|
|
|
`apps/web/app/(auth)/login/page.tsx` ahora detecta el admin global tras el
|
|
login y lo manda directo a `/clientes` (gestión de tenants), no a `/dashboard`
|
|
(operativo despacho). `dashboard/page.tsx` también tiene `useEffect` defensivo
|
|
que redirige si llega ahí por URL directa.
|
|
|
|
```ts
|
|
const isGlobalAdmin = isGlobalAdminRfc(response.user?.tenantRfc, userRole, platformRoles);
|
|
if (isGlobalAdmin) router.push('/clientes');
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Sidebar — banner "Configuración inicial" oculto
|
|
|
|
`components/layouts/sidebar.tsx`: el banner que linkea a `/onboarding` solo se
|
|
muestra cuando `(!contribuyentes || contribuyentes.length === 0) && role !== 'cliente' && !isGlobalAdmin`.
|
|
El admin global nunca tendrá contribuyentes en su tenant raíz Horux 360 — el
|
|
banner sería ruido permanente.
|
|
|
|
(Una versión inicial también limpiaba todos los items operativos del sidebar
|
|
para el admin global. Revertida — el admin global mantiene acceso completo
|
|
para impersonar tenants. Solo cambia el banner.)
|
|
|
|
---
|
|
|
|
## 4. `/admin/usuarios` — fix `roleLabels[role].icon` undefined
|
|
|
|
Bug latente desde que se introdujeron los roles del despacho. `roleLabels`
|
|
solo tenía `owner/contador/visor` (Horux 360 mainline); cuando aparecía un
|
|
user con rol `cfo`, `supervisor`, `auxiliar` o `cliente`, el lookup retornaba
|
|
`undefined` y `roleInfo.icon` lanzaba TypeError.
|
|
|
|
Fix: agregar los 7 roles + `defaultRoleInfo` como fallback defensivo:
|
|
|
|
```ts
|
|
const roleLabels: Record<string, { label: string; icon: typeof Shield; color: string }> = {
|
|
owner: { label: 'Dueño', icon: Shield, color: 'text-primary' },
|
|
cfo: { label: 'CFO', icon: Briefcase, color: 'text-indigo-600' },
|
|
contador: { label: 'Contador', icon: Calculator, color: 'text-green-600' },
|
|
supervisor: { label: 'Supervisor', icon: UserCheck, color: 'text-blue-600' },
|
|
auxiliar: { label: 'Auxiliar', icon: UserCog, color: 'text-cyan-600' },
|
|
cliente: { label: 'Cliente', icon: User, color: 'text-amber-600' },
|
|
visor: { label: 'Visor', icon: Eye, color: 'text-muted-foreground' },
|
|
};
|
|
const defaultRoleInfo = { label: 'Sin rol', icon: User, color: 'text-muted-foreground' };
|
|
```
|
|
|
|
---
|
|
|
|
## 5. `/configuracion/precios-suscripcion` — planes despacho
|
|
|
|
La página leía `plan_prices` (BD central, planes Horux 360 legacy:
|
|
starter/business/business_ia/enterprise). En el fork no aplican.
|
|
|
|
**Reescrita** para mostrar los 4 planes despacho desde `DESPACHO_PLAN_PRICES`:
|
|
|
|
| Plan | Mensual | Anual 1er año | Anual renovación | RFCs | Timbres/mes |
|
|
|---|---:|---:|---:|---:|---:|
|
|
| Mi Empresa | $580 | $5,800 | $5,800 | 1 | 50 |
|
|
| Mi Empresa + | $900 | $9,000 | $9,000 | 1 | 50 |
|
|
| Business Control | No aplica | $25,850 | $25,850 | 100 | 0 |
|
|
| Enterprise | No aplica | $43,000 | $43,000 | 100 | 0 |
|
|
|
|
**Modo read-only** porque los precios viven en `DESPACHO_PLAN_PRICES`
|
|
(catálogo estático en `@horux/shared`).
|
|
|
|
### Capacidad latente para edición
|
|
|
|
Migración aplicada `20260426230000_despacho_plan_prices`:
|
|
|
|
```sql
|
|
CREATE TABLE despacho_plan_prices (
|
|
plan TEXT PRIMARY KEY,
|
|
monthly DECIMAL(10,2),
|
|
first_year DECIMAL(10,2) NOT NULL,
|
|
renewal DECIMAL(10,2) NOT NULL,
|
|
permite_monthly BOOLEAN NOT NULL DEFAULT false,
|
|
updated_at TIMESTAMP NOT NULL
|
|
);
|
|
```
|
|
|
|
Seed inicial con los 4 planes y sus valores. Permite migrar a editable cuando
|
|
se quiera — service + endpoints + UI editable quedan como follow-up.
|
|
|
|
---
|
|
|
|
## 6. Gestión de clientes (`/clientes`)
|
|
|
|
Página enriquecida con KPIs y operaciones para el admin global.
|
|
|
|
### Backend
|
|
- **Service**: `apps/api/src/services/admin-clientes.service.ts`
|
|
- `getClientesStats({ from, to })` — devuelve:
|
|
- `suscripcionesPorPlan`: groupBy plan con count (status=authorized).
|
|
- `ingresos`: sum + count de `Payment.amount` con status=approved en rango.
|
|
- `noRenovaciones`: subs con `currentPeriodEnd` en rango y status terminal
|
|
(cancelled / trial_expired / paused) + datos del tenant.
|
|
- `usuariosPorCliente`: count de memberships activos por tenant.
|
|
- `getTenantUsuarios(tenantId)` — drill-down: lista users + rol + isOwner.
|
|
- **Controller**: `controllers/admin-clientes.controller.ts` con
|
|
`requireStaff(req)` (platform_admin/ti).
|
|
- **Routes**: `routes/admin-clientes.routes.ts` montadas en
|
|
`/api/admin/clientes` (`GET /stats`, `GET /:tenantId/usuarios`).
|
|
|
|
### UI
|
|
- Selector de rango de fechas (default mes en curso).
|
|
- 4 KPI cards: clientes registrados / suscripciones activas (con breakdown por
|
|
plan en pie) / ingresos del periodo / no renovaciones.
|
|
- Tabla "Clientes que no renovaron" expandible con detalle (cliente, RFC, plan,
|
|
vencimiento, status).
|
|
- En cada item de la lista de clientes, click sobre el contador de usuarios
|
|
abre un modal con la lista (email, nombre, rol, badge de owner).
|
|
|
|
---
|
|
|
|
## 7. Auto-facturación de pagos al cliente
|
|
|
|
CLAUDE.md ya documentaba `invoicing.service.ts:emitInvoiceIfApplicable`. Cada
|
|
webhook `payment.approved` lo dispara. Idempotente por `Payment.facturapiInvoiceId`,
|
|
fail-soft si Facturapi falla.
|
|
|
|
### Ajustes en este turno
|
|
- `PLAN_LABELS` extendido con los 4 planes despacho. Antes la factura mostraba
|
|
el codename (`mi_empresa`, `business_cloud`) en lugar de "Mi Empresa" /
|
|
"Enterprise".
|
|
- Texto "Horux 360" → "Horux Despachos" en la descripción del CFDI y en el
|
|
concepto de timbres.
|
|
|
|
### Prerequisito operativo (manual del admin)
|
|
|
|
El emisor de las facturas es el tenant Horux 360 (RFC `HTS240708LJA`).
|
|
Requiere:
|
|
|
|
1. **CSD válido** subido vía `/configuracion/csd` por Carlos (admin global).
|
|
2. `tenants.facturapi_org_id` poblado tras crear la organización en Facturapi.
|
|
|
|
Hoy la columna está en `null` para el tenant recién bootstrapeado. Mientras
|
|
falte, `emitInvoiceIfApplicable` registra error en consola y `Payment.facturapiInvoiceId`
|
|
queda null. **Pendiente operativo**: que Carlos suba el CSD.
|
|
|
|
---
|
|
|
|
## 8. Gestión de add-ons (`/configuracion/addons`)
|
|
|
|
Página nueva para que el admin global edite el catálogo de add-ons.
|
|
|
|
### Backend
|
|
- **Controller**: `controllers/admin-addons.controller.ts`
|
|
- `listCatalogo` — incluye count de suscripciones activas por add-on.
|
|
- `updateCatalogoItem(id, { nombre?, precio?, active? })` con audit log.
|
|
- **Routes**: `/api/admin/addons/catalogo` (`GET`, `PUT /:id`). `requireStaff`.
|
|
|
|
### UI
|
|
- Tabla con columnas: codename, nombre (editable), precio MXN (editable),
|
|
frecuencia, suscripciones activas (read-only), estado (badge), acciones.
|
|
- Edición inline con dos botones (guardar / cancelar) por fila.
|
|
- Toggle de activación con **confirmación condicional**: si el add-on tiene
|
|
≥1 suscripción activa, pide confirmar antes de desactivar.
|
|
- Card link agregada al `/configuracion` raíz solo visible para admin global.
|
|
|
|
### Add-ons del catálogo actual
|
|
- `lolita_ia_contribuyente` — Lolita IA (por contribuyente) — $250/mes
|
|
- `modulo_ia` — Módulo IA Fiscal — $390/mes
|
|
- `rfcs_extra_10` — +10 RFCs adicionales — $190/mes
|
|
- `rfcs_extra_50` — +50 RFCs adicionales — $690/mes
|
|
- `timbres_extra_500` — +500 timbres mensuales — $490/mes
|
|
- `contribuyente_extra_business_cloud` — Contribuyente adicional — $45/mes (overage automático Business Control / Enterprise)
|
|
|
|
---
|
|
|
|
## 9. Sync al repo OneDrive
|
|
|
|
Tras cada bloque de cambios, ejecutado:
|
|
|
|
```powershell
|
|
robocopy "C:\Users\chtr1\Downloads\Horux_despacho" "C:\Users\chtr1\OneDrive\Documentos\GitHub\Horux_despachos" /E `
|
|
/XD node_modules .next .turbo dist .pnpm data email-previews .git xmls `
|
|
/XF .env .env.local "*.log" tsconfig.tsbuildinfo /NFL /NDL /NJH
|
|
```
|
|
|
|
Excluye `node_modules`, builds, caches, secretos, datos de tenants, y el
|
|
`.git/` del destino para preservar el repo origen.
|
|
|
|
---
|
|
|
|
## 10. Pendientes derivados
|
|
|
|
- **Cargar CSD del Horux 360** vía `/configuracion/csd` para activar
|
|
auto-facturación real. Sin esto, `emitInvoiceIfApplicable` falla silencioso.
|
|
- **Hacer editable `DespachoPlanPrice` desde UI**: la migración + seed están
|
|
aplicados pero falta service + endpoint + UI editable. Mientras tanto la
|
|
página de precios queda read-only.
|
|
- **Notificación al desactivar add-on con suscripciones activas**: hoy se
|
|
bloquean las contrataciones nuevas pero las activas siguen vigentes. Quizá
|
|
enviar email al owner avisando que el add-on quedará "deprecated".
|
|
- **Visual cue del prerequisito faltante de Facturapi org**: agregar alerta
|
|
en `/clientes` o `/configuracion` cuando el tenant Horux 360 no tenga
|
|
`facturapi_org_id` para que Carlos lo configure.
|
|
|
|
---
|
|
|
|
## 11. Pendientes históricos (sin cambio)
|
|
|
|
- SMTP `.env` prod (cron de notificaciones loguea a consola sin SMTP).
|
|
- Cloudflare Tunnel + `FRONTEND_URL` HTTPS dev.
|
|
- Typecheck web cleanup (~18 errores preexistentes).
|
|
- Nómina (tipo N) y Carta Porte sin implementar.
|
|
- SAT rejections — esperando captura real.
|
|
- Re-notificación bug 2.4 visibilidad auxiliares (sin reproducción específica).
|