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.

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.