Guía del panel admin

Todas las rutas /admin/* del portal están restringidas a usuarios con globalRole = 'admin_msp'. Las rutas adicionales requieren permisos específicos de sub-rol MSP. Esta guía recorre cada sección del admin.

Requisito de acceso

Debes estar logueado con un usuario cuyo user.role = 'admin_msp' en la base de datos. Los client admins (client_admin) no ven la sección admin del sidebar.

Estructura de navegación

La sección admin aparece debajo de un separador en el sidebar del portal. Los items se filtran tanto por el rol principal admin_msp como opcionalmente por un permission key (permiso de sub-rol MSP):

Ruta	Label	Ícono	Permiso requerido
/admin/dashboard	Admin dashboard	BarChart3	ninguno (admin_msp)
/admin/tenants	Tenants	Building2	tenants.read
/admin/leads	Leads	UserPlus	leads.read
/admin/tenant-requests	Tenant requests	FileText	tenant_requests.read
/admin/impersonations	Impersonations	Eye	impersonation.read_log
/admin/team	MSP team	ShieldCheck	team.read
/admin/settings/roles	Roles	KeyRound	roles.read
/admin/discount-codes	Discount codes	Tag	ninguno
/admin/billing/fees	Billing fees	DollarSign	ninguno
/admin/onboarding-queue	Onboarding queue	ListChecks	ninguno
/admin/commissions	Commissions	BadgeDollarSign	commissions.manage
/admin/my-commissions	My commissions	CircleDollarSign	ninguno

---

Dashboard admin (/admin/dashboard)

[Screenshot: /admin/dashboard tarjetas de métricas globales]

Muestra métricas globales:

• Total tenants — conteo de todos los tenants por estado (active, past_due, suspended)
• Monthly revenue — suma de total_charge de billing_periods abiertos
• Total calls this month — suma de total_calls de billing periods abiertos

Fuente de datos: trpc.admin.globalOverview → admin.service.getGlobalOverview().

Nota: Los valores de revenue y llamadas vienen de billing_periods que tiene RLS. En la implementación actual, pueden mostrar 0 si app.current_tenant no está seteado para consultas cross-tenant. Se planea una función SECURITY DEFINER para solucionar esto.

---

Tenants (/admin/tenants)

[Screenshot: /admin/tenants lista con badges de estado]

Lista todos los tenants con: nombre, slug, plan, estado, cantidad de teléfonos, cantidad de líneas, estado de Stripe.

Filtros disponibles: estado (active, past_due, suspended, cancelled), búsqueda de texto (nombre o slug).

Acciones desde la lista:

• Click en nombre del tenant → va a /admin/tenants/:id detalle
• Crear nuevo tenant: /admin/tenants/new

Tabs de detalle del tenant (/admin/tenants/:id/*)

Tab ruta	Qué muestra
/overview	Info de contacto, plan, badge de estado, accountCode, rango de extensiones, IDs de Stripe
/edit	Formulario de edición: nombre, slug, plan, rango de extensiones, account code, campos de contacto, notas internas
/billing	Billing periods e invoices del tenant. Links al detalle de invoice con InvoiceBreakdown.
/users	Miembros del org de este tenant. Opciones para desactivar/reactivar.
/inventory	Números de teléfono y trunk lines asignados a este tenant (tablas Fase 11 — solo lectura por ahora)
/config	tenant_billing_config: dirección fiscal, código de jurisdicción, override de carrier mode, estado de exención impositiva, fee codes excluidos
/activity	Entradas de tenant_activity_log — registra cambios de estado, cambios de plan, etc.

Cambiar estado del tenant (desde tab overview o edit):

• active → suspended: bloquea todo acceso al portal excepto billing para el tenant
• suspended → active: restaura acceso completo
• Los cambios de estado también deben sincronizarse con el estado de suscripción de Stripe (ver Runbooks)

---

Leads (/admin/leads)

[Screenshot: /admin/leads lista con columnas de source y estado]

Captura de leads desde la landing page (POST /api/v1/leads). Los leads son clientes potenciales que expresaron interés.

Columnas: nombre, email, teléfono, empresa, mensaje, source, estado, created at.

Acciones:

• Marcar como contacted, qualified, disqualified
• Los leads marcados como qualified se pueden convertir a tenants (crear org + tenant desde los datos del lead)

Fuente de datos: trpc.admin.leads y trpc.leads.*.

---

Tenant requests (/admin/tenant-requests)

[Screenshot: /admin/tenant-requests cola]

Solicitudes enviadas por usuarios client_admin existentes desde el portal Settings → flujo "Request tenant". Son solicitudes de expansión (ej: un cliente quiere agregar una segunda sucursal).

Estado	Significado
pending	Recién enviada, necesita revisión
approved	Provisionada — nuevo tenant creado
rejected	Rechazada con motivo

Ir a /admin/tenant-requests/:id para revisar los detalles y aprobar o rechazar.

---

Impersonations (/admin/impersonations)

[Screenshot: /admin/impersonations tabla de log]

Log de solo lectura de todas las sesiones de impersonation. Cada entrada muestra: email del impersonator, email del usuario impersonado, organización, hora de inicio, hora de fin, IP address.

Importante: Mientras se impersona a un usuario, todas las mutaciones de escritura (mutations de protectedProcedure envueltas por impersonationAwareProcedure) están bloqueadas. La sesión de impersonation es de solo lectura por diseño.

Para iniciar una sesión de impersonation (desde el tab de usuarios del tenant): click en "Impersonate" junto a un usuario → abre una nueva sesión como ese usuario → el portal muestra un banner de impersonation → click en "Exit impersonation" para volver.

Fuente de datos: trpc.admin.impersonation.* y tabla admin_impersonations.

---

MSP team (/admin/team)

[Screenshot: /admin/team lista de usuarios MSP]

Lista todos los usuarios con role = 'admin_msp'. Muestra los sub-roles MSP de cada usuario.

Acciones:

• Invitar nuevo miembro del equipo (envía email de invitación MSP via tabla msp_invitations)
• Asignar/remover sub-roles MSP: super_admin, billing_clerk, sales_rep, technician
• Desactivar miembro del equipo

Fuente de datos: trpc.admin.team.*.

---

Roles (/admin/settings/roles)

[Screenshot: /admin/settings/roles matriz de roles y permisos]

Gestión de role definitions MSP y sus asignaciones de permisos. La matriz de permisos muestra qué permisos tiene cada sub-rol MSP.

Los roles de sistema (is_system = true) no pueden borrarse. Se pueden crear roles personalizados y asignarles cualquier subconjunto de permisos.

Las categorías de permisos incluyen: tenants, leads, billing, commissions, team, roles, impersonation, tenant_requests.

Fuente de datos: trpc.admin.roles.* → tablas msp_role_definitions, msp_permissions, msp_role_permissions.

---

Discount codes (/admin/discount-codes)

[Screenshot: /admin/discount-codes lista]

Códigos de descuento promocionales para nuevas suscripciones. Muestra código, tipo de descuento (porcentaje o monto fijo), planes aplicables, fecha de expiración y conteo de usos.

Fuente de datos: trpc.discounts.* → tabla discounts.

---

Billing fees (/admin/billing/fees)

[Screenshot: /admin/billing/fees catálogo de fees]

La interfaz de gestión de fees. Muestra todas las fee definitions con su estado, tipo, rate y jurisdicción.

Sub-rutas:

• /admin/billing/fees — lista de fees con filtros (jurisdiction, category, status)
• /admin/billing/fees/new — crear un nuevo fee
• /admin/billing/fees/:id — detalle del fee: editar, historial, análisis de impacto, test de cálculo
• /admin/billing/carrier-mode — ver carrier mode actual + checklist de requisitos
• /admin/billing/compliance — compliance dashboard: tracking de registros por authority, totales

Para documentación completa de gestión de fees ver Admin fees.

---

Onboarding queue (/admin/onboarding-queue)

[Screenshot: /admin/onboarding-queue]

Tracking de checklists de onboarding de tenants. Los nuevos tenants pasan por un flujo de onboarding gestionado por admin-onboarding.router.ts. Los admins pueden ver qué pasos completó cada nuevo tenant.

Fuente de datos: trpc.admin.onboarding.*.

---

Commissions (/admin/commissions)

[Screenshot: /admin/commissions overview]

Panel admin completo de comisiones. Requiere permiso commissions.manage. Sub-rutas:

Ruta	Contenido
/admin/commissions	Overview: reps activos, statements pendientes, último pago
/admin/commissions/vendedores	Lista de sales reps — crear, invitar, desactivar
/admin/commissions/asignaciones	Asignaciones de tenant a rep
/admin/commissions/atribucion	Log de atribución — qué rep recibe crédito por qué tenant
/admin/commissions/ingresos	Lista de revenue events
/admin/commissions/statements	Commission statements — generar, aprobar, marcar como pagados
/admin/commissions/configuracion	Settings de comisiones: tasas, schedule de pagos, reglas MLM

Para documentación de comisiones ver la sección Comisiones.

---

My commissions (/admin/my-commissions)

Disponible para todos los usuarios admin_msp sin permisos adicionales. Muestra el perfil de commission rep del usuario actual (si está vinculado). Si el usuario no está vinculado a un rep, la página muestra instrucciones sobre cómo configurarlo.

---

Referencia de acciones rápidas

Tarea	Dónde hacerlo
Verificar estado de billing de un tenant	/admin/tenants/:id/billing
Ver desglose de factura	/admin/tenants/:id/billing → click en factura
Suspender un tenant manualmente	/admin/tenants/:id/overview → cambiar estado
Invitar nuevo miembro del equipo MSP	/admin/team → Invite
Agregar un fee	/admin/billing/fees/new
Verificar registro de compliance	/admin/billing/compliance
Generar reporte tributario trimestral	trpc.adminFees.quarterlyReport (API, sin UI aún)
Impersonar un client user	/admin/tenants/:id/users → Impersonate
Revisar log de impersonation	/admin/impersonations
Aprobar/rechazar tenant request	/admin/tenant-requests/:id