Documentación / Logistics Module Documentation

Logistics Module Documentation

Documentación del Módulo de Logística

Versión: 1.0 Fecha: 2026-01-18

1. Resumen Ejecutivo

El módulo de Logística es el componente central para la gestión de operaciones de transporte y distribución de mercancías. Su propósito es automatizar y controlar todo el ciclo de vida del servicio logístico, desde la cotización inicial hasta la entrega final, garantizando la trazabilidad, eficiencia operativa y cumplimiento normativo (GRE-SUNAT).

Valor para el Negocio:

  • Eficiencia Operativa: Automatización del flujo de solicitudes de servicio, asignación de despachos y seguimiento en tiempo real.
  • Trazabilidad Completa: Tracking de envíos con números únicos, historial de estados y alertas de entrega.
  • Cumplimiento Normativo: Generación automática de Guías de Remisión Electrónica (GRE) para SUNAT.
  • Gestión de Flota: Control de vehículos propios y de terceros, conductores, mantenimiento y documentación.
  • Tarifario Flexible: Tablas de tarifas personalizadas por cliente, zona y tipo de servicio.
  • Control de Proveedores: Gestión integral de proveedores de transporte con calificación y monitoreo.

2. Arquitectura del Módulo

2.1. Componentes Principales

graph TB subgraph "Gestión Comercial" QT[Quote] QL[QuoteLine] LC[LogisticsContract] CT[ContractTariff] end subgraph "Operaciones" SR[ServiceRequest] DA[DispatchAssignment] LM[LogisticsManifest] DSL[DispatchStatusLog] DAL[DeliveryAlert] end subgraph "Flota y Recursos" FV[FleetVehicle] FD[FleetDriver] FME[FleetMaintenanceEvent] CD[ComplianceDocument] end subgraph "Proveedores" TP[TransportProvider] TPC[TransportProviderContact] TPS[TransportProviderService] end subgraph "Tarifario y Zonas" TT[TariffTable] TR[TariffRow] LZ[LogisticsZone] LZB[LogisticsZoneBoundary] end subgraph "Catálogos" LS[LogisticsService] LSM[LogisticsServiceMode] LI[LogisticsIncident] GRE[GreShipment] PFQ[PrefacturingQueue] end QT --> QL QT --> SR LC --> CT LC --> SR SR --> DA DA --> DSL DA --> DAL DA --> GRE LM --> DA FV --> DA FD --> DA TP --> FV TP --> FD TT --> TR LZ --> SR LS --> SR

3. Flujos del Proceso

3.1. Flujo Completo del Servicio Logístico

graph TD A[Cliente Solicita Cotización] -->|Crear| B(Cotización - Borrador) B --> C{Aprobación Cliente} C -->|Aprobada| D[Crear Contrato o Solicitud] C -->|Rechazada| E[Cotización Rechazada] D --> F[Solicitud de Servicio - Pendiente] F -->|Confirmar| G[Solicitud Confirmada] G -->|Aprobar| H[Solicitud Aprobada] H -->|Asignar Recursos| I[Asignación de Despacho] I --> J{Tipo de Recurso} J -->|Flota Propia| K[Vehículo + Conductor Propio] J -->|Proveedor| L[Proveedor + Vehículo + Conductor] K --> M[Crear Manifiesto] L --> M M --> N[Iniciar Ruta] N --> O[En Tránsito] O --> P{Entrega} P -->|Exitosa| Q[Entregado] P -->|Incidente| R[Registrar Incidente] R --> O Q --> S[Generar GRE] S --> T[Pre-Facturación]

3.2. Flujo de Solicitud de Servicio (ServiceRequest)

stateDiagram-v2 [*] --> PENDIENTE PENDIENTE --> CONFIRMADA: Confirmar PENDIENTE --> CANCELADA: Cancelar CONFIRMADA --> APROBADA: Aprobar CONFIRMADA --> CANCELADA: Cancelar APROBADA --> ASIGNADA: Asignar Despacho APROBADA --> CANCELADA: Cancelar ASIGNADA --> EN_PROCESO: Iniciar Recojo ASIGNADA --> CANCELADA: Cancelar EN_PROCESO --> ENTREGADA: Confirmar Entrega ENTREGADA --> [*] CANCELADA --> [*] note right of ASIGNADA Se genera tracking y número de solicitud end note note right of ENTREGADA Estado final, genera pre-facturación end note

Estados de ServiceRequest:

Estado Valor Descripción Editable Cancelable
PENDIENTE pendiente Solicitud creada, pendiente revisión Sí Sí
CONFIRMADA confirmada Datos validados por operaciones Sí Sí
APROBADA aprobada Aprobada para asignación de recursos No Sí
ASIGNADA asignada Recursos asignados (vehículo/chofer) No Sí
EN_PROCESO en_proceso En ejecución, recojo o tránsito No No
ENTREGADA entregada Entrega confirmada No No
CANCELADA cancelada Solicitud cancelada No No

3.3. Flujo de Asignación de Despacho (DispatchAssignment)

stateDiagram-v2 [*] --> PROGRAMADO PROGRAMADO --> EN_ORIGEN: Llegada a Origen PROGRAMADO --> CANCELADO: Cancelar EN_ORIGEN --> EN_TRANSITO: Iniciar Ruta EN_ORIGEN --> CANCELADO: Cancelar EN_TRANSITO --> EN_DESTINO: Llegada a Destino EN_TRANSITO --> RETRASADO: Reportar Retraso RETRASADO --> EN_TRANSITO: Reanudar RETRASADO --> CANCELADO: Cancelar EN_DESTINO --> ENTREGADO: Confirmar Entrega ENTREGADO --> [*] CANCELADO --> [*] note right of EN_TRANSITO Se registran logs de estado automáticamente end note

Estados de DispatchAssignment:

Estado Valor Descripción Editable Eliminable
PROGRAMADO programado Despacho programado Sí Sí
EN_ORIGEN en_origen Vehículo en punto de recojo Sí Sí
EN_TRANSITO en_transito En ruta hacia destino No No
EN_DESTINO en_destino Llegó al punto de entrega No No
ENTREGADO entregado Entrega completada No No
RETRASADO retrasado Reportó retraso en ruta No Sí
CANCELADO cancelado Despacho cancelado No No

3.4. Flujo de Manifiesto (LogisticsManifest)

stateDiagram-v2 [*] --> BORRADOR BORRADOR --> PROGRAMADO: Programar BORRADOR --> CANCELADO: Cancelar PROGRAMADO --> EN_RUTA: Iniciar Ruta PROGRAMADO --> CANCELADO: Cancelar EN_RUTA --> COMPLETADO: Finalizar Ruta EN_RUTA --> CANCELADO: Cancelar COMPLETADO --> [*] CANCELADO --> [*]

Estados de LogisticsManifest:

Estado Valor Descripción Editable
BORRADOR borrador En preparación, agregando despachos Sí
PROGRAMADO programado Listo con vehículo y conductor Sí
EN_RUTA en_ruta Manifiesto en ejecución No
COMPLETADO completado Todos los despachos finalizados No
CANCELADO cancelado Manifiesto cancelado No

3.5. Flujo de Cotización (Quote)

stateDiagram-v2 [*] --> BORRADOR BORRADOR --> ENVIADA: Enviar al Cliente ENVIADA --> APROBADA: Cliente Acepta ENVIADA --> RECHAZADA: Cliente Rechaza ENVIADA --> VENCIDA: Expira Validez APROBADA --> CONVERTIDA: Generar Contrato/Solicitud CONVERTIDA --> [*] RECHAZADA --> [*] VENCIDA --> [*]

Estados de Quote:

Estado Valor Descripción Editable
BORRADOR borrador En edición Sí
ENVIADA enviada Enviada al cliente No
APROBADA aprobada Aceptada por el cliente No
RECHAZADA rechazada Rechazada por el cliente No
VENCIDA vencida Fecha de validez expirada No
CONVERTIDA convertida Convertida a contrato o solicitud No

4. Lógica de Negocio y Reglas

4.1. Reglas de Solicitud de Servicio

  • Número Automático: Se genera automáticamente con formato SR-YYYYMMDD-####.
  • Número de Tracking: Único, formato TRK-XXXXXXXX (8 caracteres alfanuméricos).
  • Token de Tracking: UUID único para consulta pública del estado.
  • Transiciones de Estado: Solo se permiten las transiciones definidas en el enum.
  • Inmutabilidad: No se puede eliminar si está EN_PROCESO o ENTREGADA.

4.2. Reglas de Asignación de Despacho

  • Exclusividad de Recursos: No se puede mezclar flota propia con proveedor externo en la misma asignación.
  • Completitud de Flota Propia: Si se asigna vehículo propio, DEBE asignarse conductor propio y viceversa.
  • Completitud de Proveedor: Si se asigna proveedor, DEBEN asignarse vehículo Y conductor del proveedor.
  • Unicidad de Asignación Activa: Solo puede existir una asignación activa (no entregada/cancelada) por solicitud.
  • Validación de Fechas: La fecha de entrega programada debe ser posterior a la de recojo.

4.3. Reglas de Manifiesto

  • Asignación de Recursos: Un manifiesto debe tener recursos de flota propia O de proveedor, no ambos.
  • Estado para Iniciar Ruta: Solo puede iniciar ruta (EN_RUTA) si tiene al menos un despacho asignado.
  • Validación de Fechas: La fecha de finalización estimada debe ser posterior a la fecha de inicio.
  • Inmutabilidad: No se puede eliminar si tiene despachos EN_TRANSITO.

4.4. Reglas de Cotización

  • Número Automático: Formato COT-YYYYMMDD-####.
  • Fecha de Validez: Debe tener una fecha de vencimiento.
  • Inmutabilidad: Solo editable en estado BORRADOR.
  • No Eliminable si Convertida: Una cotización convertida no puede eliminarse.

4.5. Reglas de Proveedor de Transporte

  • Integridad Referencial: No se puede eliminar si tiene:
    • Vehículos asociados
    • Conductores asociados
    • Contratos vigentes (no vencidos/cancelados)
    • Servicios configurados

4.6. Reglas de Vehículos

  • Estado En Ruta: No se puede eliminar un vehículo con estado EN_RUTA.
  • Propiedad: Puede ser propio o de proveedor (campo ownership).
  • Documentación: Requiere documentos de cumplimiento (SOAT, Revisión Técnica, etc.).

5. Modelo de Datos Detallado

5.1. Entidades de Operaciones

Entidad Descripción Atributos Clave
ServiceRequest Solicitud de servicio logístico request_number, tracking_number, tracking_token, partner_id, origin_zone_id, destination_zone_id
DispatchAssignment Asignación de despacho a recursos service_request_id, fleet_vehicle_id, fleet_driver_id, transport_provider_id, status
LogisticsManifest Agrupación de despachos para una ruta manifest_number, fleet_vehicle_id, fleet_driver_id, transport_provider_id, departure_at
DispatchStatusLog Historial de cambios de estado dispatch_assignment_id, old_status, new_status, notes, location
DeliveryAlert Alertas de entrega (retrasos, etc.) dispatch_assignment_id, alert_type, message, resolved_at
LogisticsIncident Incidentes en operaciones dispatch_assignment_id, incident_type, description, severity, resolved_at

5.2. Entidades Comerciales

Entidad Descripción Atributos Clave
Quote Cotización de servicios quote_number, partner_id, tariff_table_id, valid_until, subtotal, total, status
QuoteLine Líneas de detalle de cotización quote_id, origin_zone_id, destination_zone_id, weight, volume, unit_price
LogisticsContract Contrato marco con cliente contract_number, partner_id, starts_at, ends_at, currency, status
ContractTariff Tarifas especiales por contrato logistics_contract_id, origin_zone_id, destination_zone_id, price

5.3. Entidades de Flota

Entidad Descripción Atributos Clave
FleetVehicle Vehículos de transporte plate, brand, model, ownership, load_capacity_kg, load_capacity_m3, status
FleetDriver Conductores full_name, document_number, license_class, license_expiration, phone, status
FleetMaintenanceEvent Eventos de mantenimiento fleet_vehicle_id, maintenance_type, scheduled_at, completed_at, cost
ComplianceDocument Documentos normativos (polimórfico) documentable_type, documentable_id, document_type, expires_at, file_path

5.4. Entidades de Proveedores

Entidad Descripción Atributos Clave
TransportProvider Proveedores de transporte business_name, ruc, mtc_code, rating, zone_id, is_active
TransportProviderContact Contactos del proveedor transport_provider_id, name, phone, email, role
TransportProviderService Servicios que ofrece el proveedor transport_provider_id, logistics_service_id, price_per_kg

5.5. Entidades de Tarifario

Entidad Descripción Atributos Clave
TariffTable Tabla de tarifas name, code, scope, partner_id, transport_provider_id, currency, status
TariffRow Fila de tarifa (origen-destino) tariff_table_id, origin_zone_id, destination_zone_id, price_per_kg, min_price
LogisticsZone Zonas geográficas code, name, type, department_id, province_id, district_id, is_active
LogisticsZoneBoundary Límites geopolíticos de zona zone_id, latitude, longitude, sequence

5.6. Catálogos y Configuración

Entidad Descripción Atributos Clave
LogisticsService Tipos de servicio logístico code, name, service_type, max_weight, lead_time_hours, requires_gre
LogisticsServiceMode Modos de servicio (Express, etc.) logistics_service_id, name, lead_time_modifier, price_modifier
GreShipment Guía de Remisión Electrónica dispatch_assignment_id, document_series, document_number, sunat_status
PrefacturingQueue Cola de pre-facturación service_request_id, status, invoice_id, queued_at, processed_at

6. Casos de Uso

6.1. Gestión Comercial

  • CU-01: Crear Cotización: Generar cotización basada en tabla de tarifas para cliente.
  • CU-02: Enviar Cotización: Enviar cotización al cliente y cambiar estado a ENVIADA.
  • CU-03: Aprobar/Rechazar Cotización: Registrar respuesta del cliente.
  • CU-04: Convertir Cotización: Crear solicitud de servicio o contrato desde cotización aprobada.
  • CU-05: Crear Contrato: Establecer contrato marco con tarifas especiales.

6.2. Operaciones de Servicio

  • CU-06: Crear Solicitud de Servicio: Registrar nueva solicitud con datos de origen/destino.
  • CU-07: Confirmar Solicitud: Validar datos y cambiar a estado CONFIRMADA.
  • CU-08: Aprobar Solicitud: Aprobar para asignación de recursos.
  • CU-09: Asignar Despacho: Asignar vehículo y conductor (propio o proveedor).
  • CU-10: Crear Manifiesto: Agrupar múltiples despachos en una ruta.
  • CU-11: Iniciar Ruta: Comenzar ejecución del manifiesto/despacho.
  • CU-12: Registrar Entrega: Confirmar entrega exitosa con evidencia.
  • CU-13: Registrar Incidente: Documentar problemas durante el transporte.

6.3. Tracking y Monitoreo

  • CU-14: Consultar Estado por Tracking: Consulta pública del estado del envío.
  • CU-15: Ver Historial de Estados: Revisar todos los cambios de estado de un despacho.
  • CU-16: Generar Alertas: Crear alertas automáticas por retrasos.

6.4. Gestión de Flota

  • CU-17: Registrar Vehículo: Alta de vehículo propio o de proveedor.
  • CU-18: Registrar Conductor: Alta de conductor con licencia y documentación.
  • CU-19: Programar Mantenimiento: Agendar mantenimiento preventivo/correctivo.
  • CU-20: Cargar Documentos: Subir documentos de cumplimiento (SOAT, etc.).

6.5. Integración SUNAT

  • CU-21: Generar GRE: Crear Guía de Remisión Electrónica.
  • CU-22: Sincronizar con SUNAT: Enviar GRE y obtener respuesta.

7. Guía de Configuración

7.1. Configuración de Zonas (LogisticsZone)

Las zonas definen las áreas geográficas de cobertura.

Tipos de Zona (ZoneType):

Tipo Descripción
departamento Zona a nivel departamental
provincia Zona a nivel provincial
distrito Zona a nivel distrital
personalizada Zona personalizada con límites propios

Configuración:

  1. Crear zonas base vinculadas a ubicaciones geográficas (UBIGEO).
  2. Definir zonas personalizadas con límites (LogisticsZoneBoundary).
  3. Establecer jerarquía padre-hijo para agregación.

7.2. Configuración de Servicios (LogisticsService)

Tipos de Servicio (ServiceType):

Tipo Descripción
courier Mensajería y paquetería
carga Carga general
express Entrega rápida
refrigerado Carga refrigerada
peligroso Materiales peligrosos

Campos Importantes:

Campo Descripción
max_weight Peso máximo permitido (kg)
max_volume Volumen máximo permitido (m³)
lead_time_hours Tiempo de entrega estándar en horas
requires_gre Si requiere Guía de Remisión Electrónica

7.3. Tarifas (TariffTable y TariffRow)

Alcance de Tarifas (scope):

Valor Descripción
general Tarifa pública general
cliente Tarifa especial para un cliente
proveedor Tarifa de costo de un proveedor

Configuración de Filas:

Cada fila define el precio para una combinación origen-destino:

Campo Descripción
origin_zone_id Zona de origen
destination_zone_id Zona de destino
price_per_kg Precio por kilogramo
price_per_m3 Precio por metro cúbico
min_price Precio mínimo por envío

7.4. Documentos de Cumplimiento (ComplianceDocument)

Tipos de Documento (DocumentType):

Tipo Descripción Aplica a
soat Seguro Obligatorio de Accidentes Vehículos
revision_tecnica Certificado de Revisión Técnica Vehículos
licencia_conducir Licencia de Conducir Conductores
sctr Seguro Complementario de Trabajo Conductores
mtc Habilitación MTC Proveedores

8. Eventos del Sistema

8.1. Eventos de Solicitud de Servicio

Evento Descripción Payload
ServiceRequestCreated Nueva solicitud creada serviceRequest
ServiceRequestStatusChanged Cambio de estado de solicitud serviceRequest, previousStatus, newStatus
ServiceRequestAssigned Recursos asignados a solicitud serviceRequest, dispatchAssignment
ServiceRequestCompleted Solicitud entregada exitosamente serviceRequest

8.2. Eventos de Despacho

Evento Descripción Payload
DispatchAssignmentCreated Nueva asignación de despacho dispatchAssignment
DispatchStatusChanged Cambio de estado de despacho dispatchAssignment, previousStatus, newStatus
DispatchDelayed Despacho reportó retraso dispatchAssignment, reason
DispatchDelivered Despacho entregado dispatchAssignment, deliveryDetails

8.3. Eventos de Manifiesto

Evento Descripción Payload
ManifestCreated Nuevo manifiesto creado logisticsManifest
ManifestStarted Manifiesto inició ruta logisticsManifest
ManifestCompleted Manifiesto completó todas las entregas logisticsManifest

8.4. Eventos de Cotización

Evento Descripción Payload
QuoteCreated Nueva cotización creada quote
QuoteSent Cotización enviada al cliente quote
QuoteAccepted Cotización aceptada por cliente quote
QuoteConverted Cotización convertida a contrato/SR quote, convertedTo

9. Matriz de Roles y Permisos (RBAC)

Recurso Super-Admin Logística Manager Operador Conductor (App)
Solicitudes Total Total Ver/Crear Ver Asignadas
Despachos Total Total Total Actualizar Estado
Manifiestos Total Total Crear/Ver Ver Asignados
Cotizaciones Total Total Ver -
Contratos Total Total Ver -
Flota (Vehículos) Total Total Ver -
Flota (Conductores) Total Total Ver Ver Propio
Proveedores Total Total Ver -
Tarifas Total Total Ver -
Zonas Total Crear/Editar Ver -
Incidentes Total Total Crear Crear
GRE Total Total Ver -

Permisos Especiales:

  • view.logistica.*: Ver todos los recursos del módulo.
  • create.logistica.*: Crear recursos del módulo.
  • update.logistica.*: Actualizar recursos del módulo.
  • delete.logistica.*: Eliminar recursos del módulo.
  • restore.logistica.*: Restaurar registros eliminados.
  • force_delete.logistica.*: Eliminación definitiva (Solo Super-Admin).

10. Reportes y Exportación

10.1. Exportadores Disponibles

Exportador Recurso Descripción
LogisticsContractExporter Contratos Contratos con clientes
LogisticsIncidentExporter Incidentes Historial de incidentes
LogisticsManifestExporter Manifiestos Manifiestos y sus despachos
LogisticsServiceExporter Servicios Catálogo de servicios
LogisticsZoneExporter Zonas Zonas geográficas configuradas

Acceso: Botón "Exportar" en la cabecera de las tablas correspondientes.

10.2. Widgets del Dashboard

Widget Descripción
LogisticsStatsWidget Estadísticas generales (solicitudes, etc.)
DispatchesByStatusChart Gráfico de despachos por estado
ManifestsByStatusChart Gráfico de manifiestos por estado
RecentIncidentsWidget Últimos incidentes reportados

11. Integración con GRE-SUNAT

11.1. Guía de Remisión Electrónica (GreShipment)

La entidad GreShipment almacena toda la información necesaria para la generación y sincronización con SUNAT.

Campos Principales:

Campo Descripción
document_series Serie del documento (ej: T001)
document_number Número correlativo
sunat_status Estado de respuesta de SUNAT
sunat_ticket Ticket de procesamiento asíncrono
transfer_reason Motivo de traslado
transfer_reason_code Código de motivo según SUNAT
total_weight Peso total en kg
packages_count Número de bultos
origin_ubigeo UBIGEO de origen
destination_ubigeo UBIGEO de destino

Payloads Almacenados (JSON):

  • sender_payload: Datos del remitente
  • receiver_payload: Datos del destinatario
  • driver_payload: Datos del conductor
  • vehicle_payload: Datos del vehículo
  • items_payload: Detalle de ítems transportados
  • response_payload: Respuesta de SUNAT

12. Solución de Problemas (Troubleshooting)

Error: "No se puede mezclar flota propia con proveedor externo"

  • Causa: Se asignó un vehículo propio y también se seleccionó un proveedor.
  • Solución: Usar solo flota propia (vehículo + conductor propios) O solo proveedor (proveedor + vehículo + conductor del proveedor).

Error: "Si asigna un vehículo propio, debe asignar un conductor propio"

  • Causa: Se seleccionó vehículo propio pero no conductor propio.
  • Solución: Asignar un conductor propio al despacho o quitar el vehículo.

Error: "Ya existe una asignación activa para esta solicitud de servicio"

  • Causa: La solicitud ya tiene un despacho que no está en estado ENTREGADO o CANCELADO.
  • Solución: Completar o cancelar el despacho existente antes de crear uno nuevo.

Error: "Esta solicitud está en progreso y no puede ser eliminada"

  • Causa: Intentas eliminar una solicitud en estado EN_PROCESO.
  • Solución: Completar o cancelar la solicitud primero.

Error: "No se puede cambiar de X a Y"

  • Causa: Transición de estado no permitida.
  • Solución: Seguir el flujo de estados definido en los diagramas.

Error: "Este vehículo está en ruta y no puede ser eliminado"

  • Causa: El vehículo tiene estado EN_RUTA.
  • Solución: Esperar a que complete la ruta o cambiar manualmente el estado.

Error: "Este proveedor tiene vehículos/conductores asociados"

  • Causa: Intentas eliminar un proveedor con recursos vinculados.
  • Solución: Eliminar primero los vehículos y conductores del proveedor.

Error: "Esta cotización ya fue convertida y no puede ser eliminada"

  • Causa: La cotización fue convertida a contrato o solicitud.
  • Solución: Eliminar primero el contrato/solicitud generado (si es posible).

13. Anexos

13.1. Enums del Módulo

Enum Valores
ServiceRequestStatus pendiente, confirmada, aprobada, asignada, en_proceso, entregada, cancelada
DispatchStatus programado, en_origen, en_transito, en_destino, entregado, retrasado, cancelado
ManifestStatus borrador, programado, en_ruta, completado, cancelado
QuoteStatus borrador, enviada, aprobada, rechazada, vencida, convertida
VehicleStatus disponible, en_ruta, en_mantenimiento, fuera_de_servicio
VehicleOwnership propio, tercero, arrendado
ZoneType departamento, provincia, distrito, personalizada
ServiceType courier, carga, express, refrigerado, peligroso
DocumentType soat, revision_tecnica, licencia_conducir, sctr, mtc, otros

13.2. Formatos de Numeración Automática

Entidad Formato Ejemplo
ServiceRequest SR-YYYYMMDD-#### SR-20260118-0001
Quote COT-YYYYMMDD-#### COT-20260118-0001
Tracking Number TRK-XXXXXXXX TRK-A1B2C3D4
Manifest MAN-YYYYMMDD-#### MAN-20260118-0001

Documentación generada el 2026-01-18. Versión 1.0.

Volver a Documentación