# EPIC-MAI-003: Ordenes de Transporte

**Version:** 1.0.0 | **Actualizado:** 2026-01-27

---

## Resumen

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MAI-003 |
| **Nombre** | Ordenes de Transporte |
| **Modulo** | MAI-003 |
| **Prioridad** | P0 - Critica |
| **SP Total** | 50 |
| **Sprint Inicio** | Por asignar |
| **Sprint Fin** | Por asignar |
| **Estado** | Backlog |
| **Owner** | Por asignar |
| **Schema BD** | transport |
| **Tabla Principal** | transport.ordenes_transporte |

---

## Objetivo

Implementar un sistema completo de gestion de Ordenes de Transporte (OT) que permita a los usuarios crear, confirmar, agrupar, asignar, monitorear y cerrar solicitudes de servicio de transporte de carga. La OT es el documento maestro que conecta la demanda comercial del cliente con la ejecucion operativa, y su correcta gestion es critica para la rentabilidad y calidad del servicio de la empresa transportista.

---

## Alcance

### Incluido

- CRUD completo de Ordenes de Transporte con datos de origen, destino, carga y tarifas
- Workflow de estados controlado: BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA, CANCELADA
- Definicion de restricciones logisticas por OT (temperatura, GPS, escolta, citas)
- Creacion y gestion de embarques como agrupacion de OTs
- Consulta de status y timeline de la OT
- Modificacion de OTs en estado BORRADOR
- Cancelacion controlada con registro de motivo
- Busqueda avanzada con filtros multiples
- Exportacion de listados en formato CSV/Excel
- Dashboard resumen de OTs por estado

### Excluido

- Planeacion y optimizacion de rutas (MAI-004)
- Despacho y checklists pre-viaje (MAI-005)
- Tracking GPS en tiempo real (MAI-006)
- Captura de POD y cierre operativo (MAI-007)
- Gestion de incidencias (MAI-008)
- Facturacion y CFDI (MAI-009)
- Portal de autoservicio para clientes (MAI-015)

---

## User Stories

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

---

## SP Total: 50

| Prioridad | Stories | SP |
|-----------|---------|-----|
| P0 (Critica) | 3 | 21 |
| P1 (Alta) | 5 | 21 |
| P2 (Media) | 2 | 8 |
| **Total** | **10** | **50** |

---

## Distribucion por Capa

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

---

## 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

| 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 |

---

## Dependencias Tecnicas

| Dependencia | Tipo | Descripcion |
|-------------|------|-------------|
| MAI-001 Auth | Bloqueante | Se requiere autenticacion y permisos RBAC funcionales |
| MAI-002 Clientes | Bloqueante | Se requiere catalogo de clientes y tarifas configuradas |
| Schema transport DDL | Bloqueante | Tablas ordenes_transporte, embarques deben existir |
| ENUMs transport | Bloqueante | estado_orden, tipo_carga deben estar creados |

---

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