Montar un entorno desde cero (alta y asociación de entidades)¶

Esta guía te lleva, paso a paso y en el orden correcto, a dar de alta un entorno operativo completo de WorkDone Sanitarios desde una base vacía. Al terminar tenés un entorno operativo: una empresa con sucursales, sectores, sanitarios con sus tags, operarios, y rutas asignadas — listo para que el personal de campo empiece a tapear.

Todo lo que hacés acá se hace en el BackOffice web: la aplicación React que el propio backend sirve en http://localhost:8080 (en desarrollo entrás con admin / admin). Cada paso de esta guía es una pantalla real del menú lateral. Para los integradores que prefieren el API, debajo de cada paso dejamos el endpoint y el JSON exactos en un bloque "Bajo el capó".

El orden importa: cada entidad depende de la anterior por una FK (foreign key). No podés crear un Sector sin su Sucursal, ni un Sanitario sin su Sector. Seguí la secuencia y no vas a chocar contra un 404 de "padre inexistente".

El orden de dependencias¶

Este diagrama es el mapa de toda la guía. Cada flecha es una dependencia: la entidad de destino necesita que la de origen exista primero.

flowchart TD
    E[1 Empresa] --> S[2 Sucursal]
    S --> SE[3 Sector]
    TS[4 TipoSanitario] --> SAN[5 Sanitario]
    SE --> SAN
    SAN --> SLA[6 SlaLimpieza 1 a 1]
    SAN --> TAG[7 TagNfc alta y asignacion]
    OP[8 Operario] --> DEV[9 Dispositivo]
    SAN --> RUTA[10 Ruta y paradas]
    RUTA --> ASIG[11 Asignacion operario a ruta]
    OP --> ASIG
    ASIG --> EJEC[12 Ejecucion del dia generada por scheduler]

{ "empresa": { "id": 1 } }

Paso 1 — Empresa (la raíz)¶

Dónde: menú lateral Estructura → pestaña Empresas → botón + Nueva.

La Empresa es el cliente del servicio (ej. AA2000). No tiene dependencias: es la raíz de toda la jerarquía. No es multi-tenant; es solo el primer nivel de agrupación. En la práctica suele haber una sola (EMPRESA-DEFAULT); el nivel existe para futuras expansiones.

La pantalla Estructura concentra los cuatro primeros niveles de la jerarquía en pestañas: Empresas, Sucursales, Sectores y Tipos de sanitario. Cada pestaña tiene su propio botón + Nueva y su lista.

{
  "codigo": "AA2000",
  "nombre": "Aeropuertos Argentina 2000",
  "activo": true,
  "visibleOpiniones": false
}

Resultado verificable: la nueva empresa aparece en la lista de la pestaña Empresas con estado Active.

Paso 2 — Sucursal (FK → Empresa)¶

Dónde: Estructura → pestaña Sucursales → + Nueva. Al crearla, elegís la empresa del paso 1 como padre.

Una Sucursal es una sede del cliente (ej. AEP, EZE). Pertenece a una Empresa.

{
  "codigo": "AEP",
  "nombre": "Aeroparque Jorge Newbery",
  "direccion": "Av. Costanera Rafael Obligado s/n",
  "activo": true,
  "empresa": { "id": 1 }
}

Resultado verificable: la sucursal aparece en la pestaña Sucursales. Su id lo usás en el paso 3.

Paso 3 — Sector (FK → Sucursal)¶

Dónde: Estructura → pestaña Sectores → + Nueva, eligiendo la sucursal del paso 2.

Un Sector es una zona dentro de la sucursal (ej. Terminal A, Patio de comidas).

{
  "codigo": "T-A",
  "nombre": "Terminal A",
  "activo": true,
  "sucursal": { "id": 1 }
}

Resultado verificable: el sector aparece en la pestaña Sectores. Su id lo usás en el paso 5.

Paso 4 — TipoSanitario (catálogo, sin FK)¶

Dónde: Estructura → pestaña Tipos de sanitario. Suele venir ya sembrado (seed: DAMAS, CABALLEROS, DISCAPACITADOS, MIXTO); en ese caso solo revisás la lista y saltás al paso 5. Si falta alguno, + Nueva.

TipoSanitario es un catálogo chico que clasifica los sanitarios.

{
  "codigo": "DAMAS",
  "nombre": "Damas",
  "activo": true
}

Resultado verificable: la pestaña Tipos de sanitario lista los tipos disponibles, listos para asignar.

Paso 5 — Sanitario (FK → Sector + TipoSanitario)¶

Dónde: menú lateral Sanitarios → botón + Nuevo. Elegís el sector (paso 3) y, opcionalmente, el tipo de sanitario (paso 4).

El Sanitario es el baño concreto donde va pegada la placa NFC. Es el centro de gravedad del sistema: la historia de limpiezas, las opiniones y el SLA viven en él.

La pantalla Sanitarios lista cada baño con su código, sector y sucursal, tipo, el tag NFC asignado (paso 7) y su estado. El botón + Nuevo abre el alta.

{
  "codigo": "AEP-T-B12",
  "nombre": "Baño Damas Terminal A planta 1",
  "descripcion": "Frente a puerta de embarque 12",
  "activo": true,
  "sector": { "id": 1 },
  "tipoSanitario": { "id": 1 }
}

Resultado verificable: el sanitario aparece en la lista de Sanitarios (todavía sin tag). Su id lo usás en los pasos 6, 7 y 10.

Paso 6 — SlaLimpieza (1:1 con el Sanitario)¶

Dónde: se configura desde la ficha del sanitario (en el detalle/edición de la pantalla Sanitarios). Es 1:1: como máximo un SLA por sanitario (sanitario es UK).

La SlaLimpieza define la exigencia de limpieza de un sanitario: cada cuánto, en qué ventana horaria y qué días.

{
  "frecuenciaMin": 120,
  "ventanaDesde": "06:00:00",
  "ventanaHasta": "23:00:00",
  "duracionMinimaSeg": 30,
  "diasSemana": "LMXJVSD",
  "activo": true,
  "sanitario": { "id": 1 }
}

Resultado verificable: el sanitario ya tiene su reloj de SLA; en el Dashboard (paso 12) aparece su columna SLA con la frecuencia (ej. c/60m). Recordá que solo una limpieza válida lo resetea.

Paso 7 — TagNfc: alta de stock + asignación al sanitario¶

Dónde: menú lateral Tags NFC. La pantalla lista todos los tags con sus pestañas (Todos / En stock / Asignados / Baja) y permite Desasignar / Reasignar desde el BackOffice.

Ponerle una placa física a un sanitario son dos transiciones de la máquina de estados del tag: primero alta de stock (EN_STOCK), después asignación al sanitario (ASIGNADO).

La pantalla Tags NFC muestra el ciclo de vida de cada tag (alias, UUID, estado, sanitario, fecha de asignación). El propio BackOffice avisa: "El alta de tags se hace desde la app móvil (requiere leer el chip NFC). Desde acá solo podés gestionar los tags ya registrados."

Como es un flujo con sus propias reglas (whitelist estricta, normalización de UUID, máximo 1 tag asignado por sanitario, auditoría en TagNfcEvento), está documentado aparte:

➡️ Seguí la guía dedicada: Registrar y asignar un tag NFC.

Resultado verificable: en la pestaña Asignados de Tags NFC, tu tag figura ligado al sanitario del paso 5. Bajo el capó, GET /api/v1/app/nfc/resolver/{uuid} devuelve { "estado": "ASIGNADO", "sanitario": { ... } }.

Paso 8 — Operario (con su rol)¶

Dónde: menú lateral Operarios → botón + Nuevo.

El Operario es la identidad del personal en la app móvil. Su rol decide qué hace en el sistema.

La pantalla Operarios lista al personal con su usuario, nombre, rol (chip de color), teléfono, email y último login. Las pestañas superiores filtran por rol; las acciones por fila incluyen editar, resetear password (ícono de llave) y resetear PIN.

Valores de rol (enum RolOperario):

{
  "usuario": "jperez",
  "nombre": "Juan",
  "apellido": "Pérez",
  "telefono": "+54 11 5555-0000",
  "email": "jperez@corpal.com",
  "activo": true,
  "rol": "OPERADOR_LIMPIEZA",
  "nuevaPassword": "unaClaveSegura123",
  "nuevoPin": "4821"
}

Resultado verificable: el operario aparece en la lista de Operarios con estado Activo. Ya puede loguearse en la app (POST /api/v1/app/auth/login-password o login-pin). Su id lo usás en el paso 11.

Paso 9 — Dispositivo del operario (alta + vinculación por código, flujo B)¶

Dónde: menú lateral Dispositivos, donde se listan los dispositivos, se dan de alta, se generan/regeneran códigos de vinculación y se habilitan/deshabilitan/desvinculan.

La pantalla Dispositivos: "Registrá uno y entregá el código al operario para vincular su teléfono". Cada fila muestra estado (Activo), vinculación (Vinculado / Sin vincular) y acciones (Desvincular).

Para que un teléfono pueda loguear y sincronizar, su Dispositivo tiene que estar registrado y activo. El login valida el device por el header X-Device-UUID antes de emitir tokens (ADR-044): un device no registrado o deshabilitado no obtiene tokens ni aunque las credenciales sean correctas, y un POST /api/v1/app/sync de un device no registrado o revocado recibe 401 (DEVICE_NO_REGISTRADO o DEVICE_REVOCADO).

Esto genera un huevo-y-gallina: el teléfono necesita estar registrado para loguear, pero su device_uuid real solo se conoce desde el propio teléfono. El flujo B (vinculación por código) lo resuelve, con el mismo patrón que la terminal Smiley: el admin da de alta el dispositivo y genera un código; el operario ingresa ese código en la app y el teléfono aporta su device_uuid real al canjearlo.

flowchart TD
    A[Admin en BackOffice, pantalla Dispositivos] --> B[POST alta con solo el nombre]
    B --> C[Backend crea APP_OPERARIO con device_uuid placeholder PENDIENTE y devuelve un codigo de 8 chars valido 2 horas]
    C --> D[Admin le pasa el codigo al operario]
    D --> E[Operario en la app, link Vincular con codigo, ingresa el codigo]
    E --> F[App llama POST api v1 app vincular con codigo mas su device_uuid real]
    F --> G[Backend fija el device_uuid real y marca el codigo como usado]
    G --> H[El operario ya puede loguear normal, el device quedo registrado y activo]

En el BackOffice (pantalla Dispositivos):

1. Alta: creás el dispositivo poniendo solo el nombre (ej. "Celular Juan Pérez"). El backend crea el registro APP_OPERARIO con un device_uuid placeholder (PENDIENTE-*, por eso figura como no vinculado) y te devuelve un código de vinculación de 8 caracteres, válido 2 horas. Anotalo: se muestra para dárselo al operario.
2. Regenerar código: si el código venció o lo perdiste, lo regenerás con un click. Es idempotente: si el device pendiente ya tiene un código vigente, devuelve el mismo; solo genera uno nuevo si no hay o está vencido.
3. Habilitar / Deshabilitar: togglean activo. Deshabilitar es la revocación (escenario de robo): en el próximo sync el teléfono recibe 401 DEVICE_REVOCADO y se bloquea solo.
4. Desvincular: rompe el binding — resetea el device_uuid a un placeholder, limpia el código y deja el device activo=false. El teléfono que tenía ese uuid deja de estar registrado (su próximo sync/login da DEVICE_NO_REGISTRADO) y la app reabre el enrolamiento (vuelve a mostrar el link "Vincular con código"). Para reusar el registro: generás un código nuevo y el operario vuelve a vincular.

En la app móvil (lo hace el operario): en el login aparece el link "Vincular con código" (solo mientras el device no esté vinculado). Lo toca, ingresa el código que le dio el admin y listo: el teléfono queda registrado y ya puede loguear con usuario + PIN/password. El detalle del flujo del lado app está en App móvil.

Resultado verificable: tras el alta, el dispositivo aparece en Dispositivos como no vinculado y con su código a la vista. Cuando el operario canjea el código desde la app, pasa a vinculado y activo; tras el primer sync, su ultimo_sync queda poblado.

Paso 10 — Ruta y sus paradas (FK → Sanitario)¶

Dónde: menú lateral Rutas → botón + Nueva ruta.

Una Ruta es una plantilla reusable: una lista ordenada de sanitarios (las paradas) que define el recorrido. La ruta es una capa de planificación arriba del tap, nunca un bloqueo: un tap fuera de ruta no es un error.

La pantalla Rutas de limpieza lista cada plantilla con su nombre, descripción, #Paradas y estado. El botón + Nueva ruta abre el alta donde agregás las paradas (sanitarios) en orden.

{
  "nombre": "Recorrido matutino Terminal A",
  "descripcion": "Limpieza de apertura, planta 1",
  "activo": true,
  "paradas": [
    { "sanitario_id": 1, "orden": 1 },
    { "sanitario_id": 2, "orden": 2 },
    { "sanitario_id": 3, "orden": 3 }
  ]
}

Resultado verificable: la ruta aparece en la lista de Rutas con su contador de #Paradas y estado Activa. Su id lo usás en el paso 11.

Paso 11 — Asignar el operario a la ruta (FK → Ruta + Operario)¶

Dónde: menú lateral Asignaciones → botón + Nueva asignación. Elegís la ruta (paso 10) y el operario (paso 8).

La RutaAsignacion conecta una ruta con un operario de forma recurrente (qué días, en qué franja horaria, durante qué vigencia). De acá salen, automáticamente, las ejecuciones de cada día.

La pantalla Asignaciones de rutas muestra cada asignación recurrente: la ruta, el operario, los días activos, el horario (ej. 08:00–16:00), la vigencia y el estado. El subtítulo lo resume: "El scheduler genera ejecuciones automáticamente."

{
  "ruta_id": 1,
  "operario_id": 7,
  "dias_semana": "LMXJV--",
  "hora_desde": "06:00:00",
  "hora_hasta": "14:00:00",
  "vigencia_desde": "2026-06-22",
  "vigencia_hasta": null,
  "activo": true
}

Cómo se generan las ejecuciones del día¶

La asignación es la plantilla recurrente; lo que el operario ve cada día es una RutaEjecucion concreta:

• Un scheduler nocturno (@Scheduled, default 0 0 4 * * * — las 04:00) recorre las asignaciones activas cuyo día matchea dias_semana y que están en vigencia, y por cada una crea la RutaEjecucion de hoy (PENDIENTE) con sus paradas como snapshot de la plantilla. Es idempotente. (Detalle de schedulers en Jobs y alertas.)
• Una limpieza válida (operador) o una supervisión cerrada (supervisor) sobre un sanitario de la ruta marca esa parada HECHA automáticamente — vía evento, el tap no sabe de rutas.
• Reasignación del día: si el operario titular falta, movés la ejecución de hoy a otro operario desde la pantalla Rutas de hoy, sin tocar la asignación recurrente. Bajo el capó:

PATCH /api/v1/admin/ruta-ejecucion/{id}/reasignar
Content-Type: application/json

{ "operario_id": 9 }

Resultado verificable: la asignación aparece en la lista de Asignaciones con sus días, horario y vigencia. Tras correr el scheduler (o el día siguiente), la ejecución del día se ve en Rutas de hoy (ver paso 12).

Paso 12 — Verificación final del entorno¶

Cerrás el círculo confirmando que las dos puntas — operario en campo y administrador en las pantallas — ven lo que tienen que ver.

El Dashboard pinta tus sanitarios¶

Dónde: menú lateral Dashboard. Filtrás por sucursal y sector y ves la grilla en tiempo real.

El Dashboard muestra el estado actual de cada sanitario: estado (Libre/Limpiando/SLA vencido/Sin datos/Sin exigencia), última limpieza, hace cuánto, el SLA configurado (paso 6) y alertas. Es la vista de "todo en orden".

El tablero de Rutas de hoy¶

Dónde: menú lateral Rutas de hoy. Filtrás por fecha, sucursal y estado, y desde acá reasignás las ejecuciones PENDIENTE/EN_CURSO.

La pantalla Rutas de hoy lista las ejecuciones generadas por el scheduler para la fecha elegida, con su operario efectivo, estado y progreso (paradas_hechas/total). Si todavía no corrió el scheduler para hoy, muestra "Sin ejecuciones para los filtros seleccionados".

Resumen de las verificaciones¶

Ver también¶

• Registrar y asignar un tag NFC — el detalle del paso 7 (alta de stock + asignación), que se hace por la app móvil.
• Modelo de datos — todas las entidades, columnas y FKs de las que habla esta guía.
• Jobs y alertas — el scheduler que genera las ejecuciones del día y los demás jobs.
• Portal del cliente — cómo el cliente final ve el estado de sus sanitarios una vez que el entorno está operativo.