History

Adrian Flores Cortes 7f45eb6383 docs(modulos): MAI-007 POD y Cierre - Especificacion completa Nuevo modulo P0 critico especificado: - README.md: Vision general, alcance, actores, flujo - REQUERIMIENTOS.md: 4 RF (4.7.1-4.7.4), RNF, validaciones - RESUMEN-EPICA.md: Valor de negocio, criterios exito, 31 SP User Stories (5): - US-MAI007-001: Capturar firma digital (8 SP) - US-MAI007-002: Registrar tiempos reales (5 SP) - US-MAI007-003: Adjuntar fotos evidencia (5 SP) - US-MAI007-004: Validar POD antes de cierre (8 SP) - US-MAI007-005: Cerrar con excepcion (5 SP) Este modulo es bloqueante para: - MAI-009 (Facturacion) - MAI-010 (Liquidaciones) - MAE-016 (Carta Porte) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>		2026-01-27 01:33:03 -06:00
..
historias-usuario	docs(modulos): MAI-007 POD y Cierre - Especificacion completa	2026-01-27 01:33:03 -06:00
README.md	docs(modulos): MAI-007 POD y Cierre - Especificacion completa	2026-01-27 01:33:03 -06:00
REQUERIMIENTOS.md	docs(modulos): MAI-007 POD y Cierre - Especificacion completa	2026-01-27 01:33:03 -06:00
RESUMEN-EPICA.md	docs(modulos): MAI-007 POD y Cierre - Especificacion completa	2026-01-27 01:33:03 -06:00

README.md

MAI-007: POD y Cierre Operativo

Version: 1.0.0 Fecha: 2026-01-27 Estado: Diseño Prioridad: P0 (Critico - Bloquea facturacion)

Descripcion General

El modulo POD (Proof of Delivery) y Cierre Operativo es responsable de capturar la evidencia de entrega, registrar tiempos reales y cerrar operativamente los viajes para permitir su facturacion.

Problema que resuelve:

Sin POD no se puede facturar al cliente
Sin registro de tiempos reales no se pueden calcular recargos por demoras
El cierre operativo es prerequisito para liquidacion de operadores

Objetivos del Modulo

Captura de POD: Registrar firma, nombre del receptor, fotos y documentos que comprueban la entrega
Registro de tiempos: Documentar llegada, inicio/fin de descarga, salida con precision
Validaciones: Asegurar que no se cierre un viaje sin evidencia completa o justificacion
Cierre contable: Congelar costos del viaje para calculo de rentabilidad

Alcance Funcional

Incluido

Captura de POD desde app movil (online/offline)
Firma digital del receptor
Captura fotografica de evidencia
Escaneo de documentos firmados
Registro de tiempos reales por parada
Calculo automatico de detention time
Validaciones de cierre
Notificacion a cliente de entrega
Integracion con facturacion

Excluido

Gestion de incidencias (MAI-008)
Generacion de facturas (MAI-009)
Liquidacion de operadores (MAI-010)

Actores

Actor	Rol en el modulo
Operador	Captura POD, registra tiempos, toma evidencias
Despachador	Valida POD, aprueba cierres con excepciones
Cliente	Recibe notificacion de entrega
Facturacion	Consulta POD para emitir factura

Flujo Principal

VIAJE EN DESTINO
      │
      ▼
┌─────────────────┐
│ Registro Arribo │ ← Automatico por geocerca o manual
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Inicio Descarga │ ← Timestamp + evidencias
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Fin Descarga    │ ← Timestamp
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│ Captura POD             │
│ - Firma digital         │
│ - Nombre receptor       │
│ - Fotos (opcional)      │
│ - Documento escaneado   │
└────────┬────────────────┘
         │
         ▼
┌─────────────────┐
│ Validaciones    │ ← POD completo? Tiempos OK?
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
[APROBADO]  [EXCEPCION]
    │         │
    │         ▼
    │    ┌──────────────┐
    │    │ Justificacion │
    │    │ + Aprobacion  │
    │    └──────┬───────┘
    │           │
    ▼           ▼
┌─────────────────┐
│ VIAJE CERRADO   │
└────────┬────────┘
         │
         ▼
   [Listo para facturar]

Datos del Modulo

Entidades Principales

Entidad	Descripcion	Estado
POD	Prueba de entrega	NO IMPLEMENTADA
FirmaDigital	Firma capturada	NO IMPLEMENTADA
FotoEntrega	Evidencia fotografica	NO IMPLEMENTADA
TiempoReal	Tiempos registrados	NO IMPLEMENTADA
CierreViaje	Registro de cierre	NO IMPLEMENTADA

Campos Clave POD

Campo	Tipo	Obligatorio	Descripcion
viaje_id	UUID	Si	Referencia al viaje
parada_id	UUID	Si	Parada de entrega
receptor_nombre	VARCHAR(150)	Si	Nombre de quien recibe
receptor_identificacion	VARCHAR(50)	No	ID del receptor
firma_digital_id	UUID	Si	Referencia a firma
fecha_entrega	TIMESTAMP	Si	Fecha/hora de entrega
status	ENUM	Si	PENDIENTE, COMPLETO, EXCEPCION
notas	TEXT	No	Observaciones

Requerimientos Funcionales

Ver archivo: REQUERIMIENTOS.md

Metricas del Modulo

KPI	Formula	Meta
POD Capturados	% viajes con POD	>98%
Tiempo promedio captura	Avg(fin_descarga - arribo)	<60 min
Detention rate	% viajes con detention	<15%
POD con excepciones	% POD con justificacion	<5%

Dependencias

Este modulo depende de:

MAI-005 (Despacho): Viaje debe estar despachado
MAI-006 (Tracking): Eventos de arribo por geocerca
MAI-011 (Gestion Flota): Datos de operador

Otros modulos dependen de este:

MAI-009 (Facturacion): No puede facturar sin POD
MAI-010 (Liquidaciones): Cierre para liquidar operador
MAE-016 (Carta Porte): Expediente fiscal del viaje

Consideraciones Tecnicas

App Movil

Debe funcionar offline con sincronizacion posterior
Compresion de fotos antes de subir
Captura de firma mediante canvas
Almacenamiento temporal seguro

Validaciones

Coordenadas GPS dentro de geocerca del destino
Timestamp coherente con eventos previos
Archivo de firma no vacio

Integraciones

Notificacion a cliente via WhatsApp/Email
Webhook a sistema de facturacion
Sincronizacion con ERP contable

Historias de Usuario

Ver carpeta: historias-usuario/

US	Titulo	Prioridad
US-MAI007-001	Capturar firma digital en entrega	Alta
US-MAI007-002	Registrar tiempos reales de operacion	Alta
US-MAI007-003	Adjuntar fotos de evidencia	Alta
US-MAI007-004	Validar POD antes de cierre	Alta
US-MAI007-005	Cerrar viaje con excepcion justificada	Media

Referencias

REQ-GIRO-TRANSPORTISTA.md - Seccion 4.7
MATRIZ-COHERENCIA-DDL-BACKEND.yml
MAPEO-RF-GIRO-A-MODULOS.yml

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