erp-transportistas-v2/docs/03-requerimientos/REQ-GIRO-TRANSPORTISTA.md

# REQ-GIRO-TRANSPORTISTA v1.0
**Documento de requerimientos por giro (solo procesos especiales) - Empresa Transportista / Logistica de Carga**
**Fecha:** 2026-01-25 (America/Mexico_City)
**Autor:** Adrian / Equipo ERP SaaS
**Alcance:** Adaptaciones y procesos especificos del giro *Autotransporte de carga / 3PL* sobre un ERP generico ya definido.

---

## 0) Proposito y alcance

Este documento define **exclusivamente** los requerimientos funcionales y de datos necesarios para operar una **empresa transportista de carga** (propia o como 3PL) y las **adaptaciones** que un ERP convencional requiere para soportar el giro, incluyendo:

- **Gestion operativa del transporte** (orden -> planeacion -> despacho -> ejecucion -> POD -> facturacion).
- **Gestion de flota y conductores** (asignacion, disponibilidad, cumplimiento, mantenimiento, combustible).
- **Tracking y visibilidad** (eventos, GPS, portal cliente, alertas, incidencias).
- **Costeo por viaje y rentabilidad** (por ruta/cliente/unidad, peajes, combustible, viaticos, mantenimiento).
- **Cumplimiento documental y fiscal** propio del transporte en Mexico (p. ej. Carta Porte) y control de evidencias.
- **Gestion de terceros** (subcontratacion de transportistas, "carriers" aliados, maniobristas).

> Nota: Se asume que el ERP base ya cubre contabilidad, compras, ventas genericas, inventarios genericos, CRM generico, RRHH generico, etc. Aqui solo se define lo que **cambia** o **se anade** por el giro.

---

## 1) Contexto operativo del giro (resumen)

En el sector **Logistica y Transporte** es comun que existan procesos fragmentados (Excel/WhatsApp/llamadas) para rutas, entregas, flota, costos y atencion al cliente. La adopcion de un ERP/CRM aporta control en tiempo real de almacenes/rutas/entregas, seguimiento de flotas y control de costos (combustible, mantenimiento) y mejor coordinacion con clientes y operaciones.

---

## 2) Perfiles y roles (giro)

1. **Ventas Logistica / Ejecutivo de Cuenta**: cotiza, negocia tarifas, define SLA, captura oportunidades.
2. **Atencion a Cliente / Customer Success**: seguimiento de envios, incidencias, reclamaciones.
3. **Planner / Trafico (Planeacion)**: consolida ordenes, planifica cargas, ventanas, rutas, recursos.
4. **Despachador (Dispatch)**: asigna unidades/operadores, libera salida, gestiona cambios en ruta.
5. **Operador / Conductor**: ejecuta viaje, checklists, eventos, evidencias, POD.
6. **Jefe de Flota**: disponibilidad de unidades, seguros, permisos, cumplimiento documental.
7. **Mantenimiento**: preventivo/correctivo, bitacora de talleres, refacciones, paros.
8. **Control de Combustible**: vales, tarjetas, consumo esperado vs real, robos/mermas.
9. **Facturacion & Cobranza**: CFDI, cargos extra (demoras, reexpedicion), conciliaciones.
10. **Carrier Manager (Terceros)**: asigna a subcontratados, valida costos, documentos y desempeno.

---

## 3) Objetos de negocio del giro (modelo conceptual minimo)

- **Cliente (shipper/consignee)** + contactos + ubicaciones (origen/destino) + ventanas de entrega.
- **Tarifa/Contrato**: por ruta (lane), por km, por tonelada, por viaje, por tipo de unidad, por zona.
- **Orden de Transporte (OT)**: solicitud del cliente, con carga/mercancia, origen/destino, ventanas, restricciones.
- **Embarque/Shipment**: agrupacion logica de OT(s) para una misma ejecucion.
- **Viaje/Trip**: ejecucion operativa (unidad + operador + remolque(s) + ruta + eventos).
- **Unidad tractora / Remolque / Caja**: activos, capacidades, documentacion, estado mecanico.
- **Operador**: licencias, vigencias, disponibilidad, HOS/bitacora, skills (doble articulado, hazmat, etc.).
- **Eventos de tracking**: salida, arribo, carga, descarga, desvio, parada, incidencia, entrega.
- **POD (Proof of Delivery)**: evidencia de entrega (firma, foto, sello, documento digital).
- **Costos de viaje**: combustible, peajes, viaticos, maniobras, multas, mantenimiento imputable, terceros.
- **Documentos regulatorios/fiscales**: CFDI con complemento Carta Porte, permisos, polizas, inspecciones.
- **Incidencia/Reclamacion**: dano, robo, retraso, rechazo, faltante, devolucion.

---

## 4) Procesos del giro y requerimientos funcionales

### 4.1 Gestion de tarifas, contratos y SLA (Logistica comercial)

**Objetivo:** cotizar y operar con reglas claras por cliente/ruta/servicio.

**Requerimientos:**
- **RF-4.1.1 Tarifario por lane y servicio**: definir tarifas por ruta (origen/destino/zona), tipo de unidad, modalidad (FTL/LTL), prioridad (express), y vigencia.
- **RF-4.1.2 Matriz de recargos (surcharges)**: combustible (fuel surcharge), demoras (detention), almacenaje, reexpedicion, reentrega, maniobras, escoltas, seguro adicional.
- **RF-4.1.3 SLA por cliente**: tiempos comprometidos, ventanas, penalizaciones, tolerancias, reglas de notificacion.
- **RF-4.1.4 Cotizacion rapida**: generar cotizacion desde CRM/ventas con calculo automatico (distancia/kms si se integra a mapas).
- **RF-4.1.5 Control de aprobaciones**: flujos de aprobacion para descuentos, tarifas especiales, recargos excepcionales.

**Criterios de aceptacion:**
- El sistema calcula automaticamente el precio con desglose (base + recargos), y guarda el "snapshot" aplicado a la OT.

---

### 4.2 Captura de Orden de Transporte (OT) con restricciones logisticas

**Objetivo:** registrar demandas con toda la informacion operable para planeacion y cumplimiento.

**Requerimientos:**
- **RF-4.2.1 Datos obligatorios OT**: cliente, origen/destino (georreferenciables), ventanas (pickup/delivery), tipo de carga, peso/volumen, unidades/pallets, temperatura (si aplica), requisitos de equipo (caja seca/refrigerada/plataforma), referencias (PO, ASN).
- **RF-4.2.2 Restricciones**: horarios de acceso, citas (appointment), requisitos de seguridad (sellos, GPS, escolta), zonas de riesgo, restricciones de circulacion.
- **RF-4.2.3 Multi-paradas**: soportar rutas con multiples puntos (pickup/drop) y secuencia.
- **RF-4.2.4 LTL vs FTL**: permitir consolidacion (LTL) o viaje dedicado (FTL) y reglas de capacidad.
- **RF-4.2.5 Documentacion adjunta**: ordenes, manifiestos, instrucciones del cliente, fotos.
- **RF-4.2.6 Portal / API de clientes**: creacion de OT por portal o API (opcional por fase).

---

### 4.3 Planeacion (TMS-like): consolidacion, capacidad y asignacion preliminar

**Objetivo:** convertir OTs en embarques y viajes factibles (capacidad/ventanas).

**Requerimientos:**
- **RF-4.3.1 Tablero de planeacion (Gantt / Kanban de trafico)**: OTs por fecha/ventana, estado, prioridad, region.
- **RF-4.3.2 Consolidacion automatica sugerida**: agrupar OTs compatibles por zona, ventana, capacidad, tipo de equipo.
- **RF-4.3.3 Calculo de capacidad**: reglas por unidad (toneladas, m3, pallets, altura, temperatura, peligrosidad).
- **RF-4.3.4 Reservas de recursos**: pre-asignar unidad/operador/remolque con bloqueo de disponibilidad.
- **RF-4.3.5 Reglas de compatibilidad**:
  - Operador con certificacion requerida.
  - Unidad apta (revision vigente, capacidades, permisos).
  - Restricciones de cliente (listas negras, requisitos de GPS).
- **RF-4.3.6 Simulacion de ruta y ETA**: estimacion de tiempos y ETAs (si se integra con mapas/telematica).

---

### 4.4 Despacho: liberacion de viaje, checklists y documentacion operativa

**Objetivo:** asegurar que el viaje "sale" completo (documentos, seguridad, checklist, asignacion final).

**Requerimientos:**
- **RF-4.4.1 Orden de Viaje (OV)**: generar OV desde embarque con: unidad, remolques, operador, ruta, paradas, instrucciones.
- **RF-4.4.2 Checklists pre-viaje**: inspeccion (llantas, frenos, luces, acoplamiento, sellos), checklist por tipo de unidad y por cliente.
- **RF-4.4.3 Control de sellos**: asignacion y registro de sellos (numero, fotos), rupturas y reemplazos con motivo.
- **RF-4.4.4 Evidencias de carga**: fotos, firma de almacen, peso/bascula.
- **RF-4.4.5 Kit documental**: compilar documentos requeridos por el viaje (OT/OV, permisos, poliza, Carta Porte, etc.) en formato digital para el operador.
- **RF-4.4.6 "Gate out" / salida oficial**: evento de salida con timestamp, usuario responsable y geolocalizacion.

---

### 4.5 Ejecucion y tracking (control de viaje en tiempo real)

**Objetivo:** visibilidad operativa para operaciones y cliente.

**Requerimientos:**
- **RF-4.5.1 Integracion GPS/Telematica**: ingestion de posiciones y eventos (encendido, velocidad, paradas) por proveedor.
- **RF-4.5.2 App movil operador** (o web movil):
  - Registro de eventos (arribo, inicio/fin de carga/descarga, incidentes).
  - Adjuntar evidencias (fotos, firma, documentos).
  - Modo offline con sincronizacion.
- **RF-4.5.3 ETA dinamico**: recalcular ETA con base en tracking/tiempo real (si hay datos).
- **RF-4.5.4 Geocercas (geofencing)**: eventos automaticos por entrada/salida de origen/destino.
- **RF-4.5.5 Alertas**:
  - Retraso vs ventana SLA.
  - Desvio de ruta.
  - Parada no programada.
  - Exceso de tiempo en carga/descarga (detention).
- **RF-4.5.6 Comunicacion omnicanal**: notificaciones a cliente (email/WhatsApp/SMS) por eventos clave (configurable).

---

### 4.6 Incidencias, excepciones y reclamaciones (Claims)

**Objetivo:** gestionar eventos anomalos con trazabilidad y responsabilidad.

**Requerimientos:**
- **RF-4.6.1 Tipos de incidencia**: retraso, rechazo en entrega, dano, robo, faltante, devolucion, accidente, multa.
- **RF-4.6.2 Flujo de atencion**: apertura -> asignacion -> investigacion -> resolucion -> cierre.
- **RF-4.6.3 Evidencias y bitacora**: adjuntar fotos, reportes, documentos y timeline.
- **RF-4.6.4 Impacto economico**: registrar costos (deducibles, penalizaciones, reexpedicion) y asociarlos a viaje/cliente.
- **RF-4.6.5 SLA de incidencias**: tiempos maximos de respuesta por severidad.
- **RF-4.6.6 Integracion a facturacion**: cargos/abonos por penalizaciones o notas de credito.

---

### 4.7 POD y cierre operativo del viaje

**Objetivo:** cerrar viajes con prueba de entrega y datos listos para facturar y medir performance.

**Requerimientos:**
- **RF-4.7.1 Captura POD**: firma digital, nombre/ID receptor, sello, fotos, documento escaneado.
- **RF-4.7.2 Validaciones**: no permitir "cierre" sin POD o sin justificacion aprobada.
- **RF-4.7.3 Tiempos reales**: registrar llegada, inicio/fin descarga, salida, para metricas de detention.
- **RF-4.7.4 Cierre contable operativo**: congelar costos del viaje (combustible, peajes, viaticos) y calcular rentabilidad preliminar.

---

### 4.8 Facturacion especializada del transporte (rate -> invoice)

**Objetivo:** facturar con reglas del giro y ligando evidencias/documentos.

**Requerimientos:**
- **RF-4.8.1 Factura por viaje/embarque/OT**: configurable.
- **RF-4.8.2 Calculo automatico de recargos**:
  - Demoras por tiempos reales vs tolerancia.
  - Fuel surcharge por indice/porcentaje.
  - Reentregas y cambios de destino.
- **RF-4.8.3 Integracion con POD**: anexar POD y evidencias a factura/expediente.
- **RF-4.8.4 Conciliacion**: comparacion cotizacion vs factura emitida vs cobrado.
- **RF-4.8.5 Estados de cuenta por cliente**: viajes, cargos, abonos, notas, aging.

---

### 4.9 Liquidacion a operadores y control de "settlements" (si aplica)

**Objetivo:** pagar a operadores (propios o terceros) con reglas por viaje, viaticos y deducciones.

**Requerimientos:**
- **RF-4.9.1 Esquemas de pago**: por km, por viaje, por porcentaje, por bono SLA.
- **RF-4.9.2 Viaticos**: anticipos y comprobacion; relacion con viaje y control de sobrantes.
- **RF-4.9.3 Deducciones**: multas, danos, faltantes (segun politica), con aprobacion.
- **RF-4.9.4 Corte y autorizacion**: cierre semanal/quincenal, exportacion a nomina/contabilidad.

---

### 4.10 Combustible, peajes y gastos de viaje (cost control)

**Objetivo:** control fino de costos variables y deteccion de fugas.

**Requerimientos:**
- **RF-4.10.1 Planeado vs real**: consumo esperado por unidad/ruta vs litros reales.
- **RF-4.10.2 Captura de cargas de combustible**: por tarjeta/vale, estacion, litros, costo, odometro, evidencia.
- **RF-4.10.3 Peajes**: integracion con TAG o captura manual; prorrateo por viaje.
- **RF-4.10.4 Gastos varios**: casetas, maniobras, montacargas, "mordidas" NO permitidas (bloqueo por politica), estacionamientos.
- **RF-4.10.5 Alertas antifraude**: desviacion de consumo, cargas fuera de ruta, cargas duplicadas.

---

### 4.11 Mantenimiento y disponibilidad de flota (Fleet Maintenance)

**Objetivo:** asegurar disponibilidad y cumplimiento mecanico/seguridad.

**Requerimientos:**
- **RF-4.11.1 Plan preventivo**: por km/horas/fecha; generacion automatica de ordenes de mantenimiento.
- **RF-4.11.2 Correctivo**: tickets por falla reportada, priorizacion, tiempos de paro.
- **RF-4.11.3 Inventario de refacciones (solo lo necesario al giro)**: minimo para taller (catalogo, stock, consumo en ordenes).
- **RF-4.11.4 Historial por activo**: costos, fallas recurrentes, MTBF/MTTR.
- **RF-4.11.5 Disponibilidad**: estado de unidad (Disponible / En viaje / En taller / Bloqueada) y capacidad de "bloqueo" por documentacion vencida.

---

### 4.12 Gestion de terceros (subcontratacion / carriers)

**Objetivo:** escalar capacidad sin perder control documental ni de calidad.

**Requerimientos:**
- **RF-4.12.1 Registro de carrier**: datos fiscales, documentos, polizas, permisos, evaluacion.
- **RF-4.12.2 Asignacion a carrier**: licitacion interna (rate shopping), adjudicacion y emision de OV a tercero.
- **RF-4.12.3 Control de documentos del tercero**: vigencias y bloqueo por vencimiento.
- **RF-4.12.4 Recepcion de POD del tercero**: portal o carga de evidencias.
- **RF-4.12.5 Costo vs ingreso**: margen por subcontratacion; reportes por carrier.
- **RF-4.12.6 Scorecard**: puntualidad, incidencias, calidad de POD, reclamos.

---

### 4.13 Portal de cliente (visibilidad y autoservicio) - si se incluye

**Objetivo:** reducir friccion operativa y elevar percepcion de valor.

**Requerimientos:**
- **RF-4.13.1 Tracking**: mapa/estado, eventos, ETA.
- **RF-4.13.2 Documentos**: POD, factura, Carta Porte (si aplica mostrar).
- **RF-4.13.3 Creacion de OT**: plantillas, cargas recurrentes, multi-paradas.
- **RF-4.13.4 Reclamaciones**: apertura y seguimiento de incidencias.

---

## 5) Cumplimiento documental/fiscal (Mexico) - requerimientos del giro

### 5.1 CFDI con Complemento Carta Porte (v3.1)

**Necesidad del giro:** El sistema debe soportar la emision y resguardo del **CFDI con complemento Carta Porte**, incluyendo llenado conforme a instructivos del SAT y escenarios tipicos del transporte.

**Requerimientos:**
- **RF-5.1.1 Soportar Carta Porte 3.1**: parametrizar version y validar catalogos/estructura.
- **RF-5.1.2 Escenarios de emision**:
  - **CFDI de Ingreso** con Carta Porte cuando se presta el servicio de transporte.
  - **CFDI de Traslado** con Carta Porte cuando corresponda al traslado sin cobrar servicio (segun operacion del contribuyente).
- **RF-5.1.3 Expediente fiscal por viaje**: relacionar el UUID del CFDI (y XML/PDF) con OT/OV/Viaje.
- **RF-5.1.4 Validaciones previas**: no permitir liberar viaje si faltan datos minimos para Carta Porte (ubicaciones, mercancia, pesos, operador/unidad, etc.) cuando aplique.
- **RF-5.1.5 Reemision/correccion controlada**: bitacora de cancelaciones y sustituciones, y su impacto en facturacion.
- **RF-5.1.6 Integracion con PAC**: timbrado, cancelacion, consulta de estatus.
- **RF-5.1.7 Evidencia para inspeccion**: disponibilidad offline del PDF/XML/QR en app movil.

**Referencias normativas clave (para parametrizacion):**
- El SAT indica uso de **Carta Porte version 3.1** a partir del **17-jul-2024** y publica instructivos y preguntas frecuentes.

---

### 5.2 Bitacora de Horas de Servicio (HOS) - NOM-087

**Necesidad del giro:** Controlar cumplimiento de tiempos de conduccion/pausas y evidencias.

**Requerimientos:**
- **RF-5.2.1 Registro HOS**: captura/ingesta de horas de conduccion, pausas, descanso; manual o por telematica.
- **RF-5.2.2 Bitacora en formato imprimible/electronico** por operador y viaje.
- **RF-5.2.3 Alertas de incumplimiento**: antes de exceder limites; bloqueo de asignacion si operador no cumple descansos.
- **RF-5.2.4 Evidencias**: trazabilidad de ediciones y responsable (auditoria).

**Referencia:** NOM-087 y lineamientos de bitacora (incluye posibilidad de formatos electronicos).

---

### 5.3 Condiciones fisico-mecanicas y seguridad - NOM-068

**Necesidad del giro:** mantener evidencia de inspecciones/condiciones para operar en vias federales.

**Requerimientos:**
- **RF-5.3.1 Checklist mecanico por norma**: checklist parametrizable por tipo de unidad y operacion.
- **RF-5.3.2 Evidencias**: fotos/firmas del responsable, fechas, resultados.
- **RF-5.3.3 Bloqueo por incumplimiento**: unidad pasa a "No disponible / Bloqueada" si falla inspeccion o documentacion.

**Referencia:** NOM-068 (DOF).

---

## 6) Reportes y KPIs especificos del giro

1. **On-time pickup / On-time delivery** por cliente/ruta/unidad/operador.
2. **OTIF** (On Time In Full) si aplica a entregas completas.
3. **Detention time** (carga/descarga) y costos asociados.
4. **Costo por km / costo por viaje** y margen por cliente/lane.
5. **Consumo combustible** (km/l) esperado vs real; ranking de anomalias.
6. **Disponibilidad de flota**: % tiempo en viaje vs taller vs bloqueada.
7. **Incidencias por 100 viajes** y costo total de reclamos.
8. **Scorecard de carriers** (si subcontrata).
9. **Cumplimiento documental**: vencimientos proximos (licencias, polizas, verificaciones).
10. **Productividad de trafico**: viajes planeados por dia, % reprogramaciones, causa raiz.

---

## 7) Requerimientos de integracion (giro)

- **GPS/Telematica**: posiciones y eventos.
- **Mapas/Distancias**: calculo de kms y ETA.
- **PAC (SAT)**: timbrado CFDI + Carta Porte y cancelaciones.
- **WhatsApp/SMS/Email**: notificaciones automaticas por eventos.
- **Tarjetas de combustible / TAG peajes**: conciliacion automatica.
- **EDI / API con clientes** (fase avanzada): recepcion de OTs (ASN/PO), actualizacion de estatus.

---

## 8) Requerimientos no funcionales criticos (orientados al giro)

1. **Movilidad + Offline**: operacion en carretera con conectividad intermitente.
2. **Trazabilidad/auditoria**: cambios en OT/OV/Viaje/Documentos con usuario/fecha/motivo.
3. **Alta disponibilidad**: operaciones 24/7; tolerancia a fallos.
4. **Seguridad**: RBAC por rol, segregacion por cliente (multi-tenant), cifrado en transito y en reposo.
5. **Evidencias**: almacenamiento seguro de fotos/documentos con retencion configurable.
6. **Performance**: tablero de trafico y tracking con miles de eventos/dia sin degradacion.

---

## Requerimientos de Modo Offline

El siguiente conjunto de requerimientos define la capacidad de operacion sin conexion a internet de la app movil para conductores, permitiendo continuidad operativa en zonas sin cobertura de red.

### RF-OFFLINE-001: Operacion de la app sin conexion

**Descripcion:** La aplicacion movil del conductor debe funcionar completamente sin conexion a internet, permitiendo registrar todos los eventos operativos del viaje.

**Criterios de aceptacion:**
- La app detecta automaticamente la perdida de conexion en menos de 5 segundos
- El conductor puede registrar eventos de viaje (arribo, salida, carga, descarga) sin conexion
- El conductor puede completar checklists de inspeccion pre-viaje sin conexion
- El conductor puede consultar informacion del viaje previamente descargada
- Los datos capturados se almacenan localmente con UUID unico, timestamp y GPS
- El sistema soporta operacion offline continua por hasta 7 dias

**Datos almacenados localmente:**

| Tipo de Dato | Descripcion | Limite |
|--------------|-------------|--------|
| Viaje activo | Detalles, paradas, instrucciones | 1 viaje |
| Checklist | Respuestas y evidencias | 500 items |
| Eventos de tracking | Cola de envio | 1000 items |
| Posiciones GPS | Historial de ubicaciones | 5000 items |
| Fotos evidencia | Con metadata GPS | 50 fotos/viaje |
| Firmas POD | Proof of Delivery | 20 firmas |

**Referencia tecnica:** ARQUITECTURA-OFFLINE.md

---

### RF-OFFLINE-002: Sincronizacion automatica al reconectar

**Descripcion:** El sistema debe enviar automaticamente todos los datos pendientes cuando se recupera la conexion a internet, sin intervencion del usuario.

**Criterios de aceptacion:**
- La sincronizacion inicia automaticamente al detectar conexion
- Los datos se envian priorizados: Firmas POD > Eventos > Checklist > Posiciones GPS > Fotos
- El sistema implementa retry automatico con exponential backoff (1s a 60s)
- Si un item falla despues de 8 intentos, se mueve a dead letter queue
- La sincronizacion pull obtiene cambios del servidor (nuevas instrucciones, cambios de viaje)
- El sistema resuelve conflictos automaticamente segun estrategias predefinidas:
  - Estados del viaje: Server wins
  - Eventos de tracking: Append-only (merge)
  - Fotos y firmas: Client wins
- Background sync funciona cuando la app esta en segundo plano

**Endpoints requeridos:**

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/sync/events | Batch de eventos |
| POST | /api/sync/positions | Batch de posiciones GPS |
| POST | /api/sync/photos | Upload de fotos |
| POST | /api/sync/signatures | Upload de firmas POD |
| GET | /api/sync/pull | Delta sync desde timestamp |

**Referencia tecnica:** SINCRONIZACION-OFFLINE.md

---

### RF-OFFLINE-003: Captura de fotos con metadata GPS

**Descripcion:** El conductor debe poder tomar fotos de evidencia que incluyan automaticamente ubicacion GPS y timestamp verificables.

**Criterios de aceptacion:**
- Captura de foto funciona sin conexion a internet
- Cada foto captura automaticamente: latitud, longitud, precision GPS, altitud, timestamp, timezone
- La metadata es inmutable y no puede ser modificada posteriormente
- Las fotos se comprimen automaticamente (max 1920x1080, 80% calidad, <500KB)
- El conductor debe categorizar cada foto: Carga, Descarga, Sello, Dano, Incidencia, Documentos, Otro
- El conductor puede agregar notas opcionales (max 500 caracteres)
- Limite de 50 fotos por viaje
- Si GPS no disponible, permite captura pero marca como "SIN_GPS"

**Configuracion de compresion:**

| Parametro | Valor |
|-----------|-------|
| Resolucion maxima | 1920 x 1080 |
| Calidad JPEG | 80% |
| Tamano maximo | 500 KB |
| Formato | JPEG |

---

### RF-OFFLINE-004: Captura de firma digital POD offline

**Descripcion:** El conductor debe poder capturar la firma del receptor para el Proof of Delivery (POD) sin necesidad de conexion a internet.

**Criterios de aceptacion:**
- Canvas de firma funciona sin conexion
- Captura automatica de metadata: timestamp, timezone, GPS, operador, viaje
- Datos obligatorios del receptor: nombre (min 3 caracteres)
- Datos opcionales: ID/credencial, cargo
- Opcion de borrar y re-firmar ilimitada
- Firma se almacena en formato SVG Path (10-50 KB) o PNG
- Metadata de la firma es inmutable
- Prioridad CRITICA en sincronizacion (se envia antes que eventos y fotos)
- El sistema intenta hasta 10 veces antes de marcar como fallido
- Opcion de "Entrega sin firma" con motivo obligatorio y foto de evidencia

**Motivos para entrega sin firma:**
- Receptor ausente
- Rechazo de mercancia
- Entrega parcial
- Otro (especificar)

---

### RF-OFFLINE-005: Indicadores de estado de sincronizacion

**Descripcion:** El usuario debe poder visualizar en todo momento el estado de la conexion y los datos pendientes de sincronizar.

**Criterios de aceptacion:**
- Indicador de conexion visible en header de todas las pantallas:
  - Verde: Online y sincronizado
  - Amarillo: Sincronizando (con animacion)
  - Rojo: Offline
  - Naranja: Online pero con errores de sync
- Badge numerico junto al indicador mostrando cantidad de items pendientes
- Panel de estado detallado accesible al tocar el indicador:
  - Estado de conexion actual
  - Tiempo offline (si aplica)
  - Ultima sincronizacion exitosa (fecha y hora)
  - Desglose de pendientes por tipo (eventos, posiciones, fotos, firmas)
  - Tamano total de datos pendientes
- Boton "Sincronizar ahora" para forzar sincronizacion
- Seccion de errores con opcion de reintentar

**Formato de ultima sincronizacion:**
- "Hace X minutos" si < 1 hora
- "Hoy a las HH:MM" si es hoy
- "Ayer a las HH:MM" si fue ayer
- "DD/MM/YYYY HH:MM" si es anterior

---

### Historias de Usuario Relacionadas

| ID | Titulo | Story Points | Prioridad |
|----|--------|--------------|-----------|
| US-MAI006-016 | Operar sin conexion | 8 | ALTA |
| US-MAI006-017 | Sincronizar al reconectar | 5 | ALTA |
| US-MAI006-018 | Ver estado de sincronizacion | 3 | MEDIA |
| US-MAI006-019 | Capturar firma POD offline | 5 | ALTA |
| US-MAI006-020 | Tomar fotos con evidencia GPS offline | 5 | MEDIA |
| **Total** | | **26** | |

---

### Stack Tecnologico para Modo Offline

| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| Storage Local | WatermelonDB | Base de datos offline-first |
| Blobs | IndexedDB (Dexie.js) | Almacenamiento de fotos/firmas |
| Intercepcion HTTP | Service Workers | Cache y offline fallback |
| Sincronizacion | Background Sync API | Push de datos en background |
| Deteccion de Red | Network Information API | Estado de conectividad |
| Queue | Workbox | Gestion de cola de sync |

---

### Documentacion de Referencia

- `docs/10-arquitectura/ARQUITECTURA-OFFLINE.md` - Arquitectura completa del modo offline
- `docs/10-arquitectura/SINCRONIZACION-OFFLINE.md` - Detalles de sincronizacion e implementacion
- `docs/02-definicion-modulos/MAI-006-tracking/historias-usuario/` - User stories detalladas

---

## 9) Fases recomendadas (MVP -> Escala)

**Fase 1 (MVP Operativo - "Despacho + Tracking + POD + Facturacion basica")**
- OT/Embarque/Viaje, asignacion, eventos, POD, portal basico, recargos principales, Carta Porte (si aplica).

**Fase 2 (Control de costos + flota)**
- Combustible/peajes, mantenimiento, disponibilidad, liquidacion operadores, scorecards.

**Fase 3 (Optimizacion y automatizacion avanzada)**
- Optimizacion de rutas, EDI, prediccion de ETA, analitica avanzada, auditoria antifraude.

---

## 10) Checklist de validacion (UAT) por proceso

1. Crear tarifa + cotizacion + convertir a OT.
2. OT con multi-paradas + restricciones -> planeacion -> pre-asignacion.
3. Despacho: checklist + sellos + evidencias -> salida.
4. Tracking: geocercas + alertas de retraso + comunicacion a cliente.
5. Incidencia: apertura -> evidencia -> resolucion -> nota de credito.
6. POD: firma+foto -> cierre -> facturacion con recargos.
7. Carta Porte: datos completos -> timbrado -> expediente por viaje -> disponibilidad movil.
8. Combustible: carga real vs esperado -> alerta anomalia.
9. Mantenimiento: preventivo por km -> bloqueo de unidad si vencido.

---

## 11) Anexos (plantillas sugeridas)

### A) Campos minimos OT (por giro)
- Cliente / Contrato / Servicio
- Origen/Destino (con geo)
- Ventanas pickup/delivery + citas
- Tipo de carga, peso, volumen, pallets
- Requisitos de equipo
- Referencias (PO/ASN)
- Seguridad: sellos, GPS, escolta
- Reglas de facturacion: por viaje/por OT, recargos aplicables

### B) Estados del viaje
**Borrador -> Planeado -> Despachado -> En transito -> En destino -> Entregado (POD) -> Cerrado -> Facturado -> Cobrado**

---

*Documento REQ-GIRO-TRANSPORTISTA v1.0 - Sistema SIMCO v4.0.0*