From 43b78c32aa8dbde1899588300f5ca90e30ed31cf Mon Sep 17 00:00:00 2001 From: "Carlos (Almeira)" Date: Thu, 20 Aug 2026 11:33:33 -0500 Subject: [PATCH] docs: expand developer context file with detailed technical history and resolved legacy bugs --- docs/developer_context.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/developer_context.md b/docs/developer_context.md index c6a838b..f012c96 100644 --- a/docs/developer_context.md +++ b/docs/developer_context.md @@ -61,3 +61,26 @@ PATH="/home/carlos/.nvm/versions/node/v22.14.0/bin:$PATH" bash package-hostinger Si eres un asistente de codificación de IA (como Antigravity), ten en cuenta lo siguiente al iniciar: 1. Este proyecto utiliza Next.js standalone. Cualquier cambio en las rutas o componentes debe comprobarse compilando el proyecto localmente. 2. La sanitización de HTML es muy estricta. Si necesitas añadir nuevos tags interactivos a las publicaciones, debes agregarlos al whitelist de `safeHtmlSchema` en `src/app/actions/entities.ts` y al sanitizador en `src/app/[slug]/page.tsx`. + +--- + +## 🏛️ Historial de Hitos Técnicos y Errores Resueltos (Logs de Sesiones) + +A lo largo del desarrollo de la plataforma, se han resuelto varios problemas críticos de arquitectura y renderizado. A continuación, se detallan para evitar regresiones: + +### 1. Error de Serialización de Componentes Servidor a Cliente ("Only plain objects...") +* **Problema**: Al intentar pasar colecciones de documentos directamente desde las Server Actions o Server Components de Next.js a componentes cliente (como `NewsCard` o `GlobalSidebar`), Next.js arrojaba el error: *"Only plain objects can be passed to Client Components"*. Esto ocurría porque los SDKs de Appwrite y ciertas funciones devuelven instancias de clase complejas u objetos con métodos prototípicos no serializables. +* **Solución**: Se implementó una política estricta de **desestructuración y serialización profunda** en los flujos de datos. En las Server Actions (por ejemplo, en `src/app/actions/entities.ts` y al consultar datos en `Home`), se aplica un parseo profundo `JSON.parse(JSON.stringify(data))` o mapeo explícito de propiedades antes de retornar los datos al cliente. + +### 2. Resolución de IDs de Media y Logotipo Corporativo Roto +* **Problema**: El logotipo corporativo y varios recursos multimedia en la interfaz fallaban en renderizarse de forma intermitente debido a inconsistencias al resolver los IDs de documentos de Appwrite frente a los IDs reales de los archivos en Storage. +* **Solución**: Se independizó la tabla de base de datos `media` de Appwrite de los IDs de archivo reales del Storage. Se ajustó el helper `getAppwriteImageUrl` para recibir el `file_id` y el `bucket_id` correctos mapeados desde el documento de la colección `media`. También se implementó una detección robusta de tipos de archivo (mimetype) en las acciones del servidor al subir archivos para categorizar correctamente imágenes y videos. + +### 3. Renderizado de Contenido Mixto (Texto Plano con HTML) +* **Problema**: Al publicar noticias, las etiquetas HTML guardadas por el editor enriquecido se mostraban en el frontend como texto plano legible (ej. se veía literalmente `

Texto

`), o bien el texto plano sin estructura perdía los saltos de línea. +* **Solución**: Se integró `isomorphic-dompurify` junto con la función `formatTextToHtml` en la vista de detalle. Esta función detecta si el contenido ya contiene etiquetas de estructura HTML. Si las tiene, respeta los elementos (sanitizándolos con un whitelist de seguridad XSS); si es texto plano, convierte inteligentemente los dobles saltos de línea en párrafos (`

`) y saltos individuales en retornos de carro (`
`), garantizando un diseño limpio. + +### 4. Migración de Infraestructura a Coolify y Soporte Multi-dominio +* **Problema**: Caídas constantes del servidor en Hostinger debido a limitaciones de memoria y errores 503 en despliegues tradicionales de Node.js. +* **Solución**: Se migró el entorno de despliegue a **Coolify**, una plataforma de self-hosting que gestiona contenedores Docker. Se configuró el enrutamiento para soportar múltiples orígenes y dominios sin errores de cabeceras CORS en el backend, mejorando la disponibilidad global de la web de Almeira. +