coconews/docs/POC_GUIDE.md

COCONEWS — Guía de la POC local

Esta guía te lleva de cero a tener COCONEWS corriendo en tu máquina en menos de 5 minutos, sin Docker, sin modelos ML y sin configuración compleja.

---

¿Qué es esta POC?

La POC (Proof of Concept) arranca únicamente:

• Backend Go (API REST en puerto 18080)
• Frontend React compilado y servido estáticamente (puerto 18001)
• PostgreSQL con 17 noticias de muestra en español, inglés y francés
• Redis en un puerto alternativo (6380) para no interferir con Redis del sistema

No se ejecutan los workers ML (NLLB-200, embeddings, NER, etc.). Las noticias ya vienen con traducciones y entidades precargadas en la BD.

---

Requisitos mínimos

Herramienta	Versión mínima	Instalar en Debian/Ubuntu
Go	1.22+ (recomendado 1.25)	sudo bash deploy/debian/prerequisites.sh
Node.js	18+	curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - && sudo apt install nodejs
PostgreSQL	14+	sudo apt install postgresql postgresql-client
Redis	6+	sudo apt install redis-server
Python 3 + bcrypt	opcional	pip3 install bcrypt (para auto-crear admin)

Para instalar todo de golpe en Debian/Ubuntu:

sudo bash deploy/debian/prerequisites.sh

---

Ejecución

# Desde la raíz del repositorio
bash poc/poc.sh

La primera vez tarda ~2-3 minutos (compilación Go + instalación de dependencias npm). Las siguientes ejecuciones arrancan en ~30 segundos.

Abrir en el navegador: http://127.0.0.1:18001

---

Login

Si tienes python3-bcrypt instalado, el script crea automáticamente un usuario admin:

Campo	Valor
Usuario	admin
Contraseña	admin123

Si no tienes bcrypt, regístrate desde la UI. El primer usuario registrado se convierte automáticamente en administrador (comportamiento del WelcomeWizard integrado).

---

Qué puedes explorar

1. Feed principal de noticias

En la página de inicio verás 17 noticias de muestra distribuidas en varias categorías:

• Ciencia y tecnología: GPT-5, inteligencia artificial, energía solar, exploración espacial
• Economía: criptomonedas, mercados, política fiscal
• Deportes: Lamine Yamal, Champions League, Fórmula 1
• Política internacional: Macron, conflictos globales
• Medio ambiente: energía eólica, cambio climático

2. Filtros y búsqueda

• Búsqueda por texto: prueba "inteligencia artificial" o "energía"
• Filtrar por idioma original: muestra noticias en inglés o francés tal como llegaron
• Solo traducidas: filtra las que ya tienen traducción al español (todas en la POC)
• Filtrar por categoría: Ciencia, Economía, Deportes, etc.
• Filtrar por entidades: personas, organizaciones, lugares

3. Entidades NER (personas, organizaciones, lugares)

Las noticias tienen entidades precargadas. En el panel lateral o en los tooltips verás:

Tipo	Ejemplos
Persona	Elon Musk, Lamine Yamal, Emmanuel Macron, Sam Altman
Organización	OpenAI, NASA, Tesla, FC Barcelona, UEFA
Lugar	España, China, Estados Unidos, París
Tema	inteligencia artificial, energía solar, criptomonedas

Haz clic en una entidad para ver todas las noticias relacionadas con ella.

4. Panel de administración

Accede con el usuario admin a:

• Feeds RSS: lista de fuentes configuradas (importa desde data/feeds.csv)
• Gestión de usuarios: ver y gestionar cuentas
• Configuración del sistema: parámetros del backend
• Estadísticas: contadores de noticias, feeds, entidades

Para importar los feeds de muestra incluidos en el repo:

1. Ve a Admin → Feeds
2. Usa la opción de importar CSV
3. Selecciona data/feeds.csv (incluye ~200 fuentes precargadas)

5. API REST directa

El backend expone una API REST documentada. Puedes explorarla directamente:

# Estadísticas generales
curl http://127.0.0.1:18080/api/stats | jq .

# Últimas noticias
curl http://127.0.0.1:18080/api/news | jq .

# Buscar noticias
curl "http://127.0.0.1:18080/api/news?q=inteligencia+artificial" | jq .

# Filtrar por idioma
curl "http://127.0.0.1:18080/api/news?lang=en" | jq .

# Entidades disponibles
curl http://127.0.0.1:18080/api/tags | jq .

# Noticias de una entidad específica
curl "http://127.0.0.1:18080/api/news?tag=OpenAI" | jq .

---

Empezar de cero

Si quieres reiniciar la BD de prueba (por ejemplo, tras cambiar el seed):

bash poc/poc.sh --clean

Esto borra la BD coconews_poc y la recrea desde cero.

---

Estructura de los datos de prueba

El seed está en poc/seed.sql. Contiene:

Elemento	Cantidad
Noticias en español	10
Noticias en inglés (con traducción)	5
Noticias en francés (con traducción)	2
Traducciones en tabla traducciones	17
Entidades NER en tabla tags	25
Asociaciones noticia↔entidad	~45

Los feeds de origen son ficticios (techcrunch.com, bbc.com, lemonde.fr, etc.) pero representan la estructura real que llegaría del ingestor RSS.

---

Diferencias con producción

Característica	POC	Producción
Traducción automática	Precargada en BD	NLLB-200 en tiempo real
Extracción de entidades	Precargada en BD	spaCy es_core_news_lg
Embeddings semánticos	No disponible	MiniLM (sentence-transformers)
Búsqueda vectorial	No disponible	Qdrant
Ingesta de feeds	No activa	rss-ingestor-go continuo
Workers ML	No activos	7 workers Python
Clusterización	No activa	Worker cluster
Redis	Puerto 6380 local	Puerto 6379 con auth

---

Solución de problemas

El backend no arranca

# Ver log completo
cat /tmp/coconews-poc/logs/backend.log

# Probar conexión BD manualmente
psql "postgres://coconews_poc:poc_password_local@127.0.0.1:5432/coconews_poc" -c 'SELECT COUNT(*) FROM noticias;'

# Probar Redis
redis-cli -p 6380 ping

El frontend muestra pantalla en blanco

Verifica que el backend está respondiendo:

curl http://127.0.0.1:18080/api/stats

Si el backend responde pero el frontend no carga datos, puede ser un problema de CORS o de la URL de la API. Revisa la consola del navegador (F12).

Error "puerto en uso"

# Ver qué usa el puerto
ss -tlnp | grep 18080
ss -tlnp | grep 18001
ss -tlnp | grep 6380

# Matar proceso
kill $(lsof -ti:18080)

O edita las variables POC_*_PORT al inicio de poc/poc.sh para usar puertos diferentes.

Error de compilación Go

# Descargar dependencias
cd backend && go mod download && go mod tidy

# Verificar versión
go version   # necesita 1.22+

# Ver log
cat /tmp/coconews-poc/logs/build-backend.log

Error npm install

# Limpiar caché y reintentar
cd frontend && rm -rf node_modules && npm install

# Ver log
cat /tmp/coconews-poc/logs/npm-install.log

PostgreSQL no arranca

sudo systemctl status postgresql
sudo journalctl -u postgresql -n 30
sudo pg_ctlcluster 16 main status

---

Logs de la POC

Todos los logs se guardan en /tmp/coconews-poc/logs/:

Archivo	Contenido
backend.log	Logs del servidor Go en tiempo real
build-backend.log	Salida de compilación Go
build-frontend.log	Salida de npm run build
redis.log	Logs de Redis
psql-schema.log	Ejecución del schema SQL
psql-seed.log	Carga de datos de prueba
frontend-serve.log	Servidor estático npx serve

Para seguir los logs en tiempo real mientras la POC corre:

# En otra terminal
tail -f /tmp/coconews-poc/logs/backend.log

---

Siguiente paso: despliegue completo

Cuando quieras probar el sistema completo con los workers ML:

# En un servidor Debian
sudo bash deploy/debian/prerequisites.sh
sudo bash deploy/debian/install.sh

Consulta DEPLOY_DEBIAN.md para la guía completa.