rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
37ed0aa919
erp-transportistas-v2/docs/03-requerimientos/REQ-GIRO-TRANSPORTISTA.md
Adrian Flores Cortes 37ed0aa919 feat: Initial project structure for ERP Transportistas 
Vertical ERP for freight transport and logistics companies.

Includes:
- Project configuration (CLAUDE.md, SIMCO orchestration)
- Backend submodule (NestJS 10.x)
- Frontend submodule (React 18.x + Vite)
- Database submodule (PostgreSQL 15 + PostGIS)
- Requirements documentation (REQ-GIRO-TRANSPORTISTA.md)
- 20 modules defined (MAI/MAE/MAA phases)

Key features:
- Transport orders (OT) management
- Fleet and driver management
- Real-time GPS tracking
- POD (Proof of Delivery)
- CFDI with Carta Porte 3.1 compliance
- Fuel and maintenance control
- Third-party carrier management

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 09:53:54 -06:00

20 KiB
Raw Blame History

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.

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