rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-transportistas-v2/docs/02-definicion-modulos/MAI-003-ordenes-transporte/README.md
Adrian Flores Cortes aebaad4fe9 chore: Consolidar y purgar documentación duplicada (TASK-006) 
Consolidación:
- MAI-003/RESUMEN-EPICA.md -> README.md (criterios, riesgos, distribución)
- MAE-016/RESUMEN-EPICA.md -> README.md (criterios, métricas, valor negocio)

Archivos eliminados:
- MAI-003-ordenes-transporte/RESUMEN-EPICA.md
- MAE-016-carta-porte/RESUMEN-EPICA.md

Documentación de purga en orchestration/tareas/2026-01-27/TASK-006

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 11:44:16 -06:00

9.2 KiB
Raw Permalink Blame History

MAI-003: Ordenes de Transporte

Modulo: MAI-003 | Version: 1.0.0 | Actualizado: 2026-01-27

Descripcion

El modulo de Ordenes de Transporte (OT) es el nucleo operativo del ERP Transportistas. Una OT representa la solicitud formal de un cliente (shipper) para mover mercancia desde un punto de origen hasta uno o multiples destinos, con restricciones logisticas especificas. Este modulo gestiona todo el ciclo de vida de la OT, desde su creacion en borrador hasta su cierre tras la facturacion.

La OT es el documento maestro que conecta las necesidades comerciales del cliente con la ejecucion operativa del transporte. Cada OT contiene informacion detallada sobre la carga, ubicaciones georreferenciadas, ventanas de tiempo, requisitos de equipo, tarifas aplicables y estado operativo. Las OTs pueden agruparse en embarques para consolidacion logistica y asignarse a viajes para su ejecucion.

Workflow de la OT

BORRADOR --> CONFIRMADA --> ASIGNADA --> EN_PROCESO --> COMPLETADA --> FACTURADA --> CANCELADA (desde cualquier estado previo a COMPLETADA)
Estado Descripcion Transiciones permitidas
BORRADOR OT recien creada, editable libremente CONFIRMADA, CANCELADA
CONFIRMADA Datos validados, lista para planeacion ASIGNADA, CANCELADA
ASIGNADA Vinculada a un embarque y/o viaje EN_PROCESO, CANCELADA
EN_PROCESO Viaje en ejecucion, carga en transito COMPLETADA
COMPLETADA Entrega realizada con POD FACTURADA
FACTURADA OT incluida en factura emitida (estado terminal)
CANCELADA OT cancelada con motivo registrado (estado terminal)

Actores

Actor Rol en el modulo
Cliente / Shipper Solicita el servicio de transporte, proporciona datos de carga y ubicaciones
Despachador Crea y confirma OTs, valida datos, coordina con clientes
Coordinador / Planner Agrupa OTs en embarques, asigna a viajes, optimiza recursos
Operador / Conductor Ejecuta el transporte fisico de la carga asociada a las OTs
Administrador Configura parametros del modulo, gestiona permisos y tarifas

Funcionalidades Clave

  1. Creacion de OT con datos completos: Origen/destino georreferenciados, datos de carga (peso, volumen, piezas, pallets), tipo de carga, ventanas de tiempo para recoleccion y entrega, referencia del cliente.
  2. Multi-paradas: Soporte para rutas con multiples puntos de recoleccion y entrega mediante la tabla paradas_viaje asociada al viaje.
  3. Agrupacion en embarques: Consolidacion de multiples OTs compatibles en un embarque para optimizar capacidad y costos.
  4. Asignacion a viajes: Vinculacion de OTs/embarques a viajes con unidad, operador y ruta asignados.
  5. Restricciones logisticas: Requisitos de temperatura, GPS, escolta, citas, instrucciones especiales por OT.
  6. Calculo de tarifa: Tarifa base, recargos, descuentos, subtotal, IVA y total calculados automaticamente.
  7. Tracking de status: Transiciones de estado controladas con trazabilidad de usuario y timestamp.
  8. Busqueda avanzada: Filtros por estado, cliente, fechas, tipo de carga, codigo y referencia.
  9. Cancelacion controlada: Cancelacion con registro de motivo y usuario responsable.

Entidades Principales (DDL)

Entidad Tabla Schema Descripcion
OrdenTransporte transport.ordenes_transporte transport Solicitud de servicio de transporte
Embarque transport.embarques transport Agrupacion logica de OTs para consolidacion
Viaje transport.viajes transport Ejecucion operativa (unidad + operador + ruta)
ParadaViaje transport.paradas_viaje transport Paradas programadas en un viaje (multi-drop)
POD transport.pod transport Proof of Delivery - evidencia de entrega
Incidencia transport.incidencias transport Registro de incidencias durante el transporte

ENUMs Relevantes

ENUM Valores Uso
estado_orden BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA, CANCELADA Estado de la OT
tipo_carga GENERAL, PELIGROSA, REFRIGERADA, SOBREDIMENSIONADA, GRANEL, LIQUIDOS, CONTENEDOR, AUTOMOVILES Clasificacion de carga
estado_pod PENDIENTE, PARCIAL, COMPLETO, RECHAZADO Estado de evidencia de entrega

API Endpoints (Proyectados)

Metodo Endpoint Descripcion
POST /api/v1/ordenes-transporte Crear nueva OT
GET /api/v1/ordenes-transporte Listar OTs con filtros y paginacion
GET /api/v1/ordenes-transporte/:id Obtener detalle de una OT
PATCH /api/v1/ordenes-transporte/:id Actualizar OT en BORRADOR
PATCH /api/v1/ordenes-transporte/:id/confirmar Confirmar OT (BORRADOR -> CONFIRMADA)
PATCH /api/v1/ordenes-transporte/:id/cancelar Cancelar OT con motivo
POST /api/v1/embarques Crear embarque agrupando OTs
GET /api/v1/embarques Listar embarques con OTs asociadas
GET /api/v1/embarques/:id Detalle de embarque
PATCH /api/v1/embarques/:id/asignar-viaje Asignar embarque a viaje
GET /api/v1/ordenes-transporte/dashboard Resumen de OTs por estado
GET /api/v1/ordenes-transporte/exportar Exportar listado de OTs (CSV/Excel)

User Stories

ID Titulo SP Prioridad Archivo
US-MAI003-001 Crear orden de transporte 8 P0 historias-usuario/US-MAI003-001.md
US-MAI003-002 Agregar multiples paradas a OT 5 P0 historias-usuario/US-MAI003-002.md
US-MAI003-003 Definir restricciones logisticas 5 P1 historias-usuario/US-MAI003-003.md
US-MAI003-004 Agrupar OTs en embarque 8 P0 historias-usuario/US-MAI003-004.md
US-MAI003-005 Consultar status de OT 3 P1 historias-usuario/US-MAI003-005.md
US-MAI003-006 Modificar OT en borrador 5 P1 historias-usuario/US-MAI003-006.md
US-MAI003-007 Cancelar OT 3 P1 historias-usuario/US-MAI003-007.md
US-MAI003-008 Buscar OTs con filtros avanzados 5 P1 historias-usuario/US-MAI003-008.md
US-MAI003-009 Exportar listado de OTs 3 P2 historias-usuario/US-MAI003-009.md
US-MAI003-010 Dashboard de OTs por status 5 P2 historias-usuario/US-MAI003-010.md

Total Story Points: 50

Dependencias

Tipo Modulo Descripcion
Depende de MAI-001 (Auth) Autenticacion, RBAC, multi-tenancy
Depende de MAI-002 (Clientes y Tarifas) Datos de shippers/consignees, tarifas por lane
Bloquea MAI-004 (Planeacion TMS) La planeacion consume OTs confirmadas
Bloquea MAI-005 (Despacho) El despacho opera sobre OTs asignadas a viajes
Bloquea MAI-006 (Tracking) El tracking monitorea viajes con OTs asociadas
Bloquea MAI-007 (POD y Cierre) El POD cierra la entrega de OTs
Bloquea MAI-009 (Facturacion) La facturacion genera CFDI sobre OTs completadas

Notas Tecnicas

  • RLS (Row Level Security): Todas las tablas del schema transport tienen RLS habilitado con aislamiento por tenant_id usando current_setting('app.tenant_id').
  • Indices: La tabla ordenes_transporte cuenta con indices en tenant_id, estado, shipper_id, fecha_recoleccion_programada y viaje_id para optimizar las consultas mas frecuentes.
  • Constraint unico: uq_ot_tenant_codigo garantiza que el codigo de OT sea unico por tenant.
  • Soft delete: Se utiliza deleted_at para eliminacion logica.
  • Auditoria: Campos created_at, created_by_id, updated_at, updated_by_id en todas las entidades.

Notas Adicionales de Epica

Criterios de Aceptacion de la Epica:

  1. Un despachador puede crear una OT con todos los datos obligatorios (origen, destino, cliente, carga)
  2. El sistema valida la transicion de estados segun el workflow definido
  3. Se pueden agrupar OTs compatibles en un embarque con totales consolidados
  4. La busqueda permite filtrar por estado, cliente, fechas, tipo de carga y codigo
  5. El dashboard muestra contadores por estado con actualizacion en tiempo real
  6. Todas las tablas tienen RLS habilitado para aislamiento por tenant
  7. Los endpoints cumplen con paginacion, filtros y ordenamiento estandar
  8. La auditoria registra usuario y timestamp en cada operacion

Riesgos Identificados:

Riesgo Impacto Mitigacion
Datos de ubicacion incompletos Alto Validacion obligatoria de campos de direccion y geocodificacion
Volumen alto de OTs por tenant Medio Indices optimizados y paginacion obligatoria en listados
Cambios de estado no controlados Alto Maquina de estados estricta en backend con validacion de transiciones
Calculo incorrecto de tarifas Alto Validacion cruzada con modulo MAI-002 y tests unitarios exhaustivos

Distribucion de Esfuerzo por Capa:

Capa Esfuerzo Estimado
Database (DDL + migraciones) 15%
Backend (entities + services + controllers) 45%
Frontend (components + pages + forms) 30%
Tests (unit + integration + e2e) 10%

MAI-003 Ordenes de Transporte - ERP Transportistas v1.0.0