7f45eb6383
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>
177 lines
5.9 KiB
Markdown
177 lines
5.9 KiB
Markdown
# 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*
|