US-050 — Audit log filtrable

Detalle de la historia¶

Historia¶

Como administrador de FleteChat, quiero consultar el registro de actividad del sistema con filtros por usuario, recurso y rango de fechas, para investigar cambios sensibles, responder a solicitudes de auditoría y resolver incidentes operativos.

Persona de usuario¶

Aplica exclusivamente al rol admin. El audit log contiene información sensible (accesos denegados, cambios de roles, movimientos de precios); su consulta está centralizada en admin. Operator y price_manager no tienen acceso a esta vista.

Contexto de negocio¶

A lo largo de todas las historias del análisis, la frase "queda en el audit log" aparece como garantía de trazabilidad. Esta historia materializa esa promesa: una vista en el backoffice donde el admin puede buscar eventos por dimensiones útiles (quién hizo qué, sobre qué, cuándo) y exportar para compartir con auditoría externa o soporte.

El audit log no se edita ni se borra (ver PR-193): su valor como evidencia depende de su integridad. El sistema mantiene el log con retención mínima declarada (ver PR-192) y ofrece export para archivo fuera del sistema si la operación lo requiere.

Criterios de aceptación¶

Acceso¶

1. El backoffice ofrece una sección "Audit log" accesible exclusivamente al rol admin. Otros roles reciben 403.

Filtros y búsqueda¶

1. La vista permite filtrar por: a. Rango de fechas (desde / hasta). b. Usuario (nombre o email). c. Tipo de recurso (cliente, cotización, embarque, parámetro, usuario, catálogo, lista de precios, handoff, etc.). d. Identificador del recurso (por ejemplo, CNNN o ENNN). e. Acción (crear, editar, desactivar, reactivar, reset password, acceso denegado, etc.).
2. Los filtros son combinables con AND. La vista muestra resultados paginados ordenados por timestamp descendente por defecto.
3. Cada entrada del audit log muestra: timestamp, actor (usuario + rol al momento del evento), tipo de recurso, identificador del recurso, acción, diff o resumen del cambio, IP y user-agent del actor.

Detalle de un evento¶

1. El admin puede expandir una entrada para ver el diff completo del cambio (valor anterior y valor nuevo para cada campo modificado) cuando aplique. Para eventos sin diff (accesos denegados, cierre forzado de sesión), se muestra el contexto relevante (endpoint, motivo, IP).

Export¶

1. El admin puede exportar el resultado de la búsqueda a CSV con los filtros aplicados; el export incluye las mismas columnas visibles en la tabla.

Integridad¶

1. El audit log es inmutable (ver PR-193): no se edita ni se borra desde la UI ni desde la API del sistema. Las únicas excepciones aceptadas son (a) la eliminación automática por política de retención (ver PR-192) y (b) la anonimización de PII en entradas históricas cuando se ejecuta una solicitud de eliminación de datos del titular (ver PR-215 y la historia de derechos del titular). Toda excepción queda documentada y auditada.
2. Cada acceso al audit log (consulta y export) queda a su vez registrado como evento de tipo "audit_access", indicando admin, filtros usados y timestamp.

Eventos auditados¶

1. El audit log cubre, como mínimo, las siguientes categorías de evento (ver PR-231 para la matriz completa, mantenida en los parámetros globales): autenticación (login exitoso, login fallido, bloqueo de cuenta, desbloqueo, cierre forzado de sesión, reset de contraseña), gestión de usuarios (creación, cambio de rol, activación, desactivación), catálogos y parámetros globales (alta, edición, desactivación, reactivación), operaciones del cliente (creación y edición de cliente, alta de números adicionales, verificación, alta y cambio de consentimiento, opt-out activado o revocado), cotizaciones y embarques (emisión, aprobación formal, cambios de estatus manuales, reenvíos de instructivo, handoff solicitado, tomado y devuelto), import de listas de precios (upload, preview, aplicación), derechos del titular (solicitudes de acceso, portabilidad, eliminación, envío de enlace, intento de OTP, descarga, ejecución, anonimización de entradas históricas), acceso a la política de privacidad y accesos al propio audit log. Historias futuras que introduzcan eventos nuevos amplían la matriz de PR-231 sin requerir cambio en US-050.

Edge cases¶

• Volumen alto de resultados en una búsqueda amplia (por ejemplo, todos los eventos del último año). La tabla pagina; el export respeta los filtros y genera CSV con streaming para no bloquear el backoffice.
• Búsqueda que no arroja resultados. La vista muestra estado vacío con sugerencia de relajar filtros.
• Export con caracteres especiales (nombres con acentos, comas en descripciones). El CSV usa UTF-8 con BOM y escapa separadores (misma convención que US-030).
• Evento antiguo fuera de la ventana de retención (ver PR-192). El evento ya no está en la base; si el admin busca esa fecha, los resultados vienen vacíos con aviso de que la ventana de retención no los cubre.
• Acceso al audit log durante una investigación interna. Los accesos mismos quedan auditados; el admin que investiga verá sus propios accesos en la lista.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P1 — soporte operativo crítico para incidentes y cumplimiento; su ausencia no rompe la operación pero reduce significativamente la capacidad de respuesta.
• Tipo: feature

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-192 — Retención del audit log. El audit log se conserva por un mínimo de 24 meses (valor parametrizable desde los parámetros globales, ver US-046). Pasada la ventana, los eventos más antiguos se eliminan por política; cada eliminación automática queda registrada como evento del propio audit log.
• PR-193 — Audit log inmutable. El audit log no se edita ni se borra desde la UI ni desde la API del sistema. Las únicas excepciones aceptadas son (a) la eliminación automática por política de retención (PR-192) y (b) la anonimización selectiva descrita en PR-215 cuando se ejecuta una solicitud válida de eliminación de datos del titular.
• PR-215 — Excepción de anonimización por eliminación de datos del titular. Cuando se ejecuta una solicitud de eliminación de datos (historia de derechos del titular), todas las entradas históricas del audit log que contengan PII del titular eliminado en sus diffs o resúmenes se reescriben para anonimizar la PII (sustitución por un marcador estable como [anonimizado]), preservando el resto del registro (timestamp, actor, tipo de recurso, identificador, acción). La operación de anonimización se registra a su vez como evento del audit log, con identificación de la solicitud que la disparó y un conteo de entradas afectadas. No es borrado: es reescritura controlada para cumplir Ley 81 sin perder la evidencia estructural del evento.
• PR-231 — Matriz de eventos auditables. FleteChat mantiene una matriz exhaustiva de eventos auditables (categoría, tipo de recurso, acción, historia de origen) como parámetro global (ver US-046). Cada historia que introduzca una acción auditable nueva la registra en esta matriz antes de implementarse; la UI de US-050 lista los tipos disponibles para filtrado a partir de esta matriz. La matriz es de gestión exclusivamente admin.

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-192, PR-193, PR-215 y PR-231 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente