metis-desk/docs/arquitectura/flujo-http.md

# Flujo HTTP

Para operaciones de negocio, usar:

```text
RequestSchema → validación en route → Controller
→ UseCase({ dto, context }) → InputMapper → Value Objects / Props
→ servicios de Application / Domain
```

Las rutas declaran validación y guards de autenticación y autorización.
El controller obtiene el contexto autenticado, invoca el caso de uso y traduce Result a HTTP.
Application no conoce Express y no construye agregados directamente desde DTOs HTTP.

El InputMapper adapta primitivas y contexto, crea Value Objects y devuelve Result.
Solo crear un RequestMapper adicional cuando exista adaptación HTTP real, como combinar body, params y query.

Los identificadores de la organización y del actor se obtienen del contexto autenticado.
customerId puede identificar al cliente atendido, pero siempre se comprueba que el actor tenga acceso antes de consultar o modificar sus datos.

## Salud y middleware común

GET /api/__health devuelve status y time. Rechaza parámetros de consulta desconocidos.
Comprueba únicamente que el proceso responde; no demuestra disponibilidad de base de datos ni autorización.
No requiere un caso de uso porque no contiene comportamiento de negocio.

Cada petición obtiene un UUID generado por el servidor, devuelto como x-request-id.
Los errores HTTP tienen code y requestId. No devuelven detalles internos.
El middleware registra método, estado, duración e identificador; no registra URL, query, cabeceras ni cuerpo.

Ante una excepción inesperada que se traduce en HTTP 500, emite además un evento JSON `http_error` en stderr (`console.error`), con el mismo `requestId` de la respuesta y del evento `http_request`. Incluye método, estado y diagnósticos técnicos: nombre del error, código de Node/MariaDB, número de error y SQLState cuando existen, y frames con archivos y líneas de origen. Recorre `cause` o `parent` de Sequelize hasta cinco errores, sin repetir ciclos; cada diagnóstico conserva hasta veinte frames.

No se serializa el objeto Error completo ni sus mensajes arbitrarios, que pueden incluir SQL, parámetros o credenciales. Los frames excluyen el mensaje completo, incluso si contiene varias líneas. Los valores lanzados que no son Error se identifican como `NonErrorThrown`. Los errores esperados del parser (400, 413 y 415) conservan únicamente el registro de petición. La respuesta HTTP continúa exponiendo solo `code` y `requestId`.

El servidor escucha en 127.0.0.1. La interfaz de desarrollo usa el proxy de Vite para /api.
Las rutas de datos de clientes requieren sesión autenticada y los guards correspondientes. Las escrituras validan origen y CSRF antes de ejecutar la operación.