Workflow — Registro de entrada

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

Flujo de un vistazo

flowchart TB
  Start([Trailer llega al patio]) --> Q{¿Hoja con QR?}
  Q -- Sí --> SC[Escanea QR]
  SC --> PF[Pre-llena ~90% campos]
  PF --> ZS[Selecciona zona]
  Q -- No --> MAN[Captura manual]
  MAN --> MIN[Campos mínimos<br/>desde catálogos cerrados]
  MIN --> ZS
  ZS --> SEAL[Captura sellos]
  SEAL --> PHOTO[Inspección 360°<br/>4 fotos obligatorias]
  PHOTO --> CONF[Confirma registro]
  CONF --> ASG[(Assignment<br/>creado en BD)]
  ASG --> WAIT{¿Trailer<br/>con GPS?}
  WAIT -- Sí --> GPS[Espera cruce de geofence Samsara]
  GPS --> CONFIRM[Marcado GpsConfirmed]
  WAIT -- No --> RONDIN[Confirmar zona<br/>en próximo rondín]

  style SC fill:#1f6feb,color:#fff
  style MAN fill:#ffc107,color:#212529
  style ASG fill:#28a745,color:#fff
  style CONFIRM fill:#28a745,color:#fff
  style RONDIN fill:#17a2b8,color:#fff

Flujo completo de registro de entrada — QR preferido, manual como fallback

Documento ejecutivo de referencia

Versión: 1.0 (depuración post-cobertura) Última actualización: 13 de mayo de 2026 Reemplaza a: asignacion.md (versión 1.4). El concepto de “asignar slot” queda obsoleto tras ADR-038/039/040. El registro de entrada en zona, con QR de hoja de salida como mecanismo primario, lo sustituye.

Este documento explica el workflow principal del YMS: cómo el personal de patio registra la entrada de un trailer al patio. La entrada es el corazón del sistema y la operación más frecuente del día. Documenta el flujo para que el personal de patio lo ejecuten consistentemente, los jefes de patio lo supervisen, y el equipo técnico lo implemente.

Conceptos fundamentales

Qué es un “registro de entrada”

Es el evento operativo que crea una Assignment activa entre un trailer y una zona del patio. Tras ADRs 038-040:

No hay slots. La zona es la unidad mínima de ubicación.
El personal de patio es la fuente de verdad. GPS confirma a posteriori.
El QR de la “carta de instrucciones / hoja de salida” es el mecanismo primario de captura — pre-llena ~90% de los campos.

Estados de la asignación

Confirmed  →  Released
     │
     └──→  ForceClosed

Estado	Significado
Confirmed	El trailer está presente en el yard, en la zona registrada. Estado inicial al crear.
Released	El trailer ya salió. Se generó al registrar la salida.
ForceClosed	Cerrada por el jefe de patio por corrección administrativa (con razón estructurada).

Reglas duras del sistema

Un trailer puede tener UNA y solo UNA asignación activa por yard. Múltiples trailers pueden coexistir en la misma zona.
Toda entrada queda auditada: quién registró, cuándo, por qué medio (QR / Manual / ManagerAction), ShipmentDocumentId asociado.
Si el trailer tiene Samsara (IsGpsCapable = true): la entrada manual del personal de patio se valida automáticamente con GPS dentro de un umbral (sugerencia 15 min). Si no hay confirmación → anomalía ManualEntryNeedsGpsConfirmation.
Si el trailer NO tiene Samsara (IsGpsCapable = false, típicamente visitantes): la zona se establece manualmente y se debe confirmar en rondín dentro del umbral (sugerencia 4h). Si no → anomalía VisitorZoneUnconfirmed.
Sellos capturados al entrar se verifican al salir (ver registro-salida.md). Mismatch → anomalía SealMismatch (High).

Las 3 variantes de registro de entrada

Variante 1 — Escaneo de QR de hoja de salida (preferida, ~80% de casos)

Contexto: el trailer llega al patio. El chofer entrega la “carta de instrucciones / hoja de salida” al personal de caseta. El documento tiene un QR.

Quién ejecuta: Operator (típicamente personal de caseta o de garita).

Flujo paso a paso:

T+0   Chofer llega y entrega documento físico al personal de patio.

T+1   El personal de patio abre yms-mobile (o yms-web en caseta) → "Registrar entrada".

T+2   Toca "Escanear QR de hoja de salida". Cámara abre.
      Apunta al QR del documento.

T+3   Sistema decodifica el QR:
      - Si el folio NO existe en BD: crea ShipmentDocument con los datos del QR.
      - Si el folio YA existe: lo enlaza al movimiento.

T+4   Pantalla pre-llena el formulario con:
      - Folio, Carrier, Línea, Número de caja, Tipo de viaje, Contenido,
        Conductor (chofer del tractor), Licencia, Origen declarado, Destino declarado.

T+5   El personal de patio completa los campos NO contenidos en el QR:
      - Sellos físicos del trailer (sello1, sello2, sello3 si aplica)
        — los captura visualmente del remolque.
      - Zona del patio donde quedará el trailer (selector con autocomplete).

T+6   Inspección rápida 360° (ADR-041):
      Pantalla "Inspección 360°" con 4 placeholders obligatorios:
      ┌─────────┬─────────┐
      │ Frente  │  Atrás  │
      ├─────────┼─────────┤
      │ Izquierdo│ Derecho│
      └─────────┴─────────┘
      El personal de patio toma cada foto desde la cámara del dispositivo.
      Si detecta un daño visible, agrega fotos extra con categoría
      DamageDetail + descripción libre, y el sistema crea automáticamente
      anomalía ManualReport razón "Daño detectado al ingreso".
      Las 4 fotos básicas son obligatorias para confirmar.

T+7   [Confirmar]. Sistema:
      - Crea Trailer si no existe en catálogo (con IsGpsCapable según SamsaraDeviceId).
      - Crea Assignment (TrailerId, ZoneId, ShipmentDocumentId, Status=Confirmed).
      - Crea MovementEvent (Type=EntryRegistered, Source=ShipmentDocumentScan,
                            RegisteredByUserId, ZoneId, ShipmentDocumentId).
      - Crea TrailerSeal por cada sello capturado.
      - Crea 4 Photo con Category = InspectionFront/Back/Left/Right
        asociadas al MovementEvent y al Assignment.
      - Si hubo DamageDetail: crea Anomaly + Photos asociadas.
      - Notifica vía SignalR al yard.

T+8   Pantalla muestra confirmación: "Entrada registrada — Folio 2026-001234,
                                       Trailer ABC-1234, Zona Norte, 4 fotos".
      Tiempo total: ~60-90 segundos (incluye inspección 360°).

T+9   (asíncrono) Si Trailer.IsGpsCapable = true:
      El worker Samsara busca posición GPS reciente. Si trailer cruzó geofence
      dentro del umbral → marca MovementEvent.GpsConfirmedAt.
      Si no llega confirmación GPS en 15 min → anomalía
      ManualEntryNeedsGpsConfirmation (Medium).

Excepción operativa — saltar inspección:

Si una situación de emergencia impide la inspección, el personal de patio puede saltarla seleccionando razón “EmergencyOperation”. Genera anomalía InspectionSkipped (Medium) que el YardManager debe revisar y aprobar.
Configurable por yard vía Settings: inspection.requirePhotosOnEntry = true|false.

Permisos: Operator+, YardManager+, Admin.

Eventos generados:

MovementEvent tipo EntryRegistered, Source = ShipmentDocumentScan.
Assignment nuevo (Confirmed).
ShipmentDocument creado o enlazado.
TrailerSeal por cada sello.
4 Photo con Category InspectionFront/Back/Left/Right asociadas al MovementEvent (ADR-041).
Si hubo daños detectados: Anomaly (ManualReport) + Photo adicionales con Category = DamageDetail.
Posterior: GpsConfirmedEntry o anomalía si no confirma GPS.

Variante 2 — Captura manual con campos mínimos (fallback, ~15% de casos)

Contexto: el documento no tiene QR, está dañado, o el personal de patio no puede escanearlo (sin batería, luz, etc.). O el trailer es interno y no trae documento.

Quién ejecuta: Operator.

Flujo paso a paso:

T+0   Personal de patio abre yms-mobile → "Registrar entrada" → "Captura manual".

T+1   Formulario muestra solo campos críticos (subset minimalista):
      - Folio (texto libre, opcional — validado con formato si se llena).
      - Carrier (dropdown desde catálogo Carrier; Admin gestiona).
      - Línea (dropdown desde catálogo Line: HG/CH/RL/LD/...).
      - Número de caja (texto, autocompleta con Trailer.Number existentes).
      - Sellos (1, 2, 3 — opcional, se llena si el remolque trae sellos).
      - Tipo de viaje (dropdown TripType, opcional).
      - Contenido (dropdown ContentType, opcional).
      - Conductor / Licencia (texto, opcional).
      - Zona del patio (selector obligatorio).

T+2   Inspección rápida 360° (ADR-041): mismas 4 fotos obligatorias
      (frente, atrás, izquierdo, derecho) que en Variante 1.

T+3   [Confirmar]. Sistema:
      - Crea ShipmentDocument con CreateManually() — Folio puede ir vacío
        si el personal de patio no lo conoce.
      - Crea Trailer si no existe (auto-discovery).
      - Crea Assignment + MovementEvent (Type=EntryRegistered,
        Source=ManualEntry).
      - Crea TrailerSeal si se llenaron.
      - Crea 4 Photo con Category InspectionFront/Back/Left/Right.

T+4   Pantalla muestra confirmación.
      Tiempo total: ~90-120 segundos (más lento que Variante 1).

T+5   Mismas reglas de confirmación GPS / rondín que en Variante 1.

Permisos: Operator+, YardManager+, Admin.

Cuándo NO usar: si el QR existe pero el personal de patio prefiere capturar manual por costumbre. Esto degrada la calidad del dato. La Variante 1 es siempre preferible.

Variante 3 — Trailer visitante sin Samsara

Contexto: llega un trailer externo sin GPS (proveedor, eventual). Puede tener documento con QR (escanea como Variante 1) o sin QR (como Variante 2). La diferencia clave: el trailer NO emitirá confirmaciones GPS, así que la zona debe confirmarse en el rondín.

Quién ejecuta: Operator.

Flujo paso a paso:

T+0   Personal de patio identifica al llegar que el trailer es visitante.

T+1   En el formulario (Variante 1 o 2), marca:
      - Trailer.Ownership = Visitor (si no estaba en catálogo).
      - Trailer.IsGpsCapable = false (sin SamsaraDeviceId).

T+2   Captura todos los campos posibles. Toma foto opcional para evidencia.

T+3   [Confirmar]. Sistema crea Assignment como en variantes anteriores,
      con la diferencia: el worker Samsara NO buscará confirmación de
      entrada (no hay GPS).

T+4   Sistema marca el Assignment con flag visible para que aparezca en la
      lista del rondín como "pendiente de confirmar zona". Se inicia
      contador hacia el umbral (sugerencia 4h).

T+5   Si el personal de patio NO confirma zona en rondín dentro del umbral →
      anomalía VisitorZoneUnconfirmed (Low). Recordatorio operativo.

Permisos: Operator+, YardManager+, Admin.

Eventos generados: mismos que Variante 1 o 2, sin confirmación GPS.

Validaciones del sistema

Validación	Comportamiento si falla
Trailer ya tiene Assignment activa en este yard	Rechaza con mensaje “Trailer XYZ ya tiene entrada activa registrada (Folio 2026-001234, Zona Norte). ¿Es duplicado? Confirma o cancela.”
Folio del QR ya existe asociado a otro Trailer	Rechaza con mensaje “El folio 2026-001234 ya está vinculado al trailer ABC-1234. Verifica el documento.”
Zona seleccionada no pertenece al yard activo	Rechaza con error de selección.
Permisos insuficientes	403 Forbidden con mensaje claro.
QR no decodifica o formato inválido	Mensaje “QR no reconocido. Usa captura manual.” y degrada a Variante 2.
Catálogos vacíos (Carrier/Line/TripType/ContentType)	Mensaje “Catálogo sin entradas activas. Contacta al Admin.” Personal de patio puede dejar el campo vacío.

Eventos auditados generados

Evento	Cuándo se genera	Quién
`MovementEvent` tipo `EntryRegistered`	Al confirmar registro de entrada	Operator+
`Assignment.Created` (auditoría implícita)	Idem	Operator+
`ShipmentDocument.Scanned` o `ShipmentDocument.ManuallyCreated`	Al crear el documento	Operator+
`TrailerSeal.Applied` (uno por sello)	Idem	Operator+
`MovementEvent` tipo `GpsConfirmedEntry`	Cuando worker Samsara valida	Sistema
`Anomaly.ManualEntryNeedsGpsConfirmation`	Si GPS no confirma en umbral	Sistema
`Anomaly.VisitorZoneUnconfirmed`	Si rondín no confirma zona en umbral	Sistema

Decisiones técnicas referenciadas

ADR-038 — Zona como unidad operativa mínima (slot eliminado).
ADR-039 — GPS como mecanismo de confirmación, no fuente de verdad.
ADR-040 — ShipmentDocument con QR como entrada primaria.
Modelo de datos — ver 01-tecnico/propuesta-maestra.md §8.0.

Documentos relacionados

registro-salida.md — flujo de salida con verificación de sellos.
rondin.md — confirmación/corrección de zonas.
anomalias.md — tipos de anomalías generadas por este workflow.
modo-caseta.md — vista web especializada para personal de caseta.
visitantes.md — detalle del flujo de trailers visitantes (Variante 3).
00-vision-general/glosario.md — definición de actores y entidades.
00-vision-general/roles-permisos.md — permisos detallados por rol.

Workflow de registro de entrada — referencia operativa.