fundamental.txt

### **Análisis Post-Mortem: Diagnóstico y Solución de Errores en Despliegue (Vercel)**

El proceso de depuración para estabilizar la aplicación `merx` en producción involucró la resolución de 3 problemas principales que se manifestaron de forma consecutiva.

**1. Problema de Archivos Estáticos (Error Visual/404 en CSS/JS):**
*   **Síntoma:** La página cargaba sin estilos o sin funcionalidades del lado del cliente.
*   **Causa:** Vercel, por convención, busca los archivos estáticos (CSS, JS, imágenes) en un directorio raíz llamado `public`. Nuestro proyecto los tenía en una carpeta `static`, que no es servida por defecto.
*   **Solución:** Se creó la carpeta `public` y se movieron los archivos estáticos a ella. Se actualizó la línea `app.use(express.static(...))` en `server.js` para que apuntara a `public`.

**2. Corrupción del Repositorio Local de Git (Comandos Inconsistentes):**
*   **Síntoma:** `git status` no mostraba los archivos nuevos que se añadían, lo que impedía confirmar los cambios y desplegar la solución anterior.
*   **Causa:** El índice de Git (el área de preparación o "staging") estaba en un estado corrupto o inconsistente, un problema poco común pero muy bloqueante.
*   **Solución:** Se forzó la reconstrucción del índice de Git ejecutando `git rm -r --cached .` (para "olvidar" temporalmente todos los archivos) seguido de `git add .` (para re-evaluarlos todos desde cero). Esto limpió el estado anómalo.

**3. Error 500 en la API (La Causa Raíz del Fallo en Producción):**
*   **Síntoma:** La aplicación fallaba con un "Error Interno del Servidor" al intentar usar la funcionalidad principal.
*   **Causa:** El código en el servidor (`server.js`) intentaba leer archivos de contexto (`.json`, `.txt`) desde una carpeta local (`conocimientos/`). Sin embargo, esta carpeta no estaba dentro del directorio del proyecto (`merxv2.1`), por lo que no se subió a Vercel. El servidor en la nube no podía encontrar los archivos y crasheaba.
*   **Solución:** Se copió la carpeta `conocimientos` con sus archivos necesarios al interior del proyecto `merxv2.1`. Al hacer esto, los archivos se incluyeron en el repositorio de Git y, por lo tanto, en el despliegue de Vercel, volviéndose accesibles para el código.

---

### **Reglas Fundamentales y Buenas Prácticas para Evitar Errores**

**1. Las Dependencias Externas son tu Principal Foco de Atención:**
*   **Archivos Locales:** Si tu código necesita leer un archivo (`fs.readFile`), ese archivo **DEBE** estar dentro de la carpeta de tu proyecto y comprometido en Git. El servidor en la nube no tiene acceso a los archivos de tu computadora personal.
*   **Variables de Entorno (API Keys, Secretos):** NUNCA escribas una clave o contraseña directamente en el código.
    *   Utiliza siempre las **Variables de Entorno** que ofrece tu plataforma de despliegue (Vercel, Netlify, etc.).
    *   **¡El nombre debe ser EXACTO!** Un error de una sola letra entre el nombre en Vercel (`GEMINI_API_KEY`) y el nombre en tu código (`process.env.GEMINI_API_KEY`) hará que todo falle. Revisa dos veces.

**2. Respeta las Convenciones de tu Plataforma (Vercel):**
*   **Directorio `public`:** Para todo lo que el navegador del usuario debe ver (CSS, JS de cliente, imágenes, fuentes), colócalo aquí. Es la regla de oro para archivos estáticos en Vercel.
*   **Rutas de API:** Tus rutas en Express (`app.post('/api/...')`) se convierten en "Serverless Functions". Son efímeras: se ejecutan, hacen su trabajo y se apagan. No pueden guardar archivos o mantener un estado interno entre llamadas.

**3. `console.log()` es tu Mejor Amigo para Depurar:**
*   Cuando algo falle en producción, la única forma de saber qué pasa adentro es a través de los logs.
*   No esperes a que algo falle. Añade `console.log()` en puntos clave de tu código para dejar un rastro (`"Entrando a la función X"`, `"Llamando a la API externa..."`, `"Error capturado: " + error.message`).
*   La pestaña **"Logs"** en tu dashboard de Vercel es tu herramienta de diagnóstico más importante. Revísala siempre primero.

---

### **Reglas Derivadas de Errores de Implementación (Octubre 2025)**

**1. Sincronización HTML/JS es Crítica:**
*   Al renombrar un `id` o `class` en un archivo HTML, es **obligatorio** buscar y actualizar todas sus referencias en los archivos JavaScript (`.js`) que dependen de él. Un desfase aquí romperá toda la interactividad de la página, a menudo de forma silenciosa (sin errores en consola).

**2. Programación Defensiva con APIs (Especialmente IA):**
*   Nunca confíes ciegamente en la estructura de datos de una API. El código del frontend **debe** tener lógica para validar la respuesta y manejar casos donde los campos esperados (`section`, `chapter`, etc.) no vengan o sean nulos. No asumir el formato de la respuesta previene que la UI muestre JSON crudo o se rompa.
*   Para obtener datos consistentes (como nombres de secciones), es más robusto que la IA devuelva un **ID** y buscar el nombre en un archivo local (`.json`), en lugar de pedirle a la IA que devuelva un nombre formateado.

**3. Una Función para Una Tarea:**
*   No reutilices una función de formato (ej. `classificationToUI`) para una estructura de datos para la que no fue diseñada. Si los datos del "paso 1" y del "informe final" son diferentes, cada uno debe tener su propia función de formato (ej: `reportToUI`).

**4. Cuidado con los Tipos de Datos:**
*   Al comparar datos de distintas fuentes (ej: un número de un `.json` local y un valor de una IA que podría ser texto), evita la comparación estricta (`===`). Usa comparación flexible (`==`) o convierte explícitamente el tipo (`parseInt()`) para prevenir errores de tipo de dato que son difíciles de depurar.