Modelo de datos¶

Si sos nuevo en WorkDone Sanitarios, este es el mapa que tenés que tener a mano. Todo el sistema gira alrededor de una idea simple: el personal de limpieza acerca su teléfono (o una terminal) a una placa NFC pegada en un sanitario y eso registra un trabajo. El resto del modelo existe para darle contexto a ese tap: dónde está el sanitario, quién lo hizo, con qué placa, qué pasó adentro y si cuenta para el SLA.

Esta página describe el modelo de datos v2, que reemplaza al v1. La fuente de verdad son las tablas MSSQL del backend (Spring Boot / JHipster). El nombre de dominio va siempre en español (sanitario, trabajo, operario) — nunca se renombra a inglés. La app móvil Android mantiene un espejo local (Room) de un subconjunto de estas tablas para funcionar offline; las diferencias están en la sección Espejo móvil.

Diagrama de entidades¶

El siguiente diagrama muestra las entidades principales y sus relaciones. La jerarquía física baja por la izquierda (Empresa → Sucursal → Sector → Sanitario) y la operación NFC cuelga del Sanitario.

erDiagram
    EMPRESA ||--o{ SUCURSAL : tiene
    SUCURSAL ||--o{ SECTOR : tiene
    SECTOR ||--o{ SANITARIO : contiene
    TIPO_SANITARIO ||--o{ SANITARIO : clasifica
    SANITARIO ||--o| SLA_LIMPIEZA : "define (1:1)"
    SANITARIO ||--o| TAG_NFC : "asignado (máx 1)"
    SANITARIO ||--o{ TRABAJO : "registra"
    SANITARIO ||--o{ OPINION : "recibe"
    TAG_NFC ||--o{ TAG_NFC_EVENTO : audita
    OPERARIO ||--o{ TRABAJO : crea
    OPERARIO ||--o{ TAG_NFC_EVENTO : ejecuta
    DISPOSITIVO ||--o{ TRABAJO : "registra desde"
    DISPOSITIVO ||--o{ OPINION : "captura (terminal)"
    DISPOSITIVO ||--o| SANITARIO : "terminal Smiley"
    TRABAJO ||--o{ TRABAJO_EVENTO : "reporta"
    EVENTO_LIMPIEZA ||--o{ TRABAJO_EVENTO : "instancia"
    TRABAJO ||--o{ ALERTA : "puede generar"
    MOTIVO_OPINION ||--o{ OPINION : clasifica

    EMPRESA {
        bigint id PK
        nvarchar codigo UK
        nvarchar nombre
        bit activo
    }
    SUCURSAL {
        bigint id PK
        bigint empresa_id FK
        nvarchar codigo UK
        nvarchar direccion
    }
    SECTOR {
        bigint id PK
        bigint sucursal_id FK
        nvarchar codigo
    }
    SANITARIO {
        bigint id PK
        nvarchar codigo UK
        bigint sector_id FK
        bigint tipo_sanitario_id FK
    }
    TAG_NFC {
        bigint id PK
        nvarchar uuid_tag UK
        nvarchar estado
        bigint sanitario_id FK
    }
    OPERARIO {
        bigint id PK
        nvarchar usuario UK
        nvarchar rol
    }
    DISPOSITIVO {
        bigint id PK
        nvarchar device_uuid UK
        nvarchar tipo
    }
    TRABAJO {
        bigint id PK
        nvarchar client_uuid UK
        nvarchar tipo
        nvarchar estado
        bigint operario_id FK
        bigint sanitario_id FK
    }
    TRABAJO_EVENTO {
        bigint id PK
        bigint trabajo_id FK
        bigint evento_limpieza_id FK
    }
    EVENTO_LIMPIEZA {
        bigint id PK
        nvarchar codigo UK
    }
    OPINION {
        bigint id PK
        nvarchar client_uuid UK
        bigint sanitario_id FK
        nvarchar valor
    }

La jerarquía física¶

Toda la infraestructura cuelga de una cadena de cuatro niveles. No es multi-tenant: la Empresa es el cliente del servicio, no un aislamiento de datos.

Empresa (cliente del servicio, ej. AA2000 — NO multi-tenant)
  └── Sucursal (ej. AEP, EZE)
        └── Sector (ej. Terminal A, Patio de comidas)
              └── Sanitario (+ TipoSanitario)

• Empresa — el cliente contratante (ej. AA2000). Tiene un codigo único global.
• Sucursal — una sede del cliente (ej. AEP, EZE). Pertenece a una Empresa.
• Sector — una zona dentro de la sucursal (ej. Terminal A, Patio de comidas). Su codigo es único dentro de la sucursal (UK compuesta sucursal_id, codigo).
• Sanitario — el baño concreto donde va la placa NFC. Su codigo es único global (ej. "AEP-T-B12"). Se clasifica opcionalmente con un TipoSanitario.

Empresa¶

Sucursal¶

Sector¶

TipoSanitario¶

Catálogo chico. Seed: DAMAS, CABALLEROS, DISCAPACITADOS, MIXTO.

Sanitario¶

La placa NFC y su máquina de estados¶

Cada placa física es un registro TagNfc identificado por su uuid_tag (normalizado: trim/upper/sin espacios en todo punto de entrada). El sistema usa whitelist estricta: un tag no registrado es inutilizable. Un tap con UUID desconocido genera un trabajo OFFLINE_PENDIENTE_RESOLUCION y una alerta TAG_DESCONOCIDO.

●──ALTA_STOCK(app móvil)──► EN_STOCK ──ASIGNACION──► ASIGNADO
                              ▲  │ ▲                    │
                              │  │ └───DESASIGNACION────┘
                       RE_ALTA│  └──BAJA──► BAJA

• Alta de stock SOLO desde la app móvil (rol ADMIN — hay que leer el chip onsite).
• Asignar / desasignar / reasignar / baja: app o BackOffice web. Re-alta: solo web.
• Máximo 1 tag ASIGNADO por sanitario. Para reemplazar: desasignar → asignar.
• BAJA solo desde EN_STOCK (desasignar primero).

TagNfc¶

Constraints MSSQL: UNIQUE(uuid_tag) y UNIQUE(sanitario_id) WHERE estado='ASIGNADO' (índice filtrado que enforza "máx. 1 tag asignado por sanitario").

TagNfcEvento (auditoría dedicada, inmutable)¶

Registra cada transición de la máquina de estados.

Usuarios, dispositivos y roles¶

Operario¶

El Operario es la identidad del personal en la app móvil. Su rol decide qué tipo de trabajo crea.

Semántica de roles en la app:

• OPERADOR_LIMPIEZA crea trabajos LIMPIEZA.
• SUPERVISOR crea trabajos SUPERVISION.
• ADMIN no crea trabajos por tap — su app es la de Gestión NFC.

Dispositivo¶

El Dispositivo es el equipo físico: un celular con la app del operario o una terminal Smiley (kiosk). Una parte de sus columnas son de telemetría y provisioning.

Constraint: UNIQUE(sanitario_id) WHERE tipo='TERMINAL_SMILEY' AND activo=1 — máx. 1 terminal activa por sanitario (solo prod; H2 no lo enforza).

RefreshToken acompaña al login: token_hash, operario_id, device_uuid, issued_at, expires_at, revoked_at, con rotation.

Trabajo: la entidad central¶

El Trabajo es el corazón del sistema: un registro por turno de limpieza o supervisión (mismo motor, distinto tipo). Se crea por tap NFC (el tap funciona como toggle: el primero abre INGRESO, el segundo cierra EGRESO).

TrabajoEvento (puente con snapshot, inmutable)¶

Cuando se cierra un trabajo, el operario reporta uno o más eventos. La relación N:N entre Trabajo y EventoLimpieza se materializa acá, con snapshot del catálogo para preservar el histórico:

trabajo_id FK · evento_limpieza_id FK · codigo_snapshot · nombre_snapshot · observacion NULL · created

Eventos de limpieza¶

EventoLimpieza es un catálogo configurable (no un enum) de qué puede reportar el operario al cerrar.

Seed:

Reglas: mínimo 1 evento en un EGRESO normal · EGRESO_CIERRE_AUTOMATICO va SIN eventos · la validación de rol y exclusividad es server-side (no se confía en la app).

SLA y alertas¶

SlaLimpieza¶

Define la exigencia de limpieza por sanitario (relación 1:1, sanitario_id es UK).

sanitario_id FK UK · frecuencia_min · ventana_desde/hasta · duracion_minima_seg · activo

V21_ROBUSTEZ agrega dias_semana CHAR(7) NN default 'LMXJVSD' (patrón Lun..Dom): un día sin su letra queda en estado SIN_EXIGENCIA (sin alertas SLA). Default = todos los días (comportamiento v1 intacto).

Alerta (inmutable)¶

Smiley y opiniones del público¶

Las terminales Smiley (kiosk) y los QR públicos capturan la opinión del usuario del baño. Esta capa vive solo en el MODEL del backend (V21_SMILEY / V22_QR_PUBLICO); el MODEL del mobile no la documenta.

Opinion (transaccional, inmutable)¶

Entidades de soporte del módulo:

• MotivoOpinion — catálogo (codigo UK, nombre, orden, activo, soft delete, auditoría). Seed: SUCIO, SIN_INSUMOS, MAL_OLOR, ALGO_ROTO, OTRO.
• ReglaTendencia — define cuándo una racha de negativas dispara TipoAlerta.TENDENCIA_NEGATIVA. sanitario_id FK NULL (null = regla global; la específica pisa la global), ventana_min, modo (CONTEO | PROPORCION), umbral_negativas, umbral_pct + min_opiniones. Seed: 1 regla global CONTEO 3/30.

Anti doble-tap y robustez (solo backend)¶

El ANEXO DT agrega la tabla tap_descartado (inmutable): un INGRESO que rebota a < rebote-ingreso-seg de un EGRESO del mismo operario+sanitario+device se registra acá con motivo REBOTE_POST_EGRESO y no crea Trabajo (el sync responde RECHAZADO_REBOTE, idempotente). Campos: client_uuid UK, operario_id/dispositivo_id FK NN, sanitario_id FK NULL, motivo NVARCHAR(40) NN, ts_local_device/server_received_ts.

Otras capas que viven solo del lado backend: calendario_excepcion (feriados por sucursal), motivo_contingencia (registro manual), alerta_notificacion (suscripciones a mail), portal del cliente (cliente_empresa_acceso, authority ROLE_CLIENTE), rutas (ruta, ruta_parada, ruta_asignacion, ruta_ejecucion, ruta_ejecucion_parada) y planos (plano, plano_pin). No se detallan acá; consultá el MODEL del backend.

Espejo móvil (Room)¶

La app Android no habla con MSSQL: mantiene un espejo local en Room poblado por sync, para funcionar offline-first. El espejo es un subconjunto del modelo backend.

Diferencias clave a tener en cuenta:

• No hay ubicacion_local (igual que en backend: descompuesto en sucursal/sector).
• El soft delete no se persiste local: se traduce a activo=false.
• Las credenciales NUNCA bajan: operario_local no tiene pin_hash ni password_hash.
• Las migraciones de Room están versionadas y nunca usan fallbackToDestructiveMigration — la cola offline (trabajo_pendiente) debe sobrevivir a cada upgrade de schema.