Módulo System

Le da al Super admin una pantalla para ver si algo falla y resolverlo sin entrar al servidor. Mide la salud de cada pieza, registra los eventos relevantes agrupados y ejecuta acciones dentro del alcance de la app: nunca toca Docker (ADR-0022, ADR-0023 y ADR-0059).

Endpoints

Todas van bajo /api/v1 y exigen sesión. Los tres permisos son solo del Super admin, salvo que se concedan a una persona. “Acción” quiere decir:

• Permiso system.actions.execute, revisado antes de validar.
• Reautenticación: el código de la aplicación de autenticación en mfa_code. Sin él responde 422 REAUTHENTICATION_REQUIRED, y el front abre el diálogo del código.
• 5 acciones por minuto por persona (throttle:system-actions).
• Registro en admin_actions con un tipo system_*, visible en Auditoría.

Salud

GET /system/health mide en el momento (LaravelHealthProbe) y lo interpreta con HealthRules:

La respuesta trae el estado general (el peor de todos), cada componente con sus datos, el modo mantenimiento (desde cuándo y quién lo activó) y la app (entorno, versión de Laravel y de PHP).

Señales de vida. El scheduler corre system:check cada minuto: deja su señal en Redis y encola WorkerHeartbeat, que deja la del worker cuando este lo procesa. Así se comprueba que la cola de verdad se procesa, no solo que el proceso existe.

Eventos

SystemEvents (puerto compartido en Shared) es la única forma de registrar. Lo usan:

• Agrupación. La huella es SHA-256 del tipo y su origen (la clase y la línea de un error, un servicio, una cuenta). DatabaseSystemEvents hace un INSERT … ON DUPLICATE KEY UPDATE: suma al contador, actualiza mensaje, contexto, última vez y código de soporte, y reabre lo resuelto.
• Sin datos sensibles. De un error de base de datos queda solo su código SQLSTATE. La cuenta de un login bloqueado va enmascarada (EmailAddress::masked). Nunca se guardan tokens, contraseñas ni contenido de jobs.
• Nunca rompe nada. Si registrar falla, queda en el log de Laravel y la petición sigue.
• Estados: abierto → revisado → resuelto; un resuelto se puede reabrir. Al cambiarlo queda quién y cuándo. Pedir el mismo estado no cambia nada.
• Lista: de la última vez más reciente a la más antigua, con filtros por estado, severidad y tipo (separados por comas) y el mismo cursor de la auditoría (TimeCursor).
• Limpieza: system:prune-events borra cada día los resueltos hace más de 90 días (trazo.system.events_retention_days).

Lo que no se registra (es una respuesta esperada, no una falla): las reglas de negocio (DomainException), los errores de validación, los 404 y los tokens vencidos. bootstrap/app.php las excluye del reporte de Laravel.

Acciones

Modo mantenimiento

EnforceMaintenance corre en todas las rutas de la API:

• Sin mantenimiento, no hace nada.
• Con mantenimiento, quien no tiene system.actions.execute recibe 503 SERVICE_UNAVAILABLE. Quien lo tiene sigue trabajando y cada respuesta lleva X-Maintenance: on.
• Siempre abiertos: auth.login, auth.mfa.challenge.* y auth.logout, para que el Super admin pueda entrar. /up no pasa por la API y responde normal.
• Si Redis no responde, se considera apagado: no conviene cerrar la app por una falla que ya es mayor.

Errores

Capas

Dónde está en el código

• backend/app/Modules/System/
• Registro compartido: Shared/Application/Ports/SystemEvents.php y Shared/Application/SystemEventType.php
• Manejo de errores y middleware: bootstrap/app.php; tareas: routes/console.php
• Pruebas: tests/Feature/System/SystemTest.php y tests/Unit/System/SystemDomainTest.php
• Tablas: system_events y admin_actions
• Operación: Sistema