diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/README.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/README.md new file mode 100644 index 0000000..a91cad6 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/README.md @@ -0,0 +1,219 @@ +# 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* diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/REQUERIMIENTOS.md new file mode 100644 index 0000000..b51960a --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/REQUERIMIENTOS.md @@ -0,0 +1,176 @@ +# 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* diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/RESUMEN-EPICA.md new file mode 100644 index 0000000..09bf67c --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/RESUMEN-EPICA.md @@ -0,0 +1,190 @@ +# RESUMEN-EPICA.md - MAI-007: POD y Cierre Operativo + +**Codigo:** MAI-007 +**Nombre:** POD y Cierre Operativo +**Version:** 1.0.0 +**Fecha:** 2026-01-27 + +--- + +## Valor de Negocio + +### Problema + +Actualmente las empresas transportistas enfrentan: +- Disputas con clientes por falta de evidencia de entrega +- Retrasos en facturacion por documentacion incompleta +- Perdida de ingresos por no documentar detention time +- Imposibilidad de calcular rentabilidad real por viaje + +### Solucion + +Un sistema robusto de captura de POD que: +- Provee evidencia digital irrefutable de entrega +- Automatiza el registro de tiempos para recargos +- Cierra operativamente el viaje para facturacion inmediata +- Calcula rentabilidad preliminar al cerrar + +### Beneficios Esperados + +| Beneficio | Metrica | Impacto | +|-----------|---------|---------| +| Reduccion disputas | -80% reclamos sin evidencia | Ahorro legal | +| Facturacion rapida | -3 dias ciclo facturacion | Flujo de caja | +| Recargos detention | +15% captura detention | Ingresos | +| Visibilidad costos | 100% viajes con rentabilidad | Decisiones | + +--- + +## Actores y Stakeholders + +### Usuarios Primarios + +| Actor | Responsabilidad | Frecuencia | +|-------|-----------------|------------| +| Operador | Captura POD, registra tiempos | Cada entrega | +| Despachador | Valida POD, aprueba excepciones | Continuo | +| Supervisor | Autoriza cierres especiales | Bajo demanda | + +### Usuarios Secundarios + +| Actor | Interes | +|-------|---------| +| Facturacion | Usa POD para emitir facturas | +| Atencion Cliente | Consulta POD para responder dudas | +| Gerencia | Revisa metricas de entrega | + +--- + +## Flujo Principal + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ VIAJE EN DESTINO │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 1. REGISTRO ARRIBO │ +│ - Automatico: Geocerca detecta unidad en destino │ +│ - Manual: Operador registra en app │ +│ - Sistema: Timestamp + coordenadas │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 2. DESCARGA │ +│ - Operador marca inicio descarga │ +│ - Operador marca fin descarga │ +│ - Sistema: Calcula duracion, compara vs SLA │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 3. CAPTURA POD │ +│ - Operador captura firma digital en pantalla │ +│ - Operador ingresa nombre receptor │ +│ - Operador toma fotos (opcional) │ +│ - Operador escanea documento firmado (opcional) │ +│ - Sistema: Valida datos minimos │ +└─────────────────────────────────────────────────────────────────┘ + │ + ┌─────────┴─────────┐ + │ │ + ▼ ▼ + ┌──────────────────┐ ┌──────────────────┐ + │ POD COMPLETO │ │ POD INCOMPLETO │ + │ │ │ │ + │ Firma OK │ │ Falta firma o │ + │ Receptor OK │ │ receptor │ + └────────┬─────────┘ └────────┬─────────┘ + │ │ + │ ▼ + │ ┌──────────────────┐ + │ │ EXCEPCION │ + │ │ │ + │ │ Motivo + Notas │ + │ │ Enviar a aprobar │ + │ └────────┬─────────┘ + │ │ + ▼ ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 4. CIERRE VIAJE │ +│ - Sistema: Congela costos │ +│ - Sistema: Calcula rentabilidad │ +│ - Sistema: Cambia estado a CERRADO │ +│ - Sistema: Notifica a facturacion │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ LISTO PARA FACTURAR │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Criterios de Exito + +### Funcionales + +- [ ] Operador puede capturar POD completo en <2 minutos +- [ ] Sistema funciona offline y sincroniza al reconectar +- [ ] Excepciones requieren aprobacion de supervisor +- [ ] Cierre calcula rentabilidad automaticamente + +### Tecnicos + +- [ ] Fotos comprimidas a <500KB +- [ ] Firma almacenada como imagen PNG +- [ ] Sincronizacion en <30 segundos con conexion +- [ ] Logs de auditoria completos + +### Negocio + +- [ ] 98% de viajes con POD capturado +- [ ] <5% de POD con excepciones +- [ ] Facturacion dentro de 24h del cierre +- [ ] 100% viajes con rentabilidad calculada + +--- + +## Riesgos y Mitigaciones + +| Riesgo | Probabilidad | Impacto | Mitigacion | +|--------|--------------|---------|------------| +| Operador sin conectividad | Alta | Alto | Modo offline robusto | +| Fotos muy pesadas | Media | Medio | Compresion automatica | +| Firma ilegible | Media | Medio | Validacion de trazos minimos | +| Rechazo de cierre sin POD | Baja | Alto | Flujo de excepciones | + +--- + +## Dependencias + +### Prerequisitos +- MAI-005 (Despacho): Viaje despachado +- MAI-006 (Tracking): Geocercas configuradas +- MAI-011 (Flota): Operador asignado + +### Habilita +- MAI-009 (Facturacion): Requiere POD para facturar +- MAI-010 (Liquidaciones): Requiere cierre para liquidar +- MAE-016 (Carta Porte): Expediente completo + +--- + +## Story Points Estimados + +| Historia | Complejidad | SP | +|----------|-------------|---| +| US-MAI007-001 | Alta | 8 | +| US-MAI007-002 | Media | 5 | +| US-MAI007-003 | Media | 5 | +| US-MAI007-004 | Alta | 8 | +| US-MAI007-005 | Media | 5 | +| **Total** | | **31** | + +--- + +*Epica MAI-007 - ERP Transportistas - Sistema SIMCO v4.0.0* diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-001.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-001.md new file mode 100644 index 0000000..8f8ffe6 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-001.md @@ -0,0 +1,90 @@ +# US-MAI007-001: Capturar firma digital en entrega + +**ID:** US-MAI007-001 +**Modulo:** MAI-007 (POD y Cierre) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** capturar la firma digital del receptor en mi dispositivo movil +**Para** tener evidencia irrefutable de que la mercancia fue entregada + +--- + +## Criterios de Aceptacion + +### CA-001: Captura de firma +**Dado** que estoy en la pantalla de captura POD +**Cuando** el receptor firma con su dedo en el area de firma +**Entonces** el sistema captura la firma como imagen y la muestra en preview + +### CA-002: Validacion de firma +**Dado** que intento guardar el POD sin firma +**Cuando** presiono el boton guardar +**Entonces** el sistema muestra error "Firma requerida" y no permite continuar + +### CA-003: Datos del receptor +**Dado** que capturo la firma +**Cuando** completo los datos del receptor (nombre obligatorio, ID opcional) +**Entonces** el sistema asocia estos datos a la firma capturada + +### CA-004: Limpiar y reintentar +**Dado** que la firma capturada no es satisfactoria +**Cuando** presiono el boton "Limpiar firma" +**Entonces** el area de firma se limpia y puedo capturar nuevamente + +### CA-005: Modo offline +**Dado** que no tengo conexion a internet +**Cuando** capturo una firma +**Entonces** el sistema la almacena localmente y sincroniza cuando haya conexion + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────┐ +│ POD - Entrega #12345 │ +├─────────────────────────────────────────┤ +│ │ +│ Nombre receptor: [________________] │ +│ ID receptor: [________________] │ +│ (opcional) │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ │ │ +│ │ │ │ +│ │ [AREA DE FIRMA] │ │ +│ │ │ │ +│ │ │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ [Limpiar] [Continuar →] │ +│ │ +└─────────────────────────────────────────┘ +``` + +--- + +## Notas Tecnicas + +- La firma se almacena como PNG base64 en SQLite local +- Resolucion minima: 300x150 px +- Validar que haya al menos 50 puntos de trazo +- Coordenadas GPS se capturan automaticamente +- Sincronizacion via endpoint POST /api/v1/pod/:id/firma + +--- + +## Definicion de Done + +- [ ] Codigo implementado y revisado +- [ ] Tests unitarios (cobertura >80%) +- [ ] Tests de integracion con backend +- [ ] Funciona en modo offline +- [ ] Documentacion de API actualizada +- [ ] Demo aprobada por Product Owner diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-002.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-002.md new file mode 100644 index 0000000..6cdad68 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-002.md @@ -0,0 +1,106 @@ +# US-MAI007-002: Registrar tiempos reales de operacion + +**ID:** US-MAI007-002 +**Modulo:** MAI-007 (POD y Cierre) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** registrar los tiempos de arribo, descarga y salida +**Para** que el sistema calcule automaticamente si hubo detention time + +--- + +## Criterios de Aceptacion + +### CA-001: Registro de arribo +**Dado** que llego al destino +**Cuando** presiono "Registrar Arribo" o entro a geocerca +**Entonces** el sistema registra timestamp y coordenadas del arribo + +### CA-002: Registro de inicio descarga +**Dado** que estoy en el destino y comienza la descarga +**Cuando** presiono "Iniciar Descarga" +**Entonces** el sistema registra el timestamp de inicio + +### CA-003: Registro de fin descarga +**Dado** que la descarga ha terminado +**Cuando** presiono "Finalizar Descarga" +**Entonces** el sistema registra el timestamp de fin y calcula duracion + +### CA-004: Calculo de detention +**Dado** que he registrado todos los tiempos +**Cuando** el tiempo de espera (arribo a inicio descarga) excede 2 horas +**Entonces** el sistema marca el evento como "detention" para facturacion + +### CA-005: Validacion de secuencia +**Dado** que intento registrar fin descarga antes de inicio +**Cuando** presiono el boton +**Entonces** el sistema muestra error "Registre inicio de descarga primero" + +--- + +## Flujo de Tiempos + +``` +ARRIBO (10:00) + │ + ├─── Tiempo de espera ───┐ + │ │ + ▼ │ +INICIO DESCARGA (11:30) │ 90 min (OK, < 2h) + │ │ + ├─── Tiempo descarga ────┤ + │ │ + ▼ │ +FIN DESCARGA (12:15) │ 45 min + │ │ + └────────────────────────┘ + Total: 2h 15min +``` + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────┐ +│ Tiempos - Viaje #12345 │ +├─────────────────────────────────────────┤ +│ │ +│ Destino: Bodega Central CDMX │ +│ │ +│ ✓ Arribo: 10:00 hrs │ +│ ✓ Inicio descarga: 11:30 hrs │ +│ ○ Fin descarga: --:-- hrs │ +│ │ +│ Tiempo espera: 1h 30min ✓ │ +│ (Tolerancia SLA: 2h) │ +│ │ +│ [ Finalizar Descarga ] │ +│ │ +└─────────────────────────────────────────┘ +``` + +--- + +## Notas Tecnicas + +- Los tiempos se almacenan en UTC +- La geocerca puede disparar arribo automatico +- Tolerancia SLA viene del contrato del cliente +- Detention time se factura segun reglas configuradas + +--- + +## Definicion de Done + +- [ ] Registro de 4 eventos (arribo, inicio, fin, salida) +- [ ] Calculo automatico de detention +- [ ] Integracion con geocercas +- [ ] Tests unitarios +- [ ] Funciona offline diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-003.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-003.md new file mode 100644 index 0000000..b52eca8 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-003.md @@ -0,0 +1,96 @@ +# US-MAI007-003: Adjuntar fotos de evidencia + +**ID:** US-MAI007-003 +**Modulo:** MAI-007 (POD y Cierre) +**Prioridad:** Alta +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** operador de transporte +**Quiero** adjuntar fotos de la entrega como evidencia +**Para** documentar el estado de la mercancia al momento de entrega + +--- + +## Criterios de Aceptacion + +### CA-001: Captura de foto +**Dado** que estoy en la pantalla de POD +**Cuando** presiono "Tomar foto" +**Entonces** se abre la camara y puedo capturar una imagen + +### CA-002: Seleccion de galeria +**Dado** que ya tome fotos previamente +**Cuando** presiono "Seleccionar de galeria" +**Entonces** puedo elegir fotos existentes del dispositivo + +### CA-003: Limite de fotos +**Dado** que ya tengo 5 fotos adjuntas +**Cuando** intento agregar otra +**Entonces** el sistema muestra "Maximo 5 fotos por POD" + +### CA-004: Compresion automatica +**Dado** que tomo una foto de alta resolucion +**Cuando** la adjunto al POD +**Entonces** el sistema la comprime a max 500KB automaticamente + +### CA-005: Preview y eliminacion +**Dado** que tengo fotos adjuntas +**Cuando** toco una foto en la lista +**Entonces** puedo verla en pantalla completa y eliminarla si es necesario + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────┐ +│ Fotos de Evidencia │ +├─────────────────────────────────────────┤ +│ │ +│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ +│ │ img │ │ img │ │ img │ │ + │ │ +│ │ 1 │ │ 2 │ │ 3 │ │ │ │ +│ └─────┘ └─────┘ └─────┘ └─────┘ │ +│ │ +│ 3 de 5 fotos │ +│ │ +│ [📷 Tomar foto] [🖼 Galeria] │ +│ │ +└─────────────────────────────────────────┘ +``` + +--- + +## Tipos de Evidencia Sugeridos + +| Tipo | Descripcion | +|------|-------------| +| Estado mercancia | Foto de cajas/pallets al entregar | +| Documento firmado | Foto de remision con firma | +| Area descarga | Foto del area de descarga | +| Sello roto | Evidencia si se rompe sello | +| Dano | Documentar cualquier dano visible | + +--- + +## Notas Tecnicas + +- Fotos se almacenan en cache local hasta sincronizar +- Compresion JPEG calidad 70% +- Metadata EXIF preservada (fecha, GPS si disponible) +- Endpoint: POST /api/v1/pod/:id/fotos (multipart) + +--- + +## Definicion de Done + +- [ ] Captura desde camara +- [ ] Seleccion desde galeria +- [ ] Compresion automatica +- [ ] Preview de fotos +- [ ] Eliminacion de fotos +- [ ] Funciona offline diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-004.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-004.md new file mode 100644 index 0000000..62c6920 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-004.md @@ -0,0 +1,119 @@ +# US-MAI007-004: Validar POD antes de cierre + +**ID:** US-MAI007-004 +**Modulo:** MAI-007 (POD y Cierre) +**Prioridad:** Alta +**Story Points:** 8 + +--- + +## Historia de Usuario + +**Como** despachador +**Quiero** que el sistema valide automaticamente que el POD este completo antes de cerrar +**Para** asegurar que tenemos toda la documentacion necesaria para facturar + +--- + +## Criterios de Aceptacion + +### CA-001: Validacion de firma +**Dado** que intento cerrar un viaje +**Cuando** el POD no tiene firma capturada +**Entonces** el sistema bloquea el cierre y muestra "POD sin firma" + +### CA-002: Validacion de receptor +**Dado** que intento cerrar un viaje +**Cuando** el POD no tiene nombre de receptor +**Entonces** el sistema bloquea el cierre y muestra "Receptor no identificado" + +### CA-003: Validacion de tiempos +**Dado** que intento cerrar un viaje +**Cuando** no se han registrado todos los tiempos requeridos +**Entonces** el sistema muestra advertencia pero permite continuar + +### CA-004: Cierre exitoso +**Dado** que el POD cumple todas las validaciones +**Cuando** confirmo el cierre +**Entonces** el sistema: +- Cambia estado del viaje a CERRADO +- Congela costos del viaje +- Calcula rentabilidad preliminar +- Notifica a facturacion + +### CA-005: Resumen de cierre +**Dado** que cierro un viaje exitosamente +**Cuando** se completa el proceso +**Entonces** veo un resumen con: costos, ingresos estimados, margen + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────┐ +│ Cerrar Viaje #12345 │ +├─────────────────────────────────────────┤ +│ │ +│ Validaciones: │ +│ ✓ POD con firma │ +│ ✓ Receptor identificado │ +│ ✓ Tiempos registrados │ +│ ⚠ Sin fotos adjuntas (opcional) │ +│ │ +│ ───────────────────────────────────── │ +│ │ +│ Resumen financiero: │ +│ Ingresos: $15,000.00 │ +│ Costos: $11,200.00 │ +│ - Combustible $5,500.00 │ +│ - Peajes $1,200.00 │ +│ - Viaticos $800.00 │ +│ - Otros $3,700.00 │ +│ ───────────────────────────────────── │ +│ Margen: $3,800.00 (25.3%) │ +│ │ +│ [Cancelar] [Confirmar Cierre ✓] │ +│ │ +└─────────────────────────────────────────┘ +``` + +--- + +## Reglas de Validacion + +| Validacion | Tipo | Bloquea cierre | +|------------|------|----------------| +| Firma presente | Requerido | Si | +| Nombre receptor | Requerido | Si | +| Tiempos completos | Recomendado | No | +| Fotos adjuntas | Opcional | No | +| GPS en geocerca | Recomendado | No | + +--- + +## Estados del Viaje + +``` +EN_TRANSITO → EN_DESTINO → ENTREGADO → CERRADO → FACTURADO +``` + +--- + +## Notas Tecnicas + +- Al cerrar se crea snapshot de costos en `cierres_viaje` +- Calculo de margen: (tarifa_cliente - sum(costos)) / tarifa_cliente +- Notificacion a facturacion via evento/webhook +- El cierre es irreversible sin rol de admin + +--- + +## Definicion de Done + +- [ ] Validaciones automaticas implementadas +- [ ] Calculo de rentabilidad correcto +- [ ] Notificacion a facturacion +- [ ] Snapshot de costos inmutable +- [ ] UI de confirmacion clara +- [ ] Tests de integracion diff --git a/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-005.md b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-005.md new file mode 100644 index 0000000..ff326aa --- /dev/null +++ b/docs/02-definicion-modulos/MAI-007-pod-cierre/historias-usuario/US-MAI007-005.md @@ -0,0 +1,138 @@ +# US-MAI007-005: Cerrar viaje con excepcion justificada + +**ID:** US-MAI007-005 +**Modulo:** MAI-007 (POD y Cierre) +**Prioridad:** Media +**Story Points:** 5 + +--- + +## Historia de Usuario + +**Como** despachador +**Quiero** poder cerrar un viaje sin POD completo con una justificacion +**Para** no bloquear el proceso cuando hay situaciones excepcionales + +--- + +## Criterios de Aceptacion + +### CA-001: Opcion de excepcion +**Dado** que el POD no cumple validaciones +**Cuando** intento cerrar el viaje +**Entonces** el sistema ofrece la opcion "Cerrar con excepcion" + +### CA-002: Motivo obligatorio +**Dado** que selecciono cerrar con excepcion +**Cuando** no selecciono un motivo del catalogo +**Entonces** el sistema no permite continuar + +### CA-003: Justificacion detallada +**Dado** que selecciono un motivo de excepcion +**Cuando** escribo la justificacion detallada (min 20 caracteres) +**Entonces** puedo proceder con la solicitud de excepcion + +### CA-004: Aprobacion pendiente +**Dado** que solicito cierre con excepcion +**Cuando** completo el formulario +**Entonces** el viaje queda en estado "EXCEPCION_PENDIENTE" hasta aprobacion + +### CA-005: Notificacion a supervisor +**Dado** que hay una excepcion pendiente +**Cuando** se crea la solicitud +**Entonces** el supervisor recibe notificacion para aprobar/rechazar + +--- + +## Catalogo de Motivos + +| Codigo | Motivo | Descripcion | +|--------|--------|-------------| +| EXC-001 | Rechazo en destino | Cliente rechazo la mercancia | +| EXC-002 | Entrega parcial | Solo se entrego parte de la carga | +| EXC-003 | Falla dispositivo | No se pudo capturar firma/fotos | +| EXC-004 | Emergencia | Accidente, robo, desastre natural | +| EXC-005 | Cambio destino | Cliente solicito entregar en otro lugar | +| EXC-006 | Otro | Especificar en justificacion | + +--- + +## Mockup / UI + +``` +┌─────────────────────────────────────────┐ +│ Cierre con Excepcion - Viaje #12345 │ +├─────────────────────────────────────────┤ +│ │ +│ ⚠ El POD no cumple validaciones: │ +│ ✗ Sin firma capturada │ +│ │ +│ ───────────────────────────────────── │ +│ │ +│ Motivo de excepcion: * │ +│ ┌─────────────────────────────────┐ │ +│ │ Rechazo en destino ▼ │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ Justificacion detallada: * │ +│ ┌─────────────────────────────────┐ │ +│ │ El cliente rechazo la carga │ │ +│ │ por dano visible en 3 cajas. │ │ +│ │ Se levanto acta con fotos. │ │ +│ │ Contacto: Juan Perez, almacen │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ Evidencia adicional: │ +│ [+ Adjuntar foto/documento] │ +│ │ +│ ───────────────────────────────────── │ +│ ℹ Esta solicitud sera enviada a │ +│ supervisor para aprobacion. │ +│ │ +│ [Cancelar] [Enviar Solicitud] │ +│ │ +└─────────────────────────────────────────┘ +``` + +--- + +## Flujo de Aprobacion + +``` +SOLICITUD CREADA + │ + ▼ +┌────────────────┐ +│ SUPERVISOR │ +│ revisa │ +└───────┬────────┘ + │ + ┌────┴────┐ + │ │ + ▼ ▼ +APROBADA RECHAZADA + │ │ + ▼ ▼ +CERRADO PENDIENTE + (regresar a operador) +``` + +--- + +## Notas Tecnicas + +- Excepciones se registran en tabla `excepciones_pod` +- Notificacion via push notification y email +- Timeout de aprobacion: 24 horas (escalamiento automatico) +- Auditoria completa de quien aprobo/rechazo y cuando + +--- + +## Definicion de Done + +- [ ] Formulario de excepcion implementado +- [ ] Catalogo de motivos configurable +- [ ] Flujo de aprobacion funcional +- [ ] Notificaciones a supervisor +- [ ] Auditoria completa +- [ ] Tests de flujo completo