Contexto de Desarrollo y Arquitectura - Almeira Web

Este archivo sirve como memoria técnica e histórica para los desarrolladores y agentes de IA (como Antigravity) que continúen trabajando en este proyecto.

🛠️ Stack Tecnológico

Core: Next.js 16 (App Router, con Server Actions habilitados).
Base de Datos y Backend: Appwrite (Autenticación, Base de datos y Almacenamiento).
Editor de Contenido: Tiptap Editor (Rich Text con soporte para imágenes, videos y embeds).
Estilos: TailwindCSS.
Empaquetado: Node standalone.

📂 Configuración del Entorno (`.env.local`)

Para levantar el proyecto en desarrollo local (npm run dev), se requiere un archivo .env.local en la raíz con el siguiente formato:

NEXT_PUBLIC_APPWRITE_ENDPOINT=https://appwrite.almeira.com.co/v1
NEXT_PUBLIC_APPWRITE_PROJECT_ID=69b84df5003bd8957c5c
APPWRITE_API_KEY=standard_cce3cd... (Ver Gitea o Consola Appwrite)
APPWRITE_DATABASE_ID=almeira
NEXT_PUBLIC_APPWRITE_MEDIA_BUCKET_ID=media_bucket

# Evolution API (WhatsApp)
EVOLUTION_API_URL=https://evolution.almeira.com.co
EVOLUTION_API_KEY=mgXxu2eA...
EVOLUTION_INSTANCE_NAME=AutomataAlmeira

# Server Config
SERVER_ACTIONS_BODY_SIZE_LIMIT=100mb

🎬 Solución del Reproductor de Video (Hito Clave)

Durante el desarrollo, se resolvió un problema crítico donde los videos subidos a las publicaciones no se reproducían en producción:

1. El Origen del Problema

Appwrite utiliza el endpoint /preview para imágenes y miniaturas. Sin embargo, para archivos de video, el navegador requiere soporte de reproducción por rangos (Range Requests) y streaming. El endpoint /preview limita la reproducción y bloquea el video en Safari y Chrome. La solución es usar el endpoint /view.

2. Implementación de la Corrección

En el Editor (RichTextEditor.tsx / MediaGridSelector.tsx): Se configuró la biblioteca de medios y el nodo de video de Tiptap para reemplazar automáticamente /preview? por /view? en las URLs de origen de los videos.
En el Servidor (entities.ts): Se actualizó el validador safeHtmlSchema que limpia el código HTML con DOMPurify para permitir las etiquetas <video> y <source>, junto a los atributos controls, src, muted, loop, autoplay, preload y poster. Además, normaliza cualquier URL de video errónea antes de guardarla en la base de datos.
En la Publicación ([slug]/page.tsx): Se implementó una mejora dinámica que extrae el primer video del contenido y lo coloca como Hero Media en la cabecera (usando la imagen destacada como poster de portada), eliminando el video redundante del cuerpo del texto. También normaliza URLs antiguas al vuelo.

🔄 Scripts de Despliegue y Compilación

package-hostinger.sh: Script Bash que compila el proyecto en modo standalone, copia los assets estáticos de .next/static y public/, inyecta la configuración para PM2 (ecosystem.config.js), configura el package.json para que Hostinger corra directamente server.js y comprime todo en un archivo zip listo para subir: almeira-web-deploy.zip.

Comando para empaquetar:

PATH="/home/carlos/.nvm/versions/node/v22.14.0/bin:$PATH" bash package-hostinger.sh

💡 Instrucciones para Agentes de IA (Continuar Trabajo)

Si eres un asistente de codificación de IA (como Antigravity), ten en cuenta lo siguiente al iniciar:

Este proyecto utiliza Next.js standalone. Cualquier cambio en las rutas o componentes debe comprobarse compilando el proyecto localmente.
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.

3.8 KiB Raw Blame History