Módulo Audit

Muestra lo que ya guardan otros módulos: el historial de todos los incidentes (incident_activities) y el registro de la administración (admin_actions). No escribe nada: solo lee, filtra y decide quién ve qué. Cada registro trae la IP y el navegador desde donde se hizo, que el historial de un incidente no muestra.

Endpoints

Todos exigen sesión.

Parámetros de las dos listas:

Un filtro que apunta a algo que no existe (una persona, un tipo o un incidente) devuelve la lista vacía.

GET /api/v1/audit/incidents?filter[incident]=26-629

{
  "data": [{
    "id": 3159,
    "created_at": "2026-10-24T21:54:57+00:00",
    "type": { "code": "status_changed", "name": "Cambio de estado" },
    "user": { "id": "01m5nzqh9rk9w9sr18d87hwkat", "name": "Carlos Mejía" },
    "incident": { "id": "01m5qyhqrkxexrgj35w0b3fh9y", "code": "TZ-26-0629", "title": "…", "deleted": false },
    "changes": { "status": { "from": { "code": "open", "name": "Abierto" }, "to": { "code": "in_progress", "name": "En progreso" } } },
    "ip_address": "172.20.0.1",
    "user_agent": "Mozilla/5.0 …",
    "links": { "incident": true }
  }],
  "meta": { "next_cursor": "MjAyNi0xMC0yNCAyMTo1NDo1NHwzMTU4", "from": "2026-09-24T…", "to": "2026-10-24T…" }
}

En la administración, cada registro trae target_user y target_role en lugar de incident, y details en lugar de changes. Un rol eliminado llega con deleted: true y con el código y el nombre que quedaron en el detalle.

Quién ve qué

• Dos permisos. Con un solo audit.view, el Administrador veía los incidentes de todos y el Supervisor veía la administración. Los dos se pueden conceder a una persona puntual.
• Alcance de la administración (AdminAuditScope). Para quien no es la cima, un registro se ve si lo hizo esa persona, o si la persona o el rol afectados están por debajo de su nivel.
  • El nivel de una persona es el de su rol más alto hoy.
  • Un rol eliminado se mide por el nivel guardado en el detalle.
  • Un registro sin persona ni rol afectado solo lo ve quien lo hizo y la cima. Es el caso de las exportaciones de incidentes (incidents_exported), que guardan el número de filas y los filtros.
  • La misma regla está en SQL (DatabaseAdminAudit) y una prueba compara las dos registro por registro.
• Enlaces (links): el back dice si quien consulta puede abrir lo que se nombra.
  • El incidente, con la misma regla del detalle (IncidentAccess).
  • La ficha de la persona, con users.view.
  • La del rol, con roles.manage y si el rol todavía existe.

Cursor

• Orden. De lo más reciente a lo más antiguo, por (created_at, id). El id desempata los registros del mismo segundo.
• Cursor. Es la fecha y el id del último registro entregado, en base64 sin relleno: opaco para el front. Uno alterado responde 422 con INVALID_CURSOR.
• Fin de la lista. Se pide una fila de más: si llega, hay otra tanda y next_cursor trae su cursor; si no, va en null.
• Sin total. No se cuenta la tabla. Contar recorrería todo el rango, cada vez más grande.

Rendimiento medido sobre 523.088 filas: menos de 2 ms en cada caso, sin ordenar en memoria (ADR-0056).

Errores

Capas

Quien consulta se arma con RequestAdmin del módulo Users: nivel y permisos efectivos.

Dónde está en el código

• backend/app/Modules/Audit/
• Rutas: Http/routes.php
• Migraciones: 000031 y 000032
• Pruebas: tests/Feature/Audit/AuditTest.php y tests/Unit/Audit/AuditDomainTest.php
• Decisión: ADR-0056