# 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:**
```json
{
  "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*