# 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

1. **Captura de POD:** Registrar firma, nombre del receptor, fotos y documentos que comprueban la entrega
2. **Registro de tiempos:** Documentar llegada, inicio/fin de descarga, salida con precision
3. **Validaciones:** Asegurar que no se cierre un viaje sin evidencia completa o justificacion
4. **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](./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/](./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*