# 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:

```bash
sudo bash deploy/debian/prerequisites.sh
```

---

## Ejecución

```bash
# 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:

```bash
# 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
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](../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

```bash
# 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:
```bash
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"

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:

```bash
# 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:

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

Consulta [DEPLOY_DEBIAN.md](DEPLOY_DEBIAN.md) para la guía completa.