# 04 — Gestión de Variables de Entorno y Configuración
## Estándar obligatorio de variables públicas, privadas y archivos .env en Next.js

> **Uso:** El manejo inadecuado de claves de entorno puede exponer información confidencial en el navegador del cliente. Esta guía define cómo gestionar de forma segura e incremental las configuraciones en Next.js.

---

## 1. Alcance de Variables: Privadas vs Públicas

Next.js por defecto protege todas las variables cargadas en el proceso de Node.js. El cliente (navegador) no tiene forma de leerlas a menos que se expongan de manera explícita.

### 1.1 Variables del Servidor (Privadas)
No llevan prefijo. Solo están disponibles en **Server Components, API Routes, Middleware, e Inbound/Outbound logs del lado del servidor**.
* **Ejemplos:** Llaves secretas de cifrado Kong, URLs directas de red de Spring Boot, contraseñas de servicio.
* *NUNCA* intentes acceder a ellas desde componentes declarados con `use client`. Retornarán `undefined`.

### 1.2 Variables del Cliente (Públicas)
Deben llevar **obligatoriamente** el prefijo `NEXT_PUBLIC_`. Next.js las inyecta en el bundle de Javascript durante el build, haciéndolas accesibles desde cualquier navegador.
* **Ejemplos:** URL pública de API routes locales, Google Analytics keys, variables de tema visual.
* *REGLA DE ORO:* Nunca asignes llaves secretas o tokens de servicio a variables con prefijo `NEXT_PUBLIC_`.

---

## 2. Matriz de Configuración del Proyecto

Las variables estándar que deben estar definidas en tu entorno local son:

| Variable | Tipo | Propósito | Ejemplo |
|---|---|---|---|
| `NODE_ENV` | Privada | Define el entorno actual | `development` / `production` |
| `API_URL_SERVER` | Privada | Endpoint directo de la red interna del backend Spring Boot | `https://api-internal.tudominio.com/api` |
| `NEXT_PUBLIC_API_URL` | Pública | URL de la API local de Next.js para peticiones del cliente | `http://localhost:3000/api` |
| `KONG_SECRET_KEY` | Privada | Clave de cifrado perimetral de datos | `k-secret-key-321-abc` |
| `ENABLE_SERVER_LOGS` | Privada | Activa/Desactiva escritura en logs/app.log | `true` |

---

## 3. Ejemplo de Archivo `.env.local`

Este archivo es de carácter local y **no se incluye en git** (debe estar en `.gitignore`).

```env
# ==========================================
# CONFIGURACIÓN DEL SERVIDOR (PRIVADAS)
# ==========================================
NODE_ENV=development
API_URL_SERVER=http://localhost:8080/api
KONG_SECRET_KEY=clave_secreta_para_cifrado_local_32bits
ENABLE_SERVER_LOGS=true

# ==========================================
# CONFIGURACIÓN DEL CLIENTE (PÚBLICAS)
# ==========================================
NEXT_PUBLIC_API_URL=http://localhost:3000/api
```

---

## 4. Validación de Entorno

Para evitar que la aplicación arranque con configuraciones incompletas o corruptas que generen fallos silenciosos, se recomienda validar las variables críticas al inicializar la app (por ejemplo, en `lib/config.ts`):

```typescript
// lib/config.ts
const requiredServerEnv = ['API_URL_SERVER', 'KONG_SECRET_KEY'];

export function validateEnvironment() {
  const missing = requiredServerEnv.filter((key) => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`[CRITICAL] Faltan variables de entorno requeridas en el servidor: ${missing.join(', ')}`);
  }
}
```