Manual SuperAdmin — Operación Habbita

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

Versión 1.0.1 · Actualizado Julio 2026

1. Introducción

El menú Habbita está disponible para usuarios con rol SuperAdmin de la empresa gestora (Help U S.A.S). Desde ahí se administra la plataforma multi-tenant: altas de conjuntos, catálogo de planes, consulta de suscripciones, demos y comunicaciones globales. Los cobros y cambios de plan se hacen en la web comercial (Help U / Wompi); Habitta solo recibe la confirmación por API.

Este manual es exclusivo del operador de la plataforma. Los administradores de cada conjunto deben usar el manual de usuario, que no incluye estas funciones.

Módulo Habbita	Función
Planes	Catálogo de planes de la app (Demo, Esencial, Inteligente).
Tarifas	Periodos, rangos de unidades y precios mensuales por plan.
Empresas	Alta, edición, activación y tema visual de cada cliente.
Usuarios	Cuentas de acceso y asociación a empresas (roles vía Spatie / seeders).
Demos	Bandeja de registros desde `/registro`.
Suscripciones	Consulta de estado e historial de pagos (referencia). Reinicio de datos operativos.
Notificaciones	Avisos por empresa, plan o usuario.
Categorías	Códigos consecutivos de categorías de la plataforma.
Auditoría	Registro de acciones sensibles en la plataforma.

Menú lateral con sección Habbita — Figura A1 — Vista del menú Habbita para SuperAdmin. Archivo: imgs/A01-menu-habbita.png

2. Acceso y roles

2.1 SuperAdmin

Inicie sesión con su usuario de la empresa gestora (empresa_id = 1). El rol SuperAdmin está limitado a la plataforma: el menú lateral muestra únicamente la sección Habbita (planes, tarifas, empresas, usuarios, demos, suscripciones, notificaciones, categorías y auditoría).

Los módulos operativos de un conjunto (Administración, RRHH, Conjunto, Parqueaderos, Asamblea) corresponden al rol Admin y demás roles operativos. El usuario Admin de la empresa gestora (empresa_id = 1) es el perfil de soporte: puede usar el selector de conjunto y operar cada cliente con sus permisos de Admin.

El SuperAdmin gestiona solo la plataforma (Habbita) y no usa el selector de conjunto. Si necesita revisar datos operativos de un cliente, use el usuario Admin de soporte de la gestora o un Admin del conjunto cliente.

Encabezado con plan activo y campana de notificaciones — Figura A2 — Header del SuperAdmin (plan y notificaciones; sin selector de conjunto). Archivo: imgs/A02-header-plan-superadmin.png

2.2 Plan vencido

Las empresas cliente con suscripción de app vencida no pueden ingresar (pantalla /plan-vencido), salvo que tengan un pack de asamblea activo (acceso limitado a operación de asamblea). 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 configurado en el plan.
Vencido	Fecha de vencimiento superada; bloqueo de acceso.

3. Selector de conjunto (gestora)

En el encabezado, los usuarios de la gestora con rol Admin (soporte) o SuperAsamblea pueden elegir en qué conjunto trabajar sin cerrar sesión. El SuperAdmin no usa este selector.

El Admin de la gestora (perfil de soporte) cambia el contexto de sesión (empresa_id) y ve los menús operativos del cliente elegido. El SuperAsamblea solo fija un filtro de trabajo (super_asamblea_empresa_id) para el menú Asamblea operación (ver manual SuperAsamblea); no sustituye la sesión autenticada.

Disponible para usuarios de empresa_id = 1 con rol Admin (sin SuperAdmin) o SuperAsamblea.
No modifica la empresa asociada al usuario en base de datos; solo el contexto o filtro de trabajo en sesión.
Vuelva a «Gestora» o al conjunto deseado desde el mismo selector (botón deshacer cuando aplica).

Selector de conjunto en el encabezado — Figura A3 — Selector de conjunto en la gestora (cambio de contexto de sesión). Archivo: imgs/A03-selector-conjunto.png

4. Empresas

Ruta: Habbita → Empresas.

Listado de empresas cliente — Figura A4 — Listado de empresas en Habbita. Archivo: imgs/A04-empresas-listado.png

4.1 Crear empresa

Complete nombre, NIT sin dígito de verificación, correo, municipio y demás datos legales.
Seleccione el tema visual (colores del login con ?tag=).
Al crear, asigne el plan inicial (normalmente Demo) y la fecha de inicio. En edición ese campo no aparece: el plan solo cambia vía pago en la web comercial.
Defina si la empresa inicia activa o inactiva (demos suelen quedar inactivas).
Al activar una empresa inactiva, el sistema puede enviar correo de bienvenida al administrador.

4.2 Activación y acceso

La contraseña inicial del administrador del conjunto suele ser el NIT sin dígito de verificación.
Comparta la URL de login con el parámetro tag correspondiente al tema de la empresa.
Empresas inactivas no pueden operar hasta activarse (bandeja de demos o pago web — ver API).

Formulario de creación o edición de empresa — Figura A5 — Alta o edición de empresa (datos, tema y estado activo). Archivo: imgs/A05-empresa-formulario.png

5. Planes (app Habitta)

Ruta: Habbita → Planes y Habbita → Tarifas.

Estos planes son la suscripción de la plataforma (módulos y acceso a la app). Los packs de asamblea son un servicio adicional y se administran en SuperAsamblea → Planes asamblea; comprar asamblea no reemplaza el plan app.

Cada plan define código interno (API), módulos contratados y días de aviso antes del vencimiento.

Planes app — precio por unidad × rango (COP)
El valor unitario mensual se configura en .env (VALOR_UNIDAD_ESENCIAL / VALOR_UNIDAD_INTELIGENTE), no en BD. La cantidad de unidades determina el rango (Hasta 50, 51–100, …). Total del periodo: unidades × valor_unidad × meses × (1 − descuento%). Descuentos: 1 mes 0%, 3 meses 5%, 6 meses 10%, 12 meses 15%. Más de 700 unidades requiere cotización.

Plan	Código API	Valor / und.	Hasta 50	51 – 100	101 – 300	301 – 700	+700
Demo	`demo`	$5.200*	$5.200 – $260.000	Solo hasta 50 und. · 90 días · periodo trimestral
Esencial	`esencial`	$4.500	$4.500 – $225.000	$229.500 – $450.000	$454.500 – $1.350.000	$1.354.500 – $3.150.000	Cotización
Inteligente	`inteligente`	$5.200	$5.200 – $260.000	$265.200 – $520.000	$525.200 – $1.560.000	$1.565.200 – $3.640.000	Cotización

*Demo usa VALOR_UNIDAD_INTELIGENTE. Los importes de cada rango son el total mensual de referencia (piso–techo del rango × valor unidad); el cobro exacto usa las unidades contratadas. Rangos editables en Habbita → Tarifas. API: GET /api/public/planes?tipo=app (ver API).

Catálogo de planes de servicio — Figura A6 — Planes de servicio (código, módulos y aviso). Archivo: imgs/A06-planes-servicio.png

6. Suscripciones

Ruta: Habbita → Suscripciones.

Vista de solo lectura del estado comercial de cada empresa cliente, con dos pestañas: Empresas (plan, fechas, semáforo) y Pagos (historial con referencia).

Plan actual, fechas de inicio y vencimiento (pestaña Empresas).
Historial de pagos con referencia de checkout/Wompi (pestaña Pagos). Solo lectura.
Acción permitida: Reiniciar datos operativos (conserva empresa, admin, plan e historial de pagos).

SuperAdmin no asigna planes ni registra pagos desde este panel. Renovaciones y cambios de plan se activan únicamente con el pago en línea (Help U → webhook).

6.1 Reglas de vigencia al pagar

Demo vigente → plan pago: inicia hoy y suma los días restantes del demo al vencimiento.
Demo vencido → plan pago: inicia hoy, sin días bonus.
Renovación pago → pago (vigente): el nuevo periodo empieza el día siguiente al vencimiento actual.

6.2 Pagos desde la web comercial

Los pagos confirmados por Wompi llegan vía POST /api/webhooks/suscripcion/pago (ver documentación API). Help U envía el ID de la transacción Wompi como referencia; Habitta la almacena con prefijo (WEB-WOMPI-...).

Un pago de plan app renueva la suscripción de plataforma. Un pago de pack asamblea activa el servicio adicional empresas.asamblea sin quitar el plan app vigente. El flag reset_datos_demo del webhook (opcional) borra datos de prueba al salir de demo; el reinicio del panel es independiente y puede usarse en cualquier momento.

Panel de suscripciones por empresa — Figura A7 — Suscripciones: pestañas Empresas/Pagos y reinicio. Archivo: imgs/A07-suscripciones.png

7. Usuarios

Los roles del sistema (SuperAdmin, SuperAsamblea, Admin, RRHH, Asamblea, Guarda, Propietario, etc.) se definen en seeders / Spatie Permission; no hay pantalla de Roles en el menú Habbita.

7.1 Usuarios

Ruta: Habbita → Usuarios.

Cree usuarios y asígnelos a una o más empresas.
Asigne roles según la función en cada conjunto.
Use Asociar para vincular un usuario existente a otra empresa.

Gestión de usuarios y asociación a empresas — Figura A9 — Usuarios: alta, roles y asociación multi-empresa. Archivo: imgs/A09-usuarios.png

8. Notificaciones

Ruta: Habbita → Notificaciones.

Publique avisos que aparecen en la campana del header:

Dirigidos a una empresa específica, a un plan o a un usuario.
Útiles para mantenimientos programados, cambios de tarifa o recordatorios de renovación.

Formulario de avisos y notificaciones — Figura A10 — Avisos dirigidos a empresa, plan o usuario. Archivo: imgs/A10-avisos.png

9. Demos

Ruta: Habbita → Demos.

El formulario público /registro crea una solicitud y, tras validaciones, una empresa en estado inactivo con plan demo. La bandeja permite:

Revisar datos del solicitante (conjunto, NIT, contacto, tema elegido).
Aprobar o rechazar la solicitud.
Al aprobar/activar la empresa, el cliente recibe credenciales y puede ingresar.

Alternativa: el cliente paga un plan en la web comercial (flujo «Ya soy cliente» con NIT); el webhook activa la empresa si activar_empresa es verdadero. Si el demo sigue vigente, Habitta suma los días restantes al vencimiento del plan comprado.

9.1 Correos del funnel demo

Correo de recepción al solicitante al enviar el formulario.
Correo de activación al pasar la empresa a activa (panel o API).

Bandeja de solicitudes demo — Figura A11 — Solicitudes demo desde `/registro`. Archivo: imgs/A11-demos-bandeja.png

Formulario público de solicitud de demo — Figura A12 — Formulario público `/registro` (vista del solicitante). Archivo: imgs/A12-registro-publico.png

10. Categorías

Ruta: Habbita → Categorías.

Administra códigos consecutivos de categorías de la plataforma (migración create_tables_categoria_codigos). No confundir con las categorías de apartamento del módulo Administración de cada conjunto.

11. Auditoría

Ruta: Habbita → Auditoría.

Registro de acciones sensibles: pagos web, cambios de configuración, operaciones de módulos extendidos (PQRS, portería, reservas, etc.). Filtre por empresa, usuario, acción y fecha.

Listado de auditoría con filtros — Figura A13 — Registro de auditoría de la plataforma. Archivo: imgs/A13-auditoria.png

12. Integración con la web comercial

La pasarela de pago de planes no está embebida en Habitta. La web de Help U debe integrarse con la API documentada en ws.php:

Configurar el mismo HABITTA_API_TOKEN en Habitta y en la web.
Listar planes y consultar empresas antes del checkout.
Confirmar el pago tras respuesta exitosa de la pasarela.

Tareas programadas: el comando habitta:recordatorios-diarios (07:00) envía alertas de cartera y vencimientos según configuración del conjunto.

13. Base de datos y migraciones

Esta sección describe cómo está organizado el esquema de Habitta en el código Laravel (database/migrations/). Está pensada para quien despliega o mantiene la plataforma (SuperAdmin / equipo técnico de Help U).

Principio: cada archivo de migración corresponde a un módulo de negocio. Las tablas se crean completas con sus relaciones (FK) cuando ya existen las tablas de las que dependen. No se usan alter ni parches posteriores: el modelo de datos sirve a la aplicación, no al orden arbitrario de ejecución.

13.1 Comandos habituales

Comando	Cuándo usarlo
`php artisan migrate`	Entorno ya existente: aplica solo migraciones pendientes.
`php artisan migrate:fresh --seed`	Desarrollo o instalación limpia: borra todo, recrea el esquema y ejecuta seeders.
`php artisan db:seed`	Recargar datos iniciales sin tocar el esquema (catálogos, usuario gestor, permisos).

migrate:fresh destruye todos los datos. No usarlo en producción con clientes activos.

13.2 Secuencia de migraciones (orden de ejecución)

Los archivos se ejecutan por prefijo numérico. La secuencia respeta las dependencias del dominio:

#	Archivo	Contenido
000	`create_tables_cache`	Infraestructura Laravel (caché, colas).
001	`create_tables_parameters`	Catálogos: ciudades, tipos de documento, tipos de residente, tipos de obligación, tipos de parqueadero, temas, etc.
002	`create_tables_persons`	Empresas (conjuntos), personas y empleados.
003	`create_tables_residential`	Conjunto: bloques, apartamentos, residentes.
004	`create_tables_permission`	Roles y permisos (Spatie).
005	`create_tables_users`	Usuarios de acceso, sesiones y tokens. Incluye `residente_id` para el rol Propietario.
006	`create_tables_payrolls`	Nómina: periodos, empleados, préstamos, nóminas.
007	`create_tables_parking`	Parqueaderos, sorteos, asignación a apartamentos, tarifas de visitante.
008	`create_tables_cartera`	Configuración de cartera y obligaciones por apartamento.
009	`create_tables_parking_visitantes`	Arriendos de parqueadero a visitantes.
010	`create_tables_asamblea`	Asambleas, invitaciones, votación, logística.
011	`create_tables_locales`	Locales comerciales y sus obligaciones.
012	`create_tables_terceros`	Proveedores y obligaciones a terceros.
013	`create_tables_caja`	Caja menor (movimientos vinculables a arriendos visitante).
014	`create_tables_suscripcion`	Planes comerciales, suscripciones y pagos de empresa.
015	`create_tables_avisos`	Avisos globales y lecturas por usuario.
016	`create_tables_pqrs`	PQRS de residentes.
017	`create_tables_porteria`	Registro de visitas en portería.
018	`create_tables_zonas_comunes`	Áreas comunes y reservas.
019	`create_tables_mantenimiento`	Órdenes de mantenimiento.
020	`create_tables_auditoria`	Log de auditoría de la plataforma.
021	`create_tables_categoria_codigos`	Códigos consecutivos de categorías (menú Habbita → Categorías).

13.3 Relación entre parqueaderos, cartera y visitantes

El módulo de parqueaderos está repartido en tres migraciones consecutivas porque así funciona el negocio en la aplicación, no por limitación técnica:

Parking (007) — Plazas, sorteos y asignación de parqueadero a apartamento (apartamento_parqueaderos).
Cartera (008) — Las obligaciones pueden vincularse a una asignación de parqueadero (apartamento_parqueadero_id).
Visitantes (009) — Un arriendo de visitante puede generar o enlazar una obligación en cartera (apartamento_obligacion_id).

Cadena del dominio: parqueadero → cartera → visitante.

13.4 Usuarios y portal del propietario

Los usuarios de staff (Admin, RRHH, Guarda, etc.) se crean en Habbita → Usuarios y se asocian a un empleado.
Los propietarios tienen rol Propietario y un registro en usuarios con residente_id apuntando al residente del conjunto.
El acceso al portal es el mismo login (/login); la aplicación redirige al propietario a /portal.
La activación del acceso portal se hace desde Conjunto → Residentes (editar ficha del residente).

13.5 Seeders (datos iniciales)

Tras migrate:fresh --seed se ejecutan, en orden:

Seeder	Qué carga
`DaneSeeder`	Ciudades y municipios (DANE).
`ParametrosSeeder`	Tipos, cargos, medios de pago, temas visuales.
`UsuariosSeeder`	Empresa gestora, roles, permisos (plataforma, operativos y portal propietario) y usuarios demo: SuperAdmin y SuperAsamblea en Habbita; Admin, RRHH, Asamblea y Guarda para operación del conjunto.

Opcional en desarrollo: php artisan db:seed --class=ResidentialDemoSeeder para datos de prueba de apartamentos y residentes.

13.6 Buenas prácticas al modificar el esquema

En fase de desarrollo, preferir ajustar la migración original del módulo y ejecutar migrate:fresh en lugar de acumular migraciones alter.
Los catálogos (tipos_*) van en create_tables_parameters.
Si una tabla depende de otra, su archivo debe ejecutarse después (número mayor o nombre posterior).
En producción con datos reales, usar migraciones incrementales normales y respaldo previo.

Anexo A — Lista de capturas de pantalla

Coloque cada imagen en la carpeta imgs/ (misma ruta que este manual). Los archivos del manual SuperAdmin usan el prefijo A para no mezclarse con las capturas del manual de usuario.

Archivo	Contenido sugerido
`A01-menu-habbita.png`	Menú lateral con sección Habbita
`A02-header-plan-superadmin.png`	Header: plan y notificaciones (SuperAdmin sin selector)
`A03-selector-conjunto.png`	Selector de conjunto en gestora
`A04-empresas-listado.png`	Listado de empresas
`A05-empresa-formulario.png`	Formulario alta/edición empresa
`A06-planes-servicio.png`	Catálogo de planes
`A07-suscripciones.png`	Suscripciones: pestañas Empresas/Pagos y reinicio
`A09-usuarios.png`	Usuarios y asociación
`A10-avisos.png`	Notificaciones
`A11-demos-bandeja.png`	Bandeja solicitudes demo
`A12-registro-publico.png`	Formulario público /registro
`A13-auditoria.png`	Auditoría de la plataforma

Anexo B — Soporte interno

Para incidencias de clientes, indique empresa, usuario afectado, captura y pasos. Consultas técnicas de integración: revisar logs de Laravel y la tabla de auditoría.

Contacto corporativo: Help U · soporte01.habitta@gmail.com