Saltearse al contenido
YMS — Propuesta JCBM

Workflow — Incidentes físicos

Esta página se importa íntegra desde la fuente de verdad técnica: yms-docs/03-workflows-operativos/incidentes.md — cualquier corrección debe hacerse allí.

Documento ejecutivo de referencia

Versión: 1.5 (depuración post-cobertura) Última actualización: 13 de mayo de 2026 Cambios desde versión anterior: ADR-038. Las referencias a “slot del incidente” se reemplazan por “zona del incidente”. El modelo de Anomaly ahora apunta a ZoneId (no SlotId).

Este documento explica cómo el sistema YMS soporta el manejo de incidentes físicos en el patio — accidentes, robos, derrames, emergencias médicas, daños a trailers. El sistema NO reemplaza protocolos físicos de seguridad ni respuesta a emergencias, pero registra y comunica los incidentes para tener trazabilidad operativa y soporte ante disputas. Los incidentes se ubican a nivel de zona.

¿Qué es un incidente físico?

Un incidente físico es cualquier evento no esperado que afecte la operación segura del patio. Tipos típicos:

TipoEjemplos
Accidente vehicularChoque entre tracto y trailer, golpe contra estructura, vuelco.
Daño a trailerTrailer dañado al llegar, dañado durante la estadía, sin documentación visible.
Robo o intento de roboTrailer perdido sin registro de salida, mercancía sustraída, vehículo no autorizado.
Emergencia médicaLesión a personal de patio, chofer, visitante.
Derrame o contaminaciónFuga de combustible, mercancía derramada (si aplica al patio).
Estructura del patioCaída de muro/cerca, falla de sistema eléctrico, inundación.
OtroEventos no categorizados que requieren documentación.

El sistema YMS NO es un sistema de gestión de emergencias. Para protocolos de respuesta (llamar a 911, evacuación, etc.), el cliente debe tener procedimientos físicos independientes. El YMS solo documenta y comunica lo que ocurrió.

Conceptos fundamentales

Reglas duras del sistema

  1. El registro de un incidente es manual. El sistema NO detecta automáticamente accidentes (no tiene cámaras, sensores físicos).
  2. Todo incidente requiere foto obligatoria. Sin evidencia visual, no procede.
  3. Notificación inmediata al jefe de patio. Cualquier miembro del personal de patio o caseta puede registrar; el YardManager recibe notificación SignalR + email.
  4. Los incidentes son anomalías de tipo PhysicalIncident — entran al workflow normal de resolución de anomalías.
  5. No hay categoría de “emergencia” que bloquee el sistema. El YMS sigue operando aunque haya incidente.
  6. Severidad por defecto: High. Los incidentes son siempre prioritarios.

Flujo de registro de un incidente

Quién puede registrar

  • Operator+ del yard (personal de patio, personal de caseta).
  • YardManager (típicamente quien recibe el reporte verbal).
  • Admin (si está accediendo al sistema).

Flujo paso a paso

T+0   Persona detecta incidente físico (ella misma o se le reporta).


T+1   Si hay riesgo a vida → llamar a emergencias FÍSICAS primero (911).
      El registro en el sistema es paso secundario, NO bloquea atención.


T+2   Abre yms-mobile (personal de patio) o yms-web (caseta/manager).


T+3   Toca/click "+ Reportar" → "Incidente físico".


T+4   Modal pide:
      - Tipo (Accidente / Daño / Robo / Médico / Derrame / Estructura / Otro).
      - Severidad sugerida (Low / Medium / High — default High).
      - Trailer afectado (si aplica, autocomplete o lista de recientes).
      - Zona afectada (si aplica).
      - Personas involucradas (texto libre: chofer, personal de patio, etc.).
      - Descripción detallada (texto libre obligatorio mínimo 50 chars).
      - Foto(s) obligatoria(s) — múltiples fotos permitidas.
      - Si Médico: campo adicional "¿Se llamó a emergencias?" (Sí/No).


T+5   [Reportar]. Sistema:
      - Crea Anomaly de tipo PhysicalIncident con severidad seleccionada.
      - Adjunta fotos.
      - Notificación inmediata al YardManager (SignalR + email + sonido).
      - Si severity = High: notifica también al Admin global.
      - Audit log con todos los detalles.


T+6   Confirmación visible: "Incidente reportado. Notificación enviada al jefe de patio."


T+7   El YardManager investiga (workflow normal de anomalías).
      Resolución requiere razón documentada.

Tiempo total: 1-3 minutos (depende de cuántas fotos se tomen y detalle del texto).

Casos especiales por tipo

Caso A: Accidente vehicular

Acciones operativas:

  1. Personal afectado se atiende físicamente (primeros auxilios, llamar a emergencias).
  2. Si hay heridos: llamar a 911 ANTES de registrar en sistema.
  3. Una vez controlada la situación física, se registra en sistema.

Información esencial a capturar:

  • Trailer(s) involucrado(s).
  • Otros vehículos involucrados (tracto, montacargas, etc.).
  • Personas heridas (si aplica).
  • Daños visibles (fotos múltiples desde varios ángulos).
  • Croquis o ubicación específica.

Acción del YardManager:

  • Notifica a aseguradora del cliente si aplica.
  • Registra reporte oficial físico (separado del sistema YMS).
  • Resuelve anomalía con razón “AccidentResolved” + nota detallada.

Caso B: Trailer dañado al llegar

Acciones operativas:

  1. Personal de patio detecta daño visualmente al recibir el trailer.
  2. Registra incidente con foto del daño ANTES de registrar la entrada del trailer.

Importancia operativa:

  • El registro inmediato es prueba clave ante disputas con el transportista o cliente que reclame “el trailer llegó así”.
  • Sin registro al ingreso, cualquier daño detectado después puede atribuirse al patio.

Caso C: Robo o intento de robo

Acciones operativas:

  1. Si está en curso: prioritario llamar a seguridad/policía físicamente.
  2. NO confrontar al sospechoso por cuenta propia.
  3. Registrar en sistema una vez controlada la situación.

Información esencial:

  • Trailer afectado (si se robaron uno).
  • Mercancía afectada (si se llevaron contenido).
  • Descripción del/los sospechoso(s) si visible.
  • Hora del incidente.
  • Cámaras de seguridad disponibles (referencia para investigación posterior).

Acción del YardManager:

  • Notifica a autoridades.
  • Coordina con seguridad para revisar cámaras.
  • Si trailer robado: marca como Lost + Deactivate con razón.

Caso D: Emergencia médica

Prioridad absoluta: atención física a la persona afectada. Sistema YMS es secundario.

Después de controlar la situación:

  • Registrar en sistema con tipo Médico.
  • Marcar “¿Se llamó a emergencias?” según corresponda.
  • Notificar al Admin del cliente para reporte interno.

Lo que SÍ y NO permite el sistema

Operación¿Permitido?Quién
Reportar incidente con foto obligatoria✅ SíOperator+, YardManager+, Admin
Reportar sin foto❌ No—
Reportar sin descripción detallada❌ No (mínimo 50 caracteres)—
Resolver/descartar incidente✅ SíYardManager+, Admin
Editar incidente después de creado❌ No (append-only, agregar comentarios sí)—
Borrar reporte de incidente❌ No—
Múltiples fotos en un mismo incidente✅ Sí—
Adjuntar más fotos después✅ SíYardManager+ con razón

Reportes y métricas

Métricas operativas

El YMS genera (post-MVP) métricas a partir de los incidentes registrados:

  • Tasa de incidentes por mes.
  • Distribución por tipo (% accidentes vs daños vs robos).
  • Tiempo promedio de resolución por tipo.
  • Trailers más involucrados en incidentes (por número o ruta).
  • Zonas con más incidentes (mapa de calor).

Estas métricas alimentan decisiones operativas: ¿necesitamos más iluminación en Zona Norte? ¿Hay un transportista con mayor tasa de daños? ¿Las cámaras tienen ángulos muertos?

Reporte por incidente

Cada incidente cerrado genera un reporte consultable con:

  • Tipo, severidad, fecha/hora.
  • Trailer y zona afectados.
  • Reportante (con timestamp).
  • Descripción completa.
  • Fotos.
  • Audit log de cambios de estado.
  • Resolución y razón.

Decisiones de diseño tomadas

Decisión 1: Incidentes son Anomaly tipo PhysicalIncident, no entidad separada

Adoptado: los incidentes físicos se modelan como Anomaly con tipo PhysicalIncident.

Justificación: evita duplicación de modelo. Las anomalías ya tienen workflow probado. La diferencia es de tipo y origen, no de comportamiento.

Implicación técnica: agregar PhysicalIncident al enum AnomalyType.

Decisión 2: Foto obligatoria en TODOS los incidentes

Adoptado: sin foto, no procede el reporte.

Justificación: la evidencia visual es esencial ante disputas y auditoría. Pedir foto en cada incidente es bajo costo operativo (1-2 segundos) ante alto valor probatorio.

Decisión 3: Severidad por defecto High

Adoptado: todos los incidentes nacen como severidad High.

Justificación: los incidentes son por definición prioritarios. El YardManager puede degradar a Medium/Low durante investigación si concluye que era menor.

Decisión 4: Notificación inmediata multi-canal

Adoptado: SignalR + email + sonido al YardManager. Si severidad High, también al Admin.

Justificación: los incidentes requieren respuesta rápida. Multi-canal asegura que se vea independientemente de qué dispositivo está atendiendo.

Decisión 5: Sistema NO maneja respuesta a emergencias

Adoptado: el sistema solo registra y comunica. NO hay funcionalidad de “activar protocolo de emergencia”, “llamar 911 desde la app”, etc.

Justificación: las respuestas físicas son responsabilidad del cliente con sus protocolos propios. El sistema duplicaría esa lógica sin agregar valor real.

Documentos relacionados

  • 03-workflows-operativos/anomalias.md — workflow general de anomalías
  • 03-workflows-operativos/registro-salida.md — registro de salida con foto cuando hay daño
  • 00-vision-general/roles-permisos.md — quién puede reportar y resolver

Para mapa completo de la documentación, ver yms-indice.md.

Documento ejecutivo del workflow de incidentes físicos — referencia operativa.