erp-transportistas-v2/docs/02-definicion-modulos/MAI-007-pod-cierre/REQUERIMIENTOS.md

REQUERIMIENTOS.md - MAI-007: POD y Cierre Operativo

Version: 1.0.0 Fecha: 2026-01-27 Fuente: REQ-GIRO-TRANSPORTISTA.md - Seccion 4.7

---

Requerimientos Funcionales

RF-4.7.1: Captura POD

Descripcion: El sistema debe permitir capturar la prueba de entrega (Proof of Delivery) incluyendo firma digital, nombre/ID del receptor, sello, fotos y documento escaneado.

Criterios de Aceptacion:

1. El operador puede capturar firma digital en pantalla tactil
2. El sistema registra nombre y opcionalmente ID del receptor
3. El operador puede adjuntar 1-5 fotos de evidencia
4. El operador puede escanear documento firmado (carta de porte, remision)
5. La captura funciona en modo offline con sincronizacion posterior
6. El sistema valida que la firma no este vacia
7. El sistema registra coordenadas GPS de la captura

Mapeo a DDL:

• Tabla: pod
• Campos: receptor_nombre, receptor_identificacion, firma_digital_id, foto_ids, documento_url, coordenadas, fecha_captura

Endpoints Requeridos:

• POST /api/v1/pod - Crear POD
• PUT /api/v1/pod/:id - Actualizar POD
• POST /api/v1/pod/:id/firma - Subir firma digital
• POST /api/v1/pod/:id/fotos - Subir fotos
• POST /api/v1/pod/:id/documento - Subir documento escaneado

Prioridad: Alta

---

RF-4.7.2: Validaciones POD

Descripcion: El sistema no debe permitir "cerrar" un viaje sin POD o sin justificacion aprobada por un supervisor.

Criterios de Aceptacion:

1. El boton "Cerrar Viaje" esta deshabilitado si no hay POD capturado
2. Si no hay POD, el sistema muestra opcion "Cerrar con Excepcion"
3. Cerrar con excepcion requiere:
   • Motivo de excepcion (catalogo + texto libre)
   • Aprobacion de supervisor (puede ser posterior)
4. El sistema notifica al supervisor cuando hay excepciones pendientes
5. Las excepciones se registran en bitacora de auditoria

Mapeo a DDL:

• Tabla: pod campo status (COMPLETO, EXCEPCION_PENDIENTE, EXCEPCION_APROBADA)
• Tabla: excepciones_pod (viaje_id, motivo, justificacion, aprobador_id, fecha_aprobacion)

Endpoints Requeridos:

• POST /api/v1/viajes/:id/cierre-excepcion - Solicitar cierre con excepcion
• PUT /api/v1/excepciones/:id/aprobar - Aprobar excepcion
• PUT /api/v1/excepciones/:id/rechazar - Rechazar excepcion

Prioridad: Alta

---

RF-4.7.3: Tiempos Reales

Descripcion: El sistema debe registrar tiempos de llegada, inicio/fin de descarga y salida para metricas de detention y SLA.

Criterios de Aceptacion:

1. El operador puede registrar:
   • Hora de arribo al destino
   • Hora de inicio de descarga
   • Hora de fin de descarga
   • Hora de salida del destino
2. Los eventos pueden capturarse automaticamente por geocerca
3. El sistema calcula automaticamente:
   • Tiempo de espera (arribo a inicio descarga)
   • Tiempo de descarga (inicio a fin)
   • Tiempo total en destino
4. El sistema compara vs tolerancia del SLA del cliente
5. Si se excede tolerancia, genera flag de "detention"
6. Los tiempos alimentan calculo de recargos en facturacion

Mapeo a DDL:

• Tabla: tiempos_reales
• Campos: viaje_id, parada_id, hora_arribo, hora_inicio_descarga, hora_fin_descarga, hora_salida, detention_minutos, excede_sla

Endpoints Requeridos:

• POST /api/v1/tiempos-reales - Registrar tiempo
• GET /api/v1/viajes/:id/tiempos - Consultar tiempos del viaje
• GET /api/v1/viajes/:id/detention - Consultar detention calculado

Prioridad: Alta

---

RF-4.7.4: Cierre Contable Operativo

Descripcion: Al cerrar el viaje, el sistema debe congelar los costos (combustible, peajes, viaticos) y calcular rentabilidad preliminar.

Criterios de Aceptacion:

1. Al cerrar viaje, el sistema:
   • Marca costos como "cerrados" (no editables)
   • Suma total de costos del viaje
   • Calcula margen vs precio cotizado
   • Genera registro de cierre con snapshot de valores
2. El cierre puede revertirse solo con autorizacion especial
3. El sistema genera alerta si margen es negativo
4. El viaje cerrado pasa a estado "LISTO_FACTURAR"
5. El sistema notifica a facturacion que hay viaje listo

Mapeo a DDL:

• Tabla: cierres_viaje
• Campos: viaje_id, fecha_cierre, usuario_cierre, total_costos, total_ingresos, margen, status

Endpoints Requeridos:

• POST /api/v1/viajes/:id/cerrar - Cerrar viaje
• POST /api/v1/viajes/:id/reabrir - Reabrir viaje (admin)
• GET /api/v1/viajes/:id/rentabilidad - Consultar rentabilidad

Prioridad: Alta

---

Requerimientos No Funcionales

RNF-001: Performance App Movil

La captura de POD debe completarse en menos de 30 segundos incluyendo firma y fotos.

RNF-002: Disponibilidad Offline

El modulo debe funcionar sin conexion, almacenando datos localmente hasta 72 horas.

RNF-003: Compresion de Imagenes

Las fotos deben comprimirse a max 500KB antes de sincronizar.

RNF-004: Seguridad

La firma digital debe almacenarse cifrada y ser verificable contra el registro de entrega.

RNF-005: Auditoria

Todos los eventos de POD deben registrarse en log de auditoria con usuario, timestamp y coordenadas.

---

Validaciones de Negocio

Validacion	Descripcion	Accion si falla
POD_001	Firma no puede estar vacia	Rechazar POD
POD_002	Receptor nombre obligatorio	Rechazar POD
POD_003	GPS dentro de geocerca destino	Warning, permitir con nota
POD_004	Tiempos en secuencia logica	Rechazar si arribo > descarga
POD_005	Viaje en estado EN_DESTINO	No permitir captura

---

Matriz de Trazabilidad

RF	Tabla DDL	Entity	Endpoint	US
RF-4.7.1	pod	POD	POST /api/v1/pod	US-MAI007-001, US-MAI007-003
RF-4.7.2	excepciones_pod	ExcepcionPOD	POST /viajes/:id/cierre-excepcion	US-MAI007-005
RF-4.7.3	tiempos_reales	TiempoReal	POST /api/v1/tiempos-reales	US-MAI007-002
RF-4.7.4	cierres_viaje	CierreViaje	POST /viajes/:id/cerrar	US-MAI007-004

---

MAI-007 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0