Arquitectura de checklists operativos: el procedimiento que vive en el sistema

El módulo de checklists operativos gestiona tres listas de tareas diarias, una por turno, con registro de ejecución, log de eventos y procedimientos enlazados. Este artículo describe las decisiones de diseño que convierten una simple lista de tareas en una herramienta operativa real.

→ Contexto de negocio: Checklists operativos en hotelería

Tres checklists, un sistema unificado

El módulo gestiona tres listas de tareas diarias, una por turno:

• Turno de mañana — apertura de caja, preparación de housekeeping, revisión de llegadas, conciliación de habitaciones, informes del día.
• Turno de tarde — relevo de mañana, gestión de incidencias acumuladas, preparación del cierre parcial.
• Night audit — cierre de caja, arqueos, informes R118, verificación de reservas del día siguiente, procedimientos de seguridad nocturna.

Cada checklist tiene entre 23 y 60 pasos agrupados en secciones temporales (por ejemplo, “7:00 - 7:30 — Inicio y preparación”). Los pasos se definen en ficheros JSON que viven en el repositorio del proyecto, no en la base de datos. Esto tiene una razón: el contenido de un checklist cambia con la misma frecuencia que el código (cuando un procedimiento se revisa, se actualiza el JSON y se despliega), mientras que la ejecución del checklist —quién marcó qué, cuándo, con qué comentario— vive en MySQL.

El registro de ejecución: quién hizo qué y cuándo

Cada paso completado queda registrado con tres datos:

• Quién — el identificador del usuario que marcó el paso, resuelto al nombre visible en la interfaz.
• Cuándo — la marca de tiempo del momento exacto en que se marcó.
• Estado — marcado o desmarcado. Si un recepcionista desmarca un paso, el sistema limpia la atribución y queda constancia en el log de eventos.

La interfaz muestra debajo de cada paso completado el nombre del usuario y la hora. Si otro compañero intenta desmarcar un paso que marcó alguien distinto, el sistema pide confirmación antes de hacerlo. No es un bloqueo: es un aviso de que alguien más ya dio ese paso por completado.

Además del estado del paso, cada paso admite comentarios (hasta 500 caracteres) y adjuntos (imágenes subidas a Cloudinary, servidas a través de un proxy del backend que nunca expone la URL firmada al cliente). Un recepcionista que detecta una incidencia en la apertura de caja puede dejar una nota y una foto directamente en el paso correspondiente, sin salir del checklist.

El log de eventos: auditoría operativa

Toda acción sobre un checklist escribe una fila en la tabla checklist_event_log:

• check / uncheck — un paso se marca o desmarca.
• comment — se añade o elimina un comentario (con el ID del comentario en el payload JSON).
• attach — se sube o elimina un adjunto.
• reset_manual — un usuario reinicia el checklist manualmente.

El log tiene una retención de 7 días. Cada lunes a las 04:00, un cron job elimina las filas anteriores a esa ventana. Siete días es suficiente para cualquier auditoría operativa real (reclamaciones de huéspedes, turnos conflictivos, investigación de incidencias) y mantiene la tabla ligera.

¿Por qué un log separado si ya tenemos done_by_user_id en el estado del paso? Porque el estado del paso es el estado actual (puede cambiar si alguien desmarca), mientras que el log es la trazabilidad inmutable de lo que ocurrió. Son dos capas de información con propósitos distintos: el estado sirve para saber en qué punto está el turno; el log sirve para reconstruir la secuencia de acciones.

El reinicio diario: cron a las 06:30 con red de seguridad

A las 06:30 de la mañana, hora de Madrid, un cron job ejecuta el reinicio diario. La operación es un único UPDATE sobre la tabla checklist_runs:

UPDATE checklist_runs
SET reset_at = NOW(),
    reset_by_user_id = 'system-cron',
    reset_reason = 'cron'
WHERE hotel_id = 1
  AND hotel_date < CURDATE()
  AND reset_at IS NULL

Todas las ejecuciones activas de días anteriores se cierran de golpe. Sus estados de paso quedan congelados como historial. El siguiente recepcionista que abra el checklist recibe una ejecución nueva, vacía, con la fecha del día.

Pero hay un escenario que hay que cubrir: si el servidor está dormido a las 06:30 (plataformas con free tier que suspenden la instancia por inactividad), el cron no se dispara. Para eso existe un reinicio perezoso: cada vez que se consulta el estado de un checklist (GET /:id/run), el servicio ejecuta primero closeStaleRuns(), que cierra cualquier ejecución de días anteriores que siga abierta. Es una consulta indexada e idempotente — si no hay nada que cerrar, no hace nada — y garantiza que el reinicio ocurre aunque el cron haya fallado.

El historial de ejecuciones cerradas es accesible desde la interfaz con filtros por fecha y paginación. Un jefe de recepción puede revisar qué pasos se completaron (o no) en cualquier día de los últimos meses, quién los marcó y con qué comentarios.

Procedimientos y referencias: el conocimiento del hotel enlazado al paso

Este es el aspecto que transforma el checklist de una simple lista de verificación a un sistema de acceso al conocimiento operativo. Cada paso puede enlazarse a uno o varios documentos de procedimiento o referencia mediante el campo ref en el JSON de definición:

{
  "id": "s1-2",
  "text": "Preparar Housekeeping para pisos",
  "ref": "reference:housekeeping-pisos"
}

El frontend renderiza estos enlaces como iconos junto al paso. Al pulsarlos, el recepcionista accede directamente al documento correspondiente sin tener que buscarlo en carpetas compartidas o archivos de Word con nombres imposibles.

Hay dos tipos de documentos enlazables:

• Procedimientos (guides) — documentos Markdown con instrucciones paso a paso. Actualmente hay 13, la mayoría ligados al night audit (cierre de caja, arqueos, manejo de incidencias nocturnas, protocolos de seguridad).
• Referencias (references) — documentos de consulta rápida: cómo generar un informe R118 detallado, listado de miembros del equipo, procedimientos de housekeeping, contactos de mantenimiento. También 13 en la actualidad.

Los documentos se escriben en Markdown con metadatos YAML (autor, versión, fecha de actualización) y se sirven desde el propio sistema. No son archivos sueltos en una carpeta compartida: están versionados en el repositorio, indexados en un catálogo con categorías y buscables por nombre y descripción desde la barra lateral del módulo.

El resultado es que un recepcionista nuevo, en su primer turno de noche, puede seguir el checklist paso a paso y, cuando llegue a “Cierre de caja”, pulsar el enlace y leer el procedimiento detallado de cierre, todo dentro de la misma interfaz. No necesita preguntar al compañero experimentado, ni buscar un PDF en el disco compartido, ni abrir un Word que probablemente esté desactualizado.

Validación de contenido: el backend como guardián

Un detalle técnico que merece mención: los pasos que el frontend renderiza y los que el backend acepta como válidos vienen de dos copias del mismo JSON —una en frontend/content/checklist/tasks/ y otra en backend/content/checklist/tasks/. El backend usa su copia para validar que el stepId que llega en una petición PATCH corresponde a un paso real del checklist. Un middleware (validateChecklistParams) rechaza con 400 cualquier stepId que no exista en el JSON, y con 404 cualquier checklistId que no tenga fichero correspondiente.

Esto previene que un cliente manipulado envíe un stepId inventado y escriba estados espurios en la base de datos. La validación es defensiva: el frontend ya conoce los pasos correctos, pero el backend no confía en el cliente.

En resumen

Para el día a día del equipo de recepción, lo importante es esto:

Antes: cada turno tenía una lista de tareas en la cabeza del recepcionista con experiencia. Los procedimientos estaban repartidos en documentos de Word en carpetas del ordenador, en Excel compartidos por email, en notas adhesivas junto al monitor, o directamente en la memoria de alguien.

Ahora: hay tres checklists digitales —mañana, tarde y night audit— con todos los pasos del turno organizados por franjas horarias. Cada recepcionista marca los pasos que completa, y el sistema registra quién lo hizo y a qué hora. Al día siguiente a las 06:30, la lista se resetea automáticamente y empieza limpia para el nuevo turno.

Cuando un paso requiere seguir un procedimiento concreto —el cierre de caja, la preparación de housekeeping, la generación de un informe—, el recepcionista pulsa un enlace y accede al procedimiento actualizado, redactado en Markdown y versionado en el sistema. No hay que buscarlo. No hay que preguntar. Está ahí, enlazado al paso que lo necesita.

Y si algo no está claro, cada paso admite comentarios y fotos: el recepcionista puede dejar una nota para el compañero del turno siguiente, adjuntar una captura de una incidencia y cerrar el paso con contexto completo. La información fluye entre turnos dentro del sistema, no por WhatsApp ni en post-its.