Saltar a contenido

Glosario del dominio

WorkDone tiene un vocabulario propio, en español, que aparece por todos lados: en el modelo de datos, en los endpoints, en las conversaciones con el cliente. Los nombres de dominio se mantienen en español (sanitario, trabajo, operario) — no se renombran a inglés. Esta página define los términos reales del sistema, agrupados por categoría, para que cuando los leas en el código o en una reunión sepas exactamente de qué se habla. Si un término te lleva a otro, seguilo: el dominio es una red, no una lista.

Fuente

Todas las definiciones salen del modelo de datos del backend y de las convenciones del ecosistema. Cuando necesites el detalle de columnas, índices o estados, la referencia es el modelo de datos del backend.

Jerarquía física

Cómo se organiza el espacio, de lo más grande a lo más chico. Es una cadena de pertenencia estricta: cada nivel cuelga del anterior.

Término Definición
Empresa El cliente del servicio (por ejemplo AA2000). Es el nivel más alto de la jerarquía. No es multi-tenant: una instalación de WorkDone sirve a una operación, la empresa es un dato de catálogo, no un aislamiento de inquilinos.
Sucursal Una sede física de la empresa (por ejemplo AEP, EZE). Cuelga de una empresa.
Sector Una zona dentro de la sucursal (por ejemplo "Terminal A", "Patio de comidas"). Cuelga de una sucursal. Su código es único dentro de la sucursal.
Sanitario El baño concreto que se limpia y controla. La unidad operativa central. Cuelga de un sector, tiene un código único global (ej. AEP-T-B12) y opcionalmente un tipo. La historia de limpiezas vive acá, no en la placa.
TipoSanitario Catálogo chico que clasifica al sanitario: DAMAS, CABALLEROS, DISCAPACITADOS, MIXTO. 
graph TD
    E["Empresa<br/>(ej. AA2000)"] --> S["Sucursal<br/>(ej. AEP, EZE)"]
    S --> SE["Sector<br/>(ej. Terminal A)"]
    SE --> SAN["Sanitario<br/>(ej. AEP-T-B12)"]
    TS["TipoSanitario<br/>(DAMAS/CABALLEROS/…)"] -.-> SAN

Operación: trabajos, taps y SLA

El núcleo de lo que el sistema registra. Acá vive el "qué pasó y cuándo".

Término Definición
Tap El gesto de acercar el teléfono a la placa NFC. Funciona como un toggle: el primer tap abre el trabajo (ingreso), el segundo lo cierra (egreso).
Trabajo La entidad central: un turno de limpieza o de supervisión. Mismo motor, distinto tipo. Tiene su client_uuid (idempotencia), inicio, fin, duración, estado y modo de registro.
Ingreso El estado del trabajo apenas se abre (primer tap). El operario "entró" al sanitario.
Egreso El estado del trabajo cuando se cierra (segundo tap). Queda registrada la duración.
Cierre automático Cierre de un trabajo que quedó "colgado" (sin egreso). Lo cierra el scheduler con la duración truncada. Lleva un warning; el cierre automático sí resetea el SLA, pero no cuenta como limpieza válida medida.
Tipo de trabajo LIMPIEZA (lo crea el OPERADOR_LIMPIEZA) o SUPERVISION (lo crea el SUPERVISOR). El tipo lo define el rol del operario. La supervisión nunca resetea el SLA.
Modo de registro Cómo se registró el trabajo: ONLINE, OFFLINE_SYNC, OFFLINE_PENDIENTE_RESOLUCION (tag desconocido) o MANUAL (registro sin placa).
Evento de limpieza Lo que el operario reporta al cerrar el trabajo ("¿cómo quedó el sanitario?"). Catálogo configurable, no enum. Seed: SIN_NOVEDAD, ROTURAS, REPONER_INSUMOS, NO_SE_PUDO_LIMPIAR, NO_ESTA_LIMPIO. Algunos generan alerta; algunos invalidan la limpieza (no resetean el SLA).
SLA El compromiso de frecuencia de limpieza de un sanitario (SlaLimpieza): cada cuántos minutos debe limpiarse, en qué ventana horaria y qué días de la semana.
SLA vencido Estado en el que un sanitario pasó su frecuencia comprometida sin una limpieza válida. Dispara la alerta SLA_VENCIDO.
Limpieza válida La definición clave para SLA y dashboard: un trabajo tipo=LIMPIEZA cerrado, sin eventos que invaliden la limpieza y con duración no anómala. Solo las limpiezas válidas resetean el reloj del SLA.
Duración anómala Un egreso con duración por debajo del piso de validez configurado. Se marca y no cuenta como limpieza válida (un tap-tap demasiado corto no es una limpieza real).
Cuenta para SLA Bandera por trabajo que materializa si esa fila cuenta para el SLA. NFC siempre cuenta; el registro manual depende de configuración; el cierre por scheduler no cuenta.
Registro sin placa / manual Registro de limpieza cuando la placa no se puede leer (rota, ausente, no lee). El operario elige el sanitario y un motivo de contingencia. Cuenta como válida (no perjudica el cumplimiento) y avisa a administración.
Cierre con eventos La pantalla del egreso donde el operario selecciona los eventos de limpieza antes de confirmar. 
stateDiagram-v2
    [*] --> INGRESO: primer tap
    INGRESO --> EGRESO: segundo tap (con eventos)
    INGRESO --> EGRESO_CIERRE_AUTOMATICO: scheduler (colgado)
    EGRESO --> [*]
    EGRESO_CIERRE_AUTOMATICO --> [*]

Tecnología NFC y dispositivos

Las piezas físicas y de identidad del ecosistema.

Término Definición
NFC Near Field Communication. La tecnología de proximidad con la que el teléfono lee la placa del sanitario.
Tag NFC / Placa El chip pegado en el sanitario. Contiene una URL con un UUID (https://workdone.lubeca.tech/t/{uuid}). El móvil lee la URL y extrae el UUID. En el modelo es TagNfc.
UUID del tag El identificador único que viaja en la placa. Se normaliza (trim/mayúsculas/sin espacios) en todo punto de entrada antes de usarlo.
Whitelist estricta Regla de seguridad: un tag no registrado es inutilizable. Un tap con un UUID desconocido genera un trabajo OFFLINE_PENDIENTE_RESOLUCION y la alerta TAG_DESCONOCIDO.
Máquina de estados del tag El ciclo de vida de una placa: EN_STOCK → ASIGNADO (a un sanitario) → BAJA, con desasignación y re-alta. Máximo un tag ASIGNADO por sanitario.
Alta de stock Dar de alta una placa nueva. Solo desde la app móvil (rol ADMIN), porque hay que leer el chip onsite.
Gestión NFC La app del rol ADMIN: en vez de registrar limpiezas, lee tags y los administra (alta, asignar, desasignar, reasignar, baja).
Dispositivo Un equipo registrado: un teléfono de operario (APP_OPERARIO) o una terminal Smiley (TERMINAL_SMILEY). Tiene device_uuid, api_key, número de terminal y telemetría. Se puede deshabilitar (teléfono perdido/robado).
api_key La credencial del dispositivo (no de la persona). Identifica al equipo para rate limiting y trazabilidad.
device_uuid El identificador del dispositivo, al que se liga el refresh token de la sesión.
Drift de reloj La diferencia entre el reloj del dispositivo y el del servidor, medida en el sync. Un drift grande dispara la alerta RELOJ_DESVIADO.
Doble-tap / rebote Dos taps físicos muy seguidos. El sistema descarta el ingreso que rebota justo después de un egreso (REBOTE_POST_EGRESO) para no crear un trabajo espurio. 
stateDiagram-v2
    [*] --> EN_STOCK: ALTA_STOCK (app móvil)
    EN_STOCK --> ASIGNADO: ASIGNACION
    ASIGNADO --> EN_STOCK: DESASIGNACION
    EN_STOCK --> BAJA: BAJA
    BAJA --> EN_STOCK: RE_ALTA (solo web)

Sincronización e idempotencia

Los conceptos que sostienen el offline-first. Profundizados en Arquitectura.

Término Definición
Offline-first El cliente opera 100% sin red y trata la conexión como eventual. Nada se pierde, nada se duplica.
client_uuid El identificador del evento, generado en el dispositivo al toque, antes de cualquier I/O. Es la clave de idempotencia.
Idempotencia Garantía de que reenviar el mismo evento (mismo client_uuid) produce el mismo resultado. Reintentar es seguro.
Sync El intercambio periódico (cada ~15 min, al recuperar red, al abrir/loguear) entre cliente y backend: el cliente empuja su cola, el backend responde con deltas y estados.
Cola offline Los trabajos pendientes guardados localmente (Room) que sobreviven a crashes, reinicios y actualizaciones hasta que se sincronizan.
Delta Las filas de catálogo cambiadas desde el último sync (updated_at > last_sync) que el backend devuelve para que el cliente actualice su cache.
ts_local_device El timestamp del dispositivo al momento del evento. Es la verdad temporal; el cliente garantiza el orden cronológico de la cola por este campo.
server_received_ts Cuándo el backend recibió el evento. Convive con ts_local_device pero no lo reemplaza.
updated_at Marca de tiempo de catálogo que habilita los deltas de sync.
Soft delete Borrado lógico (deleted_at) en catálogos: la fila no se elimina, así el sync puede propagar la baja a los clientes. En el BackOffice la convención es desactivar (activo=false), no borrar.

Opinión del público (Smiley)

La cara pública del sistema: lo que ve y toca el visitante del baño.

Término Definición
Smiley / Terminal de opinión La tablet en modo kiosko montada a la salida del sanitario. El visitante opina con un toque (3 caritas) y, si fue negativa, puede indicar un motivo. En reposo muestra "Último servicio: hace X min". Sin login.
Opinión El registro inmutable de una carita: POSITIVA, NEUTRA o NEGATIVA, con su motivo opcional, su client_uuid y su origen.
Origen de la opinión TERMINAL_SMILEY (la tablet) o QR_PUBLICO (escaneo de QR). Las de QR son "de segunda clase": no alimentan el motor de tendencias ni las stats de confianza.
Motivo de opinión El detalle de una opinión negativa. Seed: SUCIO, SIN_INSUMOS, MAL_OLOR, ALGO_ROTO, OTRO.
Tendencia negativa Una racha de opiniones negativas que supera un umbral en una ventana de tiempo. Dispara la alerta TENDENCIA_NEGATIVA.
QR público Cara de transparencia para el visitante vía QR (/p/{slug}): muestra el estado público del sanitario (ej. "Limpiado hace X min") y permite opinar de forma anónima.
Provisioning / vinculación El proceso por el que una terminal Smiley se asocia a un sanitario y recibe su identidad (número de terminal, alias) desde el backend. El device no define su identidad legible: la asigna el backend.
Modo kiosko El confinamiento de la tablet (Lock Task, launcher dedicado, sin barras de sistema, autoarranque) para que el visitante no salga de la app Smiley.

Planificación y supervisión

Capas que se montan por encima de la operación.

Término Definición
Ruta / Recorrido Plantilla reusable de paradas (sanitarios) en un orden. Es una capa de planificación arriba del tap, nunca un bloqueo: planifica, no impide registrar.
Parada de ruta Un sanitario dentro de una ruta, con su orden.
Asignación de ruta La recurrencia semanal de una ruta a un operario (qué días, en qué ventana horaria, desde/hasta qué fecha).
Ejecución de ruta La instancia de una ruta en un día concreto (PENDIENTE → EN_CURSO → COMPLETADA/INCOMPLETA). Una limpieza válida marca su parada como HECHA.
Alerta Una señal que el sistema levanta para administración: SLA_VENCIDO, DURACION_ANOMALA, OPERARIO_INACTIVO_OFFLINE, TAG_DESCONOCIDO, EVENTO_REPORTADO, RELOJ_DESVIADO, TAG_DEFECTUOSO, TENDENCIA_NEGATIVA. Puede atenderse manualmente o, en algunos casos, auto-atenderse.
Calendario de excepciones Fechas (feriados, paradas) por sucursal en las que no se exige limpieza: el SLA se pausa y no saltan alertas.
Dashboard La grilla en tiempo real del BackOffice: cada sanitario con su estado (LIBRE / LIMPIANDO / SLA_VENCIDO), tiempo desde la última limpieza y operarios activos.
Portal del cliente Acceso de solo lectura (ROLE_CLIENTE) a la transparencia del servicio: un cliente ve únicamente las empresas a las que tiene acceso, validado server-side.

Roles del sistema

Quién es quién. Los tres roles operativos viven en el operario; los demás son del plano web/público.

Término Definición
Operario La persona que usa la app móvil. Tiene usuario, PIN/password (hasheados, nunca viajan al móvil) y un rol.
OPERADOR_LIMPIEZA El rol que limpia: crea trabajos de tipo LIMPIEZA.
SUPERVISOR El rol que controla: crea trabajos de tipo SUPERVISION.
ADMIN El rol que gestiona placas: su app es Gestión NFC, no registra limpiezas por tap.
ROLE_CLIENTE Authority web de solo lectura para el portal de transparencia. No accede a endpoints operativos.
Usuario web (jhi_user) La cuenta del BackOffice (supervisión/administración), en un plano de autenticación separado del móvil.
Visitante El público anónimo que opina en la terminal Smiley o por QR. No tiene cuenta.

Para ver cómo estos términos se conectan en flujos concretos, volvé a Arquitectura; para el panorama general, a la página de inicio.