Respuestas Sugeridas Para Logistica

Este documento convierte las preguntas abiertas en respuestas sugeridas para usar en talleres, capacitacion y cierre del manual. Cada respuesta fue contrastada contra el codigo y la documentacion incluida en el repositorio.

Leyenda de confianza:

• Alta: el codigo o el modelo de datos lo define explicitamente.
• Media: el codigo lo soporta, pero falta que Operaciones confirme la politica humana.
• Baja: el sistema no impone la regla; se propone como criterio operativo.

Resumen Ejecutivo

Dominio	Decision sugerida	Confianza
Estados	Usar Estado_Principal y Estado_secundario1 como ciclo operativo de Zoho; mapear Driver App, tracking y portal como estados satelite.	Alta
Evidencia	La foto de evidencia es obligatoria al completar desde Driver App; firma, pago, receptor y bultos dependen del tipo.	Alta
Tracking	El link publico dura 24 horas y solo expone datos operativos de entrega, no datos financieros ni internos.	Alta
Conductores	La Driver App debe ser el canal oficial para cierre en campo; cualquier excepcion debe quedar como contingencia controlada.	Media
Ruteo	El motor optimiza, pero la ruta publicada y asignacion persistida son la fuente operativa.	Media
Finanzas	Politica base: contado, al cobro y credito; los medios concretos se normalizan por canal.	Media
Flota	Los umbrales de combustible existen, pero el bloqueo por mantenimiento necesita regla humana oficial.	Media
Gobernanza	apps/logistics-api debe tratarse como legado sin fuente activa; la funcionalidad viva esta repartida entre core, clients, drivers y engine.	Alta

Estados Y Ciclo De Vida

1. Lista oficial de estados de tarea por tipo

Respuesta sugerida para usar:
Para ADOMI, PICK, ENVNA, CSH, LSH y MANIF, el ciclo oficial debe partir de Zoho:

• Estado_Principal: Por Realizar, Completa, Reprogramada, Cancelado.
• Estado_secundario1: Por Asignar, Asignada, Recibido, En Transito, Entregada, Reprogramada, Cancelada.

La diferencia por tipo no debe crear estados nuevos sin necesidad; debe cambiar la evidencia requerida, el origen/destino, el pago y la notificacion.

Confianza: Alta para la lista de estados; Media para asumir que todos los tipos comparten exactamente el mismo catalogo operativo.
Evidencia: apps/zoho-app/docs/data-model.md, apps/zoho-app/AGENTS.md.

2. Estados terminales y reabribles

Respuesta sugerida para usar:
Completa/Entregada y Cancelado/Cancelada deben tratarse como terminales. Reprogramada cierra el intento actual, pero mantiene continuidad operacional mediante nueva fecha o nueva ejecucion asociada. Por Realizar, Por Asignar, Asignada, Recibido y En Transito son estados activos.

Una reapertura no debe hacerse editando silenciosamente el terminal; debe quedar como evento nuevo, reprogramacion, reasignacion o correccion auditada.

Confianza: Media.
Evidencia: workflows de reprogramacion en apps/zoho-app/app/forms/Reprogramar_Tareas, eventos task_rescheduled, task_cancelled y task_completed.

3. Diferencia entre estados de Zoho, Driver App, tracking y portal

Respuesta sugerida para usar:
Estado_Principal representa el estado de negocio de la tarea en Zoho. Estado_secundario1 representa el detalle operativo de la tarea. driverAppStatus representa el avance reportado desde la Driver App (pending, assigned, inProgress, completed, problem) y no debe reemplazar al estado de negocio. delivery_tracking.status representa el link publico del cliente (pending, en_route, arrived, completed, cancelled). mobilizations.status representa una solicitud del portal cliente (requested, picked_up, in_transit, delivered, available_for_pickup, cancelled).

Confianza: Alta.
Evidencia: packages/core-shared/src/schema.ts, apps/drivers-backend/shared/schema.ts, apps/clients-backend/src/db/schema.ts.

4. Quien puede cambiar manualmente un estado y bajo que evidencia

Respuesta sugerida para usar:
Solo roles operativos con permiso de gestionar tareas/rutas deben cambiar estados manualmente en dashboard o Zoho. El conductor no debe editar estados desde dashboard; debe reportar avance desde Driver App. Toda edicion manual debe tener motivo, actor, fecha y evidencia cuando aplique.

Confianza: Media.
Evidencia: permisos canManageJobs, bloqueo de rol conductor en dashboard, auditLogs, taskEvents, historiales de reprogramacion y cancelacion.

Ingreso De Demanda

1. Campos obligatorios por tipo de tarea

Respuesta sugerida para usar:
Todo ingreso debe tener tipo de tarea, referencia, fecha prometida, origen, destino, contacto, direccion o coordenadas, politica de pago, cliente/empresa y detalle de paquetes cuando aplique. Para flujos de entrega o recoleccion con evidencia, deben existir datos que permitan notificar, enrutar y cerrar: telefono, direccion, bultos o tracking, monto esperado si hay cobro, y ventana horaria si fue prometida.

Confianza: Media.
Evidencia: formularios Zoho Tareas, grid Registro_de_Paquetes, schemas de tasks, mobilizations y completions.

2. Solicitudes del portal que requieren aprobacion antes de entrar a ruta

Respuesta sugerida para usar:
El portal permite crear movilizaciones a roles owner, admin y operator. En el codigo no aparece un paso universal de aprobacion antes de ruta, por lo que la respuesta operativa sugerida es: una solicitud del portal entra como requested y queda lista para validacion operativa; si Logistica requiere aprobacion formal, debe definirse como estado o regla adicional.

Confianza: Media.
Evidencia: apps/clients-backend/src/common/roles.ts, apps/clients-backend/src/routes/mobilization.routes.ts.

3. Quien corrige datos incompletos de PARED/SIGMA

Respuesta sugerida para usar:
Si el dato incompleto impide operar hoy, lo corrige el operador de Logistica en la fuente operativa autorizada. Si el error es recurrente o viene mal mapeado, lo corrige Integraciones. Si es informacion de negocio del cliente, se devuelve al cliente o al sistema origen.

Confianza: Media.
Evidencia: referencias movimientoTracking, integraciones PARED/SIGMA y workflows de actualizacion/reprogramacion; la asignacion humana exacta no esta codificada.

4. Cuando crear tarea manual en dashboard vs Zoho

Respuesta sugerida para usar:
Crear en dashboard cuando la tarea nace de operacion interna moderna, portal, administracion o flujo que ya vive en Core. Crear en Zoho cuando el origen oficial del flujo sigue siendo Zoho o una integracion historica conectada a Zoho. No duplicar la misma tarea en ambos sistemas: si hay que corregir, se edita la fuente de verdad y se deja que la sincronizacion propague.

Confianza: Media.
Evidencia: tasks.id puede ser Zoho ID o UUID local; rawData conserva datos Zoho; existe sync Zoho-Core.

Ruteo

1. Motor oficial por flujo

Respuesta sugerida para usar:
La ruta oficial para ejecucion es la asignacion persistida al conductor y visible para operacion. El engine, Google/Fleet o la logica Zoho/Zelta pueden proponer u optimizar, pero no son "oficiales" hasta que la secuencia queda publicada/asignada.

En fase actual, Zoho/Zelta mantiene flujos historicos; Dashboard/Core coordina rutas y visibilidad; Engine funciona como optimizador especializado.

Confianza: Media.
Evidencia: route_optimizations, driver_route_sessions, integraciones routeViewerV2, engine backend y rutas de optimizacion.

2. Cuando reoptimizar una ruta publicada

Respuesta sugerida para usar:
Reoptimizar cuando se completa una tarea, se agrega o elimina tarea, se reasigna conductor, cambia fecha/ventana/direccion, el conductor o vehiculo queda no disponible, o una incidencia afecta ETA, capacidad o cumplimiento.

Confianza: Media.
Evidencia: reoptimizacion autonoma tras completar tareas, triggerReason: task_completed, funciones de asignacion/desasignacion y reprogramacion.

3. Quien puede romper la secuencia sugerida por el motor

Respuesta sugerida para usar:
Solo supervisor, manager u operador autorizado debe romper la secuencia. El conductor puede reportar una causa operativa, pero la excepcion debe quedar registrada como incidente, problema, reprogramacion o reasignacion.

Confianza: Media.
Evidencia: roles con permisos de rutas/tareas; Driver App registra eventos y problemas, no administra la planificacion global.

4. Datos que bloquean entrada a ruta

Respuesta sugerida para usar:
Una tarea no debe entrar a ruta si le falta direccion o coordenadas usables, fecha de entrega/recoleccion, tipo, referencia, cliente/contacto cuando hay notificacion, bultos o paquete cuando aplica, conductor/vehiculo requerido, o si esta cancelada, completada o duplicada. Tambien debe bloquearse cuando exista regla financiera o de saldo que impida operar.

Confianza: Media.
Evidencia: schemas de tareas/movilizaciones, endpoints de ruteo, validaciones de completado y referencias de saldo/rayo en docs fuente.

Conductor

1. Uso obligatorio de Driver App

Respuesta sugerida para usar:
La Driver App debe ser el canal oficial para iniciar tracking, reportar avance, subir evidencia y cerrar tareas en campo. El dashboard bloquea el acceso del rol conductor, lo que confirma que el conductor no debe operar desde el dashboard. Cualquier excepcion sin app debe documentarse como contingencia supervisada.

Confianza: Media-alta.
Evidencia: apps/core-backend/server/auth.ts, endpoints Driver App, driverAppStatus.

2. Evidencia obligatoria por tipo de tarea

Respuesta sugerida para usar:
Para completar desde Driver App son obligatorios taskReference, driverId y evidencePhotoUrl. Segun el tipo de tarea, se debe agregar firma, receptor, cantidad de bultos, fotos adicionales, notas y datos de pago. En Zoho, la evidencia de entrega/recoleccion, firma y pago quedan en SCAN.

Confianza: Alta para la foto obligatoria; Media para la matriz por tipo.
Evidencia: /api/tasks/:id/complete, task_completions, docs de SCAN en Zoho.

3. Que hacer sin conexion al cerrar

Respuesta sugerida para usar:
El conductor debe capturar la evidencia en la app y permitir que la cola persistente de uploads reintente al recuperar conexion. La tarea no debe considerarse oficialmente cerrada hasta que el backend confirme cierre y sincronizacion. Si la app no logra sincronizar, el conductor debe reportarlo al supervisor con referencia, hora y evidencia disponible.

Confianza: Media-alta.
Evidencia: upload-queue:v1, replayQueue, useUploadQueueProcessor, cierre backend con evidencia obligatoria.

4. Motivos permitidos de problema, reprogramacion y cancelacion

Respuesta sugerida para usar:
Los motivos permitidos deben salir del catalogo de Zoho Motivos_para_reprogramar_una_entrega cuando se trate de reprogramacion. Otro solo debe usarse con detalle obligatorio. Cancelacion y problema deben registrar motivo textual y evidencia cuando aplique, hasta que Logistica cierre un catalogo equivalente para esos casos.

Confianza: Media.
Evidencia: Reprogramar_Tareas, validacion de Detalle_otro_motivo, funciones taskRescheduled, taskCancelled.

Tracking Y Comunicacion

1. Clientes que reciben link WhatsApp e idioma

Respuesta sugerida para usar:
Reciben link por WhatsApp las tareas normalizadas como delivery que tengan telefono de cliente. El idioma se normaliza desde customerLanguage; si no hay dato confiable, usar el idioma por defecto del flujo.

Confianza: Alta para condicion tecnica; Media para politica de idioma.
Evidencia: /api/tracking/start, normalizeTaskType, normalizeLanguage, sendTrackingWhatsApp.

2. Duracion del link de tracking

Respuesta sugerida para usar:
El link de tracking dura 24 horas desde su creacion.

Confianza: Alta.
Evidencia: expiresAt.setHours(expiresAt.getHours() + 24) en /api/tracking/start.

3. Informacion publica permitida y oculta

Respuesta sugerida para usar:
El link publico puede mostrar estado, tipo de tarea, nombre del conductor, ubicacion del conductor, destino, nombre del cliente, referencia, ETA y timestamps operativos. Debe ocultar pagos, notas internas, telefonos, IDs internos sensibles, auditoria, errores de sync, datos financieros y cualquier raw payload.

Confianza: Alta.
Evidencia: respuesta publica de /api/tracking/:id, que excluye datos sensibles.

4. SLA de actualizacion de ubicacion

Respuesta sugerida para usar:
Prometer "casi en tiempo real" con una meta operativa de 10 a 60 segundos, no una garantia contractual estricta. El backend acepta actualizaciones periodicas y reenvia ubicacion al dashboard; existe throttling para evitar saturacion.

Confianza: Media.
Evidencia: PATCH /api/tracking/:id/location, background location en Driver App, throttle de envio de ubicacion.

Finanzas

1. Politica para medios de pago

Respuesta sugerida para usar:
La politica comercial base es Contado, Al Cobro y Credito. Los medios operativos aceptados deben mapearse a efectivo, Yappy, ACH/transferencia, tarjeta, credito y ninguno cuando no aplica. Yappy Directorio requiere codigo de confirmacion para cierre desde Driver App.

Confianza: Media.
Evidencia: Politica_de_pago en Zoho, paymentMethodEnum, validacion de Yappy en /api/tasks/:id/complete.

2. Diferencia pago vs factura/movimiento que genera alerta

Respuesta sugerida para usar:
Debe generar alerta cualquier diferencia entre monto esperado y monto capturado. Para Yappy, usar tolerancia maxima de centavos; para efectivo, transferencia o credito, cualquier diferencia debe quedar como nota o revision de cobranza antes de liquidar.

Confianza: Media.
Evidencia: captura de pagos en SCAN y Driver App; validaciones de Yappy y modelos de pagos/movimientos. La politica de tolerancia final no esta centralizada.

3. Quien corrige pagos mal clasificados

Respuesta sugerida para usar:
Contabilidad o cobranza corrige pagos mal clasificados, con auditoria. El conductor puede reportar el error, pero no debe modificar pagos cerrados despues de la liquidacion. Operaciones puede solicitar correccion si el pago afecta cierre de ruta.

Confianza: Media.
Evidencia: roles contabilidad, permisos canManageAR, caja/liquidacion diaria en Zoho, audit logs.

4. Proceso de deuda vencida

Respuesta sugerida para usar:
Cobranza identifica deuda vencida, revisa estado de cuenta, contacta al cliente, envia link o instruccion de pago, registra nota/seguimiento y escala si no hay respuesta. Si la deuda bloquea operacion, el bloqueo debe quedar como politica comercial visible para Operaciones.

Confianza: Media.
Evidencia: modulos AR/collections, movimientos, payment links, notas y scoring de cobranza en Core.

Flota

1. Mantenimiento que bloquea asignar vehiculo

Respuesta sugerida para usar:
Debe bloquear asignacion cuando el vehiculo este inactivo, fuera de servicio, en mantenimiento critico, con documentacion vencida relevante, o con lavado/recordatorio vencido que Logistica defina como obligatorio. El codigo contiene gestion de vehiculos y recordatorios, pero no impone universalmente este bloqueo.

Confianza: Baja-media.
Evidencia: modulos de vehiculos, schedules de lavado/recordatorios, rutas de flota. Falta regla central de bloqueo.

2. Validacion de kilometraje oficial

Respuesta sugerida para usar:
El kilometraje oficial debe ser el ultimo odometro validado por captura operativa, cruzado contra GPS/Satrack y OCR cuando exista imagen. Si hay discrepancia material, se debe abrir revision antes de usarlo para combustible o mantenimiento.

Confianza: Media.
Evidencia: vehicleUsageSessions, odometer-snapshot, odometer-ocr, comparacion GPS vs odometro en anomalias de combustible.

3. Umbrales de combustible/anomalia

Respuesta sugerida para usar:
Usar los umbrales codificados como linea base:

• Consumo excesivo: rendimiento menor a 60% del esperado, o umbral configurado por perfil.
• Severidad alta si baja de 40% del esperado.
• Cantidad excesiva: carga mayor a 110% de capacidad del tanque.
• Intervalo sospechoso: menos de 4 horas entre cargas y total combinado mayor a 120% del tanque.
• Alto costo por km: mas de 150% del promedio de flota.
• Diferencia GPS/odometro: alerta si supera 5%; alta si supera 15%.
• Retroceso de odometro: mas de 10 km hacia atras.

Confianza: Alta.
Evidencia: apps/core-backend/server/services/fuel-anomaly-detection.ts.

4. KPI de conductor accionable

Respuesta sugerida para usar:
Los KPI accionables son puntualidad, completitud, cancelaciones, reprogramaciones, velocidad, uso de app, problemas y volumen. La evaluacion debe revisar resultados contra minimo de tareas antes de sancionar o premiar.

Confianza: Alta.
Evidencia: driver-evaluation.ts, driverEvaluationSettings, pesos por dimension.

Sistemas Y Gobernanza

1. Matriz oficial de fuente de verdad por campo

Respuesta sugerida para usar:

Campo / dato	Fuente de verdad sugerida
Ciclo historico de tarea, referencia, integraciones ADOMI/PICK/ENVNA/CSH/LSH/MANIF	Zoho hasta migracion formal
Estado de ejecucion en campo, evidencia, cierre conductor	Driver App / Drivers Backend
Visibilidad operativa, auditoria, rutas, AR, flota, combustible	Dashboard Core
Solicitudes y usuarios de clientes	Portal Clientes
Optimizacion, simulacion y sesiones de ruta	Engine
Pagos cerrados/liquidacion	Zoho + Core Finanzas, segun flujo
Tracking publico	Drivers Backend tracking

Confianza: Media-alta.
Evidencia: boundaries de apps, schemas compartidos, sync events, docs de integraciones.

2. Schedules Zoho activos en produccion

Respuesta sugerida para usar:
El repositorio contiene estos schedules de Zoho: Actualizar_rutas_de_entre, Desasociar_tareas, Notificaci_n_cambio_de_ga, Notificar1, Notificar_entrega_de_tare, Recordatorio_rotaci_n_de, caducar_lavado_de_auto, caducar_recordatorio, crear_seguimiento_de_coli, generar_recordatorios_lav, generar_recordatorios_lav2, getNewRoute, notificar_creacion_envio y verificar_sigmas_despacha. Deben revisarse en Zoho Creator produccion para confirmar si estan activos, pausados o solo historicos.

Confianza: Media.
Evidencia: apps/zoho-app/app/schedules y metadata exportada.

3. Procedimiento ante fallas repetidas de sync

Respuesta sugerida para usar:
Primero revisar el panel de sincronizacion/admin y sync_events; despues identificar fuente de verdad y ultimo evento exitoso; reintentar solo si el evento es idempotente; si falla repetidamente, abrir incidente con payload, referencia, sistema origen, sistema destino y hora. No corregir manualmente en varios sistemas a la vez.

Confianza: Media-alta.
Evidencia: syncEvents, endpoints de admin sync, servicios de sync y webhooks con registro success/error.

4. Eventos con idempotencia obligatoria

Respuesta sugerida para usar:
Todo evento externo que cambie estado debe tener idempotencia: completado, cancelado, reprogramado, asignado, desasignado, inicio/llegada/problema de conductor, pagos, tracking y webhooks de portal. El minimo es event_id estable o clave unica por referencia + tipo de evento + timestamp controlado.

Confianza: Media-alta.
Evidencia: driver-events exige event_id, webhooks Zoho V2 usan event_id/zoho_event_id, taskEvents conserva eventos.

5. Modulo que reemplaza o absorbe apps/logistics-api

Respuesta sugerida para usar:
Ningun modulo debe declararse como reemplazo formal todavia. En el estado actual del repositorio, apps/logistics-api parece legado o artefacto compilado: solo hay dist, caches y dependencias locales visibles, no fuente activa. Funcionalmente, lo vivo esta repartido entre apps/core-backend, apps/clients-backend, apps/drivers-backend y apps/engine-backend.

Decision recomendada: marcar apps/logistics-api como legado hasta que Direccion confirme si se archiva, se restaura fuente o se absorben contratos pendientes en Core/Clients/Drivers/Engine.

Confianza: Alta para el estado del repo; Baja para la decision empresarial.
Evidencia: inspeccion de apps/logistics-api, mapa actual de apps del monorepo.

Preguntas Que Aun Debe Firmar Logistica

Estas respuestas ya son utilizables como borrador, pero antes de convertirlas en politica oficial se recomienda pedir firma sobre:

1. Catalogo final de estados por tipo de tarea y si algun tipo necesita excepcion.
2. Matriz exacta de evidencia obligatoria por tipo.
3. Politica formal de aprobacion de movilizaciones del portal.
4. SLA prometido al cliente para tracking.
5. Tolerancias financieras por medio de pago.
6. Reglas de bloqueo por mantenimiento o flota.
7. Schedules activos reales en Zoho produccion.
8. Decision final sobre apps/logistics-api.