Workflow — Editor de layout

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

Documento ejecutivo de referencia

Versión: 2.0 Última actualización: 13 de mayo de 2026

Este documento explica cómo el YardManager (o Admin) modifica las zonas del patio en el sistema YMS sin necesidad de programadores. El editor de zonas es lo que da autonomía al cliente para reorganizar el patio cuando crece o cambia.

¿Qué es el Editor de Zonas?

Es una herramienta dentro de yms-web que permite:

Crear zonas dibujando polígonos sobre un mapa con imagen satelital.
Editar zonas existentes (mover vértices, ajustar forma, renombrar).
Eliminar zonas que dejaron de usarse.
Versionar los cambios — la versión anterior queda archivada.
Publicar una nueva LayoutVersion para que se refleje en tableros y app móvil.

Quién lo usa: YardManager o Admin desde yms-web.

Cuándo se usa:

Configuración inicial del patio (Sprint 23 nuevo).
Reorganización interna (dividir zona grande en dos, agregar zona nueva por nuevo cliente).
Pérdida o ganancia de superficie operativa (activación del terraplén norte, cierre temporal de área).

Nota MVP: modificar el polígono perimetral del patio NO está incluido en MVP. Si el perímetro físico cambia (caso raro), TI lo modifica directamente en BD con script controlado.

Conceptos fundamentales

Estados de `LayoutVersion`

Draft → Published → Archived

Estado	Significado
Draft	Versión en edición. Solo visible al editor; NO afecta operación.
Published	Versión activa. Tablero, app móvil y rondín la usan. Solo 1 por yard.
Archived	Versión anterior reemplazada. Se conserva para histórico (assignments y movimientos antiguos siguen consultables).

Reglas duras

Solo una LayoutVersion está Published por yard a la vez.
Las zonas tienen polígonos geométricos válidos: mínimo 3 vértices, cerrados, sin auto-intersección.
Las zonas de un mismo yard NO pueden solaparse.
Toda zona debe estar dentro del polígono perimetral del yard.
Lock pesimista en draft: mientras un usuario edita, otros ven “bloqueado por X” (2h de timeout por inactividad).
Publicación requiere ChangeNotes obligatorias que queden en histórico.
Si una zona se elimina y tiene Assignment activa, la publicación se bloquea hasta que la asignación se cierre o re-zonifique.

Flujo de edición y publicación

Variante 1 — Crear / editar zonas

Quién ejecuta: YardManager+, Admin.

T+0   YardManager abre yms-web → Yard Settings → "Editar zonas".

T+1   Si no hay draft activo, sistema crea LayoutDraft a partir
      de la LayoutVersion publicada.
      Si otro usuario tiene el lock → mensaje "Bloqueado por X
      desde hace N minutos. Esperar o pedir desbloqueo al Admin."

T+2   Mapa Leaflet abre con:
      - Imagen satelital del yard.
      - Polígonos de las zonas vigentes (semitransparentes).
      - Barra de herramientas: crear, mover vértices, renombrar, eliminar.

T+3   Operaciones disponibles:

      Crear zona:
        Click "+ Nueva zona" → cursor cambia a "dibujar polígono".
        Click sucesivos para vértices → doble click para cerrar.
        Modal pide: Nombre, código (opcional), color de visualización.

      Editar zona:
        Click sobre zona → vértices se vuelven editables (handles).
        Arrastrar vértices para cambiar forma.
        Click derecho sobre vértice: agregar/eliminar.

      Renombrar zona:
        Click sobre nombre → editable inline.

      Eliminar zona:
        Click sobre zona → botón "Eliminar".
        Si la zona tiene asignaciones activas: el sistema marca
        un blocker visible "N trailers actualmente en esta zona —
        debes re-zonificarlos antes de publicar".

T+4   Auto-save cada 30s. Heartbeat cada 60s para mantener el lock.

T+5   Cualquier momento: click "Vista de diff" → ve resumen de cambios.

T+6   Click "Salir sin publicar" → draft se conserva.
      Click "Descartar cambios" → confirmación destructiva, draft se borra.

Variante 2 — Publicar nueva versión

T+0   YardManager click "Publicar".

T+1   Modal muestra:
      - Resumen de cambios: zonas añadidas, modificadas, eliminadas.
      - Blockers (si hay): zonas eliminadas con asignaciones activas.
      - Warnings (si hay): zonas modificadas significativamente que tienen trailers.
      - Campo obligatorio: ChangeNotes (mínimo 30 chars).
      - Confirmación destructiva: tipear código del yard para confirmar.

T+2   Si hay blockers → botón "Publicar" deshabilitado.
      YardManager debe cerrar las asignaciones afectadas o re-zonificar
      los trailers desde yms-web antes de volver a intentar publicar.

T+3   [Confirmar publicación]. Sistema:
      - Crea LayoutVersion nueva (Status=Published).
      - Archiva LayoutVersion anterior (Status=Archived).
      - Genera LayoutSnapshot inmutable con la geometría completa.
      - Si hubo zonas renombradas/movidas con assignments: re-mapea
        automáticamente las assignments a la nueva versión de la zona.
      - Notifica vía SignalR a todos los clientes del yard:
        - yms-web: tablero refresca.
        - yms-mobile: invalidación de cache local, descarga de nueva versión.

T+4   AuditLog con: usuario, timestamp, ChangeNotes, diff resumido.

T+5   Lock del draft se libera.

Tiempo total estimado: ~5-15 min para cambio típico (1-3 zonas).

Validaciones del sistema

Validación	Mensaje al usuario
Polígono con <3 vértices	”Una zona requiere al menos 3 vértices.”
Polígono auto-intersecante	”La zona no puede cruzarse a sí misma.”
Zonas solapadas en el mismo yard	”Esta zona se solapa con Zona X. Ajusta los vértices.”
Zona fuera del perímetro del yard	”La zona debe estar dentro del polígono del patio.”
Publicación sin ChangeNotes	”Describe brevemente el cambio antes de publicar.”
Lock conflict (otro usuario está editando)	“Bloqueado por usuario X. Esperar o pedir desbloqueo al Admin.”
Zona eliminada con assignments activas	”N trailers están en esta zona. Re-zonifícalos o cierra sus asignaciones antes de publicar.”

Permisos

Acción	Operator	YardManager	Admin
Abrir el editor	❌	✅	✅
Crear / editar / eliminar zonas en draft	❌	✅	✅
Publicar nueva versión	❌	✅	✅
Forzar desbloqueo de otro usuario	❌	❌	✅
Editar perímetro del yard	❌	❌	❌ (post-MVP)

Eventos auditados

Evento	Cuándo
`LayoutDraft.Created`	Al abrir el editor sin draft previo
`LayoutDraft.Updated`	Cada auto-save con cambios respecto al estado previo
`LayoutDraft.Discarded`	Al descartar cambios
`LayoutVersion.Published`	Al publicar nueva versión (con ChangeNotes)
`LayoutDraft.LockForciblyReleased`	Cuando Admin libera lock de otro usuario

Decisiones técnicas referenciadas

ADR-038 — Zona como unidad operativa mínima.
Sprint 23 (nuevo) — Editor de Zonas base.
Sprint 24 (nuevo) — Versionado y publicación de zonas.
Modelo de datos — 01-tecnico/propuesta-maestra.md §8.0.

Documentos relacionados

registro-entrada.md — el personal de patio selecciona zona al registrar entrada.
rondin.md — el personal de patio confirma/corrige zona en rondín.
anomalias.md — anomalías de zona.

Workflow del Editor de Zonas — referencia operativa.