# REQUERIMIENTOS.md - MAI-003 Ordenes de Transporte

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

---

## Resumen

| Metrica | Valor |
|---------|-------|
| Total Requerimientos | 25 |
| Prioridad Alta | 12 |
| Prioridad Media | 9 |
| Prioridad Baja | 4 |
| Fuente DDL | 01-transport-schema-ddl.sql |
| Fuente Funcional | REQ-GIRO-TRANSPORTISTA.md (secciones 4.2, 4.3) |

---

## Requerimientos Funcionales

### Creacion y Datos de la OT

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-001 | El sistema debe permitir crear una Orden de Transporte con los datos obligatorios: codigo unico por tenant, shipper (cliente), consignee (destinatario), direccion de origen, direccion de destino y usuario creador. | Alta | MAI-002 (Clientes) |
| RF-MAI003-002 | El sistema debe registrar la referencia del cliente (referencia_cliente) como dato opcional para vincular la OT con el sistema del shipper (PO, ASN). | Alta | MAI-002 (Clientes) |
| RF-MAI003-003 | El sistema debe capturar datos completos de origen y destino: direccion, codigo postal, ciudad, estado, pais (default MEX), latitud, longitud, contacto y telefono. | Alta | - |
| RF-MAI003-004 | El sistema debe registrar las fechas y ventanas de tiempo programadas: fecha_recoleccion_programada, fecha_entrega_programada, ventana_recoleccion_inicio/fin y ventana_entrega_inicio/fin. | Alta | - |
| RF-MAI003-005 | El sistema debe capturar los datos de carga: tipo_carga (GENERAL, PELIGROSA, REFRIGERADA, SOBREDIMENSIONADA, GRANEL, LIQUIDOS, CONTENEDOR, AUTOMOVILES), descripcion_carga, peso_kg, volumen_m3, piezas, pallets, valor_declarado y moneda. | Alta | - |
| RF-MAI003-006 | El sistema debe generar automaticamente un codigo unico de OT por tenant, cumpliendo con la constraint uq_ot_tenant_codigo definida en DDL. | Alta | - |

### Restricciones Logisticas

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-007 | El sistema debe permitir definir requisitos de temperatura para carga refrigerada: requiere_temperatura (boolean), temperatura_min y temperatura_max en grados Celsius. | Media | MAI-011 (Flota) |
| RF-MAI003-008 | El sistema debe permitir marcar requisitos de seguridad: requiere_gps (boolean), requiere_escolta (boolean) y requiere_cita (boolean). | Media | MAI-006 (Tracking) |
| RF-MAI003-009 | El sistema debe permitir registrar instrucciones especiales como texto libre para comunicar al operador y al equipo de despacho. | Media | MAI-005 (Despacho) |
| RF-MAI003-010 | El sistema debe registrar la modalidad de servicio (FTL o LTL) para determinar si el viaje es dedicado o consolidado. | Alta | MAI-004 (Planeacion) |

### Tarifas y Costos

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-011 | El sistema debe permitir asociar una tarifa a la OT (tarifa_id) y registrar tarifa_base, recargos, descuentos, subtotal, IVA y total. | Alta | MAI-002 (Tarifas), MAI-009 (Facturacion) |
| RF-MAI003-012 | El sistema debe calcular automaticamente subtotal, IVA y total al confirmar la OT, basandose en la tarifa asignada y los recargos/descuentos aplicados. | Alta | MAI-009 (Facturacion) |

### Workflow y Estados

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-013 | El sistema debe implementar el workflow de estados: BORRADOR -> CONFIRMADA -> ASIGNADA -> EN_PROCESO -> COMPLETADA -> FACTURADA, con CANCELADA accesible desde BORRADOR, CONFIRMADA y ASIGNADA. | Alta | - |
| RF-MAI003-014 | El sistema debe permitir modificar los datos de una OT unicamente cuando se encuentra en estado BORRADOR. En estados posteriores, la OT es de solo lectura. | Alta | - |
| RF-MAI003-015 | El sistema debe registrar la transicion de estado con el usuario responsable (updated_by_id) y la fecha de actualizacion (updated_at). | Media | MAI-001 (Auth) |
| RF-MAI003-016 | El sistema debe permitir cancelar una OT registrando el motivo de cancelacion y marcando deleted_at como fecha de cancelacion logica. | Media | - |

### Embarques (Agrupacion de OTs)

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-017 | El sistema debe permitir crear embarques con codigo unico por tenant, descripcion y cliente principal, cumpliendo la constraint uq_embarque_tenant_codigo. | Alta | - |
| RF-MAI003-018 | El sistema debe permitir agrupar multiples OTs de un mismo cliente en un embarque, actualizando los totales consolidados: total_ots, peso_total_kg, volumen_total_m3. | Alta | MAI-004 (Planeacion) |
| RF-MAI003-019 | El sistema debe actualizar el campo embarque_id en cada OT al agregarla a un embarque, y recalcular los totales del embarque al agregar o quitar OTs. | Media | - |
| RF-MAI003-020 | El sistema debe permitir asignar un embarque a un viaje (viaje_id) y actualizar el estado del embarque en consecuencia. | Media | MAI-004 (Planeacion) |

### Consulta y Busqueda

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-021 | El sistema debe proporcionar un listado paginado de OTs con filtros por: estado, shipper_id, rango de fecha_recoleccion_programada, tipo_carga, codigo y referencia_cliente. Los indices idx_ot_estado, idx_ot_shipper e idx_ot_fechas deben soportar estas consultas. | Alta | - |
| RF-MAI003-022 | El sistema debe mostrar el detalle completo de una OT incluyendo datos de carga, ubicaciones, restricciones, tarifa, estado actual y embarque/viaje asociados. | Media | - |
| RF-MAI003-023 | El sistema debe proporcionar un dashboard con contadores de OTs agrupadas por estado para el tenant actual. | Baja | - |

### Exportacion

| ID | Descripcion | Prioridad | Modulo Relacionado |
|----|-------------|-----------|-------------------|
| RF-MAI003-024 | El sistema debe permitir exportar el listado de OTs filtrado en formato CSV, incluyendo: codigo, referencia_cliente, shipper_nombre, consignee_nombre, origen_ciudad, destino_ciudad, fecha_recoleccion_programada, fecha_entrega_programada, estado y total. | Baja | - |
| RF-MAI003-025 | El sistema debe permitir exportar el listado de OTs filtrado en formato Excel (XLSX) con las mismas columnas que el formato CSV, ademas de formato de celdas y encabezados estilizados. | Baja | - |

---

## Requerimientos No Funcionales

| ID | Descripcion | Categoria |
|----|-------------|-----------|
| RNF-MAI003-001 | Todas las tablas del modulo deben tener RLS habilitado con politica de aislamiento por tenant_id. | Seguridad |
| RNF-MAI003-002 | El listado de OTs con filtros debe responder en menos de 500ms para tenants con hasta 100,000 OTs. | Performance |
| RNF-MAI003-003 | Las transiciones de estado deben ser atomicas y registrar auditoria completa (usuario, timestamp). | Integridad |
| RNF-MAI003-004 | Los endpoints de listado deben soportar paginacion con cursor o offset, limitada a 100 registros por pagina. | Escalabilidad |
| RNF-MAI003-005 | La exportacion de datos debe soportar hasta 50,000 registros sin timeout del servidor (procesamiento asincrono si excede 10,000). | Escalabilidad |

---

## Trazabilidad DDL -> Requerimiento

| Tabla DDL | Requerimientos Asociados |
|-----------|-------------------------|
| transport.ordenes_transporte | RF-MAI003-001 a RF-MAI003-016, RF-MAI003-021, RF-MAI003-022 |
| transport.embarques | RF-MAI003-017 a RF-MAI003-020 |
| ENUM transport.estado_orden | RF-MAI003-013 |
| ENUM transport.tipo_carga | RF-MAI003-005 |
| INDEX idx_ot_estado | RF-MAI003-021 |
| INDEX idx_ot_shipper | RF-MAI003-021 |
| INDEX idx_ot_fechas | RF-MAI003-021 |
| CONSTRAINT uq_ot_tenant_codigo | RF-MAI003-006 |
| CONSTRAINT uq_embarque_tenant_codigo | RF-MAI003-017 |

---

## Trazabilidad Funcional -> Requerimiento

| Seccion REQ-GIRO-TRANSPORTISTA | Requerimientos Asociados |
|-------------------------------|-------------------------|
| RF-4.2.1 Datos obligatorios OT | RF-MAI003-001, RF-MAI003-003, RF-MAI003-004, RF-MAI003-005 |
| RF-4.2.2 Restricciones | RF-MAI003-007, RF-MAI003-008, RF-MAI003-009 |
| RF-4.2.3 Multi-paradas | RF-MAI003-003 (origen/destino base), ver MAI-004 para paradas_viaje |
| RF-4.2.4 LTL vs FTL | RF-MAI003-010 |
| RF-4.2.5 Documentacion adjunta | RF-MAI003-009 (instrucciones_especiales) |
| RF-4.3.1 Tablero de planeacion | RF-MAI003-023 |
| RF-4.3.2 Consolidacion | RF-MAI003-017, RF-MAI003-018 |

---

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