Panel Admin

El Panel Admin es el centro de control para administradores de la plataforma Factux, permitiendo gestionar usuarios, suscripciones, características del sistema y soporte técnico.

Ruta

/admin

Acceso

Acceso Restringido

Este panel está protegido por RoleGuard y solo es accesible para usuarios con rol admin. Los usuarios sin permisos de administrador serán redirigidos automáticamente.

Estructura del Panel

El Panel Admin está organizado en 6 secciones principales:

1. Overview

• Ruta: /admin/overview
• Descripción: Dashboard principal con métricas del sistema
• Métricas incluidas:
  • Total de usuarios registrados
  • Suscripciones activas
  • Ingresos mensuales
  • Uso de recursos
  • Tickets de soporte pendientes
  • Tasa de conversión

2. Usuarios

Gestión completa de usuarios de la plataforma.

Submódulo	Ruta	Descripción
Usuarios Finales	/admin/users/end-users	Propietarios de negocios (rol: owner)
Asesores	/admin/users/advisors	Asesores fiscales (rol: advisor)
Negocios	/admin/users/businesses	Empresas registradas en la plataforma
Administradores	/admin/users/admins	Usuarios con acceso administrativo
Tax IDs Duplicados	/admin/users/duplicate-tax-ids	Detección de CIF/NIF duplicados

3. Suscripciones

Control de planes, pagos y uso del sistema.

Submódulo	Ruta	Descripción
Planes	/admin/subscriptions/plans	Gestión de planes (Free, Basic, Premium)
Activas	/admin/subscriptions/active	Suscripciones actualmente vigentes
Pagos	/admin/subscriptions/payments	Historial de transacciones y pagos
Uso	/admin/subscriptions/usage	Monitoreo de límites y consumo

4. Características (Features)

Gestión de funcionalidades y permisos.

Submódulo	Ruta	Descripción
Features	/admin/features	Feature flags y habilitación por plan
Sidebar Items	/admin/features/sidebar-items	Configuración de elementos del menú

5. Sistema

Configuración técnica y seguridad.

Submódulo	Ruta	Descripción
Configuración	/admin/system/configuration	Variables de entorno y settings
Base de Datos	/admin/system/database	Queries, migraciones, backups
Seguridad	/admin/system/security	Políticas RLS, logs de acceso
SendGrid Lists	/admin/system/sendgrid-lists	Listas de email marketing
SendGrid Contacts	/admin/system/sendgrid-contacts	Gestión de contactos de email

6. Soporte

Gestión de equipo de soporte y tickets.

Submódulo	Ruta	Descripción
Equipo	/admin/support/team	Miembros del equipo de soporte
Tickets	/admin/support/tickets	Sistema de tickets de soporte
Automatización	/admin/support/automation	Reglas automáticas de respuesta

7. Analíticas

Reportes y auditoría del sistema.

Submódulo	Ruta	Descripción
Reportes	/admin/analytics/reports	Informes de negocio y KPIs
Uso	/admin/analytics/usage	Análisis de uso de la plataforma
Audit Logs	/admin/analytics/audit-logs	Registro de eventos del sistema

---

Características Técnicas

SOPORTE TÉCNICO: Arquitectura del Panel Admin

Guardia de Roles (RoleGuard)

src/panels/_shared/guards/RoleGuard.tsx

<RoleGuard allowedRoles={['admin']}>
  <AdminLayout />
</RoleGuard>

Comportamiento:

• Verifica el rol del usuario en profiles.role
• Redirige a /unauthorized si no es admin
• Solo permite acceso a usuarios con rol exacto admin

Layout del Admin

src/panels/admin/layouts/AdminLayout.tsx

// - Sidebar con navegación por secciones
// - Outlet para renderizar children routes
// - Suspense boundary para lazy loading

Lazy Loading

Todas las páginas del panel admin usan lazy loading para optimizar el bundle:

const OverviewPage = lazy(() => import('./pages/Overview'));
const EndUsersPage = lazy(() => import('./pages/users/EndUsers'));
// ... más páginas

Beneficios:

• Reduce el tamaño del bundle inicial
• Carga solo las páginas que el usuario visita
• Mejora el tiempo de carga inicial

Rutas Anidadas (Nested Routes)

Patrón de rutas padre-hijo:

{
  path: '/admin',
  element: <RoleGuard><AdminLayout /></RoleGuard>,
  children: [
    { index: true, element: <OverviewPage /> },
    { path: 'users/end-users', element: <EndUsersPage /> },
    // ... más rutas hijas
  ]
}

Ventajas:

• Un solo RoleGuard protege todas las rutas hijas
• Layout consistente en todas las páginas
• Suspense centralizado en el Layout

Tablas Principales

Usuarios y Roles:

• profiles - Información de usuarios (con campo role)
• user_businesses - Relación usuarios-negocios
• businesses - Datos de empresas

Suscripciones:

• business_subscriptions - Suscripciones activas
• subscription_plans - Definición de planes
• subscription_audit_log - Historial de cambios
• stripe_invoices - Facturas de Stripe

Sistema:

• feature_flags - Features habilitadas por plan
• sidebar_items - Configuración del menú
• system_configuration - Variables del sistema
• user_access_logs - Logs de acceso y seguridad

Soporte:

• support_tickets - Tickets de soporte
• support_team_members - Equipo de soporte
• ticket_automation_rules - Reglas automáticas

Políticas RLS

El panel admin tiene políticas especiales de bypass para ciertos recursos:

-- Ejemplo: Admins pueden ver todos los negocios
CREATE POLICY "admin_view_all_businesses"
ON businesses FOR SELECT
TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM profiles
    WHERE profiles.user_id = auth.uid()
    AND profiles.role = 'admin'
  )
);

Edge Functions Relevantes

• admin-get-system-stats - Obtiene estadísticas del sistema
• admin-manage-subscription - Gestiona suscripciones manualmente
• admin-export-users - Exporta datos de usuarios (GDPR)
• admin-run-migration - Ejecuta migraciones de BD
• admin-send-notification - Envía notificaciones masivas

---

Mejores Prácticas

Para Administradores

1. Seguridad:

   • Mantén las credenciales de admin seguras
   • Usa autenticación de dos factores (2FA)
   • Revisa los logs de acceso regularmente

2. Gestión de Usuarios:

   • Verifica CIF/NIF duplicados semanalmente
   • Monitorea cuentas sospechosas de abuso
   • Responde tickets de soporte en menos de 24h

3. Suscripciones:

   • Revisa pagos fallidos diariamente
   • Monitorea el uso de recursos por plan
   • Gestiona downgrades y upgrades manualmente cuando sea necesario

4. Sistema:

   • Realiza backups de BD antes de migraciones
   • Monitorea errores en logs de Sentry
   • Revisa performance de Edge Functions

Para Soporte Técnico

1. Acceso Limitado:

   • Usuarios de soporte NO tienen acceso al Panel Admin
   • Solo admins pueden modificar suscripciones
   • Solo admins pueden ejecutar queries en BD

2. Documentación:

   • Documenta todas las intervenciones manuales
   • Usa el sistema de tickets para tracking
   • Escala issues críticos a admins

---

Tour Guiado

Primer Acceso al Panel Admin

1. Login como Admin:

   • Inicia sesión con cuenta de administrador
   • Verifica que tu perfil tiene role = 'admin'

2. Explora el Overview:

   • Revisa las métricas principales del dashboard
   • Identifica áreas que requieren atención (ej: tickets pendientes)

3. Revisa Usuarios:

   • Ve a /admin/users/end-users
   • Ordena por fecha de registro para ver nuevos usuarios
   • Verifica que no haya cuentas duplicadas en /admin/users/duplicate-tax-ids

4. Monitorea Suscripciones:

   • Revisa suscripciones activas en /admin/subscriptions/active
   • Verifica pagos en /admin/subscriptions/payments
   • Identifica usuarios cerca de sus límites en /admin/subscriptions/usage

5. Configura Sistema:

   • Ajusta variables en /admin/system/configuration si es necesario
   • Revisa logs de seguridad en /admin/system/security

---

Errores Comunes

Error	Causa	Solución
403 Unauthorized al acceder a /admin	Usuario no tiene rol admin	Verifica que profiles.role = 'admin' en la base de datos
Página en blanco al cargar submódulo	Error en lazy loading	Verifica la consola del navegador, posible error en componente
No aparecen datos de usuarios	Política RLS bloqueando acceso	Verifica que las políticas RLS permiten acceso a admins
Cambios en suscripción no se guardan	Error en Edge Function	Revisa logs de Supabase Edge Functions

---

Estado Actual

Panel Admin Básico

El Panel Admin actualmente tiene la estructura de navegación configurada con placeholders. La documentación detallada de cada submódulo se desarrollará en una fase posterior según prioridades del proyecto.

---

Referencias Externas

• Supabase RLS para Admin
• React Router Nested Routes
• React Lazy Loading