erp-transportistas-v2/docs/02-definicion-modulos/MAI-003-ordenes-transporte/historias-usuario/US-MAI003-010.md

US-MAI003-010: Dashboard de OTs por status

Metadata

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

Historia de Usuario

Como coordinador de trafico o gerente de operaciones de una empresa transportista, quiero visualizar un dashboard con el resumen de ordenes de transporte agrupadas por estado, para tener una vision rapida del volumen operativo, identificar cuellos de botella y tomar decisiones de asignacion de recursos.

Descripcion Detallada

El dashboard de OTs es la vista ejecutiva del modulo de ordenes de transporte. Presenta contadores y graficos que resumen el estado actual de todas las OTs del tenant, permitiendo al coordinador o gerente identificar rapidamente cuantas OTs estan pendientes de confirmacion, cuantas estan listas para planeacion, cuantas estan en ejecucion y cuantas pendientes de facturacion.

El dashboard incluye: contadores por estado (tarjetas/cards), un grafico de barras o dona con la distribucion porcentual, OTs proximas a vencer su ventana de entrega (alertas), totales de peso y volumen por estado, y un resumen de OTs creadas vs completadas en el periodo seleccionado.

Los datos del dashboard deben actualizarse al cargar la pagina y permitir filtrado por rango de fechas para analizar periodos especificos. La consulta principal utiliza el indice idx_ot_estado (tenant_id, estado) para agrupar y contar registros de forma eficiente.

Criterios de Aceptacion

Escenario 1: Visualizar contadores por estado

Dado que el tenant tiene OTs en distintos estados, Cuando el coordinador accede al dashboard de ordenes de transporte, Entonces el sistema muestra tarjetas con el conteo de OTs por cada estado: BORRADOR (12), CONFIRMADA (8), ASIGNADA (15), EN_PROCESO (22), COMPLETADA (5), FACTURADA (45), CANCELADA (3).

Escenario 2: Filtrar dashboard por rango de fechas

Dado que el coordinador desea analizar el mes de enero 2026, Cuando selecciona el rango de fechas 2026-01-01 a 2026-01-31, Entonces los contadores y graficos se actualizan mostrando solo las OTs creadas dentro de ese rango, y el resumen muestra "OTs creadas: 110, OTs completadas: 72, Tasa de completitud: 65.5%".

Escenario 3: Alertas de OTs proximas a vencer

Dado que existen OTs en estado CONFIRMADA o ASIGNADA cuya fecha_entrega_programada es dentro de las proximas 24 horas, Cuando el coordinador visualiza el dashboard, Entonces el sistema muestra una seccion de alertas con las OTs proximas a vencer, incluyendo codigo, shipper_nombre, destino_ciudad y horas restantes para la entrega.

Escenario 4: Totales consolidados por estado

Dado que el coordinador necesita dimensionar la carga operativa, Cuando visualiza el dashboard, Entonces el sistema muestra, ademas de los contadores de OTs, los totales de peso_kg y volumen_m3 agrupados por estado para los estados activos (CONFIRMADA, ASIGNADA, EN_PROCESO).

Tareas Tecnicas

• Database: Crear query de agregacion: SELECT estado, COUNT(*), SUM(peso_kg), SUM(volumen_m3) FROM transport.ordenes_transporte WHERE tenant_id = :tenantId AND deleted_at IS NULL GROUP BY estado. Utilizar el indice idx_ot_estado para optimizar. Para alertas de vencimiento: query con filtro fecha_entrega_programada BETWEEN NOW() AND NOW() + INTERVAL '24 hours' y estado IN ('CONFIRMADA', 'ASIGNADA').
• Backend: Crear metodo getDashboard(dateRange?) en OrdenTransporteService que retorne: contadores por estado, totales de peso/volumen por estado, OTs proximas a vencer, resumen de creadas vs completadas en el periodo. Configurar endpoint GET /api/v1/ordenes-transporte/dashboard?fecha_desde=2026-01-01&fecha_hasta=2026-01-31. Crear DashboardOrdenTransporteDto con la estructura de respuesta.
• Frontend: Crear pagina OrdenesTransporteDashboardPage con: fila de tarjetas/cards por estado con colores (BORRADOR=gris, CONFIRMADA=azul, ASIGNADA=naranja, EN_PROCESO=amarillo, COMPLETADA=verde, FACTURADA=verde oscuro, CANCELADA=rojo). Grafico de dona con libreria recharts o chart.js. Tabla de alertas de OTs proximas a vencer. Selector de rango de fechas con presets (hoy, esta semana, este mes, mes anterior). Totales consolidados de peso y volumen.
• Tests: Tests unitarios de la query de agregacion. Tests del calculo de tasa de completitud. Tests de integracion del endpoint de dashboard. Tests de filtrado por rango de fechas.

Dependencias

• Depende de: US-MAI003-001 (datos de OTs), US-MAI003-008 (indices de busqueda reutilizados)
• Bloquea: Ninguno directamente (vista de solo lectura ejecutiva)

Notas Tecnicas

• Endpoint: GET /api/v1/ordenes-transporte/dashboard
• Query params: fecha_desde (ISO date, opcional), fecha_hasta (ISO date, opcional)
• Respuesta ejemplo:

{
  "contadores": {
    "BORRADOR": 12,
    "CONFIRMADA": 8,
    "ASIGNADA": 15,
    "EN_PROCESO": 22,
    "COMPLETADA": 5,
    "FACTURADA": 45,
    "CANCELADA": 3
  },
  "totales": {
    "CONFIRMADA": { "peso_kg": 45000, "volumen_m3": 120.5 },
    "ASIGNADA": { "peso_kg": 78000, "volumen_m3": 210.3 },
    "EN_PROCESO": { "peso_kg": 112000, "volumen_m3": 305.8 }
  },
  "alertas_vencimiento": [
    { "id": "uuid", "codigo": "OT-2026-00089", "shipper_nombre": "Acme Corp", "destino_ciudad": "Monterrey", "horas_restantes": 8.5 }
  ],
  "resumen_periodo": {
    "creadas": 110,
    "completadas": 72,
    "canceladas": 3,
    "tasa_completitud": 65.45
  }
}

• RLS: La query de agregacion esta filtrada por tenant_id automaticamente via la politica tenant_isolation_ot
• Performance: La query GROUP BY estado con indice idx_ot_estado es eficiente incluso con cientos de miles de registros. Para la alerta de vencimiento, usar indice idx_ot_fechas
• Cache: Evaluar cache de 30-60 segundos en Redis para el dashboard, ya que no requiere datos en tiempo real exacto

---

US-MAI003-010 - ERP Transportistas v1.0.0