Saltar a contenido

14 — Superadmin (operación de la plataforma)

¿Qué es el superadmin?

Un panel separado del dashboard cliente que sirve para que el operador del SaaS:

  • Vea la lista global de Accounts y Bots.
  • Edite el catálogo de planes (precios, features, traducciones).
  • Promueva bots a "verified" tras revisar PII.
  • Vea métricas globales (MRR, churn, distribución por plan).
  • Gestione invitaciones del modo prelaunch.
  • Acceda a las facturas de todos los clientes.

No reemplaza al Django admin (/admin/). Django admin es para DBA-level. El superadmin es una UI de negocio.

Acceso

  • URL: https://app.tudominio.com/superadmin/
  • Auth: JWT con rol superadmin en SaasUser.role.
  • Para crear el primer superadmin: 
    cd backend_django && source venv/bin/activate
python manage.py shell <<'PY'
from authentication.models import SaasUser
u = SaasUser.objects.create_user(
    email='admin@tudominio.com',
    password='CAMBIA_ESTO',
    first_name='Admin',
    is_active=True, is_verified=True
)
u.role = 'superadmin'
u.save()
PY

Frontend (apps/superadmin/)

Un React SPA independiente del dashboard cliente. Build:

cd apps/superadmin && npm install && npm run build
# → apps/superadmin/dist/

Nginx lo sirve bajo /superadmin/:

location /superadmin/ {
    alias /home/blimxapp/saas/chatbot-v3-workspace/apps/superadmin/dist/;
    try_files $uri $uri/ /superadmin/index.html;
    expires 5m;
}

Si prefieres servirlo desde un subdominio (admin.tudominio.com), cambia el alias por root y ajusta vite.config.ts para base: '/'.

Páginas del superadmin

Tenants list (/superadmin/tenants)

Lista paginada de bots con búsqueda y filtros:

  • Búsqueda por slug, nombre, email del owner.
  • Filtros: plan, status, fecha de creación.
  • Métricas por bot: # FAQs, # idiomas activos, último update.

Endpoint: GET /api/sa/tenants/?page=1&search=acme&plan=Pro.

Tenant detail (/superadmin/tenants/<bot_id>)

Vista 360° de un bot:

  • Owner (Account + SaasUsers vinculados).
  • Suscripción actual (plan, estado, próxima facturación).
  • Historial de planes (billing_audit_log).
  • Últimas 50 facturas.
  • Snapshot de FAQs por idioma.
  • Botón "Promote to verified" — corre validación PII automática y, si no hay > N findings, marca el bot como is_verified=True.

Plans (/superadmin/plans)

CRUD del catálogo:

  • Crear/editar planes — modifica plans.features.limits directamente.
  • Sync con Stripe — al pegar un nuevo stripe_price_id valida que existe en Stripe.
  • Traducciones (plans.translations jsonb por idioma).
  • Toggle activo/inactivo.

Users (/superadmin/users)

Lista de SaasUsers con opciones de:

  • Activar/desactivar.
  • Cambiar rol (member → owner, owner → superadmin).
  • Forzar password reset.
  • Ver bots a los que tiene acceso.

Invoices (/superadmin/invoices)

Lista global paginada con filtros por:

  • Account, status (paid/open/uncollectible/void), rango de fechas.
  • Total recaudado en el rango.
  • Link al hosted_invoice_url de Stripe.

Analytics (/superadmin/analytics)

KPIs globales:

  • MRR (Monthly Recurring Revenue): suma de plans.price * subscriptions activas.
  • ARR: MRR * 12.
  • Total FAQs en plataforma (knowledge_base.is_faq=true).
  • Distribución por plan (pie chart).
  • Bots creados por mes (line chart).

Endpoint: GET /api/sa/analytics/overview/ — ya no incluye métricas de chat/conversaciones (producto Help Center).

Activity feed (/superadmin/activity)

Cronológico de eventos importantes:

  • Account creado / cerrado.
  • Bot creado / borrado.
  • Plan cambiado.
  • Invoice fallida.
  • Invitación aprobada / rechazada.

Endpoint: GET /api/sa/activity-feed/.

Pre-launch (/superadmin/prelaunch)

Si activas el modo prelaunch, esta página te deja:

  • Activar/desactivar el modo (toggle).
  • Aprobar/rechazar invitation_requests.
  • Generar códigos de prelaunch en lote.

Catalogos (/superadmin/catalogs)

CRUD de:

  • Business categories (business_categories).
  • Business types (business_types).

Las usan los flujos de onboarding y profile templates.

Permisos

  • Cualquiera con role=superadmin ve TODO.
  • No hay segregación de permisos dentro del superadmin (es un rol único).
  • Si necesitas separar (ej. "billing-only operator"), añade un rol nuevo y custom permissions en views_superadmin.py.

Auditoría

Toda acción del superadmin que muta datos se loguea:

  • Cambio de plan en un bot → billing_audit_log con actor_role='superadmin'.
  • Promote de bot → account_events con type='promote'.
  • Aprobación de invitación → account_events con type='invitation_approved'.

Cosas a recordar

  • Cuidado al editar plans.stripe_price_id — si cambias el price ID de un plan que ya tiene suscripciones activas, los nuevos checkouts irán al precio nuevo pero las suscripciones existentes mantienen el price viejo (Stripe behavior). Para migrar masivamente hay que llamar a subscription.update() por cada una.
  • El superadmin no impersonate clientes. Si necesitas ver el dashboard como un cliente concreto, usa el Django admin para resetear su password y entrar como él.
  • Backups antes de operaciones masivas. Si vas a editar 100+ rows desde el superadmin, primero pg_dump (ver 16-backup-restore.md).