workspace/projects/gamilit/docs/90-transversal/reportes-implementacion/frontend/MIGRATION-GUIDE-API-CONFIG.md

GUIA DE MIGRACION - Configuracion de API (Variables Granulares)

Fecha: 2025-11-24 Afecta a: Todos los desarrolladores del proyecto GAMILIT Frontend

---

QUE CAMBIO

El sistema de configuracion de API ahora usa variables granulares en lugar de URLs completas.

ANTES (Ya no funciona)

VITE_API_URL=http://localhost:3006/api
VITE_WS_URL=ws://localhost:3006

AHORA (Requerido)

VITE_API_HOST=localhost:3006
VITE_API_PROTOCOL=http
VITE_API_VERSION=v1
VITE_WS_HOST=localhost:3006
VITE_WS_PROTOCOL=ws

---

COMO ACTUALIZAR TU ENTORNO LOCAL

Paso 1: Actualizar tu archivo .env

cd apps/frontend

Edita tu archivo .env y reemplaza las variables legacy con las granulares:

# ELIMINAR ESTAS LINEAS (legacy):
# VITE_API_URL=http://localhost:3006/api
# VITE_WS_URL=ws://localhost:3006

# AGREGAR ESTAS LINEAS (granulares):
VITE_API_HOST=localhost:3006
VITE_API_PROTOCOL=http
VITE_API_VERSION=v1
VITE_WS_HOST=localhost:3006
VITE_WS_PROTOCOL=ws

Paso 2: Validar tu configuracion

npm run validate-env

Deberias ver:

✅ VITE_API_HOST: localhost:3006
✅ VITE_API_PROTOCOL: http
✅ Environment validation PASSED

Paso 3: Reiniciar tu servidor de desarrollo

npm run dev

---

TU CODIGO NO NECESITA CAMBIOS

El codigo existente que usa env.apiUrl y env.wsUrl sigue funcionando:

import { env } from '@/config/env';

// ✅ Esto sigue funcionando igual
const response = await fetch(`${env.apiUrl}/users`);
const socket = io(env.wsUrl);

Las URLs ahora se construyen automaticamente desde las variables granulares.

---

NUEVAS CAPACIDADES DISPONIBLES

Si necesitas acceso granular a los componentes de configuracion:

import { env } from '@/config/env';

// Acceso granular a protocolo, host, version
const protocol = env.api.protocol;  // 'http'
const host = env.api.host;          // 'localhost:3006'
const version = env.api.version;    // 'v1'

// Construir URLs personalizadas
const customUrl = `${env.api.protocol}://${env.api.host}/custom-endpoint`;

// WebSocket granular
const wsProtocol = env.ws.protocol; // 'ws'
const wsHost = env.ws.host;         // 'localhost:3006'

---

CONFIGURACION PARA DIFERENTES ENTORNOS

Development (.env)

VITE_API_HOST=localhost:3006
VITE_API_PROTOCOL=http
VITE_API_VERSION=v1
VITE_WS_HOST=localhost:3006
VITE_WS_PROTOCOL=ws

Production (.env.production)

VITE_API_HOST=74.208.126.102:3006  # o dominio cuando este disponible
VITE_API_PROTOCOL=http             # cambiar a https cuando SSL este configurado
VITE_API_VERSION=v1
VITE_WS_HOST=74.208.126.102:3006
VITE_WS_PROTOCOL=ws                # cambiar a wss cuando SSL este configurado

Testing (.env.test)

VITE_API_HOST=localhost:3006
VITE_API_PROTOCOL=http
VITE_API_VERSION=v1
VITE_WS_HOST=localhost:3006
VITE_WS_PROTOCOL=ws
VITE_MOCK_API=false

---

VALORES POR DEFECTO

Si no defines una variable, se usan estos defaults:

VITE_API_HOST     -> 'localhost:3006'
VITE_API_PROTOCOL -> 'http'
VITE_API_VERSION  -> 'v1'
VITE_WS_PROTOCOL  -> 'ws'
VITE_WS_HOST      -> mismo que VITE_API_HOST

Esto significa que en development puedes omitir estas variables y funcionara con localhost:3006.

---

VALIDACIONES DE PRODUCCION

El script de validacion ahora verifica:

1. Variables requeridas presentes
2. Host no apunta a localhost en produccion
3. Protocolo es HTTPS en produccion (warning si no)
4. WebSocket usa WSS en produccion (warning si no)
5. Flags de debug deshabilitados en produccion

---

TROUBLESHOOTING

Error: "Missing required variable: VITE_API_HOST"

Solucion: Agrega VITE_API_HOST=localhost:3006 a tu archivo .env

Error: "Missing required variable: VITE_API_PROTOCOL"

Solucion: Agrega VITE_API_PROTOCOL=http a tu archivo .env

Las URLs construidas son incorrectas

Verificar:

npm run validate-env

Revisa que todas las variables esten correctamente definidas.

Mi build falla con errores de configuracion

Solucion:

1. Verifica que tu .env o .env.production tenga las variables granulares
2. Ejecuta npm run validate-env para verificar configuracion
3. Si persiste, copia .env.example como base

---

REFERENCIA RAPIDA

Variables Requeridas (Minimo)

VITE_API_HOST=localhost:3006
VITE_API_PROTOCOL=http

Variables Opcionales (con defaults)

VITE_API_VERSION=v1          # default: 'v1'
VITE_WS_HOST=localhost:3006  # default: mismo que API_HOST
VITE_WS_PROTOCOL=ws          # default: 'ws'
VITE_API_TIMEOUT=30000       # default: 30000

---

ARCHIVOS DE REFERENCIA

• Ejemplo completo: apps/frontend/.env.example
• Documentacion detallada: IMPLEMENTATION-REPORT-API-CONFIG-HOMOLOGATION-2025-11-24.md
• Resumen ejecutivo: RESUMEN-HOMOLOGACION-API-CONFIG-2025-11-24.md
• Codigo fuente: apps/frontend/src/config/env.ts

---

PREGUNTAS FRECUENTES

Q: Tengo que cambiar mi codigo?

A: No. El codigo existente sigue funcionando sin cambios.

Q: Que pasa con VITE_API_URL y VITE_WS_URL?

A: Ya no se usan. Se construyen automaticamente desde variables granulares.

Q: Por que este cambio?

A: Para unificar configuracion, eliminar duplicacion, y facilitar cambios (ej: cambiar solo protocolo sin tocar host).

Q: Que pasa si no actualizo mi .env?

A: El build fallara con error "Missing required variable".

Q: Funciona con mi setup de Docker/CI/CD?

A: Si, solo actualiza las variables de entorno inyectadas.

---

SOPORTE

Si tienes problemas con la migracion:

1. Revisa esta guia
2. Consulta IMPLEMENTATION-REPORT-API-CONFIG-HOMOLOGATION-2025-11-24.md
3. Verifica tu configuracion con npm run validate-env
4. Compara tu .env con .env.example

---

Version: 1.0 Ultima actualizacion: 2025-11-24