Manual de Usuario — Patio Abierto

Versión: Fase 1 completada (sprint a/b/c demo-ready). Fecha: 2026-07-09. Audiencia: operadores, supervisores, administradores y clientes del patio. Nota de integridad: Este manual refleja exactamente el código fuente (lib/auth/roles.ts, lib/modules.ts, components/layout/sidebar-nav.tsx). Las tarifas de almacenaje son ILUSTRATIVAS; los datos aduanales/fiscales son reales (D-011). La autorización se re-verifica siempre en servidor aunque la UI la anticipe.

---

1. Introducción

¿Qué es Patio Abierto?

Patio Abierto es una plataforma web multi-tenant para la gestión operativa de patios de almacenamiento. La vertical original es aduanal (recinto fiscalizado de comercio exterior en México), pero el núcleo soporta otras verticales: aeropuerto de carga, 3PL/cross-dock, cold storage y self-storage (ver sección 3.10 Verticales).

Cada tenant (empresa operadora) tiene su propio subconjunto de módulos encendidos y su vocabulario configurado (por ejemplo, en la vertical aeropuerto el "contenedor" se llama "ULD").

Modos de operación

Modo	Cuándo aplica	Diferencia visible
Demo	Sin llaves de Supabase configuradas o acceso sin autenticar	Selector de rol en la UI; datos de 27 contenedores semilla; degradación grácil sin errores de consola
Producción	Supabase Auth activo (D-017) + variables de entorno configuradas	Inicio de sesión real con correo/contraseña; rol y RFC provienen del app_metadata del usuario; datos en Postgres real

Cómo iniciar sesión

1. Navega a /login.
2. Modo producción: ingresa tu correo y contraseña. Al autenticarte, el sistema lee tu rol y RFC desde app_metadata en Supabase (sin auto-elevación posible).
3. Modo demo: aparece un selector de rol en pantalla. Elige el rol que quieres explorar.
4. Una vez autenticado, el sidebar muestra únicamente los módulos que tu tenant tiene habilitados y tu rol puede ver (doble filtro: módulo del tenant ∧ permiso RBAC).
5. Si accedes a una ruta sin permiso, el sistema te redirige a /sin-acceso.

---

2. Matriz rol × permiso (fuente única: lib/auth/roles.ts)

⚠️ Esta matriz es provisional (marcada PROPUESTA en el código) y está pendiente de confirmación definitiva con el cliente operador. La autorización real se re-verifica en servidor en cada acción; la UI solo la anticipa.

Permisos del dominio

Clave de permiso	Qué habilita
patio:ver	Ver inventario, malla, citas, indicadores, operaciones, kanban, proceso, almacén
ingreso:registrar	Registrar el ingreso físico de un contenedor al recinto
garita:operar	Operar la garita (cruce y conciliación de salida)
salida:registrar	Registrar la salida física de un contenedor
descarga:registrar	Registrar la descarga del buque al recinto (avanza etapa: EN_BUQUE → DESCARGADO)
modulacion:operar	Registrar el resultado de modulación (avanza etapa: EN_PATIO → MODULADO)
bloqueo:gestionar	Bloquear o desbloquear la salida de un contenedor (gate de cumplimiento)
admin:gestionar	Administrar usuarios, catálogos, config del tenant, facturación e integraciones

Permisos por rol

Permiso	admin	supervisor	operador_garita	operador_patio	cliente_readonly
patio:ver	✓	✓	✓	✓	✓
ingreso:registrar	✓	✓	—	✓	—
garita:operar	✓	✓	✓	—	—
salida:registrar	✓	✓	✓	—	—
descarga:registrar	✓	✓	—	✓	—
modulacion:operar	✓	✓	—	✓	—
bloqueo:gestionar	✓	✓	—	—	—
admin:gestionar	✓	—	—	—	—

Módulos visibles en el sidebar por rol

El sidebar aplica doble filtro: (1) el tenant tiene el módulo encendido, (2) el rol tiene al menos un permiso del módulo (any-of). La tabla asume tenant con todos los módulos activos.

Módulo (ruta)	admin	supervisor	operador_garita	operador_patio	cliente_readonly
Inventario /	✓	✓	✓	✓	✓
Malla /malla	✓	✓	✓	✓	✓
Garita /garita	✓	✓	✓	✓	—
Citas /citas	✓	✓	✓	✓	✓
Indicadores /indicadores	✓	✓	✓	✓	✓
Operaciones /operaciones	✓	✓	✓	✓	✓
Kanban /kanban	✓	✓	✓	✓	✓
Mapa proceso /proceso	✓	✓	✓	✓	✓
Almacén /almacen	✓	✓	✓	✓	✓
Facturación /facturacion	✓	—	—	—	—
Integraciones

Nota garita: el módulo Garita aparece si el rol tiene ingreso:registrar o garita:operar (any-of). Dentro, cada sección (formulario de entrada vs. cola de salida) está protegida por su permiso específico. El cliente_readonly no ve Garita.

Nota Admin: el módulo admin existe en el registro de módulos, pero aún no tiene pantalla dedicada — /admin no está implementado. Hoy la gestión de usuarios y roles se hace en el panel de Supabase (el proveedor de identidad) y la configuración de tenant es estática en código. La pantalla Admin es roadmap.

---

2.1 Rol: admin

Descripción

Acceso total: todas las operaciones + administración de usuarios, catálogos y configuración del tenant.

Módulos que ve en el sidebar

Todos los módulos que el tenant tenga encendidos, incluyendo Facturación e Integraciones. (Admin es roadmap — todavía no tiene pantalla; ver la nota de la tabla de módulos.)

Puede hacer

• Todo lo que puede hacer el supervisor.
• Gestionar usuarios y asignar roles (admin:gestionar).
• Configurar catálogos del tenant (recintos, navieras, claves aduanales).
• Ver y exportar el estado de cuenta de almacenaje (/facturacion).
• Configurar integraciones API REST y webhooks (/integraciones).
• Bloquear y desbloquear la salida de contenedores.

No puede hacer

Sin restricciones de módulos. Las restricciones son de integridad de datos (D-011): no modificar claves de pedimento reales sin catálogos oficiales.

Tareas típicas

1. Crear un usuario nuevo (hoy vía Supabase — no hay pantalla Admin todavía):

   • En el panel de Supabase (proveedor de identidad), crear el usuario y capturar en su app_metadata el rol y el rfc del tenant (server-controlled, no auto-elevable por el usuario).
   • Asignar rol, RFC del tenant y correo.
   • (Roadmap: una pantalla /admin in-app para hacer esto sin entrar a Supabase.)

2. Bloquear/desbloquear salida de un contenedor:

   • Ir a / (Inventario) → clic en el ISO del contenedor → vista detalle /contenedor/[iso].
   • En la sección de estado, usar el botón de bloqueo. El cambio es atómico (server action).

3. Revisar estado de cuenta:

   • Ir a /facturacion.
   • Ver el resumen: total a cobrar (MXN con IVA), días-almacenaje, maniobras.
   • Las tarifas son ILUSTRATIVAS; el tiempo (días en patio) es real.

---

2.2 Rol: supervisor

Descripción

Operación completa del patio sin acceso a administración de usuarios, facturación ni integraciones.

Módulos que ve en el sidebar

Inventario, Malla, Garita, Citas, Indicadores, Operaciones, Kanban, Mapa proceso, Almacén. No ve: Facturación, Integraciones, Admin.

Puede hacer

• Ver el inventario completo y el detalle de cualquier contenedor.
• Registrar ingresos al recinto (ingreso:registrar).
• Operar la garita y conciliar salidas (garita:operar, salida:registrar).
• Registrar descargas del buque (descarga:registrar).
• Registrar resultados de modulación (modulacion:operar).
• Bloquear/desbloquear salidas (bloqueo:gestionar).
• Consultar KPIs, Gantt de dwell, Kanban y mapa de proceso.

No puede hacer

• Gestionar usuarios o configurar el tenant.
• Ver facturación ni integraciones.

Tareas típicas

1. Registrar descarga del buque:

   • Ir a /garita → sección "Entrada de garita" → formulario de ingreso.
   • Capturar el ISO del contenedor, transportista, número de placa, RFC figura transporte.
   • Enviar → el contenedor pasa a estado EN_PATIO con posición asignada en malla.

2. Verificar contenedores con demora alta:

   • Ir a /indicadores → ver badge naranja "demoras" en el sidebar.
   • Identificar contenedores con dwell > umbral configurado.

3. Bloquear salida por cumplimiento:

   • Ir al detalle del contenedor /contenedor/[iso].
   • Clic en "Bloquear salida" → el badge de bloqueo aparece en Inventario y Kanban.

---

2.3 Rol: operador_garita

Descripción

Opera el cruce físico de garita: registra salidas y concilia la cola de camiones. No registra ingresos.

Módulos que ve en el sidebar

Inventario, Malla, Garita, Citas, Indicadores, Operaciones, Kanban, Mapa proceso, Almacén.

Puede hacer

• Ver el inventario y el detalle de contenedores (solo lectura).
• Operar la garita: revisar y autorizar la cola de salida (garita:operar).
• Registrar la salida física de un contenedor (salida:registrar).
• Consultar citas de camiones programados.

No puede hacer

• Registrar ingresos de contenedores (el formulario de entrada en Garita está oculto para este rol).
• Registrar descargas del buque.
• Operar la modulación.
• Bloquear o desbloquear salidas.
• Acceder a facturación, integraciones o admin.

Tareas típicas

1. Autorizar la salida de un contenedor:

   • Ir a /garita → sección "Cola de salida".
   • La tabla muestra cada contenedor con su estado: autorizado (✓) o bloqueado (✗).
   • Para los autorizados, pulsar "Registrar salida" → el contenedor pasa a estado SALIDO.
   • Si aparece bloqueado, escalar al supervisor o admin para desbloquear.

2. Consultar cita de un camión:

   • Ir a /citas → buscar por placa o número de reserva.
   • Confirmar ventana horaria antes de abrir la garita.

3. Verificar posición de un contenedor antes de la salida:

   • Ir a /malla → usar el parámetro ?ubicar=ISO o buscar en la tabla.
   • Confirmar posición (bloque·fila·nivel) con el operador de patio.

---

2.4 Rol: operador_patio

Descripción

Gestiona el movimiento físico dentro del recinto: ingresos, descargas y modulación. No opera la garita de salida.

Módulos que ve en el sidebar

Inventario, Malla, Garita, Citas, Indicadores, Operaciones, Kanban, Mapa proceso, Almacén.

Nota: Garita aparece en el sidebar porque operador_patio tiene ingreso:registrar (any-of). Dentro de /garita, solo ve la sección de "Entrada de garita"; la cola de salida está gateada por garita:operar que este rol no tiene.

Puede hacer

• Ver el inventario completo.
• Registrar el ingreso físico de un contenedor al recinto (ingreso:registrar).
• Registrar la descarga del buque al recinto (descarga:registrar): avanza el contenedor de EN_BUQUE a DESCARGADO.
• Registrar el resultado de modulación/selección automatizada (modulacion:operar): avanza de EN_PATIO a MODULADO.
• Ver la malla de posiciones y el mapa de proceso.

No puede hacer

• Operar la cola de salida de garita.
• Registrar salidas físicas.
• Bloquear/desbloquear contenedores.
• Acceder a facturación, integraciones o admin.

Tareas típicas

1. Registrar ingreso de un contenedor descargado del buque:

   • Ir a /garita → sección "Entrada de garita" → formulario IngresoForm.
   • Capturar ISO, tipo de contenedor (20/40ft), naviera, transportista, placa, RFC figura transporte, número de sello.
   • Enviar → el contenedor aparece en Inventario con estado EN_PATIO y posición de malla asignada.
   • Se genera el EIR (Equipment Interchange Receipt) descargable desde el detalle del contenedor.

2. Registrar resultado de modulación:

   • Una vez que el semáforo fiscal emite resultado, ir al detalle del contenedor /contenedor/[iso].
   • Usar la acción de modulación → avanza etapa en el Kanban a "Modulado".

3. Consultar posición libre antes de colocar un contenedor:

   • Ir a /malla → ver las posiciones libres (SquareDashed) vs. ocupadas (PackageCheck).
   • Los stat cards muestran: % ocupación, cantidad ocupadas, libres y número de bloques.

---

2.5 Rol: cliente_readonly

Descripción

Acceso de solo lectura para clientes externos (importadores/exportadores). Ve únicamente los contenedores del tenant/RFC propio. No puede ejecutar ninguna acción operativa.

Módulos que ve en el sidebar

Inventario, Malla, Citas, Indicadores, Operaciones, Kanban, Mapa proceso, Almacén. No ve: Garita, Facturación, Integraciones, Admin.

Puede hacer

• Ver el inventario de contenedores asociados a su RFC (filtrado por tenant).
• Ver la posición en malla.
• Ver el estado del pipeline aduanal en Kanban y Mapa proceso.
• Consultar citas programadas.
• Ver indicadores y la línea de tiempo de dwell de sus contenedores.

No puede hacer

• Ejecutar ninguna acción operativa (ingreso, salida, modulación, bloqueo).
• Ver Garita, Facturación, Integraciones ni Admin.

Tareas típicas

1. Verificar el estado de mi contenedor:

   • Ir a / (Inventario) → la tabla muestra ISO, estado, posición, demora, recinto y último movimiento.
   • Clic en el ISO → detalle /contenedor/[iso] con historial de eventos y timeline.

2. Saber en qué etapa aduanal está el contenedor:

   • Ir a /kanban → localizar el ISO en la columna correspondiente (Por arribar → Descargado → En depósito → Modulado → Desaduanado → Salido).

3. Consultar cuánto tiempo lleva en patio:

   • En el Inventario, la columna "Demora" muestra el dwell calculado desde el ingreso.
   • En /operaciones (Gantt) se visualiza la línea de tiempo completa.

---

3. Módulos: guía por pantalla

3.1 Inventario /

Para qué sirve: Vista maestra de todos los contenedores del patio. Es la pantalla de aterrizaje por defecto.

Qué muestra:

• 4 stat cards: contenedores en patio físico, total registrados, liberados (listos para garita), ocupación malla (ocupadas/capacidad).
• Chips de filtro rápido por estado: filtra la lista sin recargar la página. Los estados siguen el orden del pipeline aduanal.
• En escritorio: tabla densa con columnas Contenedor (ISO, enlace al detalle), Estado (badge + icono de bloqueo si aplica), Posición, Demora (días desde ingreso), Recinto, Último movimiento, y acción de drawer.
• En móvil: tarjetas apiladas con la misma información.
• Badge naranja en el ícono del sidebar si hay salidas bloqueadas.

Cómo usarlo:

1. Pulsa un chip de estado para filtrar (por ejemplo, "Liberado" para ver los listos para salir).
2. Pulsa el ISO para abrir el detalle del contenedor.
3. Usa el drawer (botón al final de la fila) para ver un resumen rápido sin salir de la lista.

Quién puede verlo: Todos los roles (patio:ver).

---

3.2 Malla /malla

Para qué sirve: Distribución física de posiciones del patio por bloque, fila y nivel. Muestra dónde está cada contenedor en el espacio real.

Qué muestra:

• 4 stat cards: % de ocupación, posiciones ocupadas, libres y número de bloques.
• Vista switcher (MallaSwitcher) con múltiples modos de visualización del patio.
• Parámetro URL ?ubicar=ISO: centra la vista en la posición del contenedor indicado.

Cómo usarlo:

1. Para localizar un contenedor específico, navega a /malla?ubicar=CSQU3054383 (reemplaza con el ISO real).
2. Para asignar o reubicar un contenedor, el operador de patio usa el formulario de ingreso o rehandle desde el detalle del contenedor.

Quién puede verlo: Todos los roles (patio:ver).

---

3.3 Garita /garita

Para qué sirve: Punto de control de entradas y salidas físicas del recinto. Tiene dos secciones con permisos independientes.

Sección A — Entrada de garita (requiere ingreso:registrar)

• Formulario IngresoForm: captura ISO, tipo (20/40ft), naviera, transportista, número de placa, RFC de la figura de transporte, número de sello, permiso SICT.
• Al registrar, el contenedor pasa a EN_PATIO y se le asigna posición en malla.
• Se genera el EIR (Equipment Interchange Receipt) disponible en el detalle del contenedor.
• Roles que ven esta sección: admin, supervisor, operador_patio.

Sección B — Cola de salida (requiere garita:operar)

• Tabla en tiempo real (force-dynamic) con los contenedores en proceso de salida.
• Columnas: ISO, estado (autorizado ✓ / bloqueado ✗), motivo de bloqueo si aplica, transportista, fecha.
• Acción "Registrar salida": disponible solo para contenedores autorizados (sin bloqueo activo).
• Badge rojo en el sidebar si hay salidas bloqueadas.
• Roles que ven esta sección: admin, supervisor, operador_garita.

Cómo usarlo — flujo de salida:

1. El despachante libera el contenedor (despacho aduanero concluido → estado LIBERADO).
2. El operador_garita va a /garita → Cola de salida.
3. Verifica que el contenedor aparece como "autorizado" (sin bloqueo).
4. Confirma identidad del transportista y placa.
5. Pulsa "Registrar salida" → el contenedor pasa a estado SALIDO.

---

3.4 Citas /citas

Para qué sirve: Gestión de arribos de camión programados al recinto. Permite anticipar la operación de garita.

Qué muestra: Lista/calendario de citas con ventana horaria, ISO del contenedor esperado, transportista y estado de la cita.

Quién puede verlo: Todos los roles (patio:ver).

Quién puede crear citas: roles con ingreso:registrar — es decir admin, supervisor y operador_patio. El control es real y de doble capa: el formulario "Agendar cita" se oculta en la UI con <Protect permiso={INGRESO_REGISTRAR}> (app/citas/page.tsx) y el server action agendarCita (components/patio/actions.ts) re-verifica con exigir(PERMISO.INGRESO_REGISTRAR) antes de crear. Los roles sin ese permiso (operador_garita, cliente_readonly) ven la agenda pero no el formulario.

Cómo usarlo:

1. Un rol con ingreso:registrar (admin/supervisor/operador_patio) crea la cita con la ventana horaria y los datos del transporte.
2. El operador_garita la consulta antes de abrir la garita para verificar el arribo esperado.
3. La Malla muestra las citas en su scrubber temporal para anticipar ocupación.

---

3.5 Indicadores /indicadores

Para qué sirve: KPIs operativos del patio. Incluye métricas de dwell, ocupación y alertas de demora.

Qué muestra:

• KPIs principales: dwell promedio, máximo, ocupación porcentual, contenedores con demora alta.
• Badge naranja en el sidebar con el conteo de contenedores con demora sobre el umbral.
• Gráficas y métricas en tiempo real.

Quién puede verlo: Todos los roles (patio:ver).

Cómo usarlo:

1. Revisa el badge de "demoras" en el sidebar para una alerta rápida.
2. Dentro de /indicadores, identifica qué contenedores superan el umbral de días.
3. Desde el indicador, navega al detalle del contenedor para tomar acción (escalar, notificar al cliente, gestionar bloqueo).

---

3.6 Operaciones /operaciones

Para qué sirve: Línea de tiempo de dwell (Gantt) que muestra cuánto tiempo lleva cada contenedor en cada etapa del pipeline aduanal.

Qué muestra:

• Gantt interactivo con scrubber temporal: arrastrando el slider se mueve el tiempo y se actualizan barras, citas y ocupación.
• Una fila por contenedor con su barra de tiempo desde ingreso hasta el momento actual (o salida).
• Código de color por estado/etapa.

Quién puede verlo: Todos los roles (patio:ver).

Cómo usarlo:

1. Usa el scrubber para retroceder en el tiempo y ver cómo estaba el patio en un momento dado (modo revisión).
2. Identifica visualmente los contenedores con barras más largas (mayor dwell).
3. Clic en un contenedor en el Gantt para ir a su detalle.

---

3.7 Kanban /kanban

Para qué sirve: Vista del pipeline aduanal como tablero Kanban. 6 columnas correspondientes a las etapas de despacho. Permite avanzar etapas según rol (RBAC por evento).

Las 6 columnas del pipeline (en orden):

#	Columna	Estado físico	Descripción
1	Por arribar	EN_BUQUE	Buque con ETA; mercancía aún a bordo
2	Descargado	DESCARGADO	Descargado del buque al recinto fiscalizado
3	En depósito	EN_PATIO	En recinto fiscalizado, pendiente de despacho
4	Modulado	MODULADO	Pasó el módulo de selección automatizada (semáforo fiscal)
5	Desaduanado	LIBERADO	Despacho concluido; libre para salir
6	Salido	SALIDO	Salió del recinto fiscalizado (últimos 40 mostrados)

Qué muestra:

• Cards enriquecidas por contenedor: ISO, naviera, estado, demora, bloqueo si aplica.
• Botón "Avanzar etapa" visible solo si el rol tiene el permiso para ese movimiento.
• Drag-and-drop activo cuando el flag NEXT_PUBLIC_DND=true (disponible en producción actual).
• Sidebar de personal (ILUSTRATIVO) cuando NEXT_PUBLIC_PERSONAL_MOCK=true.

Quién puede verlo: Todos los roles (patio:ver).

Quién puede avanzar etapas:

• descarga:registrar → de "Por arribar" a "Descargado" (operador_patio, supervisor, admin).
• modulacion:operar → de "En depósito" a "Modulado" (operador_patio, supervisor, admin).
• garita:operar + salida:registrar → de "Desaduanado" a "Salido" (operador_garita, supervisor, admin).

---

3.8 Mapa de proceso /proceso

Para qué sirve: Visualización del pipeline aduanal como grafo (React Flow). Muestra el flujo de etapas con conteos y métricas en vivo del inventario real.

Qué muestra:

• Nodos por cada etapa del pipeline (6 etapas) con: conteo de contenedores, bloqueos activos, dwell máximo en días.
• Flechas de flujo entre etapas.
• Datos en tiempo real: todo número viene del inventario real; si no hay dato, muestra null (no inventa).
• 3 vistas disponibles mediante tabs: Línea (flujo lineal), Flujo (grafo libre), Tablero (resumen).

Quién puede verlo: Todos los roles (patio:ver).

Cómo usarlo:

1. Úsalo para comunicar el estado del patio a nivel gerencial o al cliente.
2. Un nodo con muchos bloqueos (rojo) indica cuellos de botella operativos.
3. El dwell máximo por etapa ayuda a identificar en cuál etapa se acumula la demora.

---

3.9 Almacén /almacen

Para qué sirve: Mapa 2D/3D de la distribución física de edificios y ocupación. Vista flagship para demostrar el estado espacial del recinto de un vistazo.

Qué muestra:

• Mapa interactivo con representación 3D de los bloques de almacenamiento (Three.js/React Three Fiber).
• Colores de ocupación por zona.
• Drill-down a la malla de posiciones desde el mapa.
• Vista del contenedor con chasis rotable, número ISO real, naviera y puertas.

Nota: El módulo 3D es ILUSTRATIVO salvo Bodega A (datos reales). Las dimensiones de edificios y distribución son representativas para demo.

Quién puede verlo: Todos los roles (patio:ver).

---

3.10 Verticales /verticales

Para qué sirve: Página informativa del catálogo de verticales soportadas por la plataforma.

Vertical	Uso	Vocabulario particular
aduanal	Patio de recinto fiscalizado (original)	Contenedor, pedimento, fracción arancelaria
aeropuerto	Aeropuerto de carga	ULD, AWB, vuelo, SLA ligado a vuelo
3pl	3PL / cross-dock	Pallets, velocidad de transferencia, WMS
cold	Cold storage	FEFO, cadena de frío, temperatura
self	Self-storage B2C	Unidad, acceso desatendido
generico	Almacenamiento sin especialización	Unidad

La vertical activa se configura por tenant. El término "contenedor" en el sidebar y módulos puede cambiar a "ULD", "unidad", etc. según la vertical del tenant (hook useLabel).

Nota de guard (C-01): /verticales es una ruta utilitaria informativa sin módulo-guard. No está en MODULO_POR_RUTA ni existe una constante MODULO.VERTICALES, así que moduloDeRuta() devuelve null y el proxy la trata como default-allow (accesible a cualquier sesión, como /login o /sin-acceso). Es correcto por diseño: no lee datos de tenant. Si en el futuro se le agrega lógica por tenant, deberá promoverse a módulo en lib/modules.ts.

---

3.11 Facturación /facturacion

Para qué sirve: Estado de cuenta de almacenaje: calcula el cobro por tiempo × espacio de cada contenedor en patio.

Acceso restringido: Solo roles con admin:gestionar (únicamente admin). La ruta directa también está protegida en servidor; sin permiso redirige a /sin-acceso.

Qué muestra:

• Resumen: total a cobrar (MXN con IVA 16%), contenedores facturables, días-almacenaje (suma), maniobras.
• Tabla por contenedor con fecha de ingreso, días en patio y subtotal calculado.
• Opción de emisión de CFDI mediante Facturapi (cuando la clave API está configurada).
• Banner "TARIFAS ILUSTRATIVAS" permanente (D-011): el tiempo (días en patio) es real de los eventos; las tarifas las configura el operador por tenant.

---

3.12 Integraciones /integraciones

Para qué sirve: Panel de configuración de la API REST y webhooks para conectar sistemas externos (ERP, WMS, sistema del agente aduanal).

Acceso restringido: Solo roles con admin:gestionar (únicamente admin).

Qué muestra:

• Endpoints disponibles de la API v1 (inventario, eventos, estado de cuenta).
• Configuración de webhooks: URL destino, eventos suscritos, secreto de firma.
• Documentación en línea del contrato de la API.

Endpoints de la API v1 (disponibles sin autenticación de admin en producción):

• GET /api/v1/inventario — listado de contenedores del tenant.
• GET /api/v1/eventos — historial de eventos del patio.
• GET /api/v1/estado-cuenta — estado de cuenta de almacenaje.

---

3.13 Detalle de contenedor /contenedor/[iso]

Para qué sirve: Vista completa del ciclo de vida de un contenedor individual.

Qué muestra:

• Estado actual con badge, posición en malla, demora calculada.
• EIR (Equipment Interchange Receipt): datos de entrada capturados en el ingreso (transportista, placa, RFC figura transporte, número de sello). Descargable.
• Timeline de eventos: todos los movimientos físicos y aduanales (overlay) en orden cronológico.
• Datos aduanales cuando están disponibles: pedimento (clave SAT oficial, Apéndice 22), fracción arancelaria (TIGIE), aduana de despacho (Apéndice 1 oficial).
• Widget de rehandle (reubicación) para operadores con permiso.
• Quién registró el ingreso (auditoría F3).

Quién puede verlo: Todos los roles con patio:ver. Las acciones dentro (bloqueo, rehandle) requieren sus permisos propios.

---

4. Glosario

Término	Definición
Contenedor	Unidad de carga estándar ISO (20ft o 40ft). Se identifica por su número ISO (ej. CSQU3054383). En la vertical aeropuerto equivale a ULD; en otras verticales, a "unidad".
ISO (número de contenedor)	Código alfanumérico único de 11 caracteres (4 letras + 6 dígitos + 1 dígito verificador) conforme a norma ISO 6346. Ej.: CSQU 305438 3.
Malla	Distribución física del patio en posiciones identificadas por bloque, fila y nivel (ej. A-03-1). Cada posición puede estar ocupada o libre.
Dwell / Demora	Tiempo que lleva un contenedor dentro del recinto desde su ingreso. Se mide en días. Una demora alta (sobre el umbral configurado) genera alerta en Indicadores. No incluye cálculo de dinero (ese es el cobro de almacenaje).
EIR	Equipment Interchange Receipt (Comprobante de Intercambio de Equipo). Documento que acredita la recepción física del contenedor en el recinto: fecha, ISO, transportista, placa, sello y estado físico. Generado automáticamente al registrar el ingreso en Garita.
Pedimento	Documento legal de declaración de importación/exportación ante el SAT/ADUANAS. La clave del pedimento sigue la estructura oficial del Apéndice 22 de las RGCE. Datos fiscales siempre reales (D-011).
Fracción arancelaria	Código de 8 dígitos de la TIGIE (Tarifa de la Ley de los Impuestos Generales de Importación y Exportación) que clasifica la mercancía. Catálogo oficial SAT.
Aduana	Clave de 3 dígitos (Apéndice 1 de las RGCE) que identifica la aduana de despacho. Ej.: 470 = Manzanillo, 240 = Veracruz.
Recinto fiscalizado	Instalación habilitada por el SAT donde se depositan las mercancías de comercio exterior mientras se completa el proceso de despacho aduanero.
Modulación / Semáforo fiscal	Proceso de selección automatizada (SAAI) que determina si un pedimento requiere reconocimiento aduanero (rojo) o es liberado de forma directa (verde). Avanza el estado del contenedor de EN_PATIO a MODULADO.
Despacho aduanero	Proceso legal completo desde la llegada de la mercancía al recinto hasta su liberación: descarga → depósito → modulación → reconocimiento (si aplica) → pago de contribuciones → liberación.
Pipeline aduanal

---

5. Notas de gobernanza operativa

Autorización: defensa en profundidad

La UI anticipa los permisos (sidebar filtrado, botones ocultos) pero no es la defensa real. Cada server action y cada endpoint de API re-verifica el permiso del usuario autenticado en servidor antes de ejecutar cualquier mutación. Un usuario no puede escalar privilegios manipulando la UI o llamando directamente a los endpoints.

Integridad de datos aduanales (D-011)

• Las claves de pedimento y fracciones arancelarias son catálogos oficiales citados (Apéndice 22 / TIGIE / Apéndice 1 RGCE).
• Nunca se inventan datos fiscales. Si no existe el catálogo o el dato, la pantalla muestra — o TODO, nunca un valor sintético.
• Las tarifas de almacenaje son ILUSTRATIVAS (banner permanente en /facturacion); el tiempo (días en patio) calculado es real.
• La demora es solo tiempo; no incluye cálculo de multas o recargos (eso es función del agente aduanal externo).

Gate D-015: merge a main

Todo PR que llegue a main debe pasar: build sin errores (npm run build), TypeScript sin errores (tsc), 464+ tests en verde, y revisión de código. El ejecutor no audita su propio PR.

Gate D-016: go visual del CEO

Toda pantalla CEO-facing requiere aprobación visual del CEO antes de llegar a producción.

Semáforo de capacidad

• 🟢 VERDE: operación normal.
• 🟡 AMARILLO: operación con alerta al CEO.
• 🔴 ROJO: pausa obligatoria. El CEO decide. Sin excepciones.

---

Fuentes del código: lib/auth/roles.ts, lib/modules.ts, components/layout/sidebar-nav.tsx, lib/customs/aduana.ts, páginas en app/. Última revisión: 2026-07-09.