feat(poc): expandir POC con datos multilingues, admin pre-creado y guia completa
- 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>
This commit is contained in:
SITO
parent
b3bf3d7a7f
commit
10f0555c46
4 changed files with 553 additions and 73 deletions
287
docs/POC_GUIDE.md
Normal file
287
docs/POC_GUIDE.md
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue