# 03 — Contrato de Headers y Trazabilidad (traceId)
## Contrato de comunicación entre Cliente, Next.js Server Components y APIs de Downstream

> **Uso:** Esta guía detalla cómo estructurar y propagar los headers de autenticación e identificación del dispositivo, asegurando la trazabilidad del `traceId` de extremo a extremo.

---

## 1. El Ciclo de Vida del `traceId` (Request Correlation)

El `traceId` es la clave de correlación única generada por el cliente que permite rastrear una petición desde el navegador del usuario, pasando por Next.js App Router, Kong Gateway, hasta llegar a las APIs de Spring Boot y bases de datos.

En nuestro Internet Banking Seguro:
- El `traceId` se toma del valor `device.deviceSessionReference` enviado por el cliente o del ID de sesión generado por Next.js Middleware.
- Se propaga obligatoriamente en todas las cabeceras de las llamadas de servicios HTTP a APIs downstream.

---

## 2. Matriz de Headers Requeridos

Cuando Next.js Server Components o Route Handlers realizan peticiones al backend (Spring Boot), deben incluir el siguiente contrato de headers bancarios:

| Header | Tipo | Propósito | Fuente en Frontend |
|---|---|---|---|
| `Authorization` | Bearer Token | Autenticación del usuario final | Extraído de la cookie HTTP-only `access_token` |
| `traceId` | UUID / String | Correlación única de petición | `deviceSessionReference` o UUID de middleware |
| `appId` | String | Identificación del cliente (ej. portal web) | Variable de entorno (.env) del servidor |
| `agencyCode` | String | Identificación de la agencia física | Extraído del perfil del usuario (Zustand/Cookie) |
| `customerReferenceFintechId` | String | Identificación del cliente fintech | Extraído del JWT decodificado en Next.js server |

---

## 3. Ejemplo Práctico de Propagación de Headers

Al consumir el backend desde una llamada de servidor en Next.js (ej. en una API Route o Server Action):

```typescript
import { cookies } from 'next/headers';
import { NextRequest } from 'next/server';

export async function fetchCuentasUsuario(deviceSessionId: string) {
  const cookieStore = cookies();
  const token = cookieStore.get('access_token')?.value;

  if (!token) {
    throw new Error('No hay sesión activa para propagar credenciales');
  }

  // Estructuramos el contrato de headers obligatorios
  const headers = new Headers({
    'Authorization': `Bearer ${token}`,
    'traceId': deviceSessionId,
    'appId': process.env.API_APP_ID || 'PORTAL_WEB_SAFE',
    'customerReferenceFintechId': 'FT-1002394', // Extraído previamente del JWT
  });

  const response = await fetch(`${process.env.API_URL_SERVER}/cuentas`, {
    method: 'GET',
    headers: headers,
    next: { revalidate: 60 } // Cache inteligente
  });

  if (!response.ok) {
    throw new Error(`Fallo en backend: ${response.statusText}`);
  }

  return response.json();
}
```

---

## 4. Respuestas del Servidor al Cliente

Las API Routes locales de Next.js (`/app/api/...`) deben encapsular la respuesta al cliente siguiendo una estructura coherente y propagando el `traceId` de vuelta para facilitar la depuración:

```json
{
  "statusResponse": {
    "status": "ok",
    "statusCode": "200",
    "message": "Operación exitosa",
    "traceId": "c983d7aa-c81b-4f99-923f-e14b512c0199"
  },
  "data": {
    "cuentas": [
      { "id": "1", "saldo": 5000 }
    ]
  }
}
```