10f0555c46
- poc/seed.sql: 17 noticias (ES/EN/FR) con traducciones y 25 entidades NER - poc/poc.sh: corregir VITE_API_URL (faltaba sufijo /api), crear admin con bcrypt - docs/POC_GUIDE.md: guia paso a paso para que el compañero explore la demo - README.md: añadir credenciales admin y enlace a la guia POC Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
287 lines
7.9 KiB
Markdown
287 lines
7.9 KiB
Markdown
# 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.
|