# US-MAI005-010: Consultar logs de despacho

**ID:** US-MAI005-010
**Modulo:** MAI-005 (Despacho)
**Prioridad:** Media
**Story Points:** 3

---

## Historia de Usuario

**Como** supervisor de operaciones
**Quiero** consultar el historial de asignaciones y reasignaciones de despacho
**Para** auditar decisiones, analizar patrones y mejorar procesos operativos

---

## Criterios de Aceptacion

### CA-001: Listar logs de despacho
**Dado** que accedo a la seccion de auditoria de despacho
**Cuando** cargo la vista de logs
**Entonces** veo una lista de acciones ordenadas por fecha descendente

### CA-002: Mostrar informacion relevante
**Dado** que veo la lista de logs
**Cuando** observo cada registro
**Entonces** veo: fecha/hora, viaje, accion, unidad, operador, usuario que ejecuto

### CA-003: Filtrar por viaje
**Dado** que busco logs de un viaje especifico
**Cuando** ingreso el codigo del viaje
**Entonces** veo solo los logs relacionados con ese viaje

### CA-004: Filtrar por unidad
**Dado** que quiero ver historial de una unidad
**Cuando** filtro por codigo de unidad
**Entonces** veo todas las asignaciones y reasignaciones de esa unidad

### CA-005: Filtrar por tipo de accion
**Dado** que quiero ver solo reasignaciones
**Cuando** filtro por accion 'REASSIGNED'
**Entonces** veo solo los registros de reasignacion con sus motivos

### CA-006: Filtrar por rango de fechas
**Dado** que quiero ver logs de un periodo
**Cuando** selecciono fecha inicio y fin
**Entonces** veo solo los logs dentro de ese rango

### CA-007: Ver detalle de log
**Dado** que veo un registro en la lista
**Cuando** hago click para ver detalle
**Entonces** veo toda la informacion incluyendo: score, motivo, detalle, unidad anterior (si reasignacion)

### CA-008: Exportar a Excel
**Dado** que tengo una consulta de logs
**Cuando** solicito exportar
**Entonces** descargo un archivo Excel con los logs filtrados

---

## Mockup / UI

```
+-----------------------------------------------------------------------+
| AUDITORIA DE DESPACHO - LOGS                                          |
+-----------------------------------------------------------------------+
| Filtros:                                                              |
| Viaje: [VJE-____] Unidad: [U-___] Accion: [Todas v]                  |
| Fecha: [01/01/2026] a [27/01/2026]  Usuario: [Todos v]               |
| [Buscar]                                              [Exportar Excel]|
+-----------------------------------------------------------------------+
|                                                                       |
|  Fecha/Hora        | Viaje    | Accion     | Unidad | Operador     |  |
|  ------------------|----------|------------|--------|--------------|  |
|  27/01 10:35:22    | VJE-0456 | REASSIGNED | U-012  | Carlos Lopez |  |
|  [>] Reasignado desde U-005 | Motivo: Operador no disponible        |  |
|  -------------------------------------------------------------------|  |
|  27/01 08:30:15    | VJE-0456 | ASSIGNED   | U-005  | Juan Perez   |  |
|  [>] Score: 87.5 | Asignado por: admin@transportes.com              |  |
|  -------------------------------------------------------------------|  |
|  27/01 08:29:45    | VJE-0456 | SUGGESTED  | U-005  | Juan Perez   |  |
|  [>] Sugerencia #1 de 5 | Score: 87.5                                |  |
|  -------------------------------------------------------------------|  |
|  26/01 16:45:00    | VJE-0455 | CANCELLED  | U-008  | Roberto S.   |  |
|  [>] Motivo: Viaje cancelado por cliente                             |  |
|  -------------------------------------------------------------------|  |
|  26/01 14:20:33    | VJE-0455 | ASSIGNED   | U-008  | Roberto S.   |  |
|  [>] Score: 72.0 | Asignado por: dispatch@transportes.com           |  |
|  -------------------------------------------------------------------|  |
|                                                                       |
|  Mostrando 1-50 de 234 registros    [< Anterior] [1] [2] [3] [>]     |
|                                                                       |
+-----------------------------------------------------------------------+

+-----------------------------------------------------------------------+
| DETALLE DE LOG                                                   [X]  |
+-----------------------------------------------------------------------+
|                                                                       |
|  ID: log-2026012710352                                                |
|  Fecha: 27 Enero 2026, 10:35:22                                       |
|                                                                       |
|  VIAJE                                                                |
|  Codigo: VJE-0456                                                     |
|  Cliente: Transportes MX                                              |
|  Ruta: CDMX -> Queretaro                                              |
|                                                                       |
|  ACCION: REASSIGNED                                                   |
|                                                                       |
|  UNIDAD ANTERIOR                                                      |
|  Unidad: U-005 Kenworth T680                                          |
|  Operador: Juan Perez Garcia                                          |
|                                                                       |
|  NUEVA UNIDAD                                                         |
|  Unidad: U-012 Freightliner Cascadia                                  |
|  Operador: Carlos Lopez Hernandez                                     |
|                                                                       |
|  MOTIVO                                                               |
|  Tipo: Operador no disponible                                         |
|  Detalle: Operador reporto enfermedad esta manana                     |
|                                                                       |
|  EJECUTADO POR                                                        |
|  Usuario: admin@transportes.com                                       |
|  IP: 192.168.1.100                                                    |
|                                                                       |
|  SCORE AL MOMENTO                                                     |
|  Nueva unidad: 72.0                                                   |
|  Desglose: Dist 70 | Cap 100 | Disp 50 | Skills 100                  |
|                                                                       |
|                                                              [Cerrar] |
+-----------------------------------------------------------------------+
```

---

## Notas Tecnicas

- Endpoint: `GET /api/dispatch/logs`
- Requiere permiso `dispatch:audit`
- Paginacion con limit/offset (default 50 por pagina)
- Indices en `dispatch_logs`: trip_id, unit_id, action, timestamp
- Exportacion genera archivo Excel via stream (no cargar todo en memoria)
- Retencion de logs: 2 anios (configurable por tenant)
- Incluir IP del usuario en metadata para auditoria

---

## Definicion de Done

- [ ] Endpoint /dispatch/logs implementado
- [ ] UI de lista de logs paginada
- [ ] Filtros funcionales (viaje, unidad, accion, fechas, usuario)
- [ ] Modal de detalle de log
- [ ] Exportacion a Excel
- [ ] Indices de base de datos optimizados
- [ ] Politica de retencion configurada
- [ ] Tests de queries con filtros
- [ ] Tests de exportacion

---

*US-MAI005-010 - Modulo MAI-005 - ERP Transportistas*