Ciclo de vida de los tags NFC¶

Si recién entrás al proyecto, esta es la página que explica cómo nace, se asigna, se reasigna y se da de baja una placa NFC en WorkDone Sanitarios, y qué transiciones de estado son válidas (y cuáles no). Una placa (tag_nfc) es el chip físico que el personal acerca con el teléfono para registrar un trabajo; antes de poder usarse, tiene que recorrer un ciclo de vida controlado.

La fuente de verdad de este documento es el backend (Spring Boot / JHipster), concretamente TagNfcLifecycleService: el servicio que concentra TODAS las transiciones de estado del tag. Ningún otro componente cambia el estado de un tag por su cuenta.

Para el contexto del modelo de tablas, ver Modelo de datos. Para cómo estas operaciones viajan offline desde la app, ver Sincronización.

Máquina de estados¶

Un tag tiene tres estados (EstadoTag): EN_STOCK, ASIGNADO y BAJA. El alta lo crea directamente en EN_STOCK. Las transiciones entre estados están todas mediadas por una acción concreta del TagNfcLifecycleService.

stateDiagram-v2
    [*] --> EN_STOCK: ALTA_STOCK

    EN_STOCK --> ASIGNADO: ASIGNACION
    ASIGNADO --> EN_STOCK: DESASIGNACION
    ASIGNADO --> ASIGNADO: REASIGNACION (otro sanitario)

    EN_STOCK --> BAJA: BAJA
    BAJA --> EN_STOCK: RE_ALTA (solo web)

    note right of ASIGNADO
        REASIGNACION es un solo
        paso atomico: ASIGNADO -> ASIGNADO'
        (decision 2026-06-10)
    end note

Acciones¶

Cada acción valida el estado de origen esperado, aplica el cambio y persiste un TagNfcEvento con la AccionTagNfc correspondiente. La siguiente tabla resume qué hace cada una.

ALTA_STOCK — alta idempotente¶

Crea el tag en EN_STOCK con activo = false. Es idempotente por uuid: si el uuid normalizado ya existe en tag_nfc, devuelve el tag existente sin crear evento ni modificar nada. Esto es clave para la idempotencia best-effort del sync (ver más abajo).

ASIGNACION — vincular a un sanitario¶

Requiere que el tag esté EN_STOCK y que el sanitario destino no tenga ya un tag ASIGNADO. Pasa el tag a ASIGNADO, le setea el sanitario, asignadoEn y activo = true.

DESASIGNACION — devolver a stock¶

Sólo válida desde ASIGNADO. Limpia el sanitario, asignadoEn, pone activo = false y devuelve el tag a EN_STOCK. Guarda el sanitarioAnterior en el evento.

REASIGNACION — mover entre sanitarios (atómica)¶

Mueve un tag de un sanitario a otro en un solo paso atómico, sin pasar por EN_STOCK. El tag permanece ASIGNADO; sólo cambian sanitario y asignadoEn.

BAJA — desactivar definitivamente¶

Sólo válida desde EN_STOCK. Pone el tag en BAJA, setea dadoBajaEn y activo = false. Un tag ASIGNADO no puede darse de baja directamente: hay que desasignarlo primero.

RE_ALTA — reactivar desde baja (solo web)¶

Devuelve un tag desde BAJA a EN_STOCK (limpia dadoBajaEn, activo = false). Disponible únicamente desde web (BackOffice); no se procesa por /sync.

Transiciones inválidas¶

Cada método valida el estado de origen esperado antes de aplicar el cambio. Si el tag está en un estado distinto del esperado, se lanza TransicionInvalidaException, que en el sync se reporta como TRANSICION_INVALIDA. Además, si el uuid no existe en tag_nfc, resolverTag lanza la misma excepción (tag no registrado).

Estas son las combinaciones que rechazan la operación:

Normalización de UUID¶

Todo punto de entrada de uuid pasa por UuidTagNormalizer.normalize() antes de cualquier búsqueda o persistencia. La forma canónica es: null-safe, sin espacios (internos y de borde) y en mayúsculas (raw.replaceAll("\\s+", "").toUpperCase()).

Cada método del TagNfcLifecycleService normaliza el uuid en su primera línea. TrabajoTapService también normaliza para resolver el tag al procesar un tap (el uuid_tag_leido del Trabajo se persiste crudo, como snapshot del tap).

Auditoría¶

Cada transición exitosa persiste un TagNfcEvento (tabla inmutable tag_nfc_evento). El evento captura: el tag, el uuidTag (ya normalizado), la AccionTagNfc, sanitarioAnterior, sanitarioNuevo, operario, dispositivo, fecha y notas.

Estados de procesamiento NFC en el sync¶

Cuando los eventos NFC viajan en la cola del sync, cada ítem se procesa de forma aislada (un ítem que falla no aborta el sync completo) y se devuelve con un EstadoNfcEventoProcesado. La autorización es estricta: solo el operario con rol ADMIN puede enviar ítems NFC; si no lo es y la cola no está vacía, todos los ítems se rechazan con ROL_INSUFICIENTE sin abortar.

Más sobre el protocolo de sincronización, orden de procesamiento y casos offline en Sincronización.

// TODO v2.1: tabla nfc_evento_procesado para idempotencia estricta por client_uuid.