rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ec43d9c6cd
erp-transportistas-v2/docs/02-definicion-modulos/MAI-003-ordenes-transporte/historias-usuario/US-MAI003-005.md
Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 
Modules documented:
- MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US
- MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-008 (Incidencias): 3 US (18 SP)
- MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-012 (Combustible): 3 US (18 SP)
- MAI-013 (Mantenimiento): 3 US (18 SP)
- MAI-014 (Carriers): 3 US (18 SP)
- MAI-015 (Portal): 3 US (18 SP)
- MAE-016 (Carta Porte): 10 US
- MAE-017 (HOS): 3 US (16 SP)
- MAE-018 (Reportes): 3 US (18 SP)

Phase 2+3 complete: 13 modules, 50+ User Stories

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 02:24:35 -06:00

4.7 KiB
Raw Blame History

US-MAI003-005: Consultar status de OT

Metadata

Campo Valor
ID US-MAI003-005
Epica EPIC-MAI-003 - Ordenes de Transporte
Modulo ordenes-transporte
Prioridad P1
Story Points 3
Sprint Por asignar
Estado Backlog

Historia de Usuario

Como despachador o ejecutivo de cuenta de una empresa transportista, quiero consultar el estado actual y el historial de una orden de transporte, para informar al cliente sobre el progreso de su envio y tomar decisiones operativas oportunas.

Descripcion Detallada

La consulta de status de OT es una operacion frecuente en el dia a dia operativo. Los despachadores y ejecutivos de cuenta necesitan verificar rapidamente en que fase se encuentra cada OT para responder consultas de clientes, coordinar con el equipo de planeacion y monitorear el avance general de las operaciones.

La consulta muestra el estado actual de la OT (BORRADOR, CONFIRMADA, ASIGNADA, EN_PROCESO, COMPLETADA, FACTURADA o CANCELADA), los datos principales del servicio (shipper, consignee, origen, destino, fechas programadas), la asignacion operativa (embarque y viaje asociados si existen) y los datos financieros (tarifa, total).

Adicionalmente, el sistema debe mostrar un timeline con las transiciones de estado de la OT, incluyendo fecha/hora y usuario responsable de cada cambio, utilizando los campos de auditoria (created_at, updated_at, created_by_id, updated_by_id).

Criterios de Aceptacion

Escenario 1: Consulta por codigo de OT

Dado que existe una OT con codigo OT-2026-00015 en el tenant actual, Cuando el usuario busca por codigo "OT-2026-00015", Entonces el sistema muestra la vista de detalle con el estado actual, datos del servicio, ubicaciones, carga, tarifa, embarque y viaje asociados.

Escenario 2: Visualizacion del estado actual con indicador visual

Dado que una OT se encuentra en estado EN_PROCESO, Cuando el usuario consulta el detalle de la OT, Entonces el sistema muestra un indicador visual (badge de color) del estado actual y un timeline que refleja los estados por los que ha pasado la OT con fecha, hora y usuario de cada transicion.

Escenario 3: Consulta de OT con embarque y viaje asociados

Dado que una OT esta en estado ASIGNADA con embarque_id y viaje_id poblados, Cuando el usuario consulta el detalle, Entonces el sistema muestra los datos del embarque (codigo, total de OTs, peso/volumen total) y del viaje (codigo, unidad, operador, fechas de salida/llegada programadas) con enlaces para navegar al detalle de cada uno.

Escenario 4: Consulta de OT inexistente

Dado que el usuario busca una OT con un ID o codigo que no existe en su tenant, Cuando realiza la consulta, Entonces el sistema devuelve un error 404 con mensaje "Orden de transporte no encontrada".

Tareas Tecnicas

  • Database: Utilizar las tablas existentes transport.ordenes_transporte, transport.embarques y transport.viajes con JOINs para obtener datos relacionados. Los indices idx_ot_tenant y uq_ot_tenant_codigo soportan la busqueda por id y codigo.
  • Backend: Agregar metodo findById() y findByCodigo() en OrdenTransporteService que retorne la OT con relaciones cargadas (embarque, viaje). Configurar endpoint GET /api/v1/ordenes-transporte/:id con query parameter opcional ?include=embarque,viaje para cargar relaciones. Crear OrdenTransporteDetailDto con datos completos de la OT.
  • Frontend: Crear pagina OrdenTransporteDetailPage con secciones: informacion general, origen/destino (con mapa), datos de carga, restricciones, tarifa/costos, embarque asignado, viaje asignado, timeline de estados. Implementar badge de colores por estado. Incluir acciones contextuales segun estado (confirmar, cancelar, editar).
  • Tests: Tests unitarios de consulta por id y codigo. Tests de integracion del endpoint GET con relaciones. Tests de manejo de OT inexistente (404).

Dependencias

  • Depende de: US-MAI003-001 (la OT debe existir)
  • Bloquea: Ninguno directamente (funcionalidad de solo lectura)

Notas Tecnicas

  • Endpoint: GET /api/v1/ordenes-transporte/:id
  • Query params: ?include=embarque,viaje para cargar relaciones lazy
  • RLS: La consulta esta automaticamente filtrada por tenant_id via RLS policy
  • Timeline: Dado que la tabla no almacena un historial explícito de transiciones, inicialmente el timeline se construye con created_at (creacion) y updated_at (ultima actualizacion). En una fase futura se recomienda implementar una tabla de historial de estados o usar la tabla de auditoria del modulo MAI-001
  • Performance: La consulta por UUID (PK) es O(1). La consulta por codigo usa el indice uq_ot_tenant_codigo

US-MAI003-005 - ERP Transportistas v1.0.0