Manual SuperAdmin — Plataforma Huella

Guía para el equipo gestor (Help U): colegios cliente, planes, tarifas por alumnos, suscripciones, demos, notificaciones y auditoría.

Versión 1.0.1 · Actualizado Julio 2026

1. Introducción

El menú Plataforma está disponible para usuarios con rol SuperAdmin de la empresa gestora (Help U). Desde ahí se administra el SaaS multi-tenant de colegios: altas de empresas, catálogo de planes, tarifas por rango de alumnos, demos y comunicaciones globales. Los cobros y cambios de plan se hacen en la web comercial (Help U / pasarela); Huella solo recibe la confirmación por API.

Este manual es exclusivo del operador de la plataforma. El personal de cada colegio debe usar el manual de usuario.

Módulo	Función
Planes	Catálogo Demo, Básico, Profesional.
Tarifas	Periodos de facturación, rangos de alumnos y precios mensuales.
Empresas	Alta, edición, activación y tema visual de cada colegio.
Años lectivos	Catálogo global de años lectivos usados por los colegios.
Usuarios	Cuentas de acceso y asociación a empresas (roles Spatie).
Demos	Bandeja de registros desde `/registro`.
Suscripciones	Consulta de estado e historial de pagos. Reinicio de datos operativos.
Notificaciones	Avisos por empresa, plan o usuario.
Auditoría	Registro de acciones sensibles.

2. Acceso y roles

2.1 SuperAdmin

Inicie sesión con un usuario de la empresa gestora (empresa_id = 1). El rol SuperAdmin ve únicamente el menú Plataforma (planes, tarifas, empresas, años lectivos, usuarios, demos, suscripciones, notificaciones y auditoría).

Los módulos operativos del colegio (Configuraciones, Académico, RRHH, Finanzas) corresponden a roles como Admin, Rector, Coordinador, etc. El usuario Admin de la gestora es el perfil de soporte: puede usar el selector de colegio y operar cada cliente con permisos de Admin.

El SuperAdmin no usa el selector de colegio. Para revisar datos operativos, use el Admin de soporte de la gestora o un Admin del colegio cliente.

2.2 Plan vencido

Los colegios con suscripción vencida no pueden ingresar (pantalla /plan-vencido). La empresa gestora no está sujeta a esta restricción.

2.3 Semáforo de suscripción

Estado	Significado
Al día	Suscripción activa dentro del periodo.
Próximo a vencer	Dentro del rango de aviso del plan.
Vencido	Fecha de vencimiento superada; bloqueo de acceso.

3. Selector de colegio (gestora)

En el encabezado, el usuario Admin de la gestora (soporte) puede elegir en qué colegio trabajar sin cerrar sesión. El SuperAdmin no usa este selector.

Cambia el contexto de sesión (empresa_id) y muestra los menús operativos del cliente.
No modifica la empresa asociada al usuario en base de datos; solo el contexto de trabajo.
Puede volver a «Gestora» o al colegio deseado desde el mismo selector.

4. Empresas (colegios)

Alta y edición de clientes: NIT (9 dígitos), datos de contacto, municipio, tema visual y estado activo. Desde la ficha se gestiona el administrador del colegio (credenciales).

Rutas: listado /admon/empresas, ficha y administrador asociado.
Al crear desde el panel se puede iniciar en demo o dejar pendiente de pago comercial.
El tema (tema_id) afecta branding de PDFs y la sugerencia comercial; el login usa ?tag=.

5. Años lectivos

Catálogo global de años lectivos que los colegios asocian a periodos académicos y matrículas. Mantenga años activos para el ciclo en curso; no elimine años con datos históricos vinculados.

6. Planes

Catálogo de planes de la plataforma escolar (solo estos códigos):

Código	Nombre	Notas
`demo`	Demo	Hasta 50 alumnos; facturación trimestral; precio fijo demo.
`basico`	Básico	Tarifa calculada: tope del rango × `VALOR_ALUMNO_BASICO`.
`profesional`	Profesional	Tarifa calculada: tope del rango × `VALOR_ALUMNO_PROFESIONAL`.

Las capacidades del plan definen qué módulos se anuncian en la web comercial. Help U solo oferta basico y profesional para cobro (el demo no se vende en checkout).

7. Tarifas

Los precios no se guardan en base de datos. Se calculan en runtime: tope del rango × valor/alumno (.env), luego × meses × (1 − descuento%) según el periodo (mensual 0%, trimestral 5%, semestral 10%, anual 15%). Más de 700 alumnos requiere cotización. La web usa GET /api/public/cotizar.

8. Suscripciones

Panel de consulta: plan actual, semáforo, historial de pagos y referencia de checkout. Ya no se asignan planes ni se registran pagos manuales aquí; eso lo hace el pago en línea.

Acción disponible: reinicio de datos operativos (conserva empresa, admin, plan e historial de pagos; borra datos académicos/operativos del colegio). Útil al salir de una prueba demo.

9. Usuarios

Gestión de cuentas: crear/editar usuarios, asociarlos a empresas y roles Spatie (SuperAdmin, Admin, Rector, Coordinador, Secretaria, Docente, Estudiante, Solicitante).

10. Notificaciones

Avisos dirigidos a todas las empresas, a un plan, a un colegio o a un usuario. Aparecen en la campana del encabezado de la aplicación.

11. Demos

Bandeja de solicitudes creadas en /registro. Desde aquí se revisan y activan colegios en plan demo según el flujo comercial acordado. Tras la prueba, el cliente paga en la web; el webhook puede enviar reset_datos_demo.

12. Auditoría

Registro de acciones sensibles (pagos web, cambios de suscripción, reinicios, etc.). Consulte por empresa, tipo de evento o rango de fechas.

13. API web comercial

La integración completa (auth, cotizar, alta, webhook) está en ws.php.

Token: HUELLA_API_TOKEN · encabezados Authorization: Bearer … o X-Huella-Token.
Prefijo de referencias: HUELLA_PAGO_PREFIJO (default WEB).

14. Base de datos y migraciones

En desarrollo: php artisan migrate:fresh --seed (incluye gestora + colegio demo). En producción: migrate --force y seeders base acordados (sin demo).

No ejecute migrate:fresh en producción: borra todos los datos.

15. Soporte

Contacto Help U: helpu1@helpu.com.co · Sitio: https://helpu.com.co.